------------------------------------------------------------------------------ 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 ___[_]. For example, human_bazooka_stand_reload. does not include alert postures for weapon animations - weapon animations are effectively always alert. 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. is false for all weapon animations. 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 ___, 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 __stand_, i.e. from bdroid_tool_stand_shoot2 (this is to support grenades/melee) 4) from ___, 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 ___[_]. For example, bdroid_tool_prone_idle_checkweapon. may include alert animations for weapons that support them. defaults to 'full' for human_rifle_*, to 'lower' for turn* animations, and to 'upper' for other animations. is true for all animations except turn*. 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 ___, 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 ___, i.e. from human_tool_crouchalert_idle_lookaround. 3) from ___, 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 __[_]. For example, bdroid_tool_jump. defaults to 'full' for human_rifle_*, and to 'upper' for others. is true for thrown_flail, thrown_tumblefront, thrown_tumbleback, abd jetpack_hover, and false for all others. 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 __, i.e. from bdroid_rifle_jump_up. 2) from __, 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 __ or _. 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 _. 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 __, i.e. from bdroid_rifle_stap_ride. 1) from _, i.e. from bdroid_stap_ride. 2) from __, 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 _, 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 high res 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__, with the exception of handsdown, which is named humanfp_. Droidekafp only contains four animations, idle, walk, shoot, and reload, but is otherwise similarly named (droideka_rifle_). 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 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 .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, and 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 or _. 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 = " []" SkeletonName = " []" AnimationName and SkeletonName are synonyms. If no property is found, defaults to 'human'. 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 .zafbin and optionally for .zaabin. ex. SkeletonName = "wookie" AnimationLowRes = "" SkeletonLowRes = "" AnimationLowRes and SkeletonLowRes are synonyms. If no property is found, defaults to 'humanlz'. Specifies a custom low res skeleton and possibly animation bank to use for this soldier. Generates a requirement for .zafbin and optionally for .zaabin. ex. SkeletonLowRes = "wookielz" Weapon ODFs: AnimationBank = "[_]" _ 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, is ignored, since the character type is based on the soldier wielding the weapon. Generates a requirement for __* 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 in order to generate the correct requirement. ex. AnimationBank = "rifle" CustomAnimationBank="[_] [alert|noalert]" Defines a custom weapon type used by this weapon for animation and its relationship to the weapon hierarchy. _ defaults to 'human_'. 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, is ignored, since the character type is based on the soldier wielding the weapon. Generates a requirement for __* 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 in order to generate the correct requirement. ex. CustomAnimationBank = "leia_pistol pistol alert" ComboAnimationBank="[_] " Defines a custom melee weapon that uses a combo file to control the weapon simulation and animations, and its relationship to the hierarchy. _ defaults to 'human_'. must either be a standard type or a type previously defined with CustomAnimationBank/ComboAnimationBank. At run time, is ignored, since the character type is based on the soldier wielding the weapon. Generates a requirement for __* 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 in order to generate the correct requirement. Also generates a requirement for .combo. ex. ComboAnimationBank = "human_sabre melee all_hero_lukejedi" Other ODFs: AnimationName = "" Specifies a skeleton and possibly a bank of animations to use for this object. Generates a requirement for .zafbin and optionally for .zaabin. ...Animation = "" Specifies a specific animation to be found in an already loaded animation bank. Generates a requirement for an animation named . Controllable ODFs: PilotAnimation = "" Defines a custom soldier animation . Generates a requirement for a soldier animation named 'human_'. OrdnanceGrapplingHook/WeaponAreaEffect ODFs: SoldierAnimation = "" Defines a custom soldier animation . Generates a requirement for a soldier animation named 'human_'. EntityPropAnimated ODFs: AttachTrigger = " <...> ..." Defines a custom soldier animation . Generates a requirement for an animation '' and a soldier animation named 'human_'.