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

title, type, weight

title	type	weight
NPC Commands	docs	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

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