AdvancedNPC

A feature-rich NPC plugin for PocketMine-MP with persistent storage, 45+ mob types, and clean code organization.

Version: 1.0.0
API: 5.0.0
Author: PixelMCN

---

Features

• No Gravity - NPCs stay exactly where placed, even in mid-air
• 45+ Mob Types - All Minecraft mobs supported (Villager, Zombie, Enderman, Pig, Wolf, and 40+ more)
• Custom Skins - Human NPCs use player skins with separate file storage
• Interactive Commands - Execute commands when players click NPCs
• Body Tracking - Optional feature to make NPCs face nearby players
• Edit Mode - Simple UI form to edit NPC properties in-game
• Organized Codebase - Clean folder structure for easy maintenance

---

Commands

Command	Description	Permission
/npc create <title> [type]	Create an NPC at your location	advnpc.command.create
/npc remove <id>	Remove an NPC by ID	advnpc.command.remove
/npc list	List all NPCs in current world	advnpc.command.list
/npc tp <id>	Teleport to an NPC	advnpc.command.tp
/npc edit on|off	Toggle edit mode	advnpc.command.edit
/npc reload	Reload all NPCs	advnpc.command.reload

Note: Type parameter is optional and defaults to Human.

---

Usage Examples

Create NPCs

/npc create BankNPC                # Creates Human NPC with your skin
/npc create "Shop Keeper"          # Use quotes for multi-word names
/npc create Villager1 Villager     # Create Villager mob NPC
/npc create Guard Zombie           # Create Zombie mob NPC
/npc create Archer Skeleton        # Create Skeleton mob NPC
/npc create Exploder Creeper       # Create Creeper mob NPC

Edit NPCs

/npc edit on                 # Enable edit mode
Click any NPC               # Opens edit form
Change properties           # Title, subtitle, command, position, scale, etc.
Save changes                # NPC updates immediately
/npc edit off               # Disable edit mode

Manage NPCs

/npc list                   # Shows all NPCs in current world
/npc tp 1                   # Teleport to NPC with ID 1
/npc remove 2               # Delete NPC with ID 2
/npc reload                 # Reload all NPCs from files

---

Configuration

config.yml

# Enable debug messages
debug: false

# Default NPC behavior
default-behavior:
  body-tracking: false       # NPCs rotate towards players
  tracking-range: 10.0       # Range in blocks

# NPC appearance
appearance:
  show-nametag: true
  nametag-visible-range: 20.0

# Custom skins
custom-skins-enabled: true

messages.yml

All plugin messages are customizable with color code support.

---

File Structure

AdvancedNPC/
├── commands/           # Command handlers
├── entities/           # NPC entity classes
├── managers/           # Data and skin management
├── forms/              # UI forms
├── events/             # Custom events
└── utils/              # Utility classes

See STRUCTURE.md for detailed documentation.

---

Data Storage

NPC Data

• Location: plugin_data/AdvancedNPC/worlds/<world>.yml
• Format: YAML with all NPC properties
• One file per world

Skin Data

• Location: plugin_data/AdvancedNPC/skins/<skinid>.dat
• Format: JSON with base64-encoded skin data
• Separate files keep YAML files small

---

NPC Properties

Each NPC has the following properties:

Property	Type	Description
id	int	Unique ID in the world
name	string	Internal name
type	string	Entity type (Human only works visually)
title	string	Display name above NPC
subtitle	string	Text below title
command	string	Command executed on click (without /)
x, y, z	float	Position coordinates
yaw, pitch	float	Rotation angles
world	string	World name
body_tracking	bool	Enable player tracking
tracking_range	float	Tracking distance
scale	float	Entity size multiplier
skin_file	string	Reference to skin file

---

API Usage

Get Plugin Instance

$plugin = \PixelMCN\AdvancedNPC\Main::getInstance();

Access NPC Manager

$npcManager = $plugin->getNPCManager();

Get NPCs in World

$npcs = $npcManager->getNPCsByWorld("world");
foreach ($npcs as $npc) {
    echo $npc['name'] . " at " . $npc['x'] . "," . $npc['y'] . "," . $npc['z'];
}

Get Specific NPC

$npc = $npcManager->getNPCById(1, "world");
if ($npc !== null) {
    echo "NPC: " . $npc['name'];
}

Listen to NPC Interactions

use PixelMCN\AdvancedNPC\events\NPCInteractEvent;

public function onNPCInteract(NPCInteractEvent $event): void {
    $player = $event->getPlayer();
    $npcName = $event->getNPCName();
    
    $player->sendMessage("You clicked " . $npcName);
    
    // Cancel to prevent default command execution
    $event->cancel();
}

---

Permissions

Permission	Description	Default
advnpc.command	Base command access	op
advnpc.command.create	Create NPCs	op
advnpc.command.remove	Remove NPCs	op
advnpc.command.list	List NPCs	op
advnpc.command.tp	Teleport to NPCs	op
advnpc.command.edit	Edit NPCs	op
advnpc.command.reload	Reload NPCs	op

---

Supported Mob Types

Currently implemented and working:

• Human - Player-like NPC with custom skin
• Villager - Villager mob appearance
• Zombie - Zombie mob appearance
• Skeleton - Skeleton mob appearance
• Creeper - Creeper mob appearance

Other mob types in the type list will default to Human appearance.

Note: Mob NPCs (Villager, Zombie, etc.) use default mob appearance and don't support custom skins.

---

Troubleshooting

NPCs disappear after restart

• Check if worlds/<world>.yml exists
• Enable debug mode in config.yml
• Check console for error messages
• Try /npc reload

NPCs falling through ground

• This should not happen (gravity disabled)
• If it does, report as a bug

Skin not loading

• Check if skin file exists in skins/ folder
• Default skin will be used if file is missing
• Try recreating the NPC

Body tracking not working

• Check body_tracking: true in NPC data
• Verify player is within tracking range
• Use /npc edit on and toggle the setting

---

Installation

1. Download the plugin
2. Place in plugins/ folder
3. Restart server
4. Plugin will create necessary files and folders

---

Support

For issues, questions, or feature requests:

• Check STRUCTURE.md for detailed documentation
• Enable debug mode for detailed logs
• Check console for error messages

---

License

This plugin is provided as-is. Modify and distribute as needed.

---