Frame commands
Introduction
Each animation can have commands attached. These are either global (they influence the entire animation), or per-frame (they do something at the frame with the given number).
Apart from the default D3 frame commands, the darkmod team has added a few new, useful frame commands. This page tries to describe them all.
Animation Primer
In animation, there are some important concepts:
Channel
This is the channel the animation plays on, usually LEGS, TORSO, HEAD and so on. Animations can play on one channel, or on multiple channels at the same time. Different channels can also play different animations at the same time.
Override
Override means that the overridden channel is forced to play the same anim as the originating channel, i.e. LEGS is forced to run the same anim as TORSO. This is usually meant as "idle override" => if the HEAD animation channel is currently idle, it is overridden by the anim played on TORSO.
Synchronizing
Synchronizing is meaning two different things, it ensures that two channels are in sync with each other (such that the hands of the TORSO channel are matching the LEGS movement, like one would expect it when observing the AI - we had a bug report of that back when we implemented the walk animation for the new skeleton), and secondly it is deactivating the framecommands on the channel being synchronized, to prevent double-firing of anim frame commands.
How to use
You need an animation in the md5anim format, and a definition for your AI, which must be placed in the model defitinion of your AI. Here is an example from model tdm_ai_proguard defined inside def/tdm_ai_guard_proguard_devel.def:
anim throw_dice01 models/md5/chars/guards/proguard/throw_dice.md5anim { no_random_headturning frame 17 sound tdm_dice_click frame 19 create_missile RightHand frame 19 attach atdm:drop_dice01 dice01 hand_r frame 71 sound tdm_dice_shaking frame 81 sound tdm_dice_shaking frame 119 destroy dice01 frame 119 launch_missile RightHand frame 122 sound tdm_dice_rolling frame 144 sound_voice snd_reaction }
Default Doom3 frame commands
Command | Description | Example |
---|---|---|
call | calls a global script function | frame 1 call overrideLegs
|
object_call | calls a script object function | frame 1 object_call ArrowInvisible
|
event | Calls an event function | Unused so far
|
sound | Plays the referenced sound shader on the general sound channel. | frame 12 sound readable_page_turn
|
sound_voice | Plays the referenced sound shader on the voice sound channel. | frame 23 sound_voice snd_sight
|
sound_voice2 | Plays the referenced sound shader on the second voice sound channel. | frame 1 sound_voice2 monster_boss_vagary_attack1
|
sound_body | Plays the referenced sound shader on the body sound channel. | frame 50 sound_body snd_footstep
|
sound_body2 | Plays the referenced sound shader on the second body sound channel. | frame 92 sound_body2 snd_footstep
|
sound_body3 | Plays the referenced sound shader on the third body sound channel. | Not used so far, but similiar to sound_body
|
sound_weapon | Plays the referenced sound shader on the weapon sound channel. | frame 16 sound_weapon snd_drawsword
|
sound_global | Plays the referenced sound shader on the global sound channel. | Not used so far, but similiar to sound_body
|
sound_item | Plays the referenced sound shader on the item sound channel. | Not used so far, but similiar to sound_body
|
sound_chatter | Plays the referenced sound shader on the chatter sound channel. | frame 57 sound_chatter snd_alert_idle
|
skin | Sets a new skin for the model. Skin name is optional, if left off, no skin (e.g. the default skin) is used. | frame 1 skin tdm_burnt_flesh
|
fx | Plays the named fx (effect combining particle, sound and light). | Not used so far
|
trigger | Triggers the given target (e.g. activates it). | Not used so far
|
triggerSmokeParticle | Triggers the named particle (which can be everything, not just smoke). | frame 1 triggerSmokeParticle smokestack
|
melee | Starts melee action? | frame 9 melee melee_elemental_fire
|
direct_damage | Does direct damage to the target entity. | Not used so far.
|
muzzle_flash | Used to flash the weapon muzzle. | Not used so far.
|
attack | Attack the named entity. | Not used so far.
|
attack_begin | Begin an attack. | Not used so far.
|
attack_end | Stop an attack. | Not used so far.
|
create_missile | Create (in the def specified) missile at the given attachment position. | frame 2 create_missile RMissile
|
launch_missile | Launches a missile from the given attachment position. | frame 16 launch_missile LeftHand
|
fire_missile_at_target | Fires a missile at the target. | Not yet used.
|
footstep | Unknown. | frame 12 footstep
|
leftfoot | Unknown. | frame 12 leftfoot
|
rightfoot | Unknown. | frame 12 rightfoot
|
enableEyeFocus | Unknown. |
|
disableEyeFocus | Unknown. |
|
disableGravity | Gravity no longer affacts this model. |
|
enableGravity | Gravity affacts this model again. |
|
jump | Makes it jump. |
|
enableClip | Unknown |
|
disableClip | Unknown |
|
enableWalkIK | Unknown |
|
disableWalkIK | Unknown |
|
enableLegIK | Unknown |
|
recordDemo | Unknown |
|
aviGame | Unknown |
|
TDM frame commands
Keyword | Description | Version | Example |
---|---|---|---|
setRate | Sets the anim rate, used for speeding up/slowing down walking and crouchwalking animations to get correct footstep sounds. | v1.00 + |
|
reattach | Move an attachment to a different position. Used f.i. to move the weapon from the back to hand. | v1.00 + | frame 16 reattach melee_weapon hand_r
|
pause | Pause the animation at its current frame, wait for unpause from somewhere else. | v1.00 + | Not used yet.
|
melee_hold | Holds a melee attack at a given point in the animation (e.g., at the back swing in attacks, at the parry position in parries). Similar to pause but also updates actor's melee status. | v1.00 + | frame 6 melee_hold
|
melee_attack_start | v1.00 + | frame 16 melee_attack_start melee_weapon slash_rl
| |
melee_attack_stop | v1.00 + | frame 16 melee_attack_stop weapon
| |
melee_parry_start | v1.00 + | frame 5 melee_parry_start melee_weapon left
| |
melee_parry_stop | v1.00 + | frame 5 melee_parry_stop melee_weapon
| |
set_combat_flag | v1.00 + | frame 16 set_combat_flag melee
| |
clear_combat_flag | v1.00 + | frame 16 clear_combat_flag melee
| |
attach | Spawns an entity of the given class and attaches it with the given attach name on the given attach position. | v1.02 + | frame 42 attach atdm:prop_single_card card hand_r
|
destroy | Detach and destroy the entity at the named attachment. Usually used after attach. | v1.02 + | frame 42 destroy card
|
drop | Detach and drop to world the entity at the named attachment. Usually used after pickup. | v1.02 + | frame 42 drop bucket
|
pickup | Find the entity with the given name, then attach it as the named attachment at the given position. See this article for more information. | v1.02 + | frame 42 pickup atdm_water_bucket_01 bucket hand_l
|
putdown | Detach and drop to world the entity at the named attachment, and restore the original position and angle it had at time of pickup. (If you use "putdown" on an entity that was created via spawn, it will simply drop to the floor). | v1.02 + | frame 80 putdown bottle
|
activate_at_joint | Activate the entity attached to the given joint. | v1.02 + | frame 42 activate_at_joint hand_r
|
activate_near | Find the entity with the given name, near (attached or not) the given joint, then activate it. See this article for more information. | v1.02 + | frame 42 activate_near hand_r
|
create_missile_from_def | Create a specific projectile at the given joint name. The projectile entityDef name must be passed as first argument, the joint name as second argument. | v1.04 + | frame 10 create_missile_from_def atdm:projectile_firearrow LeftHand
|