State

This article is about the definition and format of states. For a list of states that are used in SRB2, see List of states.

States are the animation frames of an Object that control its and appearance and activity for a certain period of time. Each state can assign a sprite and an action to the Object for a specific duration and then change to a pre-determined next state. This leads to sequences of multiple states which follow each other in a fixed order. Every such sequence eventually reaches a final state that either lasts indefinitely or loops back to an earlier state in the sequence. Every Object has up to eight state sequences which it can activate and switch between when certain conditions are met.

Called states

To start a state sequence, the Object has to call its first state. For this purpose, Objects have eight state slots in which the first states of the correspondent state sequences are stored. When a certain condition is met, the state referenced in such a slot will be called and the Object will cycle through the subsequent state sequence. This sequence eventually reaches a final state that either lasts indefinitely or loops back to an earlier state in the sequence. Thus, the sequence continues until the condition for another state slot is met and a different sequence is started. For example, an enemy goes into its SpawnState upon being spawned and cycles through a sequence of states (or maybe just a single state that loops back to itself). The sequence continues until the enemy spots a player, goes into its SeeState and starts a different state sequence. If the enemy is hit by the player, it will interrupt the state sequence it is currently in and change into its PainState instead.

Which state slots are called under what conditions depends on the type of Object and the actions it uses. For the vast majority of Objects, only a few of these eight slots may be necessary or even usable. Listed below are the eight available state slots and their most common usages:

• SpawnState is the state that an Object calls when it is spawned. Its Duration may not be 0. If the SpawnState has an action, it will not be performed when the Object is first spawned unless the MF_RUNSPAWNFUNC flag is set on the Object. If the SpawnState is called again after that, however, the action will be performed even without the flag. This is the only state slot that is used for the same purpose by all Objects that use it. All Objects must have a SpawnState that is not S_NULL to be able to exist, even invisible Objects such as ambient sound effects. The state S_SPAWNSTATE is made specifically to go to this state of the Object using it.
• SeeState is usually used by Objects that interact with the player. It is called once the Object spots a player, which can be done with the action A_Look and certain actions that are made specifically for some of SRB2's specific enemies. The state S_SEESTATE is made specifically to go to this state of the Object using it.
• PainState is the state that Objects with the flag MF_BOSS or MF_ENEMY go to when they are damaged but not yet dead. Enemies with a SpawnHealth of 1 automatically die upon being hit and therefore do not use this state.
• MeleeState is the first of two attack states for use with certain actions such as A_Chase and A_Boss1Chase. These actions will call this or MissileState when the Object should attack. Otherwise, this is used for miscellaneous purposes. The state S_MELEESTATE is made specifically to go to this state of the Object using it.
• MissileState is the second of two attack states for use with certain actions such as A_Chase and A_Boss1Chase. These actions will call this or MeleeState when the Object should attack. Otherwise, this is used for miscellaneous purposes. The state S_MISSILESTATE is made specifically to go to this state of the Object using it.
• DeathState is the state that Objects generally go to when they are destroyed or killed, i.e. they have no health points left. The sequence of states following should eventually point to S_NULL, if DeathState is not S_NULL itself, which is used to remove Objects from the map. The state S_DEATHSTATE is made specifically to go to this state of the Object using it.
• XDeathState is usually used as the fleeing state for bosses. It is called by the action A_BossDeath. Otherwise, this is used for miscellaneous purposes. The state S_XDEATHSTATE is made specifically to go to this state of the Object using it.
• RaiseState is used for miscellaneous purposes. A_ShootBullet, A_DropMine and A_JetgShoot all spawn Objects with this state. In this case, the RaiseState value refers to an Object instead of a state. The state S_RAISESTATE is made specifically to go to this state of the Object using it.

Attributes

Every state has several attributes assigned to it. They include the sprite that the Object should display while in the state, an action to perform, the duration of the state and the next state to call. The action is optional, but all other attributes are mandatory.

• SpriteName: The four-letter prefix for the sprite set to use while in the current state. Every Object (except for invisible ones and cases where multiple Objects share the same sprites) has its own sprite set which contains all sprites that it may display. This parameter does not actually choose the sprites, it only specifies in which set they can be found. A complete listing of sprite sets can be found in the list of sprites.
• SpriteFrame: Out of the selected sprite set, this chooses which frame to display. A frame is a single freeze image of an Object, displayed from up to eight different angles. The value to be used is the fifth letter of the desired sprite's lump name, e.g. "A" if the sprite's name is PLAYA1. Additionally, certain values can be added on top of that to specify the frame's translucency and brightness settings. The bitwise OR operator (|) should be performed on these values to combine them, e.g. FF_FULLBRIGHT|FF_TRANS10|A.
  • Translucency flags:
    • FF_TRANS10: 10% translucent (90% opaque)
    • FF_TRANS20: 20% translucent (80% opaque)
    • FF_TRANS30: 30% translucent (70% opaque)
    • FF_TRANS40: 40% translucent (60% opaque)
    • FF_TRANS50: 50% translucent (50% opaque)
    • FF_TRANS60: 60% translucent (40% opaque)
    • FF_TRANS70: 70% translucent (30% opaque)
    • FF_TRANS80: 80% translucent (20% opaque)
    • FF_TRANS90: 90% translucent (10% opaque)
  • Blending mode flags:
    • FF_ADD: The sprite uses additive blending. Combine with translucency flags to change the intensity.
    • FF_SUBTRACT: The sprite uses subtractive blending. Combine with translucency flags to change the intensity.
    • FF_REVERSESUBTRACT: The sprite uses reverse subtractive blending. Combine with translucency flags to change the intensity.
    • FF_MODULATE: The sprite uses modulative blending.
  • Other appearance flags:
    • FF_FULLBRIGHT: Full brightness, the sprite is not affected by lighting.
    • FF_FULLDARK: Full darkness, the sprite is not affected by lighting.
    • FF_SEMIBRIGHT: Takes the average between full brightness and the light level of the sector that the object is in.
    • FF_VERTICALFLIP: The sprite is flipped upside-down. Not to be confused with Object flipping, as this does not affect its gravity.
    • FF_HORIZONTALFLIP: The sprite is flipped left-to-right. Note that this will be done 'after' the proper rotation (if applicable) is calculated based on the camera angle to the Object.
    • FF_PAPERSPRITE: The sprite is rendered as a "line", instead of always facing the camera. This is named after the look of the Paper Mario games.
    • FF_FLOORSPRITE: The sprite is rendered on a horizontal plane, instead of always facing the camera. Often called a "splat", a combination of the words "sprite" and "flat".
  • Animation flags:
    • FF_ANIMATE: Makes the state animated by cycling through several consecutive frames. Var1 sets the number of frames to cycle through. The animation starts at the frame set by SpriteFrame and then continually switches to the next frame until it has advanced by the amount of frames specified by Var1; then it restarts at the first frame. Var2 sets the delay in tics before switching to the next frame. For example, if you set SpriteFrame = FF_ANIMATE|A, Var1 = 25 and Var2 = 1, the state will cycle through the frames A–Z, spending 1 tic on each frame, and repeating upon reaching the end, as long as the Object is in the state. Note that this is 26 frames in total, but Var1 is only 25; this is because SRB2 checks the difference between the current frame and the original frame.
      • FF_RANDOMANIM: FF_ANIMATE will start at a random point in the animation, rather than starting from the beginning of the animation.
      • FF_GLOBALANIM: FF_ANIMATE will be synced up to the global level timer, rather than starting from the beginning of the animation.
  • If the state uses the SPR_PLAY sprite set, SpriteFrame instead determines the sub-set of SPR_PLAY to use. These sub-sets are identified with constants using the SPR2_ prefix, followed by the four-letter prefix of the sprites for a particular player animation – e.g.: SPR2_STND uses the sprites with STND prefix. Note that the frame used by the state cannot be controlled by SpriteFrame; it will start at A and will be incremented each time the state itself, or another state with the same sprite set and sub-set, is called by the Object, until the Object calls another state without these properties. Additionally, states using the SPR_PLAY sprite set can have the following flags (in addition to the flags already listed above):
    • FF_SPR2SUPER: This state is a Super Sonic animation.
    • FF_SPR2ENDSTATE: Once all of this state's animation frames finish playing completely, then it goes to the state specified in Var1.
    • FF_SPR2MIDSTART: This state has a 50% chance of starting in the middle of the animation. Notably used for Tails' tail overlay.

• Duration: This sets how long the state lasts in tics (35 tics equal one second). Set it to 0 to instantly change to the next state, and to -1 to make the state last indefinitely. Note that an Object's SpawnState may not have a duration of 0.
• Action: Specifies an action to be performed during the state. This parameter is optional; not all states need to include an action.
• Var1 and Var2: These are variables that can modify the behavior of some actions. Their purpose depends on the action being used and is documented in the Wiki article for the respective action. They are also used for animated states; see above.
• Next: Specifies the state to go to after the current state's duration is over.

SOC definition

This is an example of a state definition written with SOC and the syntax it uses.

State S_FLAMEJETFLAMEB1
SpriteName = DFLM
SpriteFrame = FF_FULLBRIGHT|FF_TRANS40|B
Duration = 1
Action = A_MoveRelative
Var1 = 0
Var2 = 5
Next = S_FLAMEJETFLAMEB2

Lua definition

This is an example of a state definition written with Lua. Note that "sprite", "frame", "tics" and "nextstate" are used instead of SpriteName, SpriteFrame, Duration and Next, respectively; all other attributes are written in all-lowercase.

Longhand definition

states[S_FLAMEJETFLAMEB1] = {
        sprite = SPR_DFLM,
        frame = FF_FULLBRIGHT|FF_TRANS40|B,
        tics = 1,
        action = A_MoveRelative,
        var1 = 0,
        var2 = 5,
        nextstate = S_FLAMEJETFLAMEB2
}

Shorthand definition

This requires all the fields to be filled out. The order of the fields follow the longhand definition above.

states[S_FLAMEJETFLAMEB1] = {SPR_DFLM, FF_FULLBRIGHT|FF_TRANS40|B, 1, A_MoveRelative, 0, 5, S_FLAMEJETFLAMEB2}