State
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. ItsDuration
may not be 0. If theSpawnState
has an action, it will not be performed when the Object is first spawned unless theMF_RUNSPAWNFUNC
flag is set on the Object. If theSpawnState
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 aSpawnState
that is notS_NULL
to be able to exist, even invisible Objects such as ambient sound effects. The stateS_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 actionA_Look
and certain actions that are made specifically for some of SRB2's specific enemies. The stateS_SEESTATE
is made specifically to go to this state of the Object using it.PainState
is the state that Objects with the flagMF_BOSS
orMF_ENEMY
go to when they are damaged but not yet dead. Enemies with aSpawnHealth
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 asA_Chase
andA_Boss1Chase
. These actions will call this orMissileState
when the Object should attack. Otherwise, this is used for miscellaneous purposes. The stateS_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 asA_Chase
andA_Boss1Chase
. These actions will call this orMeleeState
when the Object should attack. Otherwise, this is used for miscellaneous purposes. The stateS_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 toS_NULL
, ifDeathState
is notS_NULL
itself, which is used to remove Objects from the map. The stateS_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 actionA_BossDeath
. Otherwise, this is used for miscellaneous purposes. The stateS_XDEATHSTATE
is made specifically to go to this state of the Object using it.RaiseState
is used for miscellaneous purposes.A_ShootBullet
,A_DropMine
andA_JetgShoot
all spawn Objects with this state. In this case, theRaiseState
value refers to an Object instead of a state. The stateS_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 isPLAYA1
. 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 bySpriteFrame
and then continually switches to the next frame until it has advanced by the amount of frames specified byVar1
; then it restarts at the first frame.Var2
sets the delay in tics before switching to the next frame. For example, if you setSpriteFrame = FF_ANIMATE|A
,Var1 = 25
andVar2 = 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, butVar1
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 ofSPR_PLAY
to use. These sub-sets are identified with constants using theSPR2_
prefix, followed by the four-letter prefix of the sprites for a particular player animation – e.g.:SPR2_STND
uses the sprites withSTND
prefix. Note that the frame used by the state cannot be controlled bySpriteFrame
; 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 theSPR_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 inVar1
.FF_SPR2MIDSTART
: This state has a 50% chance of starting in the middle of the animation. Notably used for Tails' tail overlay.
- Translucency flags:
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'sSpawnState
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
andVar2
: 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}
SOC | [view] | |
General | Clear • MainCfg
| |
Objects | Object • State • Sound • Sprite2 • SpriteInfo • Sprite2Info • Freeslot
| |
Unlockable content | Emblem • ExtraEmblem • Unlockable • ConditionSet
| |
Miscellaneous | Wipes • Character • Level • Cutscene / Scene • Prompt • Menu • HudItem
| |
Related links | Actions • Constants • Custom Object tutorial |