hytale-npc-templates

Hytale NPC Template & Behavior System

Use this skill when defining NPC behavior through JSON templates. This covers the data-driven side of NPC creation — how NPCs think, act, detect threats, fight, interact with other NPCs, and transition between behavioral states. For programmatic NPC spawning via Java, see the hytale-spawning-npcs skill instead.

Prerequisite: Familiarity with JSON asset structure under Server/ directories and the Hytale ECS architecture.

---

Quick Reference

Concept	Description
Template	Abstract JSON file defining base NPC behavior, parameters, and states
Variant	Concrete NPC role that extends a template with specific parameter overrides
State	A top-level behavioral mode (e.g., Idle, Sleep, Combat)
Substate	A state nested within another, prefixed with . (e.g., .Default, .Guard)
Sensor	Condition that gates instruction execution (e.g., State, Target, Beacon, Mob, Damage)
Action	Operations performed when sensor conditions are met (e.g., State, Timeout, Random, Attack)
Motion	Movement behavior (e.g., Seek, Wander, Nothing, Follow_Path)
StateTransition	Actions performed sequentially when transitioning between states (e.g., animations)
Component	Reusable instruction/sensor module referenced via "Reference"
Parameter	Configurable value exposed in the template's Parameters block
Beacon	Message-based inter-NPC communication system
NPC Group	Named set of NPC roles used for filtering (attitudes, beacons, food targets)
Attitude Group	Defines Friendly/Hostile/Neutral relationships between NPC groups

---

File Locations

File Type	Path
NPC Templates	Server/NPC/Templates/Template_<Name>.json
NPC Variants (Roles)	Server/NPC/Roles/<Name>.json
NPC Components	Server/NPC/Components/Component_<Class>_<Name>.json
NPC Groups	Server/NPC/Groups/<GroupName>.json
Attitude Groups	Server/NPC/AttitudeGroups/<Name>.json
Appearance files	Server/NPC/Appearances/<Name>.json
Root Interactions	Server/Item/RootInteractions/Root_NPC_<Name>.json
Attack Interactions	Server/Item/Interactions/<Name>.json
Spawn Beacons	Server/NPC/SpawnBeacons/<Name>.json

---

Template Structure

Blank Template (Starting Point)

Always start from BlankTemplate and customize. A template is "Type": "Abstract" and defines defaults through Parameters.

{
  "Type": "Abstract",
  "Parameters": {
    "Appearance": {
      "Value": "Bear_Grizzly",
      "Description": "Model to be used"
    },
    "DropList": {
      "Value": "Empty",
      "Description": "Drop Items"
    },
    "MaxHealth": {
      "Value": 100,
      "Description": "Max health for the NPC"
    },
    "NameTranslationKey": {
      "Value": "server.npcRoles.Template.name",
      "Description": "Translation key for NPC name display"
    }
  },
  "Appearance": { "Compute": "Appearance" },
  "DropList": { "Compute": "DropList" },
  "MaxHealth": { "Compute": "MaxHealth" },
  "MotionControllerList": [
    {
      "Type": "Walk",
      "MaxWalkSpeed": 3,
      "Gravity": 10,
      "MaxFallSpeed": 8,
      "Acceleration": 10
    }
  ],
  "Instructions": [
    {
      "Sensor": {
        "Type": "Any"
      },
      "BodyMotion": {
        "Type": "Nothing"
      }
    }
  ],
  "NameTranslationKey": { "Compute": "NameTranslationKey" }
}

Variant (Role) File

A variant extends a template with concrete parameter values. Place next to the template.

{
  "Type": "Variant",
  "Reference": "Template_Goblin_Ogre",
  "Modify": {
    "Appearance": "Goblin",
    "MaxHealth": 124
  }
}

Variants can also override InteractionVars, Parameters, and NameTranslationKey.

---

Parameters

Parameters are defined in the "Parameters" block and referenced via { "Compute": "ParamName" }. They support computed expressions like "Compute": "ViewRange / DistractedPenalty".

"Parameters": {
  "Appearance": {
    "Value": "Bear_Grizzly",
    "Description": "Model to be used"
  },
  "ViewRange": {
    "Value": 15,
    "Description": "View range in blocks"
  },
  "DistractedPenalty": {
    "Value": 2,
    "Description": "Factor by which view/hearing range is divided when distracted"
  }
}

Computed expressions: { "Compute": "ViewRange / DistractedPenalty" } divides ViewRange by DistractedPenalty at runtime.

---

States & Substates

Setting the Start State

"StartState": "Idle",

Top-Level States

Top-level states are behavioral modes like Idle, Sleep, Eat, Combat, Alerted, ReturnHome, Search.

"Instructions": [
  {
    "Sensor": { "Type": "State", "State": "Idle" },
    "Instructions": [ ... ]
  },
  {
    "Sensor": { "Type": "State", "State": "Sleep" },
    "Instructions": [ ... ]
  },
  {
    "Sensor": { "Type": "State", "State": "Combat" },
    "Instructions": [ ... ]
  }
]

Substates

Substates are nested within a parent state and prefixed with .. The .Default substate is used automatically when entering the parent state.

{
  "Sensor": { "Type": "State", "State": "Idle" },
  "Instructions": [
    {
      "Sensor": { "Type": "State", "State": ".Default" },
      "Instructions": [ ... ]
    },
    {
      "Sensor": { "Type": "State", "State": ".Guard" },
      "Instructions": [ ... ]
    }
  ]
}

Switching States

Use a State action to switch:

{ "Type": "State", "State": "Combat" }

For substates:

{ "Type": "State", "State": ".Guard" }

---

Sensors

Sensors are conditions that gate instruction execution.

Sensor Type	Description	Key Fields
State	Matches current NPC state	State
Any	Always matches	Once (execute only once)
Target	Detects locked/nearby target	Range, TargetSlot, Filters
Mob	Detects nearby NPCs	Range, Filters ([NPCGroup, LineOfSight])
Beacon	Listens for inter-NPC messages	Message, Range, TargetSlot
Damage	Reacts to incoming damage	Combat, TargetSlot
Leash	Checks distance from spawn	Range
And	Combines multiple sensors	Sensors (array)
Reference	Uses a reusable sensor component	Component name

Sensor with Filters

{
  "Sensor": {
    "Type": "Target",
    "Range": { "Compute": "AttackDistance" },
    "Filters": [
      { "Type": "LineOfSight" }
    ]
  },
  "Actions": [ ... ]
}

Mob Sensor (NPC Group Filtering)

{
  "Sensor": {
    "Type": "Mob",
    "Range": 2.5,
    "Filters": [
      { "Type": "NPCGroup", "IncludeGroups": { "Compute": "FoodNPCGroups" } },
      { "Type": "LineOfSight" }
    ]
  }
}

---

Actions

Actions are operations executed when sensor conditions are met.

Action Type	Description	Key Fields
State	Switch to a different state	State
ParentState	Switch using imported state name	State (from _ImportStates)
Random	Randomly pick a weighted action	Actions (array with Weight + Action)
Timeout	Wait for a duration	Delay ([min, max] or fixed)
PlayAnimation	Play an animation	Slot, Animation
Attack	Execute an attack interaction	Attack, AttackPauseRange
Inventory	Manipulate NPC inventory	Operation, Item, Slot, UseTarget
Beacon	Send message to nearby NPCs	Message, TargetGroups, SendTargetSlot
TriggerSpawnBeacon	Trigger a manual spawn beacon	BeaconSpawn, Range
SetStat	Set an entity stat	Stat, Value
Remove	Remove the target entity	—
Despawn	Despawn this NPC	—
Sequence	Execute multiple actions in same tick	Actions (array)

Random Action (Weighted State Selection)

{
  "Actions": [
    {
      "Type": "Random",
      "Actions": [
        { "Weight": 70, "Action": { "Type": "State", "State": ".Guard" } },
        { "Weight": 20, "Action": { "Type": "State", "State": "Sleep" } },
        { "Weight": 10, "Action": { "Type": "State", "State": "Eat" } }
      ]
    }
  ]
}

Timeout with State Switch

{
  "Continue": true,
  "ActionsBlocking": true,
  "Actions": [
    { "Type": "Timeout", "Delay": [15, 30] },
    { "Type": "State", "State": ".Default" }
  ]
}

Inventory Actions

Operation	Description
SetHotbar	Place an item in a hotbar slot
EquipHotbar	Switch active hotbar slot

{
  "Type": "Inventory",
  "Operation": "SetHotbar",
  "Item": { "Compute": "EatItem" },
  "Slot": 2,
  "UseTarget": false
}

UseTarget: false is required to act on the NPC itself, not its target.

---

Instruction Flags

Flag	Description
Continue	If true, continue evaluating subsequent instructions even if this one matches
ActionsBlocking	If true, wait for all actions to complete before proceeding
Once	(On sensors) Execute only once when first entering the state

Common pattern — timeout then switch state:

{
  "Continue": true,
  "ActionsBlocking": true,
  "Actions": [
    { "Type": "Timeout", "Delay": [5, 10] },
    { "Type": "State", "State": "Idle" }
  ]
}

---

Motions

Motions control NPC movement. Set via BodyMotion or HeadMotion on instructions.

Motion Type	Description	Key Fields
Nothing	Stand still	—
Seek	Move toward target/position	SlowDownDistance, StopDistance, RelativeSpeed, UsePathfinder
Wander	Random wandering	MaxHeadingChange, RelativeSpeed
WanderInCircle	Circular wandering	Radius, MaxHeadingChange, RelativeSpeed

---

Content truncated.