500 lines
22 KiB
Plaintext
500 lines
22 KiB
Plaintext
------------------------------------------------------------------------------
|
|
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 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_<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 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, 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 <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>'.
|