Actions

From SRB2 Wiki
Jump to navigation Jump to search
This article or section is outdated and has not been fully updated to reflect the current version of SRB2.

Please help the Wiki by correcting or removing any misinformation, as well as adding any new information to the page.

To do
https://wiki.srb2.org/wiki/User:LJ_Sonik/List_of_outdated_Lua_stuff

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 A_FindTarget and A_FindTracer, respectively.

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.

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()

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 A_.

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

List of actions

To do
Add actions new to 2.2 to this list. See User:Monster Iestyn/2.2 Actions list for a full list of actions as of 2.2.0.

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.
  • A_CanarivoreGas: Spawns an object at the actor's X, Y, and Z coordinates.

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.

Flickies

  • A_FlickyAim: Aims the actor towards a general angle and distance from its target.
  • A_FlickySpawn: Spawns a flicky from the actor.
  • A_FlickyCenter: Handles flicky setup when used in conjunction with a placed Thing.
  • A_FlickyFly: Boosts the actor through the air (or water) towards its target.
  • A_FlickySoar: A version of A_FlickyFly meant for the Puffin.
  • A_FlickyCoast: Slows down the actor's movement, and changes its state.
  • A_FlickyHop: Makes the actor hop upon reaching the ground.
  • A_FlickyFlounder: Makes the actor flop about on the floor.
  • A_FlickyCheck: Checks the actor's airtime and vertical momentum, and changes its state accordingly.
  • A_FlickyHeightCheck: Checks the actor's height against its target, and changes its state accordingly.
  • A_FlickyFlutter: Slows down the actor and cuts its falling speed.

Miscellaneous

  Lua [view]
Language features SyntaxMetatables
SRB2 data ActionsConstantsFunctionsGlobal variablesHooksUserdata structures
SRB2Kart data Kart Userdata structuresKart FunctionsKart HooksKart Global Variables and Constants
Tutorials Freeslots and Object resourcesCustom player ability
  SOC [view]
General ClearMainCfg
Objects ObjectStateSoundSprite2SpriteInfoSprite2InfoFreeslot
Unlockable content EmblemExtraEmblemUnlockableConditionSet
Miscellaneous WipesCharacterLevelCutscene / ScenePromptMenuHudItem
Related links ActionsConstantsCustom Object tutorial