A_Repeat

A_Repeat is an action that is used to return the actor to a state a certain number of times before allowing the state's next state to be used. It is intended that this action be used at the end of a repeated/looping animation consisting of multiple states, so as to be used as many times as necessary without using up as many state freeslots. Var1 determines the number of times the action to be repeated, including the first time A_Repeat is reached; Var2 determines the state to return to before the actor's repeat counter (which is reduced by 1 each time this action is used) reaches 0.

Var1 is only applied if the actor's repeat counter (or actor.extravalue2) has reached 0, or the repeat counter's count is higher than Var1 itself. With this in mind, a Var1 of 1 can be used to "reset" the repeat counter if the state animation was interrupted in anyway during the animation – e.g. when Brak Eggman is using the flamethrower attack, but is hurt by the player before it can be finished. This should ideally be set for a state placed before the animation itself, so as not to break it unintentionally.

Note that a Var1 value below 0 will cause actor.extravalue2 to become negative, rendering this action unusable afterwards. A Var1 value of 0 will prevent actor.extravalue2 from being modified.

Example

Using SOC formatting to convey this example, typically a set of states for an animation that would use A_Repeat would be ordered like this:

#Create a new set of states via the "Freeslot" block
Freeslot
S_LOOPSTART   # uses A_Repeat to refresh the repeat counter before starting the loop; this state is not actually part of the loop itself
S_LOOP1       # start of loop; state for S_LOOPRESTART to return to
S_LOOP2
S_LOOP3
# (add more following S_LOOP3 if necessary)
S_LOOPRESTART # the main A_Repeat state, used to repeat the loop a set number of times
S_LOOPEND     # the state used after the final run of the loop

The states themselves can then be defined in a way such as this:

State S_LOOPSTART
SpriteName = PLAY
SpriteFrame = A
Duration = 0      # make state finish instantanously, since otherwise it is completely useless to be in
Action = A_Repeat
Var1 = 1          # resets repeat counter to 0
Var2 = 0          # doesn't matter what value this is set to!
Next = S_LOOP1    # start of loop

State S_LOOP1
SpriteName = PLAY
SpriteFrame = A
Duration = 35     # each state in this loop lasts a second each
Next = S_LOOP2

State S_LOOP2
SpriteName = PLAY
SpriteFrame = B   # in this loop, the sprite frame changes every state
Duration = 35
Next = S_LOOP3

State S_LOOP3
SpriteName = PLAY
SpriteFrame = C
Duration = 35
Next = S_LOOPRESTART # end of loop

State S_LOOPRESTART
SpriteName = PLAY
SpriteFrame = C
Duration = 0         # make state finish instantanously, since otherwise it is completely useless to be in
Action = A_Repeat
Var1 = 5             # animation plays 5 times (including 1st time state is reached)
Var2 = S_LOOP1       # state to use when returning to loop
Next = S_LOOPEND     # state to use after the last repeat of loop

State S_LOOPEND
SpriteName = PLAY
SpriteFrame = C
Duration = 0
Next = S_NULL # make actor disappear afterwards!

An Object using the example state S_LOOPSTART from above will cause the Object to display frames A, B and C (in order) from the SPR_PLAY sprite set for a second each, repeating this sequence four more times before the Object itself disappears from the game. If this state loop was interrupted mid-way however, the Object can return to this state later and re-start the whole loop from the beginning.