Actor states

From ZDoom Wiki

An actor's states can be defined for an actor within its DECORATE definition. States describe the animations an actor has.

Contents 1 States 2 Usage 2.1 State labels 2.2 State definitions 2.2.1 Example 2.3 Dynamic light binding 2.4 Flow control 2.4.1 Important note 3 Examples 4 See also

States

These are the predefined states each actor has access to:

Spawn

Defines the state that is displayed when an actor is spawned. For monsters this is normally also the idle loop.

Note: An actor that has just been spawned does not run the codepointer from its first “Spawn” frame. It will be called, however, if the actor loops or returns to its Spawn state later. An easy workaround to have actors call a codepointer immediately after spawning consists in having the very first frame have a duration of 0 tics, followed by another frame in which the codepointer instruction is given.

Idle

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.

See

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.

Melee

Defines the melee (near) attack.

Missile

Defines the missile (far) attack.

Pain

Defines the pain action. Multiple Pain states can be used depending on the type of damage inflicted. See custom damage types.

Death

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

XDeath

Defines the extreme (splatter) death sequence. Also entered by projectiles when hitting a bleeding actor (if no XDeath state is defined, they enter their Death state instead).

Burn

Defines the burn (fire) death sequence.

Ice

Defines the freeze (ice) death sequence.

Disintegrate

Defines the disintegration death sequence.

Raise

Defines the resurrection sequence.

note: This is when a monster is being resurrected (ie: by an Arch-Vile), not when its resurrecting another monster.

Heal

Define the healing sequence. This is called when this monster is resurrecting another one.

Crash

Defines the crash sequence. 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).

Crush

Defines the crush sequence. This is entered when the actor is crushed by ceiling/door/etc.

Wound

This state is entered when the actor's 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.

Greetings

This is used by the Strife dialog system. It is entered when a conversation is about to start.

Yes

This is used by the Strife dialog system. It is entered when the actor reacts positively to the player's choice.

No

This is used by the Strife dialog system. It is entered when the actor reacts negatively to the player's choice.

Active

This is used by Hexen-style switchable decorations. It is entered when the actor is activated.

Inactive

This is used by Hexen-style switchable decorations. It is entered when the actor is deactivated.

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.

Usage

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

A state definition consists of the following:

State labels

This is one of the keywords listed above followed by a ':'.

State definitions

These consist of a sprite name, a frame sequence, the duration in tics (1/35 seconds) (note: state duration of -1 means forever) and optionally the bright keyword to indicate a fullbright display and an action function name (code pointer.) For weapon attack frames there is also the option to specify a sprite offset with offset (x,y).

Example

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.

note: Sprite name TNT1 means no sprite.

note: If the frames '[', '\' or ']' are used the frame sequence has to be enclosed in quotation marks ('"').

note: If a weapon offset is specified with the offset keyword, the state defined cannot have a duration longer than 254 tics. This is a limitation.

Dynamic light binding

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

Flow control

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.

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.

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.

Examples

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

actor ZombieMan 3004
{
   ...
   states
   {
   Spawn:
       POSS AB 10 A_Look
       loop
   See:
       POSS AABBCCDD 4 A_Chase
       loop
   Missile:
       POSS E 10 A_FaceTarget
       POSS F 8 A_PosAttack
       POSS E 8
       goto See
   Pain:
       POSS G 3
       POSS G 3 A_Pain
       goto See
   Death:
       POSS H 5
       POSS I 5 A_Scream
       POSS J 5 A_Fall
       POSS K 5
       POSS L -1
       stop
   XDeath:
       POSS M 5
       POSS N 5 A_XScream
       POSS O 5 A_Fall
       POSS PQRST 5
       POSS U -1
       stop
   Raise:
       POSS KJIH 5
       goto See
   }
}

Note: The first frame of the “Spawn” state, “POSS A 10”, contains a codepointer, A_Look. This codepointer 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 all its codepointers reliably. 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 {
          Raise:
              stop
     }
}

See also

Using inheritance