# Animation selection setup

**Animation Selector** is a set of configuration files used to define rules for selecting and playing animations based on the current FSM-state of a unit’s.

**How the Animation Selector works**

When a unit transitions to a new state, the state handler queries the Animation Selector files to determine which animation should be played. The file defines:

* animation sets available for the given state;
* conditions for selecting a specific animation (e.g., depending on pose, weapon, view direction);
* priorities and fallback animations

Each FSM definition in the resources has a corresponding **Animation Selector file** with the same name.

**Animation Selector files** are stored in the `\properties\animation_selector\`  folder. Files have the .set extension.

Examples:

* `human.set` — used for the `human` entity
* `animal.set` — used for animal entities, such as `horse`

**Animation files** are stored either in the corresponding entity’s folder or in the shared directory: `\properties\animation\` and its subfolders.

## Animation Selector description structure

The **Animation Selector** description includes the following elements:

* Request name
* Condition;
* Animation assignment;
  * Animation playback speed.

{% hint style="info" %}
To simplify editing and reuse, it is recommended to extract logical and repetitive animation selection blocks into separate .inc files\
For example, in the Men of War II resource, the file human.set includes logic blocks via include from external files
{% endhint %}

### Animation Request Name

The request name in the Animation Selector usually matches the name of the animated object’s state. The request name may include words that clarify the context

Examples:

* `stand_idle`
* `walk`
* `lie_holdback_in`

Here's the English translation of your technical documentation text, formatted for GitBook and aligned with the Gem RTS documentation style:

***

### Animation Specification Methods

#### 1. Specifying a Direct Animation

To play a specific animation, use the `anm` block:

> **Syntax:**
>
> ```
> {anm "animation_name"}
> ```
>
> * The animation name is written in double quotes.
> * The string `" "` (empty string) means no animation will be played — the current animation will remain active.

<details>

<summary><strong>Example: Direct Animation Selection</strong></summary>

```
{lie_belt_in
	{if human_stuff holding "pistol"
		{anm "lie_take_pistol" -1}
	}
	{anm "lie_put_small" 0.75}
}
```

* `lie_belt_in` — the name of the query.
* `if` block — condition for triggering the animation.
* `lie_take_pistol` — animation name played at speed `-1` (reverse playback from end to start).
* `lie_put_small` — animation played at speed `0.75`.

</details>

#### 2. Random Animation Selection

The `random_select` block allows specifying a list of alternative animations with weighted probability:

> **Syntax:**
>
> ```
> {random_select
>     {weight n1 "animation_1"}
>     {weight n2 "animation_2"}
>     ...
> }
> ```
>
> * `weight` sets the relative probability `n`, from `0.01` to `100`.
> * Animation names are written in double quotes.

<details>

<summary><strong>Example: Random Animation Selection by Weigh</strong></summary>

```
{squat 
    {random_select
        {weight 5 "squat_idle_rifle_2"}
        {weight 2 "squat_idle_rifle_3" -1}
        {weight 1 "squat_idle_rifle_4"}
        {weight 1 "squat_idle_rifle_5"}
        {weight 1 "squat_idle_rifle_6"}
    }
}
```

* `squat_idle_rifle_2` has weight 5.
* `squat_idle_rifle_3` has weight 2 and is played in reverse (`-1` playback speed).

</details>

### 3. Counter-based Animation Selection

Looped switching of animation sets based on a numerical counter is done using the `switch_by_counter` block. This mechanism is useful for creating varied animations such as poses, walk cycles, reactions, emotions, and other repeating states.

> **Syntax:**
>
> ```
> {switch_by_counter <counter_name> 
>     {common [...]}
>     {pick <N> [...]}
>     {pick <N> [...]}
>     ...
> }
> ```

<table><thead><tr><th width="203.71875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>&#x3C;counter_name></code></td><td>The name of the counter that determines the current switch state.</td></tr><tr><td><code>common</code></td><td><em>(Optional)</em> Base animation set copied into each <code>pick</code> block before it is applied.</td></tr><tr><td><code>pick &#x3C;N></code></td><td>A pick option. The value <code>N</code> means this pick is used for <code>N</code> consecutive counter values.</td></tr></tbody></table>

#### How it works:

1. The counter starts at `0`, selecting the first `pick` block.
2. Each time the counter is triggered, its value increases by `1`, moving to the next pick.
3. The counter wraps around: once it reaches the total sum of all `N` values in `pick`, it resets to `0`.
4. Inside each `pick`, the contents of `common` (if defined) are copied and then overridden or extended by the current `pick`. \
   This means each `pick` can:
   * inherit from `common`;
   * Override specific fields;
   * Extend the base animation set with additional keys.

{% hint style="warning" %}
If `common` is not defined, all animation sets are taken directly from each `pick`.
{% endhint %}

<details>

<summary><strong>Example: Counter-based Animation Selection</strong></summary>

```
{switch_by_counter "pose"    
    {common
        {aim "aim_default_1" "aim_default_2"}
        {fire "fire_default_1" "fire_default_2"}
    }
    {pick 1} 
    {pick 2
        {aim "aim_alt_1" "aim_alt_2"}
        {fire "fire_alt_1" "fire_alt_2"}
    }
    {pick 1
        {idle "idle_look_around"}
    }
    {pick 1
        {idle "idle_gun_aside"}
    }
}
```

The `pose` counter has a cycle length of `1+2+1+1 = 5` (the sum of all `pick` values)

<table><thead><tr><th width="82.5390625">Step</th><th width="168.18359375">Value (counter pose )</th><th width="143.43359375">Pick block used</th><th>Animation Behavior</th></tr></thead><tbody><tr><td>1</td><td>0</td><td>First <code>pick</code></td><td>Uses animations from <code>common</code> (no overrides)</td></tr><tr><td>2</td><td>1</td><td>Second <code>pick</code></td><td>Overrides <code>aim</code> and <code>fire</code> from <code>common</code></td></tr><tr><td>3</td><td>2</td><td>Second <code>pick</code></td><td>Same as step 2</td></tr><tr><td>4</td><td>3</td><td>Third <code>pick</code></td><td>Adds <code>idle</code>, inherits <code>aim</code> and <code>fire</code> from <code>common</code></td></tr><tr><td>5</td><td>4</td><td>Fourth <code>pick</code></td><td>Replaces <code>idle</code>, retains <code>aim</code> and <code>fire</code> from <code>common</code></td></tr><tr><td>6</td><td>5 → reset to 0</td><td>First <code>pick</code></td><td>Loop restarts</td></tr></tbody></table>

</details>

### Animation playback speed

Animation playback speed is defined by a number following the animation name:

**Example:**

```
{anm "animation_name" 0.75}
```

* If speed is not defined, the default is `1.0`.
* Negative values (e.g., `-1`) play the animation in reverse.

### Conditions in the Animation Selector

The Animation Selector system supports **conditions** that adapt animation selection to the actor's current state or environment.

Conditions are defined within `if` blocks and can be:

* simple;
* compound;
* nested.

Any valid condition for the actor type can be used.

If the condition evaluates as true, only the animations within that block are considered.\
If no condition is met and no fallback animation is defined, the current animation remains unchanged.

> **Syntax of a Condition in the Animation Selector**:
>
> ```
> {if [condition]  
>     [...] ; anm or random_select
> }
> ```

Multiple conditions can be combined (implicitly using `and`).

> **Syntax of Compound Conditions**
>
> ```
> {if cond1 cond2 cond3
>     [...]
> }
> ```

{% hint style="success" %}
In the  idle-selector, logical operators like `and` , `not` and `or` are also supported in compound conditions.
{% endhint %}

Conditions can be nested.

> **Syntax of Nested Conditions**
>
> ```
> {if cond1   
>     {if cond2
>         {anm "animation_1"}
>     }
>     {anm "animation_2"}
> }
> ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bestway-1.gitbook.io/documentation/animation/animation-system-for-actor/animation-selection-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.