Overlay

Overlays are a special type of utility Object that exist for use in SRB2. These are designed to allow extra visuals to be displayed in front of or behind the sprite of a target Object – such as the player – regardless of the angle the target is viewed from.

Setup

Overlays are created by spawning an Object with the Object type MT_OVERLAY. These can be created with either SOCs or Lua scripts; however, in practice it is far easier to use Lua scripts due to the complexity of setting them up via SOC.

By default, an overlay Object will be spawned with the state S_NULL; because of this, the Object's state must be changed immediately after being spawned, otherwise it will disappear before it can be used. The state chosen for the overlay Object determines what sprite it displays in front or behind the target Object; this can be either a static image or an animation, depending on which states follow the overlay's current state. The overlay Object must also have a target Object set immediately after being spawned; this is the Object the overlay follows and displays a sprite in front or behind of. If this is not set, or the chosen target Object disappears during gameplay, the overlay Object itself will disappear from existance. At the very least a newly-created overlay Object must have both a state and target Object set in order to function as an overlay – other properties, such as a skin or skin color, can be applied to modify how the sprites appear on the overlay if needed.

The actions of the states an overlay Object uses are not important, but the Var1 and Var2 of the states used will have special behavior:

• Var1 determines whether the overlay displays in front or behind its target; Var1 set to 0 will display it in front, Var1 set to 1 and above will display it behind
• Var2 determines the vertical offset the overlay is displayed at, relative to the bottom of the overlay's target

Note that if a state has the FF_ANIMATE animation flag, Var1 and Var2 will be used for the state's animation instead, and the overlay will always display in front of its target with no vertical offset.

Here is an example of what could be found in a Lua script to spawn an overlay, where the target Object is called mobj and the newly-created overlay's state is set to S_PLAY_STND:

-- the overlay is spawned by P_SpawnMobj at mobj's co-ordinates, and a new local variable "overlay" is set to the new object
local overlay = P_SpawnMobj(mobj.x, mobj.y, mobj.z, MT_OVERLAY)

-- these are required to be set for the overlay to work
overlay.target = mobj
overlay.state = S_PLAY_STND -- example state

-- these are not required - they are just extras for this example
overlay.skin = "sonic"
overlay.color = SKINCOLOR_BLUE

In the above example, the newly-created overlay Object will display Sonic's standing and waiting animations (colored blue) in front of its target while following it around. As long as the target Object continues to exist, it will continue to do this indefinitely.

Examples in unmodified SRB2

• The Extra Life Monitor uses an overlay to display the icon of the nearest player. This is handled by the action A_1upThinker while the monitor is still intact and by A_MonitorPop when the monitor is popped.
• The Level End Sign uses an overlay to display the sprite of the player that spun it; this is handled by the action A_SignPlayer.
• All shield orbs are capable of spawning overlays – for each of the states SeeState, MeleeState and MissileState, an overlay will be spawned to display it unless it is S_NULL. As of v2.2, the Armageddon, Bubble, Elemental, Flame, and Lightning Shield orbs use this feature.