# 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="/pages/Ap4atTpYWVJYwkRJyI8L#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**&#x20;

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.&#x20;

**First-level condition:** `{if fsm_tags "up"}`&#x20;

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.&#x20;

**Second-level condition** \
All three conditions must be met:&#x20;

1. `human_fsm_counter "forced_smoke" once` \
   Checks the forced\_smoke counter:&#x20;
   1. If the value is greater than 0 → returns true and resets the counter to 0;&#x20;
   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.&#x20;
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 %}


---

# 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/configuring-idle-for-human-actor.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.