Lua/Functions

From SRB2 Wiki
< Lua
Jump to: navigation, search

This is a comprehensive list of all functions that can be utilized by Lua scripting, excluding those that are part of userdata structures.

In the "function" column of each table below, bolded text is the actual name of the function, text with italics represent argument types (e.g.: int, mobj_t or boolean) which should not be written in actual Lua scripts, while arguments surrounded by brackets ( [ ] ) are optional and can be omitted when using the function. Note that all argument names displayed in this article do not actually have any meaning in Lua scripts, except where noted; they are there to simplify explaining their purposes. Some functions may have alternative syntax: this may depend on the type of variables supplied for a particular argument position, for instance.

Math library

These are the functions included in SRB2's Math library. These are generally simple functions that are to be used in mathematical contexts.

Basic math

These are basic mathematical functions that can be used in any context.

Function Return value(s) Description
abs(int a) int Returns the absolute value (the number's distance from zero) of a.

Note: abs(INT32_MIN) does not have a corresponding value, as the value that would be returned by this function is out of range.

min(int a, int b) int Returns the smaller value of a or b.
max(int a, int b) int Returns the larger value of a or b.

Angle math

These are mathematical functions that are designed to be used with angles. In SRB2, these are usually represented by large integers where an angle of 1° is represented by the constant ANG1, which has a size of 11930465 – see Constants > Angles for a full list of constants used to represent angles in this scale. Sometimes, angles may also be represented as fixed-point integers (see below for information on these), where an angle of 1° is represented by the constant FRACUNIT. Some of these functions are used to convert between these two different ways of expressing angles as integers.

Also included here are the basic trigonometric functions (sin, cos and tan), which return values in the fixed-point scale.

Function Return value(s) Description
sin(angle a) fixed Returns the sine of the given angle as a fixed-point value. Output values range from -FRACUNIT to FRACUNIT.
cos(angle a) fixed Returns the cosine of the given angle as a fixed-point value. Output values range from -FRACUNIT to FRACUNIT.
tan(angle a, boolean newtan?) fixed Returns the tangent of the given angle as a fixed-point value. Output values range from about -1303*FRACUNIT to about 1303*FRACUNIT, or INT32_MIN (-32768*FRACUNIT) for 90°, 270°, etc.

Note: this function normally does not return the correct values, but instead those for 90 degrees ahead of the actual answer. A possible reason for this is because internally SRB2's tangent array is exclusively used for the rendering code. To get around this, use tan(angle, true).

FixedAngle(fixed a) angle Converts an integer in the fixed-point scale to an angle value.

e.g.: FixedAngle(90*FRACUNIT) will return ANGLE_90

AngleFixed(angle a) fixed Converts an angle value to an integer in the fixed-point scale.

e.g.: AngleFixed(ANGLE_90) will return 90*FRACUNIT

InvAngle(angle a) angle Returns the "inverse" of the given angle (360° - a).

e.g.: InvAngle(ANGLE_45) will return ANGLE_315

Fixed-point math

These are mathematical functions that are designed to be used with fixed-point integers – i.e. integers expressed as multiples of the constant FRACUNIT, or integers bit-shifted to the left by FRACBITS (FRACUNIT is the same as 1<<FRACBITS). In this system, FRACUNIT itself is treated as 1, 2*FRACUNIT (or FRACUNIT*2) is treated as 2, and so on.

Note: as Lua in SRB2 does not support floating-point numbers (i.e. 0.5, 0.25, 1.1, etc), non-integer multiples of FRACUNIT should instead be written as fractions with the numerator and denominator surrounding the constant – e.g. 0.5 is written as FRACUNIT/2, and 1.25 (or 5/4) is written as 5*FRACUNIT/4.

Function Return value(s) Description
FixedMul(fixed a, fixed b) fixed Returns the result of multiplying a by b in the fixed-point scale.

e.g: FixedMul(2*FRACUNIT, 3*FRACUNIT) will return 6*FRACUNIT

FixedInt(fixed a) fixed Returns the integer component of a as a normal integer.

e.g.: FixedInt(45*FRACUNIT) will return 45

FixedDiv(fixed a, fixed b) fixed Returns the result of dividing a by b in the fixed-point scale.

e.g.: FixedDiv(6*FRACUNIT, 3*FRACUNIT) will return 2*FRACUNIT

FixedRem(fixed a, fixed b) fixed Returns the remainder of dividing a by b in the fixed-point scale.

Note: this function will crash the game if b is negative.[confirm? – discuss]

FixedSqrt(fixed a) fixed Returns the square root of a in the fixed-point scale.

e.g.: FixedSqrt(16*FRACUNIT) will return 4*FRACUNIT

FixedHypot(fixed a, fixed b) fixed Returns the hypotenuse of a and b in the fixed-point scale (i.e. the length of the longest side of a right-angled triangle with sides a and b also present).

e.g. FixedHypot(3*FRACUNIT, 4*FRACUNIT) will return 5*FRACUNIT

FixedFloor(fixed a) fixed Returns the floor of a (the largest integer that is not larger than a) in the fixed-point scale.
FixedTrunc(fixed a) fixed Returns the value of a rounded to the nearest whole number towards 0 (or a truncated to zero decimal digits) in the fixed-point scale.
FixedCeil(fixed a) fixed Returns the ceiling of a (the smallest integer that is not smaller than a) in the fixed-point scale.
FixedRound(fixed a) fixed Returns the value of a rounded to the nearest whole number away from 0 in the fixed-point scale.

Miscellaneous

These are simple yet specialised functions that do not fit with the Basic library set of functions.

Function Return value(s) Description
GetSecSpecial(int special, int section) int Returns the sector effect number given for a particular sector special section (expected to be a value from 1 to 4), special being the composite sector special number containing all sections for a particular sector (sector.special). Output values range from 0 to 15 – see Sector types for the sector specials in each group/section corresponding to each return value.

e.g.: if a sector uses the Damage (Fire) sector special from Group 1, GetSecSpecial(sector.special, 1) will return 3.

All7Emeralds(int flags) boolean Returns true or false depending on whether flags contains all emerald flags EMERALD1 to EMERALD7 within. Expected to be used for checking either the Single Player/Co-op emeralds collected by all players (emeralds), or the multiplayer emeralds (for gametypes Match, CTF and Tag) collected by a particular player (player.powers[pw_emeralds]).
ColorOpposite(int color) int, int Returns both the opposite skin color for color, and the associated sprite frame number for the opposite color (latter is used for the exit sign).

e.g.: ColorOpposite(SKINCOLOR_WHITE) will return the values SKINCOLOR_BLACK and 10.

HUD library

These are the functions included in SRB2's HUD library. These functions relate to the head-up display, and are all prefixed with hud. (aside from the patch/string drawing functions). Where they are required, the coordinates provided to these functions should be for the base 320×200 pixel resolution – such that x is a value between 0 and 320 (measured from the left of the screen), y is a value between 0 and 200 (measured from the top of the screen), and x = 0, y = 0 is the top-left corner of the screen. These values will automatically be adjusted by the game for other resolutions.

Main

Function Return value(s) Description
hud.enable(string huditem) nil Enables huditem (see below for a list of valid options) if it was disabled by hud.disable.
hud.disable(string huditem) nil Disables huditem (see below for a list of valid options), preventing the game from drawing it.
hud.add(function func, string hook) nil Adds a new HUD drawing function. "hook" determines when the contents of the function are run. See below for a list of valid options for "hook" and the format functions for them take.

Togglable HUD items

Valid huditem string options, for the functions hud.enable and hud.disable:

Huditem name Description
"stagetitle" Stage title card
"textspectator" Information text as a spectator
"score" Score text and counter
"time" Time text and counter
"rings" Rings text and counter
"lives" Lives picture and counter
"weaponrings" Match/CTF – Weapon ring icons
"powerstones" Match/CTF – Chaos Emerald icons
"nightslink" NiGHTS link counter
"nightsdrill" NiGHTS drill bar
"nightsrings" NiGHTS ring counter
"nightsscore" NiGHTS score counter
"nightstime" NiGHTS time counter
"nightsrecords" NiGHTS screen text (Bonus time start, "Get n [more] Spheres", Ending bonuses)
"rankings" Rankings/Scores HUD – Multiplayer rankings (all gametypes)
"coopemeralds" Rankings/Scores HUD – Single Player Chaos Emerald icons
"tokens" Rankings/Scores HUD – Single Player Tokens icon and counter
"tabemblems" Rankings/Scores HUD – Single Player Emblems icon and counter

HUD hooks

Valid hook string options for the function hud.add:

Hook name Function format Description
"game" function(drawer v, [player_t stplyr, [camera_t cam]]) The function is run when the Game HUD is displayed. (Default value)

Notes:

  • stplyr is the player the HUD is being shown for
  • cam is the camera used by stplyr
"scores" function(drawer v) The function is run when the Rankings/Scores HUD is displayed.

Patch/string drawing functions

These functions can only be used within functions hooked with hud.add. Note that the v prefix given to all functions listed here is adjustable – this can be any name you like, e.g. drawer.draw can be used instead of v.draw, if the name of the first argument in the hud.add function is given as drawer instead of v.

Function Return value(s) Description
v.patchExists(string name) boolean Returns true if a graphic lump "name" exists in any WAD file loaded, returns false if not.
v.cachePatch(string name) patch_t Caches a new patch using a graphic with "name" as the name. Returns nil if the graphic doesn't exist.
v.draw(int x, int y, patch_t patch, [int flags, [colormap c]]) nil Draws a patch at the screen coordinates given.

Notes:

  • flags determines the video flags given, which control extra effects such as translucency.
  • c determines the colormap applied to the patch – use v.getColormap to obtain a value that can be used here.
v.drawScaled(fixed x, fixed y, fixed scale, patch_t patch, [int flags, [colormap c]]) nil Draws a patch at the screen coordinates given, but at a specific scale (e.g.: FRACUNIT is normal scale, FRACUNIT/2 is half normal scale, 2*FRACUNIT is twice normal scale, etc).

Notes:

  • Coordinates are required to be fixed point values (e.g.: FRACUNIT is one pixel, FRACUNIT/2 is half a pixel, 2*FRACUNIT is two pixels, etc).
  • flags determines the video flags given, which control extra effects such as translucency.
  • c determines the colormap applied to the patch – use v.getColormap to obtain a value that can be used here.
v.drawNum(int x, int y, int num, [int flags]) nil Draws a number at the screen coordinates given.

Notes:

  • flags determines the video flags given, which control extra effects such as color and translucency.
  • Unlike v.drawPaddedNum, this can also handle negative numbers.
v.drawPaddedNum(int x, int y, int num, [int digits, [int flags]]) nil Draws a number at the screen coordinates given with a set number of digits. Leading zeros will be added as padding if the number is not large enough to fit the number of digits specified.

Notes:

  • flags determines the video flags given, which control extra effects such as color and translucency.
  • Unlike v.drawNum this will not handle negative numbers.
v.drawFill([int x, [int y, [int width, [int height, [int color]]]]]) nil Fills a box of dimensions width by height with a single palette color number at the screen coordinates given. (If no parameters are given, this will default to a black box covering the entire screen.)

color also determines the video flags given, if they are added to the palette color number – only the flags V_SNAPTOTOP, V_SNAPTOBOTTOM, V_SNAPTOLEFT and V_SNAPTORIGHT will have any effect, however.

v.drawString(int x, int y, string text, [int flags, [string align]]) nil Draws text on the screen at the screen coordinates given.

Notes:

  • flags determines the video flags given, which control extra effects such as color and translucency.
  • align determines the alignment of the text or otherwise miscellaneous traits – see below for a full list of valid options.
v.stringWidth(string text, [int flags, [string widthtype]) int Returns what the width of the text displayed as graphics on the screen would be.

Notes:

  • flags determines the video flags given to the string, though only the scaling flags will have any effect on the size of the width returned by the function.
  • widthtype determines what font the string is in, which can also affect the size of the width returned by the function – see below for a full list of valid options.
v.getColormap([string/int skin, [int color]]) colormap Returns the colormap to apply to a patch for a particular character skin and/or skin color, as a special type of userdata which can only be used by v.draw or v.drawScaled. Skin names such as "sonic" or "tails" can be used, but their skin slot numbers can also be used (e.g. 0 for "sonic", 1 for "tails", etc). If either of these are used, the skin's startcolor value can affect the range of palette colors replaced by the given skin color's palette colors.

Certain negative skin numbers have special effects on the colormap returned for a patch to use:

Value Description
-1 Default – this is used by default if no skin is supplied, defaulting to remapping palette colors 160–175 (green) to the given skin color's palette colors.
-2 Boss flash – the colormap used when a boss is flashing in pain; palette color 31 (black) is remapped to palette color 0 (near-white). Overrides the effects of skin colors.
-3 Metal Sonic flash – the colormap used when Metal Sonic (Battle) is flashing in pain; palette color 239 (dark blue) is remapped to palette color 0 (near-white). Overrides the effects of skin colors.
-4 All-white flash – the colormap used when Brak Eggman is flashing in pain; all palette colors are remapped to palette color 0 (near-white). Overrides the effects of skin colors.
v.width() int Returns the screen width.
v.height() int Returns the screen height.
v.dupx() int, int Returns the screen's X scale, as both an integer and fixed point value.
v.dupy() int, int Returns the screen's Y scale, as both an integer and fixed point value.
v.renderer() string Returns the renderer used, as a string.

Possible return values:

Alignment types

Valid alignment string options for v.drawString:

Alignment name Description
"left" (Default value) The string is left-aligned; the x-coordinate is the left edge of the string graphic
"right" The string is right-aligned; the x-coordinate is the right edge of the string graphic
"center" The string is center-aligned; the x-coordinate is the center of the string graphic
"fixed" Coordinates are required to be treated as fixed-point values instead of normal integers, allowing for positions at fractions of a pixel on the screen (e.g FRACUNIT is one pixel, FRACUNIT/2 is half a pixel, 2*FRACUNIT is two pixels, etc)
"small" The string is drawn in a small font, and is left-aligned
"small-right" The string is drawn in a small font, and is right-aligned
"thin" The string is drawn in a thin font, and is left-aligned
"thin-right" The string is drawn in a thin font, and is right-aligned

Width types

Valid widthtype options for v.stringWidth:

Alignment name Description
"normal" (Default value) The string is drawn in a normal font
"small" The string is drawn in a small font
"thin" The string is drawn in a thin font

Console library

These are the functions included in SRB2's console library. These functions relate to the console and/or commands/variables to be executed by the console.

Function Return value(s) Description
COM_AddCommand(string name, function fn, [int flags]) nil Format of fn: function(player_t player, [string arg, [...]])

Registers a console command with the specified name, that executes the specified function when called. (The first argument is the player who executed the command, and all subsequent arguments are arguments passed to the command.)

Flags can be set to limit who can execute the command, accepting either numbers or true/false:

Value(s) Description
0
false
Default (anyone can use it)
1
true
Server/admin-only
2 Player 2 (splitscreen) only
3 Server/admin only + player 2 (splitscreen) only
COM_BufAddText(player_t player, string text) nil Adds the specified text to player's console buffer, but does not actually execute the command.
COM_BufInsertText(player_t player, string text) nil Executes a console command in player's console.
CV_RegisterVar(table t) consvar_t Format of t: table{string name, string defaultvalue, int flags, PossibleValue pv, function() func}

Registers a cvar with the specified name for use in the console, with its default value set to the specified value in string form. The possible values accepted are specified by pv. If the CV_CALL flag is set, the specified function is executed when the cvar is changed. Returns the consvar created.

pv can either be set to the name of one of the pre-existing PossibleValue ranges listed below, or a table listing possible values, or set to nil if not needed:

Name Range
CV_OnOff {Off = 0, On = 1}
CV_YesNo {No = 0, Yes = 1}
CV_Unsigned {MIN = 0, MAX = 999999999}
CV_Natural {MIN = 1, MAX = 999999999}

Custom PossibleValue tables need to be formatted as such:

{string1=value1, string2=value2, [...]}

This gives each possible value listed in the table a string name of its own, which can be used in the console itself when the variable is in use.

If MIN and MAX are used as string names for possible value entries, these will act as the minimum and maximum of a bounded range of possible values, allowing any value in-between the two to be picked as well. Otherwise, the selectable values for the console variable are limited explicitly only to the possible value entries listed in the table. Example of custom MIN and MAX values:

{MIN = 20, MAX = 50}

The contents of CV_RegisterVar can alternatively be laid out as such:

CV_RegisterVar({name = , defaultvalue = , flags = , PossibleValue = , func = })

Or:

CV_RegisterVar({
	name = ,
	defaultvalue = ,
	flags = ,
	PossibleValue = ,
	func = 
})

In the above two layouts the names of the variables of the table are written out, and so do not need to be placed in any particular order unlike as in the above.

CONS_Printf(player_t player, string text) nil Prints the text given to the console for player. This is similar to print(text), but this will only print for one player.

Certain ASCII characters will have special effects when printed out to the console by this function. These can either be given using decimal (\nnn) or hexadecimal codes (\xnn or \xnnnn), e.g.: \130 and \x82 will both cause text following the code to turn yellow. See Lua > Special characters for a list of these.

Base library

These are the functions included in SRB2's Base library. Note that the majority of the functions listed here are grouped according to their location in SRB2's source code.

Base functions

Function Return value(s) Description
print(string output, [string output2, [...]]) nil Outputs text in the console. Each output string will be separated into different lines.

Certain ASCII characters will have special effects when printed out to the console by this function. These can either be given using decimal (\nnn) or hexadecimal codes (\xnn or \xnnnn), e.g.: \130 and \x82 will both cause text following the code to turn yellow. See Lua > Special characters for a list of these.

freeslot(string resource, [string resource2, [...]]) nil Automatically initializes a new named resource based on the name given, declaring the name for the next freeslot available for the appropriate resource type. (e.g.: "MT_NEWOBJECT" will add a new object type). Only resources with prefixes "MT_" (object type), "S_" (state), "SPR_" (sprite) or "sfx_" (sound) can be made with this.

Note: resources that begin with "MT_" (object type), "S_" (state), or "SPR_" must be in all capital letters, while "sfx_" resources must be all lowercase.

addHook(string hook, function fn, [int/string extra]) nil Binds a function to a hook (i.e. the function will be run when a particular event happens). See Lua/Hooks for more information on using this function.
super(mobj_t actor, int var1, int var2) nil Only use this inside of an overridden A_Action function. Calls the original version of the action.
EvalMath(string word) int Converts a string to a number by checking it against the existing lists of constants available for Lua, as well as performing any operations written inside the string – e.g.: EvalMath("MF_NOGRAVITY|MF_SOLID") will return the value of MF_NOGRAVITY|MF_SOLID, which is 514.

Note: This function is deprecated, and may not work as expected. _G["CONSTANT"] has the same effect as this function for a single constant on its own, though operations are not supported directly. Furthermore, EvalMath parses text as if it were for SOC and not Lua – i.e. everything must be converted to all-uppercase to work, even lowercase constants. _G["CONSTANT"] does not require conversion between uppercase and lowercase, in contrast.

M_Random

Function Return value(s) Description
P_RandomFixed() fixed Returns a random integer from 0 to FRACUNIT-1 (65535).
P_RandomByte() int Returns a random integer from 0 to 255.
P_RandomKey(int a) int Returns a random integer from 0 to a - 1.

Note: a should not be larger than 65536. For all larger values there will be only 65536 possible different results this function can return, which will be spread out across the full range given; the rest of the numbers will be skipped.

P_RandomRange(int a, int b) int Returns a random integer from a to b, inclusive.

Note: The difference between a and b should not be larger than 65536. For all larger values there will be only 65536 possible different results this function can return, which are spread out across the full range given; the rest of the numbers will be skipped.

P_Random() int Deprecated alternative name for P_RandomByte
P_SignedRandom() int Returns a random integer from -128 to 127.
P_RandomChance(fixed p) boolean Returns true p% of the time, where p is a fixed point number from 0 to FRACUNIT. For example, P_RandomChance(FRACUNIT/2) returns true 50% of the time.

P_Maputl

Function Return value(s) Description
P_AproxDistance(fixed dx, fixed dy) fixed Compares distances dx and dy, and returns an approximate distance between them.

Note: this function will normally return a positive value, except if the distance is 38768 fracunits or larger in which case it will return negative values.

P_ClosestPointOnLine(fixed x, fixed y, line_t line) fixed, fixed Alternative version: P_ClosestPointOnLine(fixed x, fixed y, fixed x1, fixed y1, fixed x2, fixed y2)

Returns both the x and y coordinates (as two separate returned values) of the closest point to coordinates x and y on the line given.

If a set of 4 fixed-point integers (x1, y1, x2, y2) are given instead of a line_t variable, these become the coordinates of a custom-defined line with vertexes at coordinates (x1, y1) and (x2, y2).

P_Enemy

Function Return value(s) Description
P_CheckMeleeRange(mobj_t actor) boolean Returns true if actor's target is within the actor's melee range, returns false if not.
P_JetbCheckMeleeRange(mobj_t actor) boolean Same as P_CheckMeleeRange, except the melee range is adjusted for use with the Jetty-Syn Bomber.
P_FaceStabCheckMeleeRange(mobj_t actor) boolean Same as P_CheckMeleeRange, except the melee range is adjusted for use with the CastleBot FaceStabber.
P_SkimCheckMeleeRange(mobj_t actor) boolean Same as P_CheckMeleeRange, except the melee range is adjusted for use with the Skim.
P_CheckMissileRange(mobj_t actor) boolean Returns true if actor is able to shoot its target at the moment. Returns false if actor.reactiontime has not reached 0, or actor can't see the target, or otherwise the result is randomly decided based on the distance between them.
P_NewChaseDir(mobj_t actor) nil Changes actor.movedir to be the decided best direction of the actor to be in relation to its target (provided it has one of course).

Note: these directions include only the 8 basic cardinal directions (N, S, E, W, NE etc; also see the DI_ constants).

P_LookForPlayers(mobj_t actor, [fixed dist, [boolean allaround?, [boolean tracer?]]]) boolean Can the actor find a player with the conditions provided? If yes, this returns true and the actor's target is set to the first player found; otherwise this returns false (but the actor's target is unchanged).
  • dist determines the distance limit for the actor to check for players in; if dist is set to 0 however, this distance limit will be infinite.
  • allaround? determines whether the actor will look all around itself for players or just within 90° of the direction it is currently facing.
  • tracer? determines whether to use actor.tracer instead of actor.target, useful for homing missiles such as the Deton (as missiles set their target to the object who shot them, so they can't harm them).

dist defaults to 0 if not given, while allaround? and tracer both default to false if not given.

P_Mobj

Function Return value(s) Description
P_SpawnMobj(fixed x, fixed y, fixed z, int type) mobj_t Creates and returns a new Object of a given type at the x, y, and z coordinates given. Various attributes may be given to it as soon as it is spawned, such as a skin color or secondary Object flags. Further Objects may be spawned within this function to be linked to the new Object if necessary. If the new Object is given the MF_RUNSPAWNFUNC flag during this function, the action set for its SpawnState Object type property will be run by this function.

The hook "MobjSpawn" can be used to modify or replace some of the effects of this function.

Note: this is the basic function for spawning all Objects in SRB2. All other listed Lua functions (including actions) that spawn an Object therefore use this function internally to spawn them, and any changes made to this function by the "MobjSpawn" hook will affect them as well.

P_RemoveMobj(mobj_t mobj) nil Removes the Object and its thinker from existence. The hook "MobjRemoved" can be used to apply additional effects to this function.

Note: the removed Object cannot be referenced again in Lua after using this function.

Note 2: this function will produce an error if it attempts to remove an Object belonging to a player (i.e.: mobj.player must be nil for this function to work).

P_SpawnMissile(mobj_t source, mobj_t dest, int type) mobj_t Spawns a missile Object with the default missile positioning, sending it forward to dest at the value of its Speed Object type property. This returns the Object spawned by the function.
P_SpawnXYZMissile(mobj_t source, mobj_t dest, int type, fixed x, fixed y, fixed z) mobj_t Spawns a missile Object at specific x, y, and z coordinates, sending it forward to dest at its speed value. This returns the Object spawned by the function.
P_SpawnPointMissile(mobj_t source, fixed dest_x, fixed dest_y, fixed dest_z, int type, fixed x, fixed y, fixed z) mobj_t Same as P_SpawnXYZMissile, except the dest doesn't have to be an Object's coordinates! This returns the Object spawned by the function.
P_SpawnAlteredDirectionMissile(mobj_t source, int type, fixed x, fixed y, fixed z, int angle_shift) mobj_t Spawns a missile Object at the value of its Speed Object type property, but with an angle relative to the direction its source was aiming at. (The source Object must be a missile itself, and must have a target too so the spawned missile will share it's target!) This returns the object spawned by the function.
P_ColorTeamMissile(mobj_t missile, player_t player) nil In Team Match or CTF, this changes missile's color to match the player's team color (red if player is in the red team, or steel blue if in the blue team). In any other gametype, this will do nothing.
P_SPMAngle(mobj_t source, int type, angle angle, [int allowaim, [int flags2]]) mobj_t Spawns a missile Object at the value of its Speed Object type property, assuming source is a player. angle sets what direction to fire the missile in. If allowaim is set to a non-zero value, the player's vertical aiming angle determines the vertical angle the missile is fired at; otherwise, it is fired straight forward by default. flags2 allows additional flags to be added on to the missile's secondary Object flags (such as MF2_RAILRING to make the missile act like the rail ring weapon). This returns the Object spawned by the function.
P_SpawnPlayerMissile(mobj_t source, int type, [int flags2]) mobj_t Functionally identical to P_SPMAngle, except with the missile's angle always being the source's angle, and the player's vertical aiming angle will always be used. This returns the Object spawned by the function.
P_MobjFlip(mobj_t mobj) int Returns 1 or -1 depending on whether the Object is flipped (i.e. whether MFE_VERTICALFLIP is set in the Object's extra Object flags or not).
P_GetMobjGravity(mobj_t mobj) fixed Returns the amount of gravity to be applied to the Object.
P_WeaponOrPanel(int type) boolean Returns true if the Object type given is any of the weapon ammo/panel types.
P_FlashPal(player_t player, int type, int duration) nil Sets the type and duration of the player's palette – see PLAYPAL for the palette numbers available in the default PLAYPAL lump.
P_GetClosestAxis(mobj_t mobj) mobj_t Returns the closest Axis Object (of type MT_AXIS) to source.
P_SpawnParaloop(fixed x, fixed y, fixed z, fixed radius, int number, int type, int rotate, [int state, [boolean spawncenter?]]) nil Spawns a NiGHTs-style "paraloop" of objects at the x, y, and z coordinates supplied. radius determines the starting/finishing size, number determines how many objects are spawned, type determines the type of the objects spawned, state is the starting state of the object (defaults to S_NULL if not set, which means this will not be changed), and rotate sets the vertical rotation of the objects (in fact multiple paraloops are spawned with this to form the typical paraloop "ball" seen for NiGHTS Super Sonic and A_RingExplode). If spawncenter is true, the objects will all start at the center and move outwards, otherwise they will start at radius distance from the center and move inwards.
P_BossTargetPlayer(mobj_t actor, [boolean closest?]) boolean Player searching for bosses; returns true if a player is targeted, otherwise returns false. If closest is true, the boss will target the closest player it can find, otherwise the boss will target the first player it finds.
P_SupermanLook4Players(mobj_t actor) boolean Similar to P_LookForPlayers, except actor can search anywhere in the map and even through walls.
P_SetScale(mobj_t mobj, fixed scale) nil Sets mobj's scale to a new value. Editing mobj.scale does the same thing – however, calling P_SetScale will not affect mobj.destscale, unlike editing mobj.scale directly.
P_InsideANonSolidFFloor(mobj_t mobj, ffloor_t rover) boolean Returns true if the FOF exists and is non-solid, and mobj is inside it.
P_CheckDeathPitCollide(mobj_t mobj) boolean Returns true if mobj is touching a death pit floor/ceiling.
P_CheckSolidLava(mobj_t mobj, ffloor_t rover) boolean Returns true if the FOF rover is a solid lava block, and mobj is on top of or above it.
P_CanRunOnWater(player_t player, ffloor_t rover) boolean Returns true if the FOF rover is a water block, and player is able to run on top of it.

P_User

Function Return value(s) Description
P_GetPlayerHeight(player_t player) fixed Returns the player's normal height (normally 48*FRACUNIT, and is automatically corrected to match the player's current scale).
P_GetPlayerSpinHeight(player_t player) fixed Returns the player's "spin" height (2/3 of the player's full height; normally 32*FRACUNIT, and is automatically corrected to match the player's current scale)
P_GetPlayerControlDirection(player_t player) int Returns a value depending on what is happening with the player's movement controls (forwards, backwards and strafing left/right) at the moment, compared to the current movement of the player itself:
  • 0 – no controls pressed/no movement
  • 1 – pressing in direction of movement (accelerating)
  • 2 – pressing in opposite direction of movement (decelerating)
P_AddPlayerScore(player_t player, int amount) nil Adds amount to player's score. Also corrects score if < MAXSCORE (999999990), and awards lives for every 50000 points (if not losing points). Handled somewhat differently for NiGHTS stages (both normal and special stages), modifying player.marescore instead of player.score.
P_PlayerInPain(player_t player) boolean Checks if player is in pain state with pw_flashing set (and not sliding), if so this will return true, otherwise this will return false.
P_DoPlayerPain(player_t player, [mobj_t source, [mobj_t inflictor]]) nil Throws back the player setting the state to the player's pain state (does not spill rings/emeralds/flags nor remove health/shields). source is the object the damage (or inflictor) came from, and inflictor (which is either source itself or a projectile from it) the object that dealt the damage, inflictor in particular being used to determine the throw-back speed depending on the flags set. Setting the source and inflictor objects are not required.
P_ResetPlayer(player_t player) nil Resets the player! This will halt anything the player is currently doing.
P_IsObjectInGoop(mobj_t mobj) boolean Is mobj inside goop? Returns true if yes, false if no. If the object has MF_NOGRAVITY or is a spectator player, this will always return false.
P_IsObjectOnGround(mobj_t mobj) boolean Is mobj on the ground? Returns true if yes, false if no. (the "ground" can be the object's floorz or ceilingz depending on whether the object is following reverse gravity or not) If the object is currently within goop water, this will always return false.
P_InSpaceSector(mobj_t mobj) boolean Is mobj in a Space Countdown sector/FOF? Returns true if yes, false if no.
P_InQuicksand(mobj_t mobj) boolean Is mobj in a quicksand FOF? Returns true if yes, false if no.
P_SetObjectMomZ(mobj_t mobj, fixed momz, [boolean relative?]) nil Sets mobj's momz to the value given. If relative is true this will be added to the object's previous momz, otherwise it will replace it. (Note: This also corrects for scaling and reverse gravity!).
P_RestoreMusic(player_t player) nil Restores the music to whatever should be depending on whether player has any powerups or not.
P_SpawnShieldOrb(player_t player) nil Resets player's shield orb appearance to the appropriate one for the player's current shield powers.
P_SpawnGhostMobj(mobj_t mobj) mobj_t Spawns a "ghost" of mobj (a 50% translucent clone of the object that lasts only 8 tics normally before disappearing). Useful for creating afterimages of objects such as players, such as with the Super Sneakers power-up or when a player is in super form. Returns the ghost object spawned.
P_GivePlayerRings(player_t player, int amount) nil Adds amount to player's ring count. Also corrects ring count if > 9999 or < 0. Also awards extra life bonuses for multiples of 100 rings up to the value of maxXtraLife in the MainCfg block (by default this is 2, which allows for extra life bonuses up to 200 rings).
P_GivePlayerLives(player_t player, int amount) nil Adds amount to player's lives count. Also corrects lives count if > 99 or < 1.
P_ResetScore(player_t player) nil Resets player's scoreadd value to 0, ending any score chains in progress.
P_DoJumpShield(player_t player) nil Performs a Whirlwind Shield-style jump, and switches player to their falling animations.
P_BlackOw(player_t player) nil This is used by the Armageddon Shield to blow up enemies, flash the palettes of all players within the explosion radius (1536*FRACUNIT) and destroy the shield currently being held by player. Also plays the Armageddon explosion sound.
P_ElementalFireTrail(player_t player) nil Spawns two Elemental Shield-style flames for both sides and behind player, but needs to be used repeatedly to spawn a true Elemental Shield fire trail.
P_DoPlayerExit(player_t player) nil This is used to have player "complete" the level and become immobile; this will not immediately end the level itself, but prepares to end the level after a set amount of time.
P_InstaThrust(mobj_t mobj, angle angle, fixed move) nil Set an Object's horizontal momentum to the value of move in the direction of angle. Note that this will apply momentum absolutely; i.e. all existing momentum applied to the Object in any direction is lost. If the Object has MF2_TWOD, only momentum in the X-direction is modified – momentum in the Y-direction is unaffected. To add to existing momentum rather than completely replace it, see P_Thrust.
P_ReturnThrustX(mobj_t mobj, angle angle, fixed move) fixed Returns the x-component of a set thrust value at a specified angle. mobj is unused.
P_ReturnThrustY(mobj_t mobj, angle angle, fixed move) fixed Returns the y-component of a set thrust value at a specified angle. mobj is unused.
P_LookForEnemies(player_t player) boolean Returns true if there is a suitable object for player to use a homing attack on (setting the closest one found as both player's target and tracer), otherwise this returns false.

Note: the possible objects to target with this also includes springs and monitors, but does not include non-shootable enemies as well as the Deton.

P_NukeEnemies(mobj_t inflictor, mobj_t source, fixed radius) nil Damages all enemies and bosses (as well as players in shooting gametypes) within a radius around the inflictor mobj (the object causing the damage). The source mobj is where inflictor came from, if not the inflictor itself.
P_HomingAttack(mobj_t source, mobj_t target) nil The source mobj faces the target mobj and moves towards it; needs to be repeatedly used to work properly. The source's movement speed depends on what it is – players will move at 2/3 of their actionspd value, the Deton will move at 17/20 of the enemy player's normalspeed value, otherwise all other objects will use their mobjinfo speed value (threshold of 32000 for the source cuts this in half).
P_SuperReady(player_t player) boolean Returns true if the conditions are right for player to turn super by double-jumping, otherwise this returns false.
P_DoJump(player_t player, [boolean soundandstate]) nil Makes the player jump! The player's momz is set to a particular value depending on the situation, and the PF_JUMPED flag is given to the player's pflags (player.pflags). If soundandstate is set to true (the default value), the player's state will be changed to the appropriate jump states and play the jump sound. If the player has PF_JUMPSTASIS in player.pflags, or player.jumpfactor is 0, this function will do nothing.
P_SpawnThokMobj(player_t player) nil Spawns a thok trail Object for player at player's location.
P_SpawnSpinMobj(player_t player, int type) nil Spawns a spin trail Object for player at player's location, type determines the type of the object spawned.
P_Telekinesis(player_t player, fixed thrust, fixed range) nil Pushes away all enemies and players around player within a range, pushing them away at the thrust value set. If thrust is negative, this will instead pull in enemies and players towards player.

P_Map

Function Return value(s) Description
P_CheckPosition(mobj_t mobj, fixed x, fixed y) boolean, mobj_t Checks if the position is valid for the object mobj (this does not actually teleport the object to the x and y coordinates, only tests what would happen if it was at the position).

This function returns false if either a) the object has been blocked by a wall or another object, or b) the object has been removed from the map during checking; otherwise it will return true to signal the position isn't blocked. This function additionally returns the "tmthing" mobj set during the run of the function, which in the majority of cases will be mobj itself.

The blockmap is checked for any objects or walls to collide with; any objects with MF_NOBLOCKMAP cannot be collided with by this function. Do note that objects using this function that have the MF_NOCLIP won't clip with other objects or walls at all, while objects with MF_NOCLIPTHING will not clip with things but can still be blocked by walls.

P_TryMove(mobj_t mobj,fixed x, fixed y, [boolean allowdropoff?]) boolean, mobj_t Tries to move the object mobj to the x/y coordinates supplied (all done in the same tic), checking each position to make sure the object is not blocked on the way there; if it is blocked by a wall or another object, or the height of the sector is too small to fit in, this will return false and leave the object where it was to begin with (i.e the move failed); otherwise this will return true with the object at the coordinates supplied. This function additionally returns the "tmthing" mobj set during the run of the function, which in the majority of cases will be mobj itself.

allowdropoff determines whether to stop the object from falling off a platform too low to step-down when moving, or let it continue regardless of this – if allowdropoff is false and the object would be falling off a platform if it continued, this will return false.

Note: pushable objects will also move along anything on top with them if the pushable itself isn't blocked by something etc. Objects with MF_NOCLIP however will be able to move straight to the position without being blocked by anything, and allowdropoff will not affect them either way.

P_Move(mobj_t actor, int speed) boolean, mobj_t Moves the actor mobj in it's current direction (using actor.movedir rather than the angle), moving forward a distance of speed*FRACUNIT (speed does not need to be multiplied by FRACUNIT). Returns true when the actor has moved, returns false if the actor cannot move, doesn't have a direction to move in or is dead. This function additionally returns the "tmthing" mobj set during the run of the function, which in the majority of cases will be actor itself.
P_TeleportMove(mobj_t mobj, fixed x, fixed y, fixed z) boolean, mobj_t Teleports the object straight to the x, y, and z coordinates supplied, but does not account for whether the object will be stuck in this position though, and will always return true. This function additionally returns the "tmthing" mobj set during the run of the function, which in the majority of cases will be mobj itself.
P_SlideMove(mobj_t mo) nil Slides mo along a wall using its current xy-momentum; this is assuming mo has already been blocked by a wall, so this searches for the wall that blocked it before sliding.
P_BounceMove(mobj_t mo) nil Bounces mo off a wall using its current xy-momentum; this is assuming mo has already been blocked by a wall, so this searches for the wall that blocked it before bouncing.
P_CheckSight(mobj_t source, mobj_t target) boolean Checks if source can "see" target – if it can, this returns true; otherwise it returns false. This function is able to check if FOFs are blocking, but this is limited to when both mobjs are in the same sector[confirm? – discuss].
P_CheckHoopPosition(mobj_t hoop, fixed x, fixed y, fixed z, fixed radius) nil Optimized version of P_CheckPosition specifically designed for MT_HOOPCOLLIDE. (radius is unused)
P_RadiusAttack(mobj_t inflictor, mobj_t source, fixed radius) nil Damages all damageable Objects in the blockmap around inflictor, with source being the Object that inflictor came from (if not the same as inflictor itself). radius is the distance limit around inflictor to damage other objects in, which will automatically be scaled with inflictor's scale.

Objects that cannot be damaged by P_RadiusAttack include: any Objects sharing the same type as inflictor, the source Object itself, monitors, bosses, non-shootable Objects (MF_SHOOTABLE is not set), or any Objects not within the blockmap at all (MF_NOBLOCKMAP is set). P_RadiusAttack's effect will also not work through walls, and will not affect any Objects not visible from inflictor's position.

P_FloorzAtPos(fixed x, fixed y, fixed z, fixed height) fixed Returns what would be the floorz (the absolute z height of the floor) at the x, y, and z coordinates supplied. height should be the height of the object you want to check this for (needed for checking solid/quicksand FOFs). Keep in mind the coordinates and perhaps even the height don't actually have to be for an existing object necessarily!
P_DoSpring(mobj_t spring, mobj_t object) nil The spring object sends object into the air in a spring-style fashion.

P_Inter

Function Return value(s) Description
P_RemoveShield(player_t player) nil Removes any shield player may be carrying (this will not throw back the player nor play a sound).
P_DamageMobj(mobj_t target, [mobj_t inflictor, [mobj_t source, [int damage]]]) boolean Inflicts damage on the target object, causing it to lose a certain amount of health and use the state determined by target.info.painstate; however, if target has lost all health as a result of this function, P_KillMobj is called by this function instead. The return value of this function depends on whether target was damaged or not – if it was, this returns true; if not, this returns false.

inflictor and source determine where the damage came from: inflictor is the object that dealt the damage, source is the source of the damage (or where inflictor came from). For instance, when a projectile fired by a player or enemy damages target, inflictor should be set the projectile itself, and source to the object that fired the projectile. However, in situations where a player or enemy directly damages target, inflictor and source are usually both set to the same object. If the damage comes from a level hazard such as damaging sector specials or crushers (or otherwise from nowhere at all), it is best to set both these arguments to nil.

damage determines the amount of damage to deal to target, or the number of health points removed from it. Certain damage values will have special effects reserved for players:

  • 10000 – The player will instantly be killed; does not affect spectators.
  • 42000 – If the player is a spectator, they will instantly be killed.

Note that, if not given, inflictor and source both default to nil, while damage defaults to 1. The hooks "ShouldDamage" and "MobjDamage" can be used modify or replace some of the effects of this function.

P_KillMobj(mobj_t target, [mobj_t inflictor, [mobj_t source]]) nil Kills the target object, making it become intangible as well as using the state determined by target.info.deathstate (if set to nil, the object will be removed from existence). If target is an enemy or boss, and the object that killed it was a player or one of their projectiles, points may be awarded to this player. Freed animals (and/or other items) will also be spawned by enemies killed by this function.

inflictor and source follow the same meanings as in P_DamageMobj, and both default to nil if not given. The hook "MobjDeath" can be used to modify or replace some of the effects of this function.

Note: this function is not designed to be used to kill players directly; use P_DamageMobj with a damage value of 10000 instead.

P_PlayerRingBurst(player_t player, [int numrings]) nil Spills a specified number of regular rings, also spills all weapon panels, ammo and emeralds player may be carrying at the time; does not throw back the carrier themselves. If numrings is not given (or set to -1), it will default to the player's current ring count (which is player.health - 1).

In normal gameplay, up to 32 rings will be spilled by this function; the remainder will not be spawned. The speed at which the rings are flung depend on the duration since the last time this function was used (determined by player.losstime). In NiGHTS levels however, the player will drop all rings if they have the player flag PF_NIGHTSFALL (given when the player has run out of time as Super Sonic). In addition, the rings will always be flung at the same speed regardless of player.losstime's value.

Note that this function does not actually affect player.health nor player.mo.health; these must be modified manually in order for the player to actually lose rings. This does not apply to any weapon panels, ammo and/or emeralds also spilled by this function.

P_PlayerWeaponPanelBurst(player_t player) nil Spills all weapon panels that player is carrying; does not throw back player. Unlike the rings in P_PlayerRingBurst, the player will actually lose the weapon panels spilled by this function.
P_PlayerWeaponAmmoBurst(player_t player) nil The player spills all weapon panels it is carrying and all their weapon ammo; does not throw back player. Unlike the rings in P_PlayerRingBurst, the player will actually lose the weapon ammo spilled by this function.
P_PlayerEmeraldBurst(player_t player, [boolean toss?]) nil Spills all emeralds player is carrying; does not throw back the player. If toss is true, all the emeralds are thrown in the player's forward direction and a toss delay of 2 seconds is set (for players tossing emeralds), otherwise the emeralds are spilled all around the player (for players dropping emeralds after being hurt). Unlike the rings in P_PlayerRingBurst, the player will actually lose the emeralds spilled by this function.
P_PlayerFlagBurst(player_t player, [boolean toss?]) nil Spills any CTF flags player is carrying; does not throw back player. If "toss" is true, the flag is thrown in player's forward direction and a toss delay of 2 seconds is set (for if player is tossing a flag), otherwise the direction is random (for players dropping a flag after being hurt).
P_PlayRinglossSound(mobj_t source, [player_t player]) nil Plays one of the 4 player ring spill sounds randomly, which can vary depending on the skin, or plays the Mario ring loss sound if in Mario mode. source is the object the sound came from.
P_PlayDeathSound(mobj_t source, [player_t player]) nil Plays one of the 4 player death sounds randomly, which can vary depending on the skin. source is the object the sound came from.
P_PlayVictorySound(mobj_t source, [player_t player]) nil Plays one of the 4 player victory taunt sounds randomly, which can vary depending on the skin. source is the object the sound came from.
P_PlayLivesJingle(player_t player) nil Plays the Extra life jingle; by default this is the Extra life music, but in Mario mode maps and in the case of Use1upSound from the MainCfg block being turned on this is instead a sound. If the music is used, the player's pw_extralife timer is set to ExtraLifeTics+1.
P_CanPickupItem(player_t player, [boolean weapon?]) boolean Returns true if player can pick up the item, returns false if player is a bot or is flashing after being hurt.
P_DoNightsScore(player_t player) nil Awards score to player NiGHTS-style; spawns a floating score item which changes appearance depending on the player's current link count and whether the player is in bonus time.

P_Spec

Function Return value(s) Description
P_Thrust(mobj_t mobj, angle angle, fixed move) nil Boosts an Object's horizontal momentum by the value of move in the direction of angle. Note that this will apply momentum relatively; i.e. all existing momentum applied to the Object in any direction is retained – if P_Thrust is used every tic, this can result in the Object accelerating in the given direction. If the Object has MF2_TWOD, only momentum in the X-direction is modified – momentum in the Y-direction is unaffected. To replace all existing momentum instead of adding to it, see P_InstaThrust.
P_SetMobjStateNF(mobj_t mobj, int statenum) boolean The mobj's state is changed to a specified state number, but without running any actions. If statenum is S_NULL, this will remove the object on use (does not work on players!).

Note: This should not be confused with the normal method of applying new states, which would be using the code mobj.state = statenum (where mobj and statenum follow the same meanings as the arguments for P_SetMobjStateNF).

P_DoSuperTransformation(player_t player, [boolean giverings?]) nil Makes the player super. If giverings? is specified true, the player is given 50 rings when the function runs. Note that the player still needs all seven Chaos Emeralds for this function to work entirely correctly.
P_ExplodeMissile(mobj_t missile) nil Death sequence for the missile object. Halts the missile's momentum, alters its flags, plays its DeathSound and sets its state to DeathState. (Doesn't do anything if object has MF_NOCLIPTHING set, as it is used as a dummy flag to indicate when a missile is already "dead")
P_PlayerTouchingSectorSpecial(player_t player, int section, int specialnum) sector_t Checks if player is touching a sector with the specified special from the specified section. If one is found, this will return the sector with the special. Also accounts for FOFs; this will return the FOF's control sectors for them if they are the found sector.
P_FindSpecialLineFromTag(int special, int tag, [int start]) int Finds the first linedef number after start which has the linedef special and tag being searched for. start can be -1 to start from the first linedef onwards, or set to another linedef's number to carry on from perhaps the last linedef number found (start defaults to -1 if not set).
P_SwitchWeather(int weathernum, [player_t player]) nil Switches weather in-game with weathernum (use the PRECIP_ constants). If player is nil, the weather is applied globally (to all players); otherwise, the weather specified is applied only for the player who triggered the function.
P_LinedefExecute(int tag, [mobj_t actor, [sector_t caller]]) nil Executes a linedef executor. tag is the tag of the executor's trigger linedef. If set, actor is the object that activated it, and caller is the triggering sector.
P_SpawnLightningFlash(sector_t sector) nil Spawns a lightning flash in sector. For this to work in FOFs, sector should be the control sector of the FOF to flash in.
P_FadeLight(int tag, int destvalue, int speed) nil Fades all tagged sectors' lighting to a new value set by destvalue. speed determines how quickly the sector's light fades to the new value.
P_ThingOnSpecial3DFloor(mobj_t mobj) sector_t If mobj is on top of or inside an FOF with a sector special, this function returns the FOF's control sector; otherwise returns nil.
P_IsFlagAtBase(int type) boolean Returns true if the flag of the given type is at its corresponding CTF base. (Should only be used with types MT_BLUEFLAG and MT_REDFLAG)
P_SetupLevelSky(int skynum, [player player]) nil Sets the sky seen in-game to the value of skynum. If player is nil or not set, the sky is applied globally (to all players); otherwise, the sky is applied only for the player who triggered the function.
P_SetSkyboxMobj([mobj_t mobj, [boolean/int centerpoint?, [player_t user]]]) nil Alternative versions:
  • P_SetSkyboxMobj(mobj_t mobj, boolean/int centerpoint?)
  • P_SetSkyboxMobj(mobj_t mobj, player_t user)
  • P_SetSkyboxMobj(mobj_t mobj, boolean/int centerpoint?, player_t user)

Lua exclusive: sets which object correponds to either the skybox's view point or center point (defaults to view point). user is the player to apply the new skybox view to, otherwise it applies to all players. If mobj is nil, the skybox is removed.

P_StartQuake(fixed intensity, int time, [table{x, y, z} epicenter, [fixed radius]]) nil Lua exclusive: starts an earthquake camera effect. intensity determines the earthquake's strength, and time determines its duration. Currently, epicenter and radius are not supported by SRB2 itself, and will have no effect when specified.
EV_CrumbleChain(sector_t sector, ffloor_t rover) nil Shatters the FOF rover making it vanish from the map, spawning debris at the sector "sector".

R_Defs

Function Return value(s) Description
R_PointToAngle(fixed x, fixed y) angle Returns the angle between the camera's X and Y coordinates and x and y.

Note: This will not work consistently among multiple players. Use at your own risk.

R_PointToAngle2(fixed x, fixed y, fixed dest_x, fixed dest_y) angle Returns the angle created by the line from x, and y to dest_x and dest_y.
R_PointToDist(fixed x, fixed y) fixed Returns the distance from the camera's X and Y coordinates to x and y.

Note: This will not work consistently among multiple players. Use at your own risk.

R_PointToDist2(fixed x, fixed y, fixed dest_x, fixed dest_y) fixed Returns the distance from x and y to dest_x and dest_y.
R_PointInSubsector(fixed x, fixed y) subsector_t Returns the subsector that the given point is located in. (Never returns nil, even if outside of the map!)

R_Things

Function Return value(s) Description
R_Char2Frame(string char) int Returns the text character's frame number.

e.g.: R_Char2Frame("A") → 0

R_Frame2Char(int frame) string, int Returns the frame number's text character as both a string and its ASCII value.

e.g.: R_Frame2Char(0) → "A",65

R_SetPlayerSkin(player_t player, int/string skin) nil Sets the player's skin. skin can be either a skin number or a skin name string.

S_Sound

For all of the functions below with an optional player parameter, this determines which player the function is run for (if only a certain player is meant to hear a sound or change in music, for example). If this is omitted or set to nil, the function is run for all players.

Function Return value(s) Description
S_StartSound(mobj_t origin, int soundnum, [player_t player]) nil Starts the given sound effect from origin, or plays the sound globally if origin is nil. If origin exists and has a skin applied, certain sound ids may be replaced with custom sounds set for the skin. If in a Mario mode or Christmas NiGHTS level, certain sound ids will automatically be swapped with different sounds for the given level type (these take priority over custom skin sounds).
S_StartSoundAtVolume(mobj_t origin, int soundnum, uint8 volume, [player_t player]) nil Starts the given sound effect at a specific volume from origin, or plays the sound globally if origin is nil. If origin exists and has a skin applied, certain sounds may be replaced with custom sounds set for the skin. Unlike S_StartSound, Mario mode and Christmas NiGHTS have no effect on the sound id used.

Volume ranges from 0 to 255, inclusive.

S_StopSound(mobj_t origin) nil Stops any sound that the given mobj is playing.
S_ChangeMusic(string musicname, [boolean looping?, [player_t player, [int tracknum]]) nil Alternative version: S_ChangeMusic(int musicnum, [boolean looping?, [player_t player])

Changes the music to the specified music name or slot number. The music will loop by default unless looping? is specified and is false. If the music format supports multiple tracks, you can supply the track number as well – if the new music's name was given, tracknum is the track number; if a slot number was given, the track number must be stored in the upper 16 bits (i.e. musicnum == slot number+(tracknum<<16))

S_SpeedMusic(fixed musicspeed, [player_t player]) nil Changes the speed of the music – the speed given must be a multiple of FRACUNIT, where FRACUNIT is the default music speed.
S_StopMusic([player_t player]) nil Stops all music from playing.
S_OriginPlaying(mobj_t origin) boolean Returns true if the given mobj is playing any sound effect, or false if mobj is silent.
S_IdPlaying(int soundnum) boolean Returns true if the given sound number is playing anywhere, and false if it is not.
S_SoundPlaying(mobj_t origin, int soundnum) boolean Returns true if the given mobj is playing the sound number specified, and false if it is not.

G_Game

Function Return value(s) Description
G_BuildMapName([int map]) string Returns the MAPXX format name for the map, where XX uses the extended map number format. If no map number is given, the current map's number will be used.

e.g.: G_BuildMapName(100)"MAPA0"

G_DoReborn(int playernum) nil Respawns the player at the given playernum.
G_ExitLevel([int nextmap, [boolean skipstats]]) nil Alternative versions:
  • G_ExitLevel(int nextmap)
  • G_ExitLevel(boolean skipstats)

Immediately exits the level. If a value for nextmap is given, the new map number will override the map number to change to that would otherwise be set. If skipstats is set to true (defaults to false), the statistics screen will be skipped.

G_IsSpecialStage([int map]) boolean Returns true if the given map number is a Special Stage; otherwise returns false. If no map number is given, the current map's number will be used.
G_GametypeUsesLives() boolean Returns true if the current game mode uses lives (Single Player, Coop, or Competition); otherwise returns false. If in Record Attack or a NiGHTS level, this returns false regardless of gametype.
G_GametypeHasTeams() boolean Returns true if the current game mode has teams (Team Match or CTF); otherwise returns false.
G_GametypeHasSpectators() boolean Returns true if the current game mode supports spectators (Match, CTF or Tag); otherwise returns false.
G_RingSlingerGametype() boolean Returns true if the current game mode supports firing rings (Match, CTF, or Tag), or if otherwise ringslinger is enabled; otherwise returns false.
G_PlatformGametype() boolean Returns true if the current game mode is a "platformer" game type (Single Player, Coop, Race, or Competition); otherwise returns false.
G_TagGametype() boolean Returns true if the current game mode is Tag or Hide and Seek; otherwise returns false.
G_TicsToHours(int tics) int Returns the time in game tics converted to hours.
G_TicsToMinutes(int tics, [boolean full?]) int Returns the time in game tics converted to minutes. By default, this returns only values between 0 and 59, assuming the return value is used for timers with both "hours" and "minutes" displays (e.g. hours:minutes:seconds). If full? is given and is true, then hours (or multiples of 60 minutes) will not be truncated, allowing for return values over 59; this latter case is used for timers without an "hours" display (e.g. minutes:seconds).
G_TicsToSeconds(int tics) int Returns the time in game tics converted to seconds. This returns only values between 0 and 59, assuming the return value is used for timers with both "minutes" and "seconds" displays (e.g. hours:minutes:seconds).
G_TicsToCentiseconds(int tics) int Returns the time in game tics converted to centiseconds. This returns only values between 0 and 99, assuming the return value is used for timers with both "seconds" and "centiseconds" displays (e.g. minutes:seconds.centiseconds).
G_TicsToMilliseconds(int tics) int Returns the time in game tics converted to milliseconds. This returns only values between 0 and 999.

Iterator functions

None of these functions should be called directly, with the exception of thinkers.iterate. They should be used in a for loop, as such:

for player in players.iterate
   -- Handle player here
end

Note that the ending parentheses, (), are omitted in the above code – this does not apply to thinkers.iterate however, where a single argument can be supplied.

Function Iterator type Description
players.iterate() player_t Iterates over all players currently playing in the map. Do note that "player.mo" will return nil for spectating players.
thinkers.iterate([string type])
  • "mobj" → mobj_t
  • "all" → ???
Options for type are "all" and "mobj"; the default type set if not given is "mobj".
  • "mobj" iterates over all mobjs in the map that use P_MobjThinker. This excludes all precipitation (rain and snow).
  • "all" iterates over all thinkers in the map. Mobjs are treated as mobj userdata, but anything else cannot be used for anything significant.

Note that this iterator is extremely slow due to the massive iteration, and should not be used repeatedly so as not to cause framerate drops.

skins.iterate() skin_t Iterates over all valid skins loaded in the game.
mapthings.iterate() mapthing_t Iterates over all map things in the map. Remember that not all mobjs will necessarily have a respective map thing, and not all map things will necessarily have a respective mobj.
sectors.iterate() sector_t Iterates over all sectors in the map.
subsectors.iterate() subsector_t Iterates over all subsectors in the map.
lines.iterate() line_t Iterates over all linedefs in the map.
sides.iterate() side_t Iterates over all sidedefs in the map.
vertexes.iterate() vertex_t Iterates over all vertexes in the map.

Lua framework

These are the functions included with the standard Lua libraries included with SRB2 (Basic, Coroutine, String and Table).

Base Lua functions

(lua.org documentation)

Function Return value(s) Description
assert(* v, [string errormsg]) any or nil If v is nil or false, an error message is printed; otherwise, this function returns all arguments given. errormsg is the message to use when the assertion fails; if not given, the default message used is "assertion failed!".
collectgarbage([string opt, [int arg]]) "step": boolean
all others: int
Options:
  • "stop"
  • "restart"
  • "collect"
  • "count"
  • "step"
  • "setpause"
  • "setstepmul"
error(string message, [int level]) nil Terminates the last protected function called and returns message as the error message.
getfenv([function/int f]) (environment) Returns the current environment in use by the function.
getmetatable(object obj) (metatable) Returns the metatable of the given object, if it has one. If the object's metatable has a __metatable field, returns the associated value instead.
ipairs(table{} t) function, table, int Returns three values: an iterator function, the table t, and 0.

This function is to be used in a for loop, such as in the code shown below:

for k,v in ipairs(t)
	--contents
end

k and v are the key and value for each entry in table t.

next(table{} t, [int index]) (index), (value)
pairs(table{} t) function, table, nil Returns three values: the next function, the table t, and nil.

This function is to be used in a for loop, such as in the code shown below:

for k,v in pairs(t)
	--contents
end

k and v are the key and value for each entry in table t.

pcall(function fn, [* arg, [...]]) boolean, (return values) Calls function fn with the given arguments in protected mode.
rawequal(* v1, * v2) boolean Checks whether v1 is equal to v2, without invoking any metamethod.
rawget(table{} t, * index) any Gets the real value of table[index], without invoking any metamethod.
rawset(table{} t, * index, * value) table Sets the real value of table[index] to value, without invoking any metamethod. This function returns table.
select(* index, ...) index is number: (arguments)
index is "#": int
If index is a number, returns all arguments after argument number index. Otherwise, index must be the string "#", and select returns the total number of extra arguments it received.
setfenv(function/int f, table{} table) function Sets the environment to be used by the given function.
setmetatable(table{} t, table{} metatable) table Sets the metatable for the given table. (You cannot change the metatable of other types from Lua, only from C.) If metatable is nil, removes the metatable of the given table. If the original metatable has a __metatable field, raises an error.

This function returns table.

tonumber(* e, [int base]) int or nil Returns the given variable as a number, if possible. Returns nil if the variable cannot be converted to a number.

e.g.: tonumber("10") → 10

tostring(* e) string Returns the given as a string (e.g. tostring(10)"10").
type(* v) string Returns the type of v as a string.

Possible strings that may be returned by this function:

  • "no value"
  • "nil"
  • "boolean"
  • "userdata"
  • "number"
  • "string"
  • "table"
  • "function"
  • "thread"
  • "proto"
  • "upval"
unpack(table{} list, [int start, [int end]]) (table elements) Returns the elements from the given table.
xpcall(function call, function(boolean status) errortrap) boolean, (return values) Calls function f in protected mode, using errortrap as the error handler.

Coroutine library

(lua.org documentation)

Function Return value(s) Description
coroutine.create(function fn) thread Creates and returns a new coroutine that runs the function specified. To run the coroutine, use coroutine.resume.
coroutine.resume(coroutine co, [* val, [...]]) boolean, (return values from coroutine.yield) Begins or resumes execution of the coroutine specified. If the coroutine has not yet been started, passes the remaining arguments to the coroutine's function (i.e.: they become the arguments to the function). If the coroutine has yielded, the remaining arguments are passed as the results from the yield (i.e.: they become the return values of coroutine.yield). If the function errors, returns false and the error message; otherwise, returns true plus the variables returned or passed to coroutine.yield.
coroutine.running() thread or nil Returns the running coroutine, or nil when called by the main thread.
coroutine.status(coroutine co) string Returns the status of coroutine co, as a string:
  • "running", if the coroutine is running (that is, it called status)
  • "suspended", if the coroutine is suspended in a call to yield, or if it has not started running yet
  • "normal", if the coroutine is active but not running (that is, it has resumed another coroutine)
  • "dead", if the coroutine has finished its body function, or if it has stopped with an error
coroutine.wrap(function fn) function Creates and returns a wrapper for a coroutine that runs the function specified. Calling the coroutine in the format corout(args) is equivalent to calling coroutine.resume(corout, args) on a coroutine created using coroutine.create, except that it will not return the initial true value, instead propogating any errors that the coroutine throws.
coroutine.yield([...]) (return values from coroutine.resume) Temporarily suspends execution of the coroutine. Cannot be used while running a C function, a metamethod, or an iterator loop. The next time the coroutine is resumed, it will resume execution from the point of this function call. Arguments passed to this function will be returned by the coroutine.resume call that restarted the coroutine, and this function itself will return any extra arguments from the coroutine.resume call.

String library

(lua.org documentation)

Function Return value(s) Description
string.byte(string s, [int start, [int end]]) int × (end - start + 1) Alternative syntax: s:byte([int start, [int end]])

Returns the numerical values of the characters in string s. start and end can be used to offset where to start and end the conversion in the string.

string.char([int charid, [...]]) string Returns the character codes specified as characters (reverse of string.byte).
string.dump(function fn) string Returns a string containing a binary representation of the given function.
string.find(string s, string pattern, [int start, [boolean plain?]]) int, int, (captures) Alternative syntax: s:find(string pattern, [int start, [boolean plain?]])

Looks for the first match of pattern in the string s.

string.format(string formatstr, [...]) string Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string).
string.gmatch(string s, string pattern) function Alternative syntax: s:gmatch(string pattern)
string.gsub(string s, string pattern, int/string/table/function replace, [int n]) string Alternative syntax: s:gsub(string pattern, int/string/table/function replace, [int n])

Returns a copy of s in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl. Also returns the total number of matches that occurred.

string.len(string s) int Alternative syntax: s:len()

Returns the length of the string s.

e.g.: string.len("Hello") will return 5

string.lower(string s) string Alternative syntax: s:lower()

Converts string s to lowercase characters.

e.g.: string.lower("HELLO") will return "hello"

string.match(string s, string pattern, [int n]) (captures) or string Alternative syntax: s:match(string pattern, [int n])
string.rep(string s, int n) string Alternative syntax: s:rep(int n)

Repeats string s n times.

e.g.: string.rep("Hello ", 5) will return "Hello Hello Hello Hello Hello "

string.reverse(string s) string Alternative syntax: s:reverse()

Reverses string s.

e.g.: string.reverse("Hello") will return "olleH"

string.sub(string s, int start, [int end]) string Alternative syntax: s:sub(int start, [int end])

Returns a subsection of string s starting at start and optionally ending at end.

string.upper(string s) string Alternative syntax: s:upper()

Converts string s to uppercase characters.

e.g.: string.upper("hello") will return "HELLO"

Table library

(lua.org documentation)

Note: most of these functions are not designed for tables with non-integer keys.

Function Return value(s) Description
table.concat(table{} t, [string sep, [int start, [int end]]]) string Returns a string containing table t's elements concatenated together.
table.insert(table{} t, [int key], * element) nil Inserts element at position key in table t. If key is not given, element is inserted at the end of table t.
table.maxn(table{} t) int Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices.
table.remove(table{} t, [int key]) any Removes from table t the element at position key, and returns the value of the removed element. If key is not given, removes the last element of table t.
table.sort(table{} t, [function(* element_a,* element_b) comp]) nil Sorts table elements in a given order, in-place, from t[1] to t[n], where n is the length of the table t.
  Lua [view]
General BasicsFunctionsGlobal variablesHooksUserdata structures
Tutorials Freeslots and Object resourcesCustom player ability