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.

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

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.

Example: Direct Animation Selection

{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.

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.

Example: Random Animation Selection by Weigh

{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).

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> [...]}
    ...
}

Parameter	Description
<counter_name>	The name of the counter that determines the current switch state.
common	(Optional) Base animation set copied into each pick block before it is applied.
pick <N>	A pick option. The value N means this pick is used for N consecutive counter values.

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.

If common is not defined, all animation sets are taken directly from each pick.

Example: Counter-based Animation Selection

{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)

Step	Value (counter pose )	Pick block used	Animation Behavior
1	0	First pick	Uses animations from common (no overrides)
2	1	Second pick	Overrides aim and fire from common
3	2	Second pick	Same as step 2
4	3	Third pick	Adds idle, inherits aim and fire from common
5	4	Fourth pick	Replaces idle, retains aim and fire from common
6	5 → reset to 0	First pick	Loop restarts

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
    [...]
}

In the idle-selector, logical operators like and , not and or are also supported in compound conditions.

Conditions can be nested.

Syntax of Nested Conditions

{if cond1   
    {if cond2
        {anm "animation_1"}
    }
    {anm "animation_2"}
}