SetUnitAnimation

Parameters
whichUnitunit
whichAnimationstring

String of tokens separated by spaces (case-insensitive).

See the list below. Any substring not matching a token is treated as "stand" (except for the special case of using the "cinematic" token). Animation selection rules are described in the note below.

  • "alternate"
  • "alternateex"
  • "attack"
  • "berserk"
  • "birth"
  • "chain"
  • "channel"
  • "cinematic"
  • "complete"
  • "critical"
  • "death"
  • "decay"
  • "defend"
  • "dissipate"
  • "drain"
  • "eattree"
  • "entangle"
  • "fast"
  • "fifth"
  • "fill"
  • "fire"
  • "first"
  • "five"
  • "flail"
  • "flesh"
  • "four"
  • "fourth"
  • "gold"
  • "hit"
  • "large"
  • "left"
  • "light"
  • "looping"
  • "lumber"
  • "medium"
  • "moderate"
  • "morph"
  • "off"
  • "one"
  • "portrait"
  • "puke"
  • "ready"
  • "right"
  • "second"
  • "severe"
  • "sleep"
  • "slam"
  • "small"
  • "spiked"
  • "spell"
  • "spin"
  • "stand"
  • "swim"
  • "talk"
  • "third"
  • "three"
  • "throw"
  • "two"
  • "turn"
  • "upgrade"
  • "victory"
  • "walk"
  • "work"
  • "wounded"
comment

Immediately start playing new animation.

If the animation requires a change, cancel current animation and start new animation. There is no smooth transition.

The start/end behavior (like forced restart or transition to a different animation at the end) depends on the animation itself.

Example (Lua, 2.0.3):

-- Start goblin merchant's forgotten slide animation
u_ngme = CreateUnit(Player(0), FourCC("ngme"), 0, 0, -80)
SetUnitAnimation(u_ngme, "Stand Work")
note

See: QueueUnitAnimation, `SetUnitAnimationByIndex, SetUnitAnimationWithRarity, AddUnitAnimationProperties

note

Animation (sequence) selection logic:

  1. Each animation in the model has a prop array built by splitting its name by spaces and keeping only recognized tokens (unrecognized substrings are ignored). For example: "Spell Slam Alternate - 1" -> ["spell", "slam", "alternate"].
  2. The whichAnimation argument is tokenized the same way, but unrecognized substrings are replaced by "stand".
  3. For each animation, the number of matching tokens (order doesn't matter) is counted against whichAnimation tokens. The best match is the animation with the most matching tokens. Ties are broken by choosing the animation with the fewest non-matching tokens. If multiple suitable animations are found, all of them are assigned to the target, and one is played at random, using the Rarity value (defined per animation in the model) as a weight.
  4. There is an additional check for cinematic animations. If the argument contains two or more recognized tokens and the first token is "cinematic" (for example, "Cinematic Angry One"), the internal function attempts to find an animation in the model by matching the entire string exactly, bypassing the tokenizer. This may not work in pre-Reforged patches.
patch

1.00

Source
common.j (suggest an edit or discuss on Github)
return type
nothing
Source code
native          SetUnitAnimation            takes unit whichUnit, string whichAnimation returns nothing