Animstable / Archetype in BO3

Animstable / Archetype in BO3

• Archetypes(AI) within BO3 are mainly composed of four different external AI assets, a behavior tree, an animation state machine, an animation selector table, and an animation map.

• Behavior Tree Holds the overall logic of how an AI acts, eventually deciding which animation state the AI should be in to act out the desired behavior. At the end of any behavior tree evaluation an animation state much be selected, otherwise the behavior tree is in an invalid state.
  
• Animation State Machine – Holds the overall structure of how an AI should animate including main substates as well as transitions between substates. The running animation state machine is responsible for playback of animations but is not responsible for actual animation selection.
  
• Animation Selector Table – Holds database style tables used to select an animation alias based on the AI’s current blackboard state. When queried from an Animation State Machine, the selector table may return zero or more possible animation aliases, depending on table type and usage.
  
• Animation Map – Holds a lookup between an animation alias and one or more actual xanim assets. Each xanim asset mapped to a single animation alias should be equivalent in behavior. Multiple animations can exist per alias to allow for variety.
  

Each of the four assets is based on a layering system, where higher layers reference lower layers, but not vice versa. Behavior trees, ai_bt files, are the highest layer within the system and reference names of animation substates within animation state machine files, ai_asm. Animation state machines are the next layer and reference names of individual animation selector tables within an ai_ast file. Animation selector tables reference individual animation aliases within animation mapping files, ai_am and finally, animation mapping tables reference actual xanim asset names.
Going forward I’ll use the zm_factory_zombie_dog AI as an example of how these mapping work. Below are the four files I will be referencing.

share/raw/animstatemachines/zm_factory_zombie_dog.ai_asm
share/raw/animtables/zm_factory_zombie_dog.ai_am
share/raw/animtables/zm_factory_zombie_dog.ai_ast
share/raw/behavior/zm_factory_zombie_dog.ai_bt

Let’s start with simulating a behavior selection within the behavior tree, say we shot our zombie dog and selected the “DeathBehavior” accordingly. You’ll see an ASMStateName associated with the action node of one of the children of this behavior. In this case the ASMStateName is “death@zombie_dog”. This particular name is important because it conveys the substate and state name. In this case we’re choosing the substate “death” and state “zombie_dog” within the animation state machine.

{
    "type": "sequence",
    "id": "DeathBehavior",
    "children": [
        {
            "type": "condition_script",
            "id": "wasKilled",
            "interruptName": "death"
        },
        {
            "type": "action",
            "id": "defaultAction",
            "ActionName": "defaultAction",
            "ASMStateName": "death@zombie_dog",
            "TerminateFunction": "startRagdoll",
            "loopingAction": 0,
            "actionTimeMax": 0,
            "actionNotify": "death"
        }
    ]
}

Typically, the convention for ASM naming is as follows

• substate_name@state_name
• substate_name@state_name>state_name_2
• substate_name@state_name>substate_name_2@state_name

The use of the “>” symbol indicates a transition; within our ASM architecture you can have a transition to another substate only if that substate is within the same state as your current substate is. For instance, substate1@state1>substate2@state1 is legal, but substate1@state1>substate2@state2 is illegal. In these cases, you can only have a transition between the state itself, ex: substate1@state1>state2. Going back to the behavior tree for a moment, transitions in particular cannot be selected by the behavior tree’s “AsmStateName” field. The Animation State Machine will automatically handle a transition based on the Animation State Machine’s current substate, and the requested new substate from the Behavior Tree.
Once we’ve selected an animation substate within the ai_asm file we’ll eventually arrive to an “animation_selector” field. For the death@zombie_dog substate this field happens to be “death@zombie_dog”. By convention we name our animation selector tables based on which substate is using them, but this is not a required convention by the engine.

{
    "states": {
        ...
        "zombie_dog": {
            "substates": {
                "death": {
                    "animation_selector": "death@zombie_dog",
                    "terminal": true
                }
                ...
            }
        ...
    }
}

Now that we have an animation selector table name we’ll reference that particular table within the ai_ast file. Since the ai_ast file is a csv you’ll see the animation selector table name in the first row of the table, followed by the column names used by the table in the next row, ending with any number of rows representing possible selections following that. The death@zombie_dog animation selector table has a number of possible death animation selections which use the “_damage_direction” blackboard attribute for determining which row meets the necessary criteria.

death@zombie_dog,
_damage_direction,_blend_in_time,_blend_out_time,_animation_alias,_animation_mocomp,
FRONT,0.1,0,anim_death_front,mocomp_death@exposed,
BACK,0.1,0,anim_death_back,mocomp_death@exposed,
LEFT,0.1,0,anim_death_left,mocomp_death@exposed,
RIGHT,0.1,0,anim_death_right,mocomp_death@exposed,
*,0.1,0,anim_death_front,mocomp_death@exposed,

Let’s say our zombie dog got shot in the back and we selected the row with the “_animation_alias” value of “anim_death_back”. Now that we have an animation alias selected we can look up which actual animation asset to playback within our animation map. In this case there is only a single xanim entry for anim_death_back so we finally select the “ai_zombie_base_dog_death_hit_back” animation for playback.

#
anim_death_back,ai_zombie_base_dog_death_hit_back
anim_death_front,ai_zombie_base_dog_death_front,ai_zombie_base_dog_death_front_a
anim_death_left,ai_zombie_base_dog_death_hit_left
...

Credits

Treyarch