Animstable / Archetype in BO3

From COD Modding & Mapping Wiki
Jump to: navigation, search

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.


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 “[email protected]_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": "[email protected]_dog",
            "TerminateFunction": "startRagdoll",
            "loopingAction": 0,
            "actionTimeMax": 0,
            "actionNotify": "death"

Typically, the convention for ASM naming is as follows

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, [email protected]>[email protected] is legal, but [email protected]>[email protected] is illegal. In these cases, you can only have a transition between the state itself, ex: [email protected]>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 [email protected]_dog substate this field happens to be “[email protected]_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": "[email protected]_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 [email protected]_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.

[email protected]_dog,
FRONT,0.1,0,anim_death_front,[email protected],
BACK,0.1,0,anim_death_back,[email protected],
LEFT,0.1,0,anim_death_left,[email protected],
RIGHT,0.1,0,anim_death_right,[email protected],
*,0.1,0,anim_death_front,[email protected],

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.