Battlefront-1-And-2-Assets/Other/000_Notes/AnimationSystem.txt

500 lines
22 KiB
Plaintext
Raw Normal View History

------------------------------------------------------------------------------
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>'.