Actions

From SRB2 Wiki
Jump to: navigation, search

Actions are a special group of functions that determine what an Object does during a given state. They are used to control the interaction of Objects with the player and the level environment. During any state, an Object can perform one of the 184 actions coded into SRB2, although it does not need to perform one during every state. Some Objects, such as static scenery Objects, do not perform any actions at all because they do not need to interact with their environment in any way. These Objects may or may not have the MF_NOTHINK flag set, which will prevent them from using actions at all anyway. Actions are commonly associated with SOC, but Lua allows them to be called externally to states as normal functions (see below).

The Object that performs or calls an action is called the actor. Additionally, actions can assign a target or a tracer Object to the actor as reference Objects. They are used for actions that need to be performed in relation to another Object. For example, a shooting action will fire a projectile at the target; a movement attack will make the actor move towards the target. Some actions will set these themselves if they are necessary, but they can also be set manually with the actions A_FindTarget and A_FindTracer, respectively.

Some actions allow for modifications of their behavior through two signed 32-bit integer variables, called Var1 and Var2. Their effect depends entirely on the action they are used with. These can take a large range of values, both positive and negative. For some of the more complicated actions, SRB2 divides one or both of these variables into upper 16 and lower 16 bits, essentially creating up to four distinct parameters to allow for more flexible control. In these cases, the value of the variable is calculated as the desired upper 16-bit value multiplied with 65536 (or left-shifted by 16) plus the desired lower 16-bit value – this can be written in a SOC or Lua script as VarX = (upper*65536)+lower or VarX = (upper<<16)+lower.

Normally, only a single action can be performed during one state, and their effects usually last only for the moment the state is first used. However, the action A_DualAction allows for two actions to be executed in the same state. Actions can also be performed simultaneously by setting a state's duration to 0, causing the Object to change into the next state instantly. However, this is not possible in the SpawnState, whose duration may never be 0. When an Object is first spawned, the SpawnState's action is not performed unless the Object has the MF_RUNSPAWNFUNC flag set. If the SpawnState is called again after that, however, the action will be performed even without the flag.

Actions with Lua

Lua can be used to call, override, or execute along with actions. You can even create new actions for use in SOC.

Calling an action

You can call an action by simply using the following format:

A_BunnyHop(actor, var1, var2) -- actor is a mobj_t structure, and var1 and var2 are both INT32

Overriding existing functions

You may override existing actions through this format:

function A_BunnyHop(actor, var1, var2)
    -- do things
end

Using super()

However, the function super() may be used within a function to call the original, unmodified action as shown here:

function A_BunnyHop(actor, var1, var2)
    super(actor, var1, var2) -- calls the original A_BunnyHop action
    -- do things
end

Creating new actions

You may also want to create a new action, which allows it to be called in SOC and outside of the Lua script that it was defined in. This must be prefixed with A_.

function A_MyAction(actor, var1, var2)
    -- do things
end

List of actions

Go to the respective article for each action for more details on how to use it.

Movement

  • A_BubbleRise: Used to make bubbles rise.
  • A_BunnyHop: Makes the actor hop like a bunny.
  • A_CapeChase: Sets the actor's position to that of its target or tracer. If used repeatedly, the actor will continuously follow its target/tracer.
  • A_Chase: Makes the actor move towards its target. Use this repeatedly for basic chasing movement. Used by several enemies, such as the Crawlas.
  • A_FishJump: Makes the actor jump if on the ground or underwater. Used by the SDURF.
  • A_ForceStop: Immediately stops the actor's movement.
  • A_HomingChase: Makes the actor move directly towards its target or tracer. Use this repeatedly to make the actor continuously chase its target.
  • A_InstaLoop: Makes the actor move along a 2D horizontal polygon.
  • A_KnockBack: Knocks back the actor's target or tracer at its current speed.
  • A_MouseThink: The thinker for mice released by enemies.
  • A_MoveAbsolute: Moves the actor horizontally at an absolute speed.
  • A_MoveRelative: Moves the actor horizontally while keeping its current momentum.
  • A_PushAway: Pushes the actor's target or tracer away from the actor itself.
  • A_ScoreRise: Used to make score logos rise.
  • A_SkullAttack: Makes the actor fly like a missile toward its target.
  • A_Thrust: Thrusts the actor horizontally at its current angle.
  • A_ZThrust: Thrusts the actor vertically.

Rotational movement

Enemy thinkers

Boss thinkers

Rings

Powers and monitors

Spawners

Projectiles

  • A_DropMine: Makes the actor drop an Object.
  • A_FireShot: Fires an Object at the actor's target.
  • A_LobShot: Lobs an Object at the actor's target.
  • A_MissileSplit: When applied to a missile Object, creates a second missile.
  • A_MultiShot: Shoots multiple Objects horizontally that spread evenly.
  • A_NapalmScatter: Scatters a number of projectiles around in a circle; intended for use with Objects that are affected by gravity.
  • A_ShootBullet: Makes the actor fire an Object at its target.
  • A_SplitShot: Shoots a missile at either side of the actor's target.
  • A_SuperFireShot: Fires an Object at the actor's target that will even stun Super Sonic.
  • A_SuperTurretFire: Rapidly fires projectiles that will even stun Super Sonic.
  • A_TrapShot: Fires a projectile in a particular direction, rather than at an Object.
  • A_TurretFire: Rapidly fires projectiles at the actor's target.
  • A_TurretStop: Stops A_TurretFire or A_SuperTurretFire.
  • A_VileAttack: Instantly hurts the actor's target if it is in the actor's line of sight. Used as part of Brak Eggman's sniping attack.
  • A_VileFire: Thinker for Brak Eggman's targeting reticule. Keeps the actor in front of its tracer, unless its target cannot see it. Optionally draws a line directly to the actor's target.
  • A_VileTarget: Spawns an Object directly on the actor's target and sets this Object as the actor's tracer. Used as part of Brak Eggman's sniping attack.

Sounds

Remote actions

Property modifiers

Checking

  • A_BubbleCheck: Checks if the actor is underwater; if not, the actor turns invisible.
  • A_CheckAmbush: Calls a specified state if the actor is behind its target.
  • A_CheckHealth: Calls a specified state depending on the actor's current health.
  • A_CheckHeight: Calls a specified state depending on the height difference between the actor and its target.
  • A_CheckRandom: Randomly decides whether or not to call a specified state.
  • A_CheckRange: Calls a specified state depending on the actor's horizontal distance to its target.
  • A_CheckRings: Calls a specified state depending on the total number of rings held by all players.
  • A_CheckTargetRings: Calls a specified state depending on the number of rings held by the actor's target.
  • A_CheckThingCount: Calls a specified state depending on number of active Objects of a specified Object type.
  • A_CheckTotalRings: Calls a specified state if the total number of rings collected by all players is high enough.
  • A_CheckTrueRange: Calls a specified state if the actor's target is in range.
  • A_ChickenCheck: Resets a chicken if it is on the ground.
  • A_Look: Looks for a player and sets them as the actor's new target.
  • A_SearchForPlayers: Calls a specified state if the actor has found a player.

Custom value

Utility

  • A_ArrowCheck: Switches the state depending on the actor's vertical direction.
  • A_CheckBuddy: Checks if actor's "buddy" has at least one hit point left.
  • A_FaceTarget: Makes the actor face its target.
  • A_FaceTracer: Makes the actor face its tracer.
  • A_InfoState: Switches to an anchor state.
  • A_Repeat: Returns to a specified state a certain number of times. Useful for looping animations.

Miscellaneous

  Sonic Object Configuration [view]
General ClearMainCfg
Objects ObjectStateSoundFreeslot
Unlockable content EmblemExtraEmblemUnlockableConditionSet
Miscellaneous WipesCharacterLevelCutscene / SceneHudItem
Related links ActionsConstantsObject creation tutorial