Actor states

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.

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.

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))

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") (GZDoom only: not supported by ZDoom)

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

POSS AABBCCDD 4 A_Chase

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.

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.

POSS A 4
{
   A_Chase; //<-- Semicolon is REQUIRED when inside of these!
   A_SpawnItemEx("BloodyTrail",0,0,0,0,0,0,0,SXF_NOCHECKPOSITION);
}

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:

Fire:
	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:

Fire:
	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.

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.

POSS A 4
{
   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_Warp(AAPTR_TARGET,x,y,z,0,WARPF_NOCHECKPOSITION|WARPF_USECALLERANGLE|WARPF_ABSOLUTEPOSITION|WARPF_COPYVELOCITY,"Enrage"); 
       A_Jump(256,"Enrage"); //<-- This does nothing
       user_enrage = 1;
   }
   else
   {
       user_enrage = 0;
       if (user_cooldown != 0)
       { // This returns from the function, skipping the rest of it.
           return;
       } 
       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!
   }
   else
   {
       // We're out of ammo!
   }
}

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 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)
    {
        //...stuff.
       user_i++;
    }
}

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
{
    do
    {
        //...stuff.
        user_i++;
    } while (user_i < 30); //Semicolon here is important.
}

(New from 4.10.0)

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.

(GZDoom only: not supported by ZDoom)
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.

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

loop

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.

stop

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.

wait

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.

fail

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:

Spawn:
  TNT1 AAAAAAAA 0
         ^

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.

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.