Actor states

From ZDoom Wiki
(Redirected from Loop)
Jump to navigation Jump to search

An actor's states can be defined within its DECORATE definition. State sequences describe all the behavior of the actor as well as its animation.


A state definition is started with the states keyword and enclosed by braces '{', '}'.

It consists of the following:

State labels

A state label is an identifier followed by a colon (:). State labels give names to state sequences which can then be initiated or checked for using those names.

A state label can be any alphanumeric string (within reason) and is not case sensitive. Some labels (Spawn, See, Death, Ready, Select, Deselect, Fire, etc.) are assumed to exist by the engine for certain actors.

A single state can have several labels, each on a different line. However, most states do not have a label, instead they merely follow other states in sequences.

State definitions

The main elements of any given state are the following:

  1. Its sprite name
  2. Its frame letter
  3. Its duration in tics
  4. Its associated action function
  5. Its successor (the next state in sequence)

It also might have additional properties which are expressed through special keywords detailed below.

These consist of a sprite name, a frame letter, the duration in tics and optionally additional keywords and an action function name (code pointer). For example:

STUF C 5 Bright A_Look

Here, STUF is the sprite name, C is the frame letter, 5 the duration, and A_Look the action function.

The successor is defined implicitly as the next defined state, unless a goto, loop, wait, or stop keyword is used to explicitly change it. For instance:

STUF C 5 Bright A_Look
STUF D 5 Bright

Here, the successor for the first state is the second state. The second state's successor is not defined in this example.

If several states share the same sprite name, duration, keywords, and action functions, and they follow in sequence, the states can be "collapsed" together by stringing the frame letters in a word.

STUF ABCD 5 Bright A_Look

Here, four different states are defined on a single line. Each of A, B, C, and D are different states. And likewise:

STUF VVVVVV 5 Bright A_Look

The six V states are all entirely identical (except for their successor), but they are nonetheless separate states.

When the duration runs out, the actor moves to the next state in the sequence and runs the new state's action function immediately. Note that setting -1 as a duration means infinite duration. The actor, once it enters this state, will never leave it on its own; though it can still be moved to a different state by external actions (e.g., suffering damage might put it in the Pain state).

Random durations are possible with the random(min, max) function. Alternatively, you can use A_SetTics; this allows to use full-fledged DECORATE expressions to set any kind of dynamic duration; but prevents the state from having another action function.

The next state is automatically implied to be the following letter on a frame sequence, or if there aren't any more states on a line, the states defined in the next line. Alternatively, flow control keywords (loop, wait, goto, stop) listed after a state can change it. Jump functions such as A_Jump will ignore normal sequence logic and immediately move to their designated state, without waiting for the duration to run out first.

Variable duration

A state can have a random duration. Instead of defining a frame like this:

POSS A 10 A_Look

You can define it as:

POSS A random(10,20) A_Look

and the state will last a random duration between 10 and 20 tics, inclusive. More control can be obtained by using the A_SetTics function and DECORATE expressions.

POSS A 0 A_Look
POSS A 10 A_SetTics((waterlevel + 10) - (accuracy / 10))

State keywords

The existing keywords can be used in a state between the duration and the action function call.

  • Bright
The sprite will be displayed as fullbright while the actor is in this state. Note that this is ignored in fog.
  • CanRaise
Mark the state as allowing A_VileChase to target the actor provided the other conditions are met. By default, only states with a -1 (infinite) duration are eligible. Also, if a state with this keyword is reached, a monster is eligible for respawning if respawning is enabled.
  • Fast
The state has its duration halved in fast mode (if using a skill with the FastMonsters property, or the -fast command-line parameter) and for actors with the ALWAYSFAST flag. This has no effect on actors with the NEVERFAST flag.
  • Light("lightname")
Adds a dynamic light to the state. See below for further information.
  • NoDelay
Forces the action function associated to the state to be executed during the actor's first tic. This is only useful for the first state in an actor's Spawn sequence.
  • Offset(x, y)
Gives the state a sprite offset, only used for HUD sprites (most relevant for weapons. Note that Offset(0, 0) is interpreted as "keep previous offset", not as "reset offset to 0, 0" for compatibility with Hexen, which is the game from which this feature originates. More control over offsets can be gained by using A_WeaponOffset and A_OverlayOffset functions instead.
  • Slow
The state has its duration doubled in slow mode (if using a skill with the SlowMonsters property).



This defines 8 states. Each one of them uses the sprite POSS, has a duration of 4 and uses the code pointer A_Chase which is the standard walk function for monsters. Of these 8 states the first 2 will use the sprite frame 'A', the next 2 the frame 'B' and so on. The length of the frame sequence can be up to 256 characters. Valid frames are 'A'-'Z', '[', '\' and ']'. Different sprites can be freely mixed in an actor definition; however, each separate line of a state definition is limited to one sprite only.


  • If the frames '[', '\' or ']' are used the frame sequence has to be enclosed in quotation marks ('"').
  • Sprite name and frame TNT1 A means no sprite, making the actor invisible for the duration of the state.
  • It is possible for a state to keep the actor's current sprite and/or frame, using special sprite names such as "----" or "####". See the sprite page for more information.

Anonymous functions

You can declare an anonymous function by using braces in place of an action function at the end of a state. This allows you to call multiple action functions from a single state. A semicolon is required after each statement.

   A_Chase; //<-- Semicolon is REQUIRED when inside of these!

To terminate an anonymous function early, use return. It can either return a value or not. The type of value returned is used to infer the return type of the anonymous function, so if you have more than one return statement, they must all return the same type. The types are state (including jumping functions), int, bool and float. To jump to a new state, you can return a state, either by specifying it directly or by calling a jump function.

{ return state("Null"); } // Destroys the actor. All actors have a Null state by default unless overridden.
{ return state("JumpState"); } // Guarantees a jump.
{ return A_Jump(256, "JumpState"); } // So does this.
{ return state(""); } //Aborts an anonymous function without jumping and plays the rest of the tics.
{ return state(0); } //Same here.
{ return; }

In ZScript returns require a pointer acquired via FindState() or ResolveState(). The primary difference is that ResolveState() is context-aware and will work properly when called from PSprite, while FindState() won't. As a result, ResolveState() can be used from Weapon states, where self is interpeted as the weapon's owner. For example:

	TNT1 A 0
		if (invoker.ammo1.amount < invoker.ammouse1) //check ammo
			return ResolveState("Reload"); //go to Reload sequence if not enough
		return ResolveState(null); //otherwise continue to the next state

Note that any function that contains a conditional return in it must end with a null return (such as return ResolveState(null)), so that it knows where to go if the condition isn't met.

Note, returning states manually is the only way to create a complex conditional jump, whereas A_Jump* functions won't work for this, since they always jump—either to the specified sequence, or to the next state. For example, this will not work:

	TNT1 A 0
		if (invoker.ammo1.amount < invoker.ammouse1) //check ammo
			return A_Jump(256, "Reload") // jumps to Reload or to next state
		return ResolveState(null); // This will never be reached!

As a result, A_Jump* functions should not be used in anonymous functions.


Used in for, do-while and while loops. When encountered, a loop is stopped entirely and the code after the loop will continue executing.


Used in for, do-while and while loops. When encountered, a loop will restart and skip execution of all commands after the statement.

If and else keywords

Anonymous function blocks support if/else statements to do different things based a condition without the need to use an A_Jump* function to jump to another state.

It is possible to use an A_Jump-type function inside the condition part of the if statement. The jump will not happen, but if it would have, the condition is considered as true.

NOTE: All jump functions used as the condition check for an if statement need to be passed a valid state label, or the function will always return false for that condition. "Null" is a valid state that can be used instead of needing to define one, as the jump is never performed.

   if (CheckClass("PlayerPawn",AAPTR_TARGET,true))
       //A_Warp performs what it's meant to do, but will never jump.
       //The same applies to all functionality that can jump -- they do nothing here.

       A_Jump(256,"Enrage"); //<-- This does nothing
       user_enrage = 1;
       user_enrage = 0;
       if (user_cooldown != 0)
       { // This returns from the function, skipping the rest of it.
       user_cooldown = 100;

   // Using a jump function to check a condition instead of jumping
   if (CountInv("Cell") > 0)
       // We still have cell ammo!
   else if (CountInv("RocketAmmo") > 0)
       // We still have rocket ammo!
       // We're out of ammo!

For keyword

For loops will repeatedly execute code within until a user variable reaches its destined amount, or it encounters a return/continue/break keyword. The syntax of a for loop is very much like C++.

TNT1 A 1
    for (user_i = 0; user_i < 15; user_i++)
        //...stuff to execute in here. This is all done in an instant.

While keyword

While loops will repeatedly execute code until the condition is met. Unlike for loops, the while syntax only has a condition and does not auto increment. The condition is checked before the execution of the code. The syntax of a while loop is very much like C++.

TNT1 A 1
    while (user_i < 30)

Do/While keyword

Do-while loops will repeatedly execute code until the condition is met. Unlike for loops, the do-while syntax only has a condition and does not auto increment. The condition is checked after the execution of the code. The syntax of a do-while loop is very much like C++.

TNT1 A 1
    } while (user_i < 30); //Semicolon here is important.

ForEach keyword

Note: This feature is for ZScript only.

These are basically 'for' loops with syntactic sugar, designed to be more compact, and requires arrays.

foreach(variable : array)

The variable is automatically deduced, so there's no need to declare the variable beforehand. This allows simplification of a for loop like this:

Array<Actor> things;
for (int i = 0; i < things.Size(); i++)
    Actor mo = things[i];
    if (mo)
        // Do something

to this:

Array<Actor> things;
foreach (mo : things)
    if (mo)
       // Do something

WARNING: When performing with Dynamic Arrays, do not perform anything that changes the size of the array (i.e. Delete, Clear, etc) to avoid potential issues. Save those for after the loop.

Dynamic light binding

It is possible to attach a dynamic light directly to an actor state in its DECORATE definition, rather than binding it to the actor in a GLDEFS lump. The dynamic light itself must still be defined in GLDEFS, however. Contrarily to lights attached to actors in GLDEFS, a binding made to a state directly in the state definition will be inherited by derived actors.

This is done by adding the Light keyword, followed by the name of the light within parentheses and quote marks, in this way:

BLAH A 1337 Bright Light("MyLight") A_DoSomething

ZDoom itself does not support dynamic lights and thus will ignore the Light keyword and its parameter, but the actor will otherwise work correctly.

Flow control

There are 5 different instructions that control the execution order of an actor's frames directly:

Jumps to the most recently defined state label. This is used for a looping animation. Do not put a loop on a state with a duration of -1, this is unnecessary and can cause problems.
Stops animating this actor. Normally this is used at the end of the death sequences. If the last state has a duration > -1 the actor will be removed. Note that if a state contains only the stop instruction, the actor will behave as if it doesn't have that state. This can be useful, for example, to remove a state that an actor has inherited from its parent.
Loops the last defined state. This is useful if a code pointer is used that waits a given time or for a certain event. Currently useful code pointers include A_WeaponReady, A_Raise, A_FreezeDeathChunks, and similar code pointer functionality.
Used with custom inventory items, means that the state sequence failed to succeed.
goto label [+offset]
Jumps to an arbitrary state in the current actor. With this, you can also jump to a base class state, i.e. one that was inherited by a parent. The statement goto See jumps to the walking animation that has been overriden in the current actor class, or if such does not exist, to the inherited class's state. goto is however static, i.e. will not do virtual jumps — for that, see A_Jump.
Offset specifies the number of frames to skip after the specified label. That is, using "goto Spawn+2" will jump to this frame:
In addition, if an actor is using inheritance, you can use goto with the scope operator (::) to go to a parent class' state. The keyword "super" always refers to the immediate parent, but any parent class can be referred to by name as well, for example "goto Actor::GenericFreezeDeath" is a valid instruction.

Important note

This format has been designed for maximum flexibility. As a result no assumptions are made about what the designer wants. States are never implicitly created.

Also, if no flow control is used ZDoom will continue to the state provided directly after. Consecutive state labels can be used to assign the same frames to more than one state.


These are the predefined states each actor has access to:

Defines the state that is displayed when an actor is spawned. For monsters this is normally also the idle loop.
Also entered by hitscan puffs when hitting a non-bleeding actor, provided the puff has +PUFFONACTORS.
Note: An actor that has just been spawned does not run the action function attach to the first frame of its Spawn sequence. For example, if a monster calls A_Look in its first frame, it won't look for enemies until the Spawn sequence is looped once. If you need to force an actor to call the function instantly upon entering the Spawn sequence, add NoDelay before the function call.
Defines an alternate idle state for a monster to return to when it has run out of targets. If this state is not present, the monster will return to the Spawn state instead.
Defines the walking animation for a monster. Note that this state must be present for actors which are able to chase and attack other actors.
Defines the melee (close-range) attack.
Also entered by puffs when hitting an enemy with a melee attack, such as A_CustomPunch, provided the puff has +PUFFONACTORS.
Defines the missile (ranged) attack.
Defines the pain action. Multiple Pain states can be used depending on the type of damage inflicted. See custom damage types.
Defines the normal death sequence. Multiple Death states can be used depending on the type of damage that kills the actor. See custom damage types. Also entered by projectiles when hitting a wall (or an actor as well if the Crash and/or XDeath states are not defined).
Defines an alternate death sequence for projectiles. This is entered when hitting a sky plane while having the SKYEXPLODE flag set. Does not work on fast projectiles.

XDeath (internally, Death.Extreme)

Defines the extreme (splatter) death sequence (if the actor's health is lower than its GibHealth). Multiple XDeath states can be used depending on the type of damage that kills the actor.
Also entered by projectiles when hitting a bleeding actor (if no XDeath state is defined, they enter their Death state instead).
Also entered by puffs when hitting a bleeding actor, provided the puff has +PUFFONACTORS. (If the actor is non-bleeding or this state isn't defined, Spawn is used instead).
Warning: For monsters that disappear with their death states, always ensure there is at least a 1 tic delay before the stop of the actor. A VM abort can potentially happen otherwise.

Burn (internally, Death.Fire)

Defines the burn (Fire) death sequence.

Ice (internally, Death.Ice)

Defines the freeze (Ice) death sequence.

Disintegrate (internally, Death.Disintegrate)

Defines the disintegration death sequence.
Defines the resurrection sequence.
note: This is when a monster is being resurrected (ie: by an Arch-Vile), not when its resurrecting another monster.
Define the healing sequence. This is entered when this monster is resurrecting another one. Note that by the time this monster enters this state, the resurrection process has already started. The process is usually started either by A_Chase, with the CHF_RESURRECT flag passed to it, A_VileChase, or A_CheckForResurrection.
Defines the crash sequence. Multiple Crash states can be used depending on the type of damage that kills the actor. This is entered when the actor is a corpse and hits the floor.
Also entered by projectiles when hitting a non-bleeding actor (if no Crash state is defined, they enter their Death state instead).
Also entered by puffs when the attack hits a wall/plane (but for non-bleeding actors puffs use Spawn, as opposed to projectiles).


Defines the extreme (splatter) crash sequence. Multiple Crash.Extreme states can be used depending on the type of damage that kills the actor. This is entered when the actor is a corpse and hits the floor after being gibbed.
Defines the crush sequence. This is entered when the actor is crushed by ceiling/door/etc.
This state is entered when the actor is damaged and its health is lower than its WoundHealth but greater than 0. Multiple Wound states can be used depending on what type of damage is inflicted upon the actor. See custom damage types.
This state is entered if an actor with SKULLFLY hits another actor. This takes precedence over entering the Spawn or Idle states, or entering the See state if RETARGETAFTERSLAM is on.
This is used by the Strife dialog system. It is entered when a conversation is about to start.
This is used by the Strife dialog system. It is entered when the actor reacts positively to the player's choice.
This is used by the Strife dialog system. It is entered when the actor reacts negatively to the player's choice.
This is used by Hexen-style switchable decorations. It is entered when the actor is activated.
This is used by Hexen-style switchable decorations. It is entered when the actor is deactivated.
This is used by bouncers with the USEBOUNCESTATE flag. It is entered when the actor bounces. Multiple bounce states can be used depending on what the actor bounced off:
  • Bounce
  • Bounce.Floor
  • Bounce.Ceiling
  • Bounce.Wall
  • Bounce.Actor
  • Bounce.Actor.Creature
Partial matches work just like Pain states, so if an actor bounces off a floor and you don't have a Bounce.Floor state, but you do have a Bounce state, it will use the Bounce state. Conversely, if you only have a Bounce.Floor state but no Bounce state, then the actor will only enter the Bounce.Floor state when it bounces on a floor; bouncing off anything else will not cause it to change state. The Bounce.Actor.Creature state is used for bouncing over a shootable actor without the NOBLOOD flag.

Weapons and custom inventory items define a few more states to define their animations.

Note that you can also define your own states that can be referred to using A_Jump or other jump instructions.


This is an example of a state sequence. The rest of this actor has been removed for readability:

actor ZombieMan 3004
       POSS AB 10 A_Look
       POSS AABBCCDD 4 A_Chase
       POSS E 10 A_FaceTarget
       POSS F 8 A_PosAttack
       POSS E 8
       goto See
       POSS G 3
       POSS G 3 A_Pain
       goto See
       POSS H 5
       POSS I 5 A_Scream
       POSS J 5 A_Fall
       POSS K 5
       POSS L -1
       POSS M 5
       POSS N 5 A_XScream
       POSS O 5 A_Fall
       POSS PQRST 5
       POSS U -1
       POSS KJIH 5
       goto See

Note: The first frame of the “Spawn” state, “POSS A 10”, calls A_Look. This function is not called the very first time the zombie is spawned in the map, so it has to wait 10 tics to get into its second frame, “POSS B 10”. From then on, it will call A_Look every 10 tics. If it runs out of targets, and since it has no “Idle” state, it will return to its Spawn state where it will call A_Look immediately, even in the A frame.

This example demonstrates using the stop keyword to remove a state. This definition uses inheritance to define a tougher version of the imp that cannot be resurrected by the Arch-Vile:

actor SuperImp : DoomImp
     health 1500
     mass 200
     painchance 10

     States {

See also