> For the complete documentation index, see [llms.txt](https://docs.bestway.com.ua/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bestway.com.ua/animation/animation-system-for-actor/animation-selection-setup/configuring-idle-for-human-actor.md).

# Configuring idle for human actor

## General Principles

The following FSM states allow idle animations to be triggered:

* `board` — actor is linked to another object
* `lie_idle` — lying down
* `snipe` — peeking from behind cover
* `squat` — sitting
* `idle` — standing without performing any action

Idle animation selection occurs in two stages:

{% stepper %}
{% step %}

### Selecting r**equest** for the Animation Selector

The logic for choosing the request is defined in the **Idle Request Selector** file:\
`\properties\animation_selector\`**`human_idle_selector.set`**

{% hint style="info" %}
At this stage, you can optionally:

* switch the FSM state and/or apply semaphore locks;
* set a new FSM state.
  {% endhint %}
  {% endstep %}

{% step %}

#### Selecting idle animations

Based on the request selected in step one, specific idle animations are chosen.\
The selection logic is defined in **`human_idle.inc`**, which is part of the animation selector file:\
`\properties\animation_selector\`**`human.set`**
{% endstep %}
{% endstepper %}

The actor's current idle state is stored in the FSM to support chained transitions between idle states.

***

### **Idle Request Selector** configuration

> **Syntax of `human_idle_selector.set`**
>
> ```
> {init
> 	{state "<initial_state>"} ; required parameter
> 	{semaphore "<name>" <time_from> <time_to>} 
> }
> {selector
> 	{if <condition>
> 		{idle
> 			{run "<request_name>"} ; request to the Animation Selector
> 			{state "<new_state>"} ; optional FSM state change
> 			{semaphore "<name>" <time_from> <time_to>} ; optional semaphore override
> 		}
> 	}
> 	[...]	
> 	{idle
> 		{run ""} ; empty request
> 	}
> }
> ```

| Component                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{init ...}`                               | Initialization block called at game start or unit spawn. Sets the initial FSM state and semaphore locks.                                                                                                                                                                                                                                                                                                        |
| `state "<initial_state>"`                  | <p>Sets the FSM state of the actor immediately after spawning.</p><p><strong>Required</strong>.</p><p>Example: <code>"idle"</code></p>                                                                                                                                                                                                                                                                          |
| `semaphore "<name>" <time_from> <time_to>` | <p>Locks or unlocks a semaphore for a randomized time interval (in seconds).<br>Example: <code>semaphore "can\_smoke" 10 30</code> disables smoking for 10–30 seconds.</p>                                                                                                                                                                                                                                      |
| `{selector ...}`                           | Main block that defines the logic for choosing requests of the Animation Selector based on current FSM state and conditions.                                                                                                                                                                                                                                                                                    |
| `{if <condition> ...}`                     | <p>Conditional block.<br>Checks FSM state (<code>fsm\_tags</code>, <code>human\_fsm\_idle\_state</code>), semaphore status (<code>human\_fsm\_idle\_semaphore</code>), item interaction (<code>human\_stuff holding</code>), etc.<br>See: <a href="/animation/animation-system-for-actor/animation-selection-setup.md#conditions-in-the-animation-selector"><strong>Condition syntax reference</strong></a></p> |
| `{idle ...}`                               | <p>Defines what to execute if the condition is met. Typically includes a <code>run</code> command to call the Animation Selector.<br>May also include optional <code>state</code> and <code>semaphore</code> parameters.</p>                                                                                                                                                                                    |
| `run "<request_name>"`                     | <p>Triggers the specified request, which is then handled in <code>animation\_selector/human.set</code>.<br>Example: <code>run "stand\_smoking\_begin"</code> will use that request name to find matching animations.<br>An empty string means no new animation is triggered and the current one continues playing.</p>                                                                                          |

{% hint style="info" %}
When an empty request is triggered, the actor remains still for a short time, after which the request selection restarts.
{% endhint %}

### Idle states

In **Men of War II**, two idle states are used:

* `idle` — plays regular idle animations
* `smoking` — plays smoking animations

{% hint style="danger" %}
To enable idle animation selection for a state that didn’t previously support it, FSM logic must be extended to include idle handling.
{% endhint %}

### Semaphores in the **Idle Request Selector**

Semaphores are used to control the frequency and conditions under which specific requests can be triggered.\
They provide time-based restrictions that prevent all units from animating in sync.

> **Semaphore syntax**
>
> ```c
> {semaphore "<semaphore_name>" N}
> ```
>
> * `N` is the lock time in seconds

Semaphore states:

* **unlocked** — `N = 0`
* **locked** — for the specified time `N`

{% hint style="success" %}
Using two values for semaphore lock time is recommended to introduce random duration, promoting natural variation in unit behavior and avoiding synchronized animations.
{% endhint %}

{% hint style="info" %}
New semaphores are defined inside the `init` block
{% endhint %}

<details>

<summary>Idle request semaphores used in <strong>Men of War II</strong></summary>

<table><thead><tr><th width="176.09765625">Semaphore Name</th><th>Description</th></tr></thead><tbody><tr><td><code>can_smoke</code></td><td>Controls whether the smoking cycle can begin. While this semaphore is locked, the unit cannot trigger the request <code>stand_smoking_begin</code>. It is locked after each cigarette and unlocked after a random delay (e.g., 5–10 or 60–120 seconds).</td></tr><tr><td><code>can_inhale</code></td><td>Controls the interval between inhales during smoking. Used within the <code>smoking</code> state to determine when the <code>stand_smoking_process</code> request can be triggered. It is locked for a few seconds after each inhale.</td></tr><tr><td><code>can_action</code></td><td>Allows the execution of active idle behaviors (e.g., scratching, shifting weight). While locked, the unit will only play neutral idle animations such as <code>stand_breath</code>, <code>squat_breath</code>, or <code>lie_breath</code>. The lock controls the frequency of animation changes.</td></tr><tr><td><code>stop_smoking</code></td><td>Restricts the ability to end the smoking cycle. While active, the request <code>stand_smoking_end</code> will not be triggered. This is used to ensure a minimum duration in the <code>smoking</code> state to make smoking appear realistic.</td></tr></tbody></table>

</details>

<details>

<summary><strong>Example:</strong> Using semaphores in the <strong>Idle Request Selector</strong></summary>

```c
{init
	{state "idle"}
	{semaphore "can_smoke" 10 30} ; don't smoke right away
	{semaphore "can_inhale" 3 5}
	{semaphore "can_action" 5 15} ; start from breathing
}
{selector
	[...]
	{idle
		{run "stand_smoking_begin"} ; request to animation_selector/human.set
		{state "smoking"} ; change FSM state
		{semaphore "stop_smoking" 20 40} ; lock completion for 20–40 sec
		{semaphore "can_inhale" 3 5} 
	}
	[...]
}
```

Explanation

**`init` block**

* `{state "idle"}`\
  Sets the unit’s initial FSM state to `idle`.
* `{semaphore "can_smoke" 10 30}`\
  Prevents the unit from starting the smoking cycle immediately. Smoking becomes available only after 10–30 seconds.
* `{semaphore "can_inhale" 3 5}`\
  Sets the delay before the first inhale, in case the unit starts smoking soon after spawning.
* `{semaphore "can_action" 5 15}`\
  Sets a pause before the unit can perform more active idle animations. While the semaphore is locked, only breathing idles will play.

**`idle` block**

* `{run "stand_smoking_begin"}`\
  Triggers the `stand_smoking_begin` request. It will be passed to `animation_selector/human.set`, where the appropriate smoking start animations will be selected.
* `{state "smoking"}`\
  Updates the FSM state to `smoking`, which affects future request selection and conditions.
* `{semaphore "stop_smoking" 20 40}`\
  Locks the `stop_smoking` semaphore for 20–40 seconds. While active, the unit will not trigger `stand_smoking_end`.
* `{semaphore "can_inhale" 3 5}`\
  Sets the pause before the next inhale (e.g., to allow `stand_smoking_process` in the next cycle).

</details>

### Conditions

Compound conditions in the **Idle Request Selector** use logical operators `and`, `or`, and `not`.

Conditions used with highest priority:

```
{if human_fsm_idle_semaphore "can_smoke"}
{if human_fsm_idle_state "smoking_begin"}
{if fsm_tags "board"}
```

<details>

<summary>Examples of conditions used in the Idle Request Selector</summary>

| Condition                               | Meaning                                                                                          |
| --------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `fsm_tags "board"`                      | Checks whether the FSM state has the `board` tag.                                                |
| `human_fsm_counter "forced_smoke" once` | <p>Checks the FSM counter <code>forced\_smoke</code>.<br>See: \[FSM Counter Check Reference]</p> |
| `human_stuff holding "nothing"`         | Checks that the actor is holding nothing in their hands.                                         |
| `human_fsm_idle_state "idle"`           | Checks the current FSM idle state.                                                               |
| `human_fsm_idle_semaphore "can_smoke"`  | Checks whether the specified semaphore is unlocked.                                              |
| `able "attention"`                      | Checks if the `attention` ability is available.                                                  |
| `not able "attention"`                  | Inverse check — confirms that `attention` is not available.                                      |

</details>

<details>

<summary>Example: Nested compound condition in Idle Request Selector</summary>

```
{if fsm_tags "up" 
    {if human_fsm_counter "forced_smoke" once and human_stuff holding "nothing" and human_fsm_idle_state "idle" 
        {idle [...]} 
    } 
} 
```

This example uses a two-level nested condition, where each sub-condition must be true for the idle block to be executed.

**First-level condition:** `{if fsm_tags "up"}`

This block is only evaluated if the unit’s FSM state includes the tag up — for example, standing, not in cover, and ready to act.

**Second-level condition**\
All three conditions must be met:

1. `human_fsm_counter "forced_smoke" once`\
   Checks the forced\_smoke counter:
   1. If the value is greater than 0 → returns true and resets the counter to 0;
   2. If the value is 0 → returns false.\
      This is used for one-time forced actions (consume and reset).
2. `human_stuff holding "nothing"`\
   Verifies that the unit is not holding any item or weapon. I\
   f the unit is holding something, the condition fails.
3. `human_fsm_idle_state "idle"`\
   Ensures that the current internal FSM idle state is `idle`.\
   Prevents conflicts — for example, avoids triggering the same request again if the unit is already smoking.

</details>

### Examples of Requests for Idle Animation Selection

The table below shows request names defined in the idle request selector and used with the `run` command.

{% hint style="info" %}
The `_idle` index in request names typically denotes more active idle behaviors,\
while the `_breath` index denotes breathing or subtle movement animations.
{% endhint %}

<table><thead><tr><th width="249.09375">Request name</th><th>Description</th></tr></thead><tbody><tr><td><p><code>stand_idle</code></p><p><code>stand_breath</code></p></td><td>Standing — idle or subtle breathing animation</td></tr><tr><td><p><code>squat_idle</code></p><p><code>squat_breath</code></p></td><td>Sitting idle</td></tr><tr><td><code>snipe_breath</code></td><td>Peeking over low cover (e.g., trench, waist-high fence)</td></tr><tr><td><p><code>lie_idle</code></p><p><code>lie_breath</code></p></td><td>Lying idle</td></tr><tr><td><code>stand_smoking_begin</code></td><td>Lighting a cigarette</td></tr><tr><td><code>stand_smoking_process</code></td><td>Inhaling</td></tr><tr><td><code>stand_smoking_end</code></td><td>Putting out the cigarette</td></tr></tbody></table>

{% hint style="info" %}
Custom animation requests can be defined and mapped in `human_idle.inc`
{% endhint %}