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

---
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 >}}