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. Actions are commonly associated with SOC, but they can also be called via Lua, either as part of a state definition or separately like any other function (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
Some actions allow their behavior to be configured through two signed 32-bit integer parameters, 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 first tic of the state. 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.
- 1 Actions with Lua
- 2 List of actions
Actions with Lua
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
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 can also create new actions, which can be called via SOC and outside of the Lua script that they were defined in. To create a new action, simply define a new function whose name starts with the prefix
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.
- 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.
- A_Custom3DRotate: Rotates the actor around its target in three dimensions.
- A_MaceRotate: Makes a mace or chain link spin around its target or swing from side to side.
- A_OrbitNights: Makes the Chaos Emeralds in NiGHTS Special Stages orbit around Super Sonic.
- A_RotateSpikeBall: Rotates the actor around its target or tracer.
- A_SparkFollow: Rotates the actor around its target; requires the target to be a player in Super form.
- A_UnidusBall: Thinker for the Unidus's/Egg Mobile's spikeballs. Rotates the actor around its target. Depending on the situation, the actor can be thrown away from its target.
- A_BuzzFly: Thinker for the golden and red Buzzes. Makes the actor slowly fly after the player.
- A_CrawlaCommanderThink: Thinker for the Crawla Commander.
- A_DetonChase: Thinker for the Deton. Makes the actor chase after a player and explode if it comes into contact with the player.
- A_EggShield: Thinker for Egg Guard's shield. Sets the position of the actor to its target and pushes away any players touching it at the front.
- A_FaceStabChase: Modified
A_Chasefor the CastleBot FaceStabber.
- A_GuardChase: Modified
A_Chasefor the Egg Guard.
- A_HoodThink: Thinker for the Robo-Hood.
- A_JetbThink: Thinker for the Jetty-Syn Bomber.
- A_JetChase: Modified
A_Chasefor the Jetty-Syns.
- A_JetgShoot: Firing attack for the Jetty-Syn Gunner.
- A_JetgThink: Thinker for the Jetty-Syn Gunner.
- A_JetJawChomp: Attacking thinker for the Jet Jaw. Chases towards the actor's target as long as it is in view.
- A_JetJawRoam: Roaming thinker for the Jet Jaw.
- A_MinusCheck: Used to reset the Minus to digging form when it hits the floor.
- A_MinusDigging: Used by the Minus when digging in the ground.
- A_MinusPopup: Used by the Minus when popping out of the ground.
- A_PointyThink: Thinker for the Pointy.
- A_SharpChase: Thinker for the Sharp.
- A_SharpSpin: Thinker for the Sharp's spin attack.
- A_SkimChase: Modified
A_Chasefor the Skim.
- A_SnailerThink: Thinker for the Snailer.
- A_VultureCheck: Thinker for the BASH's flight. If stopped, the actor falls down until it reaches the ground.
- A_VultureVtol: Thinker for the BASH when aiming. The actor adjusts its Z position until a suitable height to attack its target from is reached.
- A_Boss1Chase: Basic chasing behavior and thinker used by the Egg Mobile. An attack may also be randomly selected by this action.
- A_Boss1Laser: Egg Mobile's laser attack thinker. Unlike other actions, this action will automatically call itself again repeatedly for the rest of the current state's duration.
- A_Boss1Spikeballs: Used to spawn each of the Egg Mobile's spikeballs (once per use of the action) during pinch phase.
- A_Boss2Chase: Egg Slimer's main thinker, for moving in a circle around an Axis and spraying goop around itself.
- A_Boss2Pogo: Egg Slimer's pinch phase thinker, for pogoing around and spraying goop around itself.
- A_Boss2PogoSFX: Old pogoing thrust behavior used by the Egg Slimer in previous versions of SRB2.
- A_Boss2PogoTarget: New pogoing thrust behavior used by the Egg Slimer from v2.1 onwards.
- A_Boss2TakeDamage: Egg Slimer's pain-invincibility handler; prevents the actor from being damaged again for a limited time.
- A_Boss3Path: Used by the fake Sea Egg clones to behave similarly to the Sea Egg itself, but taking into account where the Sea Egg itself is actually located.
- A_Boss3TakeDamage: Sea Egg's pain-invincibility handler; allows it to start moving along the paths of boss waypoints again.
- A_Boss4Raise: Used by the Eggscalibur to signal when to raise the cage surrounding it.
- A_Boss4Reverse: Used by the Eggscalibur to signal when to reverse the direction its spikeball arms spin around it.
- A_Boss4SpeedUp: Used by the Eggscalibur to signal when to increase the speed its spikeball arms spin around it.
- A_Boss7Chase: Modified
A_Chasefor v2.0's Brak Eggman.
- A_Boss7FireMissiles: Fires four missiles of a specified type from around the actor's middle. Used by v2.0's Brak Eggman to fire grabbable missiles at the player.
- A_BossDeath: Thinker for bosses after they have been defeated.
- A_BossFireShot: A specialized firing attack that allows the Egg Mobile (in previous versions of SRB2) and the Sea Egg to fire missiles from specific positions relative to themselves.
- A_BossJetFume: Used to spawn Egg Mobile-style jet fumes, a Sea Egg-style propeller, a Metal Sonic-style jet fume, or an Eggscalibur-style jet flame.
- A_BossScream: Used to spawn explosions around the actor during a boss death animation.
- A_BossZoom: An unused action similar in function to
A_SkullAttack, but with a modifiable speed.
- A_BrakChase: Modified
A_Chasefor Brak Eggman; movement speed and attacks depend on the actor's health.
- A_BrakFireShot: Makes the actor shoot an Object at its target, offset to match where Brak Eggman's gun is.
- A_BrakLobShot: A specialized version of
A_LobShotused by Brak Eggman. The actor lobs an Object at the floor a third of the way towards the target, assuming it will bounce the rest of the way.
- A_FocusTarget: Used by the Egg Mobile's laser to move towards the target player.
- A_AttractChase: Thinker for rings, CTF team rings (red and blue) and coins. If a nearby player has an Attraction Shield, the actor will be pulled towards it.
- A_OldRingExplode: Makes the actor explode like the old Explosion Ring from v1.09.4.
- A_RingDrain: Removes a specified number of rings from the actor's target player.
- A_RingExplode: Makes the actor explode like an Explosion Ring or Grenade Ring.
- A_ThrownRing: Thinker for thrown rings.
Powers and monitors
- A_1upThinker: Changes actor's sprite to nearest player's 1-up sprite.
- A_AwardScore: Awards a specified amount of points to a player.
- A_BombShield: Gives the target player an Armageddon Shield.
- A_CustomPower: Gives the target player a power-up.
- A_EggmanBox: Deals non-elemental damage to the target player. Used by the Eggman Monitor.
- A_ExtraLife: Gives the target player an extra life.
- A_ForceShield: Gives the target player a Force Shield.
- A_GiveWeapon: Gives the target player one or more weapon panels.
- A_GravityBox: Reverses the target player's gravity for the specified time.
- A_Invincibility: Makes the target player invincible.
- A_JumpShield: Gives the target player a Whirlwind Shield.
- A_MixUp: Used as a thinker for the Teleport Monitor.
- A_MonitorPop: Used as a thinker for when a monitor is popped.
- A_PityShield: Gives the target player a Pity Shield.
- A_RecyclePowers: Used as thinker for the Recycler Monitor.
- A_RingBox: Gives the target player a certain amount of rings.
- A_RingShield: Gives the target player an Attraction Shield.
- A_SuperSneakers: Gives the target player Super Sneakers.
- A_WaterShield: Gives the target player an Elemental Shield.
- A_BubbleSpawn: Spawns a randomly sized bubble if underwater. Used by the Air Bubble Patch.
- A_FanBubbleSpawn: Spawns a randomly sized bubble if underwater. Used by the Fan.
- A_GhostMe: Spawns an afterimage of the actor's current position.
- A_ParticleSpawn: Spawns a particle at a specified interval.
- A_RockSpawn: Spawns rocks at a specified interval.
- A_SmokeTrailer: Spawns a trail of Objects when used repeatedly.
- A_SpawnFreshCopy: Spawns a copy of the actor. Used to respawn Brak Eggman's electric barrier.
- A_SpawnObjectAbsolute: Spawns an Object at an absolute location.
- A_SpawnObjectRelative: Spawns an Object relative to the actor's position.
- 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_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.
- A_Pain: Plays the actor's
- A_PlayActiveSound: Plays the actor's
- A_PlayAttackSound: Plays the actor's
- A_PlaySeeSound: Plays the actor's
- A_PlaySound: Plays a sound effect.
- A_Scream: Plays the actor's
- A_DualAction: Performs two actions simultaneously.
- A_LinedefExecute: Executes a linedef executor.
- A_RandomState: Randomly chooses between two states.
- A_RandomStateRange: Randomly chooses a state from a range.
- A_RemoteAction: Tells the actor's target to perform an action remotely.
- A_RemoteDamage: Damages, kills or removes the actor or its target/tracer remotely.
- A_SetTargetsTarget: Changes the actor's target to the target of its current target.
- A_SetObjectState: Sets the state of the actor's target.
- A_SetObjectTypeState: Sets the state of Objects of a certain Object type.
- A_ChangeAngleAbsolute: Sets the actor's angle.
- A_ChangeAngleRelative: Sets the actor's angle relative to its current angle.
- A_ChangeColorAbsolute: Sets the actor's skin color.
- A_ChangeColorRelative: Sets the actor's skin color relative to its current skin color.
- A_FindTarget: Sets the actor's target.
- A_FindTracer: Sets the actor's tracer.
- A_SetFuse: Set the actor's fuse timer.
- A_SetObjectFlags: Modifies the actor's primary Object flags.
- A_SetObjectFlags2: Modifies the actor's secondary Object flags.
- A_SetRandomTics: Randomly sets the duration of the actor's current state.
- A_SetReactionTime: Sets the actor's reaction time.
- A_SetScale: Sets the actor's scale.
- A_SetTics: Sets the duration of the actor's current state.
- 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.
- A_CheckCustomValue: Calls a specified state depending on the actor's custom value.
- A_CheckCusValMemo: Calls a specified state depending on the actor's custom memory value.
- A_CusValAction: Remotely calls an action, but modifies Var1 and Var2 depending on the actor's custom value.
- A_RelayCustomValue: Changes the custom value of the actor's target/tracer.
- A_SetCustomValue: Changes the actor's custom value.
- A_UseCusValMemo: Saves or reloads the actor's custom value.
- 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.
- A_Explode: Damages Objects within range of the actor.
- A_Fall: Changes the actor's flags. Used by players who have died.
- A_ForceWin: If there are any living players, makes them finish the level, as if they stepped into the exit sector.
- A_GoopSplat: Changes the actor's flags. Used by the goop projectiles of v2.0's Brak Eggman.
- A_OverlayThink: Thinker for overlay-like Objects. Moves the actor to the position of its target.
- A_SetSolidSteam: Makes Gas Jets solid.
- A_SignPlayer: Changes the state and skin color of the Level End Sign.
- A_SlingAppear: Used to make the Hidden Chain appear in the map.
- A_SpikeRetract: Toggles the solidity of spikes.
- A_ToggleFlameJet: Turns flame jets on and off.
- A_UnsetSolidSteam: Makes solid Gas Jets intangible again.
|Language features||Syntax • Metatables|
|SRB2 data||Actions • Constants • Functions • Global variables • Hooks • Userdata structures|
|Tutorials||Freeslots and Object resources • Custom player ability|
|Sonic Object Configuration||[view]|
|Unlockable content|| |
|Related links||Actions • Constants • Custom Object tutorial|