AnimationSystem
------------------------------------------------------------------------------
Soldier Animation System
------------------------------------------------------------------------------
Character:
human [custom]
Soldier animations are organized at the top level by a hierarchy of character types, each of which (except human, the root) inherit from
another character type in the hierarchy (default: human).
Examples of custom character types are 'bdroid', 'ewok', and so on.
Custom character types are generally distinguished from human by a custom skeleton, and allow the overriding of movement and action animations
independent of the weapon being used. Custom types may be defined in soldier ODFs using the SkeletonName or AnimationName tag.
Weapon:
rifle bazooka tool pistol grenade melee [custom]
Soldier animations are organized next by a hierarchy of weapon types, each of which (except rifle, the root) inherit from another weapon type in the
hierachy. For the predefined standard types, bazooka and tool inherit from rifle and pistol, grenade, and melee inherit from tool. Custom
weapons may be defined in weapon ODFs using the CustomAnimationBank or ComboAnimationBank tag and must specify either a standard type or a
previously defined custom type as their parent.
Examples of custom weapon types might be 'hanblaster' from 'pistol' or 'lukesaber' from 'melee'. Custom weapon types are useful for defining new
weapon animations while still inheriting a skeleton and movement animations independently based on character type.
Each weapon may or may not support alert states. For instance, bazooka and melee do not, since they are effectively always alert. Combo weapon
types also specify a combo file controlling the weapon FSM simulation and associated animation states.
Posture:
stand crouch prone standalert crouchalert pronealert
A soldier who is not playing action, custom, or override animations is always in one of the above postures. Alert postures are used for a few
seconds after playing a weapon_shoot* animation to avoid popping when shooting repeatedly.
Scope:
upper lower full
A soldier is divided into upper and lower parts which can be animated independently or together.
Animations:
Animations come in several types, but most have the following parameters:
Loop - does the animation loop when it completes.
Blend time - how long does the animation take to blend in when it begins.
Scope - if the animation does not override it, what parts of the soldier are affected by the animation.
Currently, loop and blend time are hard coded.
Weapon Animations:
shoot shoot2 shoot_secondary shoot_secondary2 charge reload
Weapon animations cover various weapon specific actions, and are named
<character>_<weapon>_<posture>_<anim>[_<scope>]. For example, human_bazooka_stand_reload.
<posture> does not include alert postures for weapon animations - weapon
animations are effectively always alert.
<scope> defaults to 'upper' for all weapon animations, as they will generally be combined with movement animations on the lower body. A
weapon animation that overrides this to 'full' by being named, for instance, human_rifle_stand_shoot_full, will also have precedence over
idle movement animations on the lower body.
<loop> is false for all weapon animations.
<blend time> is 0.02s for shoot*, 0.5s for other weapon animations
Any weapon animations that are not directly defined for a character and weapon combination will inherit from other animations based on the
following rules, until a defined animation is found. For example, for bdroid_tool_crouch_shoot2:
1) from <character parent>_<weapon>_<posture>_<anim>, i.e.
from human_tool_crouch_shoot2
2) for shoot* anims, from shoot or shoot2 or shoot3, i.e.
from bdroid_tool_crouch_shoot, bdroid_tool_crouch_shoot3
3) for posture 'crouch', from <character>_<weapon>_stand_<anim>, i.e.
from bdroid_tool_stand_shoot2 (this is to support grenades/melee)
4) from <character>_<weapon parent>_<posture>_<anim>, i.e.
from bdroid_rifle_crouch_shoot.
Note that all inheritance actually happens character by character, and that rule 1 is applied for all weapons before rules 2-4 are applied. In
simpler terms, all human_* animations are resolved before bdroid attempts
to inherit from human, and all bdroid_tool_* animations inherit from human_tool_* before bdroid_grenade_* attempts to inherit from them.
Additional rules for inheritance are defined in specific cases -
See SoldierAnimatorClass.cpp::_PostLoad() for the details, which have become complicated...
After the inheritance rules have been applied, all animations except must be defined for the upper body, and no animations must be defined for
the lower body. Weapons without a charge state do not need a charge animation, and weapons without reload do not need a reload animation.
The inheritance rules allow for only one of the shoot* animations being defined, and for crouch animations being undefined, since they default
to stand posture.
Movement Animations:
idle_emote idle_checkweapon idle_lookaround(idle_takeknee)
turnleft turnright
walkforward runforward walkbackward runbackward
walkright runright walkleft runleft
Movement animations cover various turning and walking actions, and are named <character>_<weapon>_<posture>_<anim>[_<scope>]. For example,
bdroid_tool_prone_idle_checkweapon.
<posture> may include alert animations for weapons that support them.
<scope> defaults to 'full' for human_rifle_*, to 'lower' for turn*
animations, and to 'upper' for other animations.
<loop> is true for all animations except turn*.
<blend time> is 0.4 for prone/pronealert postures and 0.15 for others.
Any movement animations thate are not directly defined for a character and weapon combination will inherit from other animations based on the
following rules, until a defined animation is found. For example, for bdroid_tool_crouchalert_idle_lookaround:
0) for alert postures with weapons that do not support alert states, simply copy the final results from non alert posture.
1) from <character>_<weapon parent>_<posture>_<anim>, i.e. from bdroid_rifle_crouchalert_idle_lookaround. For alert postures,
weapons which support alert states inherit from the first parent which also supports alert states, skipping any that do not.
2) from <character parent>_<weapon>_<posture>_<anim>, i.e. from human_tool_crouchalert_idle_lookaround.
3) from <character>_<weapon>_<nonalert posture>_<anim>, i.e. from bdroid_tool_crouch_idle_lookaround
4) for human_*idle* and human_*turn* animations, from idle_emote then stand_idle_emote, i.e. human_tool_crouch_idle_checkweapon would
inherit from human_tool_crouch_idle_emote, then human_tool_stand_idle_emote.
Inheritance works as in weapon animations, with rules 0, 1 applied first.
Additional rules for inheritance are defined in specific cases -
See SoldierAnimatorClass.cpp::_PostLoad() for the details, which have become complicated...
After the inheritance rules have been applied, all idle animations must be defined for the full body, turn animations for the lower body. At least
one of walk/run must be defined for the full body for forward and backward.
If at least one of walk/run is defined for left and for right, the character will sidestep rather than twisting his body when moving left or
right. The inheritance rules also allow for idle_checkweapon and idle_lookaround being undefined.
Action Animations:
sprint
jump
jump_up
jump_forward
jump_backward
jump_left
jump_right
landsoft
landhard
fall
thrown_flail
thrown_flyingfront
thrown_flyingback
thrown_flyingleft
thrown_flyingright
thrown_tumblefront
thrown_tumbleback
thrown_bouncefrontsoft
thrown_bouncebacksoft
thrown_landfrontsoft
thrown_landbacksoft
thrown_restfrontsoft
thrown_restbacksoft
diveforward
jetpack_hover
stand_getupfront
stand_getupback
stand_getdown_prone
crouch_getdown_prone
prone_getup_stand
prone_getup_crouch
stand_death_forward
stand_death_backward
stand_death_left
stand_death_right
Action animations cover various full body transitions and special movements, and are named <character>_<weapon>_<anim>[_<scope>]. For
example, bdroid_tool_jump.
<scope> defaults to 'full' for human_rifle_*, and to 'upper' for others.
<loop> is true for thrown_flail, thrown_tumblefront, thrown_tumbleback, abd jetpack_hover, and false for all others.
<blendtime> is 0.8s for fall, 0.5s for thrown_flail, 0.4s for jump*, thrown_land*, 0.1s for thrown_tumble* and thrown_bounce*, 0.05s for
landsoft and landhard, and 0.15s for all others.
Any action animations that are not directly defined for a character and weapon combination will inherit from other animations based on the
following rules, until a defined animation is found. For example, for bdroid_tool_jump_up:
1) from <character>_<weapon parent>_<anim>, i.e. from bdroid_rifle_jump_up.
2) from <character parent>_<weapon>_<anim>, i.e. from human_tool_jump_up.
Inheritance works as in weapon animations, with rule 1 applied first.
Additional rules for inheritance are defined in specific cases - for instance, jump_* -> jump, sprint -> stand_runforward, jetpack_hover ->
jump, and so on. See SoldierAnimatorClass.cpp::_PostLoad() for the details, which have become complicated...
After the inheritance rules have been applied, all animations must be defined for the full body.
Combo Animations:
[custom]
Combo animation names are defined in combo files, along with data controlling their blend times, looping behavior, and so on.
Custom Animations:
[custom]
Custom animations generally cover various full body poses, generally used when piloting various vehicles, and are named either
<character>_<weapon>_<anim> or <character>_<anim>. For example, human_minigun_9pose or bdroid_ride_stap.
The names of these animations are defined in vehicle ODFs using one of the tags PilotAnimation, SoldierAnimation, or AttachTrigger (used by
Sarlacc Technology (TM)).
Custom animations are always full body and do not support _<scope>.
Custom animations also do not loop or blend.
Any custom animations that are not directly defined for a character and weapon combination will inherit from other animations based on the
following rules, until a defined animation is found. For example, for bdroid_tool_stap_ride:
0) from <character>_<weapon parent>_<anim>, i.e. from bdroid_rifle_stap_ride.
1) from <character>_<anim>, i.e. from bdroid_stap_ride.
2) from <character parent>_<weapon>_<anim>, i.e. from human_tool_stap_ride.
Inheritance works as in weapon animations, with rules 0, 1 applied first.
After the inheritance rules have been applied, all custom animations must be defined for every character.
------------------------------------------------------------------------------
Soldier Low Resolution Animation System
------------------------------------------------------------------------------
Character:
humanlz [custom]
Low res animation banks are separated by character type. Custom types default to inheriting from humanlz, but may specify an alternate parent
if it is already defined. Examples of custom types are bdroidlz, and ewoklz.
Animations:
rifle_stand_idle_emote rifle_crouch_idle_emote
[rifle_prone_idle_emote] rifle_stand_flail
rifle_jetpack_hover rifle_diveforward
rifle_stand_runforward rifle_stand_death_backward
Low res animations cover all possible lowres animation states, and are named <character>_<anim>, for example bdroidlz_rifle_stand_idle.
All are full body in scope. Any low res animations that are not defined for a character type inherit from the parent bank. All animations must
be defined in humanlz.
With the exception of runforward and death, all are single frame poses that may be shared by any number of low res soldiers.
Run animations use a pool of N (currently 3) looping animators, which can be shared - i.e. if there are more than 3 humanlz low res soldiers on
screen, they will begin to share poses.
Death animations use a pool of N (currently 8) unshared LRU non-looping animators. If there are more than 8 humanlz low res soldiers on screen
and dying, additional soldiers will take animators from the oldest animating soldier.
Combo Animations:
[custom]
Combo animation names are defined in combo files, along with data controlling whether the animation is reduced to a pose or not. The low res
animation system currently just uses the high res animations from the highres banks, applied to the low res skeleton - perhaps 10% performance could
be gained by converting these animations to the low res skeleton.
Combo animations use a special high res unshared pool of fixed size, similar to the death animation pool, unless they have been defined to use a single
frame pose, in which case they behave like a shared single pose anim.
Custom Animations:
[custom]
Low res custom animations work similarly to those for high res animation, except that there is no support for alternate weapons (the animation for
ride_stap must be named [bank]_ride_stap or [bank]_rifle_ride_stap.
------------------------------------------------------------------------------
Soldier First Person Animation System
------------------------------------------------------------------------------
Character:
humanfp droidekafp
First person animation banks are separated by character type, so that droideka animations will only be loaded when droideka are present on a
map. No custom types are supported currently.
Weapon:
rifle bazooka tool grenade (lascannon)
First person animations are grouped by weapon type. No custom weapon types are supported currently.
Animations:
idle run shoot shoot2 charge reload repair jump flail handsdown
First person animations cover all possible first person animation states, and are named humanfp_<weapon>_<anim>, with the exception of
handsdown, which is named humanfp_<handsdown>.
Droidekafp only contains four animations, idle, walk, shoot, and reload, but is otherwise similarly named (droideka_rifle_<anim>).
First person animations are loaded according to a hardcoded table. Some animations do not exist for some weapons and are hardcoded to load
alternates. Any animations which are not found will default to humanfp_tool_idle.
------------------------------------------------------------------------------
Animation System Data
------------------------------------------------------------------------------
Tools/Bin/ZenAsset.exe
Extracts the skeleton and animations from a set of msh files in a directory named basepose.msh and <anim>.msh, and outputs a ZAF file
containing the skeleton, a ZAA file containing the animations, and an ANIMS file containing a utfc format (text) list of animations in the ZAA.
Tools/Bin/BinMunge.exe
Converts ZAF and ZAA files to ZAFBIN, ZAABIN files used by the game, respectively.
Tools/Bin/OdfMunge.exe
Now generates requirements for individual animations, soldier animation sets, as well as for ZAABINs and ZAFBINs correctly.
Tools/Bin/LevelPack.exe
Now handles requirements for individual animations, soldier animation sets, as well as for ZAABINs and ZAFBINs correctly, using an updated
version of FILES table of content files.
Data/Animations
Contains all animation data used to build the ZAABIN, ZAFBIN, and ANIMS files used during the game munge process. Animations are built as a
separate munge process using the munge.bat in this directory, and the resulting files are checked into perforce in the appropriate munged
directory (Data/Common/munged, or Data/Sides/ALL/munged, for example).
Animations are broken down into subdirectories based on type:
SoldierAnimationBank/ for soldier animation banks and lowres animation banks
SoldierAddon/ for soldier addons like capes
FirstPerson/ for first person animation banks
Prop/ for world prop animations
Vehicle/ for vehicle animations
ZAFBIN files - contain a skeleton, possibly associated with a ZAABIN file of the same name.
ZAABIN files - contain a bank of animations.
ANIMS files - contains a text format (utfc) list of animations in a ZAA.
Data/Common/config/SoldierAnimation.SANM file A config format file containing data controlling the looping, blending,
and other animation properties of all standard high-res soldier animations.
See combo.txt for formatting information - the format is the same as Animation tags from that combo config files.
Soldier Animation Banks:
Soldier animation banks follow some specific additional rules.
Banks are expected to be named either <character> or <character>_<weapon>.
A bank is expected to only contain animations with names beginning with the bank name, i.e. bdroid.zaabin should contain animations matching
bdroid_*, and human_melee.zaabin should only contain animations matching human_melee_*. A bank may consist of only a skeleton (zafbin), or may
also contain override animations.
Any bank may additionally be broken into multiple parts in order to deal with the size limitation imposed by the in game loader. The
resulting parts must be named with an appended '_0', '_1', and so on.
human.zaabin, for instance, is split into human_0 through human_4.
Only human_0's associated skeleton (zafbin) is required at load time.
ODF Properties -
Soldier ODFs:
AnimationName = "<character> [<parent>]"
SkeletonName = "<character> [<parent>]"
AnimationName and SkeletonName are synonyms.
If no property is found, <character> defaults to 'human'.
<parent> defaults to 'human'.
Specifies a custom skeleton and possibly animation bank to use for this soldier and its place in the character hierarchy.
Generates a requirement for <character>.zafbin and optionally for <character>.zaabin.
ex. SkeletonName = "wookie"
AnimationLowRes = "<character>"
SkeletonLowRes = "<character>"
AnimationLowRes and SkeletonLowRes are synonyms.
If no property is found, <character> defaults to 'humanlz'.
Specifies a custom low res skeleton and possibly animation bank to use for this soldier.
Generates a requirement for <character>.zafbin and optionally for <character>.zaabin.
ex. SkeletonLowRes = "wookielz"
Weapon ODFs:
AnimationBank = "[<character>_]<weapon>"
<character>_ defaults to 'human_'.
Specifies the weapon type used by this weapon for animation, which must either be a standard type or a type previously defined
with CustomAnimationBank (see below).
At run time, <character> is ignored, since the character type is based on the soldier wielding the weapon.
Generates a requirement for <character>_<weapon>_* animations which requires a zaabin containing the given animations. If the
animations in question are in a weapon specific bank, i.e. gam_melee_* to be found in gam_melee.zaabin, it is useful to
specify <character> in order to generate the correct requirement.
ex. AnimationBank = "rifle"
CustomAnimationBank="[<character>_]<weapon> <parent> [alert|noalert]"
Defines a custom weapon type used by this weapon for animation and its relationship to the weapon hierarchy.
<character>_ defaults to 'human_'.
<parent> must either be a standard type or a type previously defined with CustomAnimationBank.
If alert or noalert is specified, the weapon will either support alert postures or not. If not specified, it will inherit the
alert support of its parent weapon.
At run time, <character> is ignored, since the character type is based on the soldier wielding the weapon.
Generates a requirement for <character>_<weapon>_* animations which requires a zaabin containing the given animations. If the
animations in question are in a weapon specific bank, i.e. gam_melee_* to be found in gam_melee.zaabin, it is useful to
specify <character> in order to generate the correct requirement.
ex. CustomAnimationBank = "leia_pistol pistol alert"
ComboAnimationBank="[<character>_]<weapon> <parent> <combofile>"
Defines a custom melee weapon that uses a combo file to control the weapon simulation and animations, and its relationship to
the hierarchy.
<character>_ defaults to 'human_'.
<parent> must either be a standard type or a type previously
defined with CustomAnimationBank/ComboAnimationBank.
At run time, <character> is ignored, since the character type is based on the soldier wielding the weapon.
Generates a requirement for <character>_<weapon>_* animations which requires a zaabin containing the given animations. If the
animations in question are in a weapon specific bank, i.e. human_sabre_* to be found in human_sabre.zaabin, it is useful to
specify <character> in order to generate the correct requirement.
Also generates a requirement for <combofile>.combo.
ex. ComboAnimationBank = "human_sabre melee all_hero_lukejedi"
Other ODFs:
AnimationName = "<bankname>"
Specifies a skeleton and possibly a bank of animations to use for this object.
Generates a requirement for <bankname>.zafbin and optionally for <bankname>.zaabin.
...Animation = "<animname>"
Specifies a specific animation to be found in an already loaded animation bank.
Generates a requirement for an animation named <animname>.
Controllable ODFs:
PilotAnimation = "<animname>"
Defines a custom soldier animation <animname>.
Generates a requirement for a soldier animation named 'human_<animname>'.
OrdnanceGrapplingHook/WeaponAreaEffect ODFs:
SoldierAnimation = "<animname>"
Defines a custom soldier animation <animname>.
Generates a requirement for a soldier animation named 'human_<animname>'.
EntityPropAnimated ODFs:
AttachTrigger = "<name> <...> <animname> <soldier_animname> ..."
Defines a custom soldier animation <soldier_animname>.
Generates a requirement for an animation '<animname>' and a soldier animation named 'human_<soldier_animname>'.