dao::animation
How long animations, attacks and abilities take a creature to play.
Declared in dao/Animation.h.
Classes
| Class | |
|---|---|
| Ability | The lengths of an ability’s animations for one creature, in seconds. |
| Shot | The three parts of a shot with a bow, a crossbow or a staff, in the order they play, in seconds. |
Functions
AimDuration()
std::optional<float> AimDuration(ObjectId creature)
Returns the aim time the scripts have set for a creature’s shot with SetAimLoopDuration: how long the shot holds its aim before the Fire animation.
Like the attack time, it is set only while an attack is under way. A staff’s has been 0.1 s; a bow’s can be none.
Returns seconds; nullopt if none is set or the creature is not loaded
AttackDuration()
std::optional<float> AttackDuration(ObjectId creature)
Returns the attack time the scripts have set for a creature’s attack with SetAttackDuration.
The scripts set it for a humanoid with a weapon once the attack has been rolled, during the attack, and the game clears it as the attack ends, so it is set only while an attack is under way. A melee attack with it set takes about that long; one without it takes about four fifths of its animation’s Length. For a shot it is the time of the Aim animation alone (OfShot).
Returns seconds; nullopt if none is set or the creature is not loaded
Length()
std::optional<float> Length(ObjectId creature, std::int32_t animation)
Returns how long one of a creature’s animations lasts.
An action timed by its animation ends at about four fifths of this length, where it blends into the next one. A bow’s shot does not follow kAttack’s length; OfShot gives a shot’s.
| Parameter | |
|---|---|
animation |
a row of the anim_ tables (anim_combat for attacks) |
Returns the length in seconds; nullopt if the creature is not loaded or lacks the animation
OfAbility()
Ability OfAbility(ObjectId creature, std::int32_t ability)
Returns the lengths of a talent’s or spell’s animations for a creature.
The caller decides how many times the conjure loop plays, because the scripts’ conjure tables count loops, not seconds. An ability with no cast animation, such as Pinning Shot or a spider’s Overwhelm, has none here, though its script may still play something.
| Parameter | |
|---|---|
ability |
a row of the abilities table (TABLE_ABILITIES_SPELLS) |
OfShot()
std::optional<Shot> OfShot(ObjectId creature, std::optional<float> attackTime=std::nullopt, std::optional<float> aimTime=std::nullopt)
Returns the parts of a creature’s shot, timed as the game times them.
The scripts set both times as a shot begins, so the defaults give a shot’s real parts only while it is under way. To cost a shot beforehand, pass the times the scripts would set.
| Parameter | |
|---|---|
attackTime |
the scripts’ attack time for the shot, in seconds; by default the one set on the creature now (AttackDuration) |
aimTime |
the scripts’ aim time for the shot, in seconds; by default the one set on the creature now (AimDuration) |
Returns nullopt if the creature is not loaded or lacks the Fire animation
OnPlayed()
void OnPlayed(std::function<void(ObjectId creature, std::int32_t animation, float speed, float blend, bool flag)> observer)
Calls observer each time a creature is told to play an animation, after the engine has taken the order.
This is the engine’s own play call, the one a command’s animation step, a conversation line and the idle all use, so it sees every creature’s base-layer animation. It does not see walking and running, which are not played through it, nor a clip the animation set starts on its own, such as a one-shot returning to the idle. The blend is a rate in weight per second, or a code when it is -1 (instant) or -2 (fade over a fifth of the clip). The observer runs on the game thread and often, so keep it short and do not play animations from it. The creature’s tag is the script command GetTag (dao/generated/ScriptApi.h) on the id.
| Parameter | |
|---|---|
observer |
receives the creature, the animation (a row of anim_base), the speed, the blend and the flag the engine was given |
Pause()
bool Pause(ObjectId creature, bool paused)
Pauses or resumes one creature’s animation, apart from the game’s speed, by the engine’s own pause for it: its clips stand where they are and raise no events until it is resumed, and go on from there.
Call it on the game thread. It holds the animation alone: commands, effects and damage go on, and a command started while paused (a stun, a death) runs its steps’ time but shows nothing until the resume, so resume a creature when its command ends or it starts another (dao/CommandEvents.h, OnEnd and OnStart): a blow can end a command without starting one. Two creatures in a synced animation, a grabber and the one it holds, are each their own and are paused and resumed together.
Returns false if the creature is not loaded
Rate()
std::optional<float> Rate(ObjectId creature)
Returns the speed of one creature’s animation, as Pause and SetRate leave it.
Returns nullopt if the creature is not loaded
SetPhase()
bool SetPhase(ObjectId creature, float phase)
Sets where each of a creature’s animations is in its cycle, the same place for all of them.
For frames to compare: set the same phase on every creature while the game is paused, and the pose stays there, since the game moves animations by its own clock, which stands still while paused. Unpaused, they play on from there. Call on the game thread.
| Parameter | |
|---|---|
phase |
from 0, an animation’s start, to 1, its end |
Returns false if the creature is not loaded or has no animation tree
SetRate()
bool SetRate(ObjectId creature, float rate)
Sets the speed of one creature’s animation, 1 for normal and 0 for paused; a low speed such as 0.1 keeps it moving slowly.
Call it on the game thread. Unlike Pause it leaves the creature’s movement alone, and a clip still raises its events when its time comes.
Returns false if the creature is not loaded
StepLength()
std::optional<float> StepLength(ObjectId creature, std::int32_t animation)
Returns how long a command gives one of a creature’s animations when it plays it as a step at normal speed: the animation’s length, plus those of the animations it runs on into, up to the first that loops.
| Parameter | |
|---|---|
animation |
a row of the anim_ tables |
Returns the length in seconds; nullopt if the creature is not loaded or lacks the animation
Variables
kAim
constexpr std::int32_t kAim = 249
The two animations of a shot with a bow, a crossbow or a staff, rows “Aim” and “Fire” of anim_base: raising the weapon, then loosing.
kAttack
constexpr std::int32_t kAttack = 107
The generic attack animation, row “Attack v1” (attk_v1) of anim_combat.
Every other attack animation falls back to it, and an attack with no animation of its own plays it.
kFire
constexpr std::int32_t kFire = 243