# Animations

# 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:

```json
{
  "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`, `ON_INTERACT`, `ON_ATTACK` or `DEFAULT`. |
| `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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

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

### ON_ATTACK

Plays once when the NPC is hit, at most once per second. Citizens never attack on their own, so this is a reaction to being hit. Works since Core 2.9.0 (shown as "On attack" in the NPC window).

```json
{
  "type": "ON_ATTACK",
  "animationName": "Laugh",
  "animationSlot": 4
}
```

### DEFAULT

An idle animation that plays while no other animation of the NPC runs: for each player who comes within 48 blocks, again after another animation ended, and every `interval` seconds when an interval is set. Works since Core 2.9.0 (shown as "Default" in the NPC window).

```json
{
  "type": "DEFAULT",
  "animationName": "Idle",
  "animationSlot": 1
}
```

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

```json
{
  "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.

```json
{
  "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.
:::