Init

content/world/entities/npc/npc-commands.en.md

@@ -0,0 +1,374 @@
+---
+title: NPC Commands
+type: docs
+weight: 5
+---
+
+The NPC system includes 23 admin and debug commands for managing and testing NPCs.
+
+**Package:** `com.hypixel.hytale.server.npc.commands`
+
+## Spawning Commands
+
+### /npc spawn
+
+Spawns an NPC at a location:
+
+```
+/npc spawn <npc_type> [position] [--role <role>] [--name <name>]
+```
+
+**Arguments:**
+| Argument | Type | Description |
+|----------|------|-------------|
+| `npc_type` | String | NPC asset ID |
+| `position` | Position | Spawn location (default: player position) |
+| `--role` | String | Override default role |
+| `--name` | String | Custom display name |
+
+**Examples:**
+```
+/npc spawn villager
+/npc spawn guard ~ ~1 ~ --role patrol_guard
+/npc spawn merchant --name "Bob the Trader"
+```
+
+### /npc despawn
+
+Removes an NPC:
+
+```
+/npc despawn <target>
+```
+
+**Arguments:**
+| Argument | Type | Description |
+|----------|------|-------------|
+| `target` | NPC | Target NPC (raycast or selector) |
+
+### /npc despawnall
+
+Removes all NPCs in radius:
+
+```
+/npc despawnall [radius]
+```
+
+**Arguments:**
+| Argument | Type | Description |
+|----------|------|-------------|
+| `radius` | Float | Radius in blocks (default: 50) |
+
+## Information Commands
+
+### /npc info
+
+Displays NPC information:
+
+```
+/npc info [target]
+```
+
+**Output:**
+```
+NPC Info: Villager (villager_001)
+  Position: 100.5, 64.0, -200.3
+  Role: villager_role
+  State: IDLE
+  Health: 100/100
+  Target: None
+  Current Instruction: Wander
+```
+
+### /npc list
+
+Lists all NPCs:
+
+```
+/npc list [--radius <radius>] [--type <type>]
+```
+
+**Arguments:**
+| Argument | Type | Description |
+|----------|------|-------------|
+| `--radius` | Float | Search radius |
+| `--type` | String | Filter by NPC type |
+
+### /npc debug
+
+Toggles debug visualization:
+
+```
+/npc debug <mode>
+```
+
+**Modes:**
+| Mode | Description |
+|------|-------------|
+| `path` | Show pathfinding |
+| `sensors` | Show sensor ranges |
+| `state` | Show AI state |
+| `target` | Show targeting |
+| `all` | Show everything |
+| `off` | Disable debug |
+
+## Behavior Commands
+
+### /npc role
+
+Changes NPC role:
+
+```
+/npc role <target> <role>
+```
+
+**Examples:**
+```
+/npc role @nearest guard_role
+/npc role @e[type=villager] merchant_role
+```
+
+### /npc state
+
+Forces NPC state:
+
+```
+/npc state <target> <state>
+```
+
+**States:**
+```
+/npc state @nearest IDLE
+/npc state @nearest ATTACKING
+/npc state @nearest FLEEING
+```
+
+### /npc target
+
+Sets NPC target:
+
+```
+/npc target <npc> <target_entity>
+```
+
+**Examples:**
+```
+/npc target @nearest @p
+/npc target guard_01 @e[type=zombie,limit=1]
+```
+
+### /npc cleartarget
+
+Clears NPC target:
+
+```
+/npc cleartarget <target>
+```
+
+## Movement Commands
+
+### /npc moveto
+
+Commands NPC to move to position:
+
+```
+/npc moveto <target> <position>
+```
+
+**Examples:**
+```
+/npc moveto @nearest ~ ~ ~10
+/npc moveto guard_01 100 64 -200
+```
+
+### /npc follow
+
+Commands NPC to follow entity:
+
+```
+/npc follow <npc> <target> [distance]
+```
+
+**Examples:**
+```
+/npc follow @nearest @p 3.0
+```
+
+### /npc stop
+
+Stops NPC movement:
+
+```
+/npc stop <target>
+```
+
+### /npc patrol
+
+Sets patrol path:
+
+```
+/npc patrol <target> <point1> <point2> [point3...]
+```
+
+**Examples:**
+```
+/npc patrol guard_01 0 64 0 10 64 0 10 64 10 0 64 10
+```
+
+### /npc home
+
+Sets NPC home position:
+
+```
+/npc home <target> [position]
+```
+
+## Blackboard Commands
+
+### /npc blackboard get
+
+Gets blackboard value:
+
+```
+/npc blackboard get <target> <key>
+```
+
+**Examples:**
+```
+/npc blackboard get @nearest alert_level
+/npc blackboard get guard_01 home_position
+```
+
+### /npc blackboard set
+
+Sets blackboard value:
+
+```
+/npc blackboard set <target> <key> <value>
+```
+
+**Examples:**
+```
+/npc blackboard set @nearest alert_level 1.0
+/npc blackboard set @nearest is_hostile true
+```
+
+### /npc blackboard clear
+
+Clears blackboard:
+
+```
+/npc blackboard clear <target> [key]
+```
+
+## AI Commands
+
+### /npc think
+
+Forces AI decision cycle:
+
+```
+/npc think <target>
+```
+
+### /npc instruction
+
+Forces instruction:
+
+```
+/npc instruction <target> <instruction>
+```
+
+**Examples:**
+```
+/npc instruction @nearest flee
+/npc instruction guard_01 attack
+```
+
+### /npc sensor
+
+Toggles sensor:
+
+```
+/npc sensor <target> <sensor> <enabled>
+```
+
+**Examples:**
+```
+/npc sensor @nearest visual false
+/npc sensor @nearest audio true
+```
+
+## Faction Commands
+
+### /npc faction
+
+Sets NPC faction:
+
+```
+/npc faction <target> <faction>
+```
+
+**Examples:**
+```
+/npc faction @nearest town_guard
+/npc faction villager_01 merchants
+```
+
+### /npc relation
+
+Sets faction relation:
+
+```
+/npc relation <faction1> <faction2> <relation>
+```
+
+**Relations:** `ALLIED`, `FRIENDLY`, `NEUTRAL`, `UNFRIENDLY`, `HOSTILE`
+
+**Examples:**
+```
+/npc relation guards bandits HOSTILE
+/npc relation merchants town_guard ALLIED
+```
+
+## Command Permissions
+
+| Command | Permission |
+|---------|------------|
+| `/npc spawn` | `hytale.command.npc.spawn` |
+| `/npc despawn` | `hytale.command.npc.despawn` |
+| `/npc info` | `hytale.command.npc.info` |
+| `/npc debug` | `hytale.command.npc.debug` |
+| `/npc role` | `hytale.command.npc.role` |
+| `/npc blackboard` | `hytale.command.npc.blackboard` |
+
+## Registering Custom NPC Commands
+
+```java
+public class MyNPCCommand extends AbstractCommand {
+    public MyNPCCommand() {
+        super("npc custom", "Custom NPC command");
+        withRequiredArg("target", "Target NPC", ArgTypes.NPC_REF);
+    }
+
+    @Override
+    protected CompletableFuture<Void> execute(CommandContext ctx) {
+        NPCEntity npc = ctx.get("target");
+        // Custom logic
+        return null;
+    }
+}
+
+// Register in plugin setup
+getCommandRegistry().register(new MyNPCCommand());
+```
+
+## Best Practices
+
+{{< callout type="info" >}}
+**Command Guidelines:**
+- Use selectors like `@nearest` for targeting NPCs
+- Debug commands are invaluable for testing AI
+- Blackboard commands allow runtime behavior modification
+- Use permission checks for admin commands
+{{< /callout >}}