# esx_animations (/docs/addons/esx_animations)

esx_animations is a client-side emote menu for ESX Legacy. Players open it with `F3`, pick a category and play an animation, a GTA scenario (smoking, fishing, taking photos) or a walking style. It ships with a NUI interface and can fall back to the classic [esx_context](/docs/core/esx_context) menu.

## Overview [#overview]

| | |
| --- | --- |
| Resource | `esx_animations` (version `1.1`) |
| Side | Client only (plus NUI) |
| Dependencies | `esx_lib`, `es_extended`; [esx_context](/docs/core/esx_context) when `Config.UseNui = false` |
| SQL file | none |
| Commands | `animmenu` (`F3`), `cleartasks` (`Z`) |
| Client exports | `GetConfig`, `SetConfig` |

## Installation [#installation]

```bash title="server.cfg"
ensure es_extended
ensure esx_context
ensure esx_animations
```

No database changes are needed.

## Usage in game [#usage-in-game]

| Action | Default key | Command |
| --- | --- | --- |
| Open the menu | `F3` | `/animmenu` |
| Stop the animation | `Z` | `/cleartasks` |

The keys are registered with `RegisterKeyMapping`, so each player can change them under Settings, Key Bindings, FiveM. The menu does not open while the player is dead. While the NUI is open, several controls (F2, F3, F4, F6, F7, Enter and exit vehicle) are disabled so other menus do not open behind it.

## Configuration [#configuration]

| Key | Default | Description |
| --- | --- | --- |
| `Config.Locale` | `GetConvar('esx:locale', 'en')` | Language of the NUI texts |
| `Config.UseNui` | `true` | `true` uses the NUI menu, `false` uses the ESX context menu |
| `Config.Animations` | 8 categories | The menu content, see below |

The default categories are `festives`, `greetings`, `work`, `humors`, `sports`, `misc`, `attitudem` (walk styles) and `porn` (adult gestures). Remove the last one if it does not fit your server.

### Config.Animations format [#configanimations-format]

```lua title="config.lua"
Config.Animations = {
    {
        name  = 'greetings',     -- unique id of the category
        label = 'Greetings',     -- shown in the menu
        items = {
            { label = 'Hello', type = 'anim', data = { lib = 'gestures@m@standing@casual', anim = 'gesture_hello' } },
            { label = 'Smoke', type = 'scenario', data = { anim = 'WORLD_HUMAN_SMOKING' } },
            { label = 'Confident', type = 'attitude', data = { lib = 'move_m@confident', anim = 'move_m@confident' } },
        }
    },
}
```

| `type` | `data` fields | What happens |
| --- | --- | --- |
| `anim` | `lib` (animation dictionary), `anim` (clip name) | Loads the dictionary and plays the clip once |
| `scenario` | `anim` (scenario name) | Starts the scenario in place |
| `attitude` | `lib` (clip set to load), `anim` (clip set to apply) | Changes the walking style until it is changed again |

### Translations [#translations]

The labels in `config.lua` are English. The `localization` folder contains complete replacement configs: `br`, `cs`, `de`, `en`, `fi`, `it`, `nl`, `pl`, `ru`, `sl`, `sr` and `sv` (for example `de_config.lua`). Copy the one you need over `config.lua`. The NUI language follows the `esx:locale` convar.

## Client exports [#client-exports]

### GetConfig [#getconfig]

```lua
local config = exports.esx_animations:GetConfig()
```

Returns the full `Config` table of the resource, including `Config.Animations`.

### SetConfig [#setconfig]

```lua
exports.esx_animations:SetConfig(newConfig)
```

| Name | Type | Description |
| --- | --- | --- |
| `newConfig` | `table` | Replaces the whole `Config` table |

`SetConfig` replaces the table instead of merging it, so always start from `GetConfig()`:

```lua title="client/main.lua"
local config = exports.esx_animations:GetConfig()

config.Animations[#config.Animations + 1] = {
    name = 'gang',
    label = 'Gang',
    items = {
        { label = 'Lean on wall', type = 'scenario', data = { anim = 'WORLD_HUMAN_LEANING' } },
    }
}

exports.esx_animations:SetConfig(config)
```

The change is client-side only and lasts until the resource restarts. Run it on every client, for example on `esx:playerLoaded`.

## Common issues [#common-issues]

- **Animation does nothing**: the dictionary or clip name is wrong. Check the name with a tool such as the [FiveM natives reference](https://docs.fivem.net/natives/) or an animation list.
- **Walk style sticks after `/cleartasks`**: walk styles are not tasks. Apply a different `attitude` entry, or call `ResetPedMovementClipset` in your own code.
- **Menu looks like the old ESX menu**: `Config.UseNui` is `false`.

## Related [#related]

- [esx_context](/docs/core/esx_context)
- [Streaming module](/docs/es_extended/client/modules/streaming)
- [Addons overview](/docs/addons)