United Offensive animation reference
=====================================

.. meta::
   :description: Source-derived reference for stock Call of Duty: United Offensive animation trees, the multiplayer player animation script, and the AI animation scripts.
   :keywords: call of duty, united offensive, cod uo, animation, animtree, atr, playeranim, animscripts, gsc

Status and authority
--------------------

This reference describes the three animation layers used by stock Call of
Duty: United Offensive multiplayer:

* ``animtrees/*.atr`` animation trees;
* ``mp/playeranim.script``, the player animation table;
* ``animscripts/*.gsc``, the AI animation behavior scripts.

The animation-tree format and the player animation script are specified from
the recovered stock source in the ``coduomp`` project.  The AI animation
scripts are documented from the stock script corpus.  The recovered source
does not contain the implementations of the animation methods those scripts
call, so their call forms are recorded as observed usage, not as recovered API
contracts.

No online reference, later Call of Duty dialect, or compatibility extension is
used as an authority.  A behavior which the recovered source and the stock
corpus do not establish is not generalized from another engine.

How the three layers fit together
---------------------------------

Each layer answers a different question.

.. list-table::
   :header-rows: 1
   :widths: 28 42 30

   * - Layer
     - Answers
     - Stock location
   * - Animation tree
     - Which animation names exist, how they nest, and which ones play in
       sync.
     - ``animtrees/<name>.atr``
   * - Player animation script
     - Which animations a player body part plays for a state, move type,
       condition, or event.
     - ``mp/playeranim.script``
   * - AI animation scripts
     - How an AI actor sequences animation calls for a behavior.
     - ``animscripts/*.gsc``

The tree is the naming layer.  A leaf node names an ``xanim`` asset.  A parent
node groups leaves and other parents.  Neither the player animation script nor
an AI script can play an animation that the selected tree does not define.

The player animation script is a condition table.  It selects a tree node for
the player's current state, movement, weapon, stance, and similar conditions.
The engine evaluates the table for the player and drives the player's legs and
torso.

The AI animation scripts are ordinary GSC behavior scripts.  They select an
animation tree, then issue animation method calls on an AI actor or a turret.
They also maintain a small animation state model in GSC variables, such as
``self.anim_pose`` and ``self.anim_movement``.

Which file to edit
------------------

.. list-table::
   :header-rows: 1
   :widths: 38 62

   * - Change
     - File
   * - Add, rename, group, or sync an animation name.
     - ``animtrees/<tree>.atr``, plus the referenced ``xanim`` asset.
   * - Change which player animation plays for a weapon, stance, or event.
     - ``mp/playeranim.script``.
   * - Change how an AI actor walks through a behavior.
     - The relevant ``animscripts/*.gsc`` file.
   * - Add a turret-specific animation set.
     - A narrow tree such as ``mg42.atr`` or ``30cal.atr``, plus the turret
       AI script that calls ``UseAnimTree``.
   * - Make several animations stay in phase.
     - A ``loopsync`` or ``nonloopsync`` parent in the ``.atr`` file.

Scope and limits
----------------

This reference covers the stock United Offensive multiplayer files recovered
for this documentation:

* ``animtrees/`` contains 131 ``.atr`` files in the supplied corpus, plus an
  identical ``.atr.txt`` copy of one tree.
* ``animscripts/`` contains 67 ``.gsc`` files in the supplied corpus.
* ``mp/playeranim.script`` is the 1,780-line file from ``pakuo01.pk3``.

The supplied AI corpus is a superset of the stock ``pakuo00.pk3`` set.  It
includes map-specific behavior scripts that are not in the base package.
Statements about the corpus therefore describe the supplied files, not a
minimal stock installation.

The recovered source establishes the tree parser, the tree runtime, the player
animation table parser, and the player animation playback paths.  It does not
establish the AI animation method implementations, the AI behavior selector,
or the notetrack definitions inside ``xanim`` assets.  Those gaps are named
where they matter.

This reference does not cover single-player animation data, later Call of Duty
titles, custom content, or the content pipeline that produces ``xanim``
assets.

.. toctree::
   :maxdepth: 1

   animtrees
   player_animation_script
   ai_animation_scripts