NPC Command Reference

Commands from NPCPlugin - uses hytale.command.npc.* namespace

Note: The internal permission namespace is server.commands.npc. Several NPC commands use view cone targeting instead of entity IDs - they affect NPCs within the player’s view cone (8 block distance, 30 degree angle, 2 block height tolerance).

/npc spawn

Spawn an NPC.

Permission: hytale.command.npc.spawn

/npc spawn
/npc spawn <role> [options...]

Usage Variants:

• /npc spawn (no args) - Opens the Entity Spawn UI page
• /npc spawn <role> [options...] - Spawn NPC via command

Argument	Type	Required	Default	Validation	Description
role	NpcRole	Yes	-	-	NPC role/type asset
--count	Integer	No	1	> 0	Number to spawn
--radius	Float	No	8.0	> 0	Spawn radius
--flags	String	No	-	-	Debug flags
--speed	Float	No	-	> 0	Initial velocity
--nonrandom	Flag	No	-	-	Use seed 0 for determinism
--position	String	No	-	-	Absolute position x,y,z
--posOffset	String	No	-	-	Position offset x,y,z
--headRotation	String	No	-	-	Head rotation pitch,yaw,roll
--bodyRotation	String	No	-	-	Body rotation pitch,yaw,roll
--randomRotation	Flag	No	-	-	Random rotation
--facingRotation	Flag	No	-	-	Face spawning player
--flock	String	No	1	-	Flock size or asset ID
--test	Flag	No	-	-	Test spawn validity only
--spawnOnGround	Flag	No	-	-	Snap to ground
--frozen	Flag	No	-	-	Spawn frozen/inactive
--randomModel	Flag	No	-	-	Use random skin variant
--scale	Float	No	-	-	Model scale multiplier
--bypassScaleLimits	Flag	No	-	-	Ignore scale limits

Examples:

/npc spawn Wolf                           # Spawn one wolf
/npc spawn Wolf --count=5 --radius=10     # Spawn 5 wolves in 10 block radius
/npc spawn Skeleton_Archer --frozen       # Spawn frozen skeleton
/npc spawn Wolf --scale=2.0               # Spawn large wolf
/npc spawn Trork --facingRotation         # Spawn facing player

---

/npc all

Spawn all NPC roles in a grid.

Permission: hytale.command.npc.all

/npc all [--distance=?]

Argument	Type	Required	Default	Description
--distance	Double	No	4.0	Spacing between NPCs

---

/npc clean

Remove all NPCs.

Permission: hytale.command.npc.clean

/npc clean

---

/npc freeze

Freeze NPCs (stop AI/physics).

Permission: hytale.command.npc.freeze

/npc freeze [--all] [--toggle] [--entity=?]

Argument	Type	Required	Description
--all	Flag	No	Freeze all NPCs and items in world
--toggle	Flag	No	Toggle freeze state (unfreeze if frozen)
--entity	EntityId	No	Target specific NPC (default: looked-at)

Notes:

• Without --all, targets a single NPC
• --toggle with a frozen NPC will thaw it instead

---

/npc thaw

Unfreeze NPCs (resume AI/physics).

Aliases: unfreeze

Permission: hytale.command.npc.thaw

/npc thaw [--all] [--entity=?]

Argument	Type	Required	Description
--all	Flag	No	Thaw all NPCs in world
--entity	EntityId	No	Target specific NPC (default: looked-at)

---

/npc dump

Dump NPC role data.

Permission: hytale.command.npc.dump

/npc dump [--entity=?] [--json]

Argument	Type	Required	Description
--entity	EntityId	No	Target NPC (default: looked-at)
--json	Flag	No	Output as JSON format

---

/npc appearance

NPC appearance management.

Permission: hytale.command.npc.appearance

/npc appearance <model> [--entity=?]

Argument	Type	Required	Description
model	ModelAsset	Yes	Model asset to apply
--entity	EntityId	No	Target specific NPC (default: looked-at entity)

---

/npc attack

NPC attack behavior override.

Permission: hytale.command.npc.attack

/npc attack [attack...] [--entity=?]
/npc attack clear [--entity=?]

Subcommand	Arguments	Description
(default)	[attack...] [--entity]	Set attack interaction overrides
clear	[--entity]	Clear attack overrides

Argument	Type	Required	Description
attack	Interaction[]	No	List of attack interaction assets
--entity	EntityId	No	Target NPC (default: looked-at)

---

/npc blackboard

NPC blackboard (AI state) data.

Permission: hytale.command.npc.blackboard

/npc blackboard chunks
/npc blackboard chunk <position>
/npc blackboard drop
/npc blackboard views
/npc blackboard view <chunk>
/npc blackboard blockevents
/npc blackboard entityevents
/npc blackboard resourceviews
/npc blackboard resourceview <chunk>
/npc blackboard reserve <reserve> [--entity=?]
/npc blackboard reservation [--entity=?]

Subcommand	Arguments	Description
chunks	-	Show all blackboard chunk info
chunk	<position>	Show specific chunk entry
drop	-	Clear blackboard data
views	-	Show all partial views
view	<chunk>	Show specific view info
blockevents	-	Show block event subscriptions
entityevents	-	Show entity event subscriptions
resourceviews	-	Show all resource views
resourceview	<chunk>	Show specific resource view
reserve	<reserve> [--entity]	Set/clear NPC reservation
reservation	[--entity]	Show NPC reservation status

Argument	Type	Required	Description
position	RelativePosition	Yes	Block position
chunk	ChunkPosition	Yes	Chunk coordinates
reserve	Boolean	Yes	true to reserve, false to release
--entity	EntityId	No	Target NPC (default: looked-at)

---

/npc flock

NPC flocking behavior.

Permission: hytale.command.npc.flock.*

Note: These commands use view cone targeting (8 block distance, 30 degree angle) instead of entity IDs.

/npc flock leave
/npc flock grab
/npc flock join
/npc flock playerleave

Subcommands:

Subcommand	Permission	Description
leave	npc.flock.leave	Remove NPCs in view cone from their flocks
grab	npc.flock.grab	Pull flockless NPCs in view cone into player’s flock
join	npc.flock.join	Join flock of NPC in view cone
playerleave	npc.flock.playerleave	Leave current flock

---

/npc path

NPC pathfinding.

Permission: hytale.command.npc.path

/npc path <instructions> [--entity=?]
/npc path polygon <sides> [--length=?] [--entity=?]

Subcommand	Arguments	Description
(default)	<instructions>	Set path from instruction string
polygon	<sides> [--length]	Create polygon path

Argument	Type	Required	Default	Description
instructions	String	Yes	-	Pairs of rotation,distance (e.g., “45,5,90,3”)
sides	Integer	Yes	-	Number of polygon sides
--length	Double	No	5.0	Side length
--entity	EntityId	No	Looked-at	Target NPC

---

/npc role

NPC role management.

Permission: hytale.command.npc.role

/npc role <role> [--entity=?]
/npc role [--entity=?]

Argument	Type	Required	Description
role	NpcRole	No	New role asset (omit to get current role)
--entity	EntityId	No	Target NPC (default: looked-at)

---

/npc give

Give items to NPC.

Permission: hytale.command.npc.give

/npc give <item> [--entity=?]
/npc give nothing [--entity=?]

Subcommand	Arguments	Description
(default)	<item>	Give item (armor or hand item)
nothing	-	Remove item from hand

Argument	Type	Required	Description
item	Item	Yes	Item asset ID
--entity	EntityId	No	Target NPC (default: looked-at)

---

/npc message

Send message to NPC (for scripted behavior via BeaconSupport).

Permission: hytale.command.npc.message

/npc message <message> [--expiration=?] [--entity=?] [--all]

Argument	Type	Required	Default	Description
message	String	Yes	-	Message to send
--expiration	Double	No	1.0	Message expiration time
--entity	EntityId	No	Looked-at	Target NPC
--all	Flag	No	-	Send to all NPCs

---

/npc benchmark

NPC benchmarking.

Permission: hytale.command.npc.benchmark

/npc benchmark [--roles] [--sensorsupport] [--seconds=?]

Argument	Type	Required	Default	Description
--roles	Flag	No*	-	Benchmark role execution times
--sensorsupport	Flag	No*	-	Benchmark sensor support
--seconds	Double	No	30.0	Benchmark duration

One of --roles or --sensorsupport must be specified.

---

/npc sensorstats

NPC sensor statistics.

Permission: hytale.command.npc.sensorstats

/npc sensorstats

Outputs statistics about NPC sensor usage.

---

/npc step

Step NPC behavior (when frozen).

Permission: hytale.command.npc.step

/npc step [--entity=?] [--all] [--dt=?]

Argument	Type	Required	Default	Description
--entity	EntityId	No	Looked-at	Target NPC
--all	Flag	No	-	Step all NPCs
--dt	Float	No	1/TPS	Delta time for step

---

/npc debug

NPC debug flag management.

Permission: hytale.command.npc.debug

/npc debug show [targeting-options...]
/npc debug set <flags> [targeting-options...]
/npc debug toggle <flags> [targeting-options...]
/npc debug defaults [targeting-options...]
/npc debug clear [targeting-options...]
/npc debug presets [preset]

Subcommand	Arguments	Description
show	[targeting]	Show current debug flags
set	<flags> [targeting]	Set debug flags
toggle	<flags> [targeting]	Toggle debug flags
defaults	[targeting]	Reset to default flags
clear	[targeting]	Clear all debug flags
presets	[preset]	List presets or show preset info

Argument	Type	Required	Description
flags	String	Yes	Comma-separated flag names
preset	String	No	Preset name to inspect

Multi-Select Targeting Options (for show/set/toggle/defaults/clear):

Option	Type	Default	Description
--angle	Float	30.0	View cone angle (0-180 degrees)
--range	Float	8.0	Targeting range (0-2048 blocks)
--roles	String	-	Filter by role names (comma-separated)
--nearest	Flag	-	Only affect nearest matching NPC
--cone	Flag	-	Preset: 30° cone, nearest only
--coneAll	Flag	-	Preset: 30° cone, all matching
--sphere	Flag	-	Preset: 180° (sphere), all matching
--ray	Flag	-	Preset: 0° ray, nearest

---

/npc runtests

Run interactive NPC behavior tests.

Permission: hytale.command.npc.runtests

/npc runtests [--roles=?] [--preset] [--pass] [--fail] [--abort]

Argument	Type	Required	Description
--roles	String	No*	Comma-separated role list (format: RoleName or RoleName#flockSize)
--preset	Flag	No*	Use preset coverage test NPCs
--pass	Flag	No	Mark current test as passed, proceed to next
--fail	Flag	No	Mark current test as failed, proceed to next
--abort	Flag	No	Abort testing and show results

*One of --roles or --preset required to start new test session.

Workflow:

1. Start with /npc runtests --roles=Wolf,Trork#3 or /npc runtests --preset
2. Each NPC spawns and displays expected test criteria
3. Mark results with /npc runtests --pass or /npc runtests --fail
4. Results shown after all NPCs tested or --abort used

---

/npc test

NPC position testing utilities.

Permission: hytale.command.npc.test

/npc test probe

Subcommands:

Subcommand	Description
probe	Test position validity (air, water, collision) at player location

Outputs position validation info useful for debugging NPC spawn/movement issues.