Imported from xDinkyx/Hytale-Colonies-Plugin (.github/skills/hytale-npc-actions/SKILL.md). Install upstream with npx skills add xDinkyx/Hytale-Colonies-Plugin --skill hytale-npc-actions. Copyright stays with the author.

Hytale NPC Actions & Motions

Full reference for NPC actions, body/head motions, the timer/alarm/flag systems, and the Random instruction type.

Load alongside hytale-npc-templates when implementing NPC behavior that involves actions, movement, or timed events.

Triggers

• NPC action
• action type
• Actions
• Timeout
• PlayAnimation
• Inventory action
• PickUpItem
• SetLeashPosition
• MakePath
• StorePosition
• Beacon action
• SetFlag
• TimerStart
• TimerStop
• SetAlarm
• NPC motion
• BodyMotion
• HeadMotion
• Seek motion
• Wander
• WanderInCircle
• WanderInRect
• MaintainDistance
• MotionControllerList
• timer system
• alarm system
• flag system
• Random instruction
• ExecuteFor
• ResetOnStateChange
• leash point
• UseTarget
• Inventory operation
• EquipHotbar
• SetHotbar
• Hoover
• PlaySound
• Appearance action
• DisplayName action
• SpawnParticles

Actions

Actions are operations executed when sensor conditions are met. All names are the exact JSON "Type" strings registered in the engine.

State / Lifecycle

Control Flow

Timers

Entity / Communication

World Interaction

Items

Visual / Audio

Interaction

Enabled flag on actions

Action elements can be selectively disabled using the Enabled flag:

{
  "Type": "Attack",
  "Attack": { "Compute": "SpecialAttack" },
  "Enabled": false
}

Beacon Range from Template Variables

{
  "Type": "Beacon",
  "Message": "Alert_Allies",
  "TargetGroups": { "Compute": "WarnGroups" },
  "Range": { "Compute": "AlertBeaconRange" }
}

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 Action

Full set of Inventory operations (confirmed from decompiled source):

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

{
  "Type": "Inventory",
  "Operation": "EquipHotbar",
  "Item": { "Compute": "WeaponItem" },
  "Slot": 0,
  "UseTarget": false
}

PickUpItem Action

Two modes:

• Sensor-driven (default): requires a DroppedItem sensor to provide the item target.
• Hoover mode (Hoover: true): sucks up all items in range; no sensor needed.

{
  "Type": "PickUpItem",
  "Hoover": true,
  "Range": 3.0,
  "StorageTarget": "Inventory",
  "Items": ["Hyforged:*Wood*", "Hyforged:*Log*"]
}

Motions

Motions control NPC movement. Set via BodyMotion or HeadMotion on an instruction.

Body Motion

Head Motion

MotionControllerList

Defined at template level:

"MotionControllerList": [
  {
    "Type": "Walk",
    "MaxWalkSpeed": 3,
    "Gravity": 10,
    "MaxFallSpeed": 8,
    "Acceleration": 10
  }
]

Head Motion (Watch Target)

{
  "Continue": true,
  "Sensor": { "Type": "Target", "Range": { "Compute": "AlertedRange" } },
  "HeadMotion": { "Type": "Watch" }
}

Body Motion with Pathfinding

{
  "Sensor": { "Type": "Leash", "Range": { "Compute": "LeashDistance * 0.3" } },
  "BodyMotion": {
    "Type": "Seek",
    "SlowDownDistance": { "Compute": "LeashDistance * 0.4" },
    "StopDistance": { "Compute": "LeashDistance * 0.2" },
    "RelativeSpeed": 0.8,
    "UsePathfinder": true
  }
}

WanderInCircle — leash point

WanderInCircle constrains movement to a circle centred on NPCEntity.getLeashPoint(). The leash point defaults to the NPC's spawn position. To wander around a workstation or harvested block, set the leash point first:

NPCEntity npc = store.getComponent(ref, NPCEntity.getComponentType());
if (npc != null) npc.getLeashPoint().assign(targetPosition);

// Set leash to current NPC position via JSON:
{ "Type": "SetLeashPosition", "ToCurrent": true }

Search Wander Pattern

"BodyMotion": {
  "Type": "Sequence",
  "Motions": [
    {
      "Type": "Timer",
      "Time": [3, 6],
      "Motion": { "Type": "Wander", "MaxHeadingChange": 1, "RelativeSpeed": 0.5 }
    },
    {
      "Type": "Sequence",
      "Looped": true,
      "Motions": [
        {
          "Type": "Timer",
          "Time": [3, 6],
          "Motion": { "Type": "WanderInCircle", "Radius": 10, "MaxHeadingChange": 60, "RelativeSpeed": 0.5 }
        },
        {
          "Type": "Timer",
          "Time": [2, 3],
          "Motion": { "Type": "Nothing" }
        }
      ]
    }
  ]
}

Timer System

Named, countdown timers. Each has a current value that decrements at a configurable Rate. Stop/pause/restart via actions. Query state and remaining time via Timer: Sensor.

Starting and managing a timer

// Start a 5-10 second cooldown timer named "AttackCooldown":
{ "Type": "TimerStart", "Name": "AttackCooldown", "StartValueRange": [5, 10], "Rate": 1.0 }

// Stop it:
{ "Type": "TimerStop", "Name": "AttackCooldown" }

// Pause / continue:
{ "Type": "TimerPause", "Name": "AttackCooldown" }
{ "Type": "TimerContinue", "Name": "AttackCooldown" }

// Restart to original values:
{ "Type": "TimerRestart", "Name": "AttackCooldown" }

// Modify (add time, change rate, set repeating):
{ "Type": "TimerModify", "Name": "AttackCooldown", "AddValue": 3.0, "Repeating": true }

Querying a timer

{
  "Sensor": {
    "Type": "Timer",
    "Name": "AttackCooldown",
    "State": "STOPPED",
    "TimeRemainingRange": [0, 999]
  },
  "Actions": [ { "Type": "Attack", "Attack": { "Compute": "Attack" } } ]
}

Alarm System

Lighter-weight alternative to timers for simple one-shot delays.

// Set an alarm to fire in 3-5 seconds:
{ "Type": "SetAlarm", "Name": "CooldownAlarm", "DurationRange": ["PT3S", "PT5S"] }

// Check if it has passed (and auto-clear it):
{
  "Sensor": { "Type": "Alarm", "Name": "CooldownAlarm", "State": "PASSED", "Clear": true },
  "Actions": [ ... ]
}

Duration uses ISO-8601 duration strings: "PT5S" = 5 seconds, "PT1M30S" = 90 seconds.

Flag System

Named boolean flags that persist on the NPC within a session.

// Set a flag:
{ "Type": "SetFlag", "Name": "HasSpokenToPlayer", "SetTo": true }

// Clear it:
{ "Type": "SetFlag", "Name": "HasSpokenToPlayer", "SetTo": false }

// Test it:
{
  "Sensor": { "Type": "Flag", "Name": "HasSpokenToPlayer", "Set": true },
  "Actions": [ ... ]
}

Random: Instruction (source-verified)

Random: Instruction picks a weighted random child instruction and executes it. It does not re-pick every tick; it keeps the same choice for ExecuteFor seconds, then re-rolls.

The selected child's sensor is still checked every tick — if it fails the engine runs nothing for that tick (does NOT fall back to another child).

{
  "Type": "Random",
  "ExecuteFor": [5, 10],
  "Instructions": [
    { "Weight": 3, "BodyMotion": { "Type": "WanderInCircle", "Radius": 8 } },
    { "Weight": 1, "BodyMotion": { "Type": "Nothing" } }
  ]
}

Related Skills

• hytale-npc-templates — Core template structure, states, parameters, instruction flags
• hytale-npc-sensors — All sensor types, entity filters, detection, block sensors, target slots
• hytale-npc-combat — Combat AI patterns, attack interactions, beacons
• hytale-npc-pathfinding — Plugin-driven A* navigation via ReadPosition/Seek
• hytale-npc-components — Reusable JSON instruction components