Animations

Citizens support configurable animations that make NPCs feel alive. Animations can trigger on a timer, when a player approaches, or when someone interacts with the NPC.

Animation Configuration

Animations are defined in the animations array of a citizen's JSON configuration:

{
  "animations": [
    {
      "type": "PROXIMITY",
      "animationName": "Wave",
      "animationSlot": 2,
      "interval": 15.0,
      "proximityRange": 8.0,
      "stopAfterTime": true,
      "stopTime": 3.0
    }
  ]
}

Fields

Field	Required	Default	Description
type	Yes	--	Trigger type: TIMED, TIMED_RANDOM, PROXIMITY, or ON_INTERACT.
animationName	Yes	--	Name of the animation to play (e.g. Wave, Laugh, Idle, Dance).
animationSlot	No	2	The animation slot/layer to use. See slot table below.
interval	No	5.0	Seconds between triggers (for TIMED and TIMED_RANDOM).
proximityRange	No	8.0	Detection radius in blocks (only for PROXIMITY).
stopAfterTime	No	false	Whether to stop the animation after a set duration.
stopTime	No	0.0	Seconds after which to stop the animation (only when stopAfterTime: true).
stopAnimation	No	null	Name of an animation to play when stopping (instead of just stopping).

Trigger Types

TIMED

Plays the animation at a fixed interval. Good for periodic idle behaviors like stretching or looking around.

{
  "type": "TIMED",
  "animationName": "Idle",
  "animationSlot": 1,
  "interval": 10.0
}

The NPC will play the Idle animation every 10 seconds.

TIMED_RANDOM

Same as TIMED but with random variation. The actual interval is randomly chosen between 50% and 150% of the configured value. This prevents multiple NPCs from animating in sync.

{
  "type": "TIMED_RANDOM",
  "animationName": "Laugh",
  "animationSlot": 2,
  "interval": 20.0
}

The NPC will laugh roughly every 10-30 seconds (random jitter around 20s).

PROXIMITY

Triggers when a player enters the detection range and stops when the player leaves. Perfect for greeting animations.

{
  "type": "PROXIMITY",
  "animationName": "Wave",
  "animationSlot": 2,
  "proximityRange": 8.0,
  "stopAfterTime": true,
  "stopTime": 3.0
}

When a player comes within 8 blocks, the NPC waves for 3 seconds.

tip

Proximity animations are the most common setup. Almost all default NPCs use a proximity wave animation to greet approaching players.

ON_INTERACT

Plays once when a player interacts with the NPC (presses F). Useful for talking or gesture animations during dialog.

{
  "type": "ON_INTERACT",
  "animationName": "Dance",
  "animationSlot": 4,
  "stopAfterTime": true,
  "stopTime": 5.0
}

Animation Slots

Animation slots are layers that can play simultaneously. Using different slots allows an NPC to walk and wave at the same time.

Slot	Name	Typical Use
0	Movement	Walking, running, swimming. Managed by the movement system.
1	Status	Idle stance, sitting, sleeping.
2	Action	Attack swings, interaction gestures.
3	Face	Facial expressions.
4	Emote	Wave, dance, laugh, cheer.

warning

Slot 0 (Movement) is controlled by the NPC's movement system. Overriding it with a custom animation can cause visual glitches. Use slot 2 or 4 for custom animations.

Movement Types

Movement is configured separately from animations via the movementType field on the citizen. The movement type determines the NPC's walking behavior.

Type	Description
IDLE	Stands still. The NPC does not move from its spawn position.
WANDER	Walks randomly within movementRadius blocks of the spawn point.
WANDER_CIRCLE	Walks in a circular pattern around the spawn point.
WANDER_RECT	Walks in a rectangular area around the spawn point.
PATH	Follows a predefined waypoint path.

Wander Configuration

{
  "movementType": "WANDER",
  "movementRadius": 8.0,
  "walkSpeed": 1.0
}

The system snaps the radius to discrete values for the internal NPC role system:

Configured Radius	Snapped To
Less than 3	2 blocks
3 to 6	5 blocks
7 to 11	10 blocks
12 or more	15 blocks

Rotation Towards Player

Set rotateTowardsPlayer: true to make idle NPCs face the nearest player. When a wandering NPC is interacted with, it automatically turns towards the interacting player and pauses its movement for the duration of the dialog or shop interaction.

Combining Animations

You can define multiple animations on a single NPC. They will play on their respective slots without interfering with each other.

{
  "animations": [
    {
      "type": "PROXIMITY",
      "animationName": "Wave",
      "animationSlot": 4,
      "proximityRange": 8.0,
      "stopAfterTime": true,
      "stopTime": 3.0
    },
    {
      "type": "TIMED_RANDOM",
      "animationName": "Laugh",
      "animationSlot": 2,
      "interval": 30.0,
      "stopAfterTime": true,
      "stopTime": 2.0
    }
  ]
}

This NPC waves when a player approaches and occasionally laughs on its own.

Available Animations

Common animation names that work with player models:

Name	Description
Wave	Waving gesture
Laugh	Laughing
Dance	Dancing
Idle	Standard idle stance
Cheer	Cheering/celebrating

info

The available animation names depend on the Hytale game version and the entity model being used. Entity models (non-player NPCs) may have different animation sets than player models.