2.1:Lua/Functions
Lua/Functions
< Lua
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 when using the function, 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: |
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 is equivalent to 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 |
FixedAngle(fixed a)
|
angle | Converts an integer in the fixed-point scale to an angle value.
Example: |
AngleFixed(angle a)
|
fixed | Converts an angle value to an integer in the fixed-point scale.
'Example: |
InvAngle(angle a)
|
angle | Returns the "inverse" of the given angle (360° - a).
Example: |
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 (e.g., 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.
Example: |
FixedInt(fixed a)
|
fixed | Returns the integer component of a as a normal integer.
Example: |
FixedDiv(fixed a, fixed b)
|
fixed | Returns the result of dividing a by b in the fixed-point scale.
Example: |
FixedRem(fixed a, fixed b)
|
fixed | Returns the remainder of dividing a by b in the fixed-point scale.
Note: Negative values for b are not handled correctly and may slow down the game. |
FixedSqrt(fixed a)
|
fixed | Returns the square root of a in the fixed-point scale.
Example: |
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 where the other sides have lengths a and b).
Example: |
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 specialized functions that do not fit within the base library.
| Function | Return value(s) | Description |
|---|---|---|
GetSecSpecial(int special, int section)
|
int | For a given sector type number special and a sector type group section (expected to be a value between 1 and 4), returns the number of the sector effect from section that special uses, or 0 if no effect from this group is used. The output values range from 0 to 15 – see Sector types for a list of sector effects and their corresponding effect numbers.
Example: If the sector |
All7Emeralds(int flags)
|
boolean | Returns true if flags contains all the emerald flags from EMERALD1 to EMERALD7 within. Intended 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 (the latter is used for the Level End Sign).
Example: |
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.enabled(string huditem)
|
boolean | Returns true if huditem (see below for a list of valid options) is enabled, false if it was disabled by hud.disable.
|
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, hud.disable and hud.enabled:
| 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:
|
"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:
| ||||||||||
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:
| ||||||||||
v.drawNum(int x, int y, int num, [int flags])
|
nil | Draws a number at the screen coordinates given.
Notes:
| ||||||||||
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:
| ||||||||||
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.drawString(int x, int y, string text, [int flags, [string align]])
|
nil | Draws text on the screen at the screen coordinates given.
Notes:
| ||||||||||
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:
| ||||||||||
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:
| ||||||||||
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:
| ||||||||||
v.localTransFlag()
|
int | Returns the value of translucenthud, as an alpha video flag, i.e.: V_**TRANS (see Video flags > Alpha).
|
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:
| ||||||||||
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 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:
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 = 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 ( |
Blockmap search library
These are the functions included in SRB2's Blockmap search library. This consists of only one function, searchBlockmap.
| Function | Return value(s) | Description |
|---|---|---|
searchBlockmap(string searchtype, function fn, mobj_t refmobj, [fixed x1, fixed x2, fixed y1, fixed y2])
|
boolean | Does an search through a specified area of the blockmap. This can be used to find Objects or linedefs in the area and run a function for each them. This function returns true if the search was not interrupted at any point, and false if it was.
searchtype determines what is being searched for:
fn is the function to be used on each found Object/linedef. The format of the function depends on the searchtype:
In both cases, refmobj is the same Object given in The return value of fn affects how searching continues afterwards:
If fn returns refmobj is a reference Object of your choice used within searching. If you don't supply x/y ranges to search in, it defaults to checking within the Object's radius in both axes (relative to its current X/Y position in the map). If refmobj was removed mid-search, the search stops and x1, x2, y1, and y2 are optional arguments, determining the range of X and Y coordinates in the map to search the blockmap between, if given. They determine the left, right, bottom and top limits of the area to search in, specifically. If not given, refmobj is used to set the range by default. |
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 ( |
chatprint(string output, [boolean sound])
|
nil | Outputs text in the chat window (or the console if it cannot be output in the chat window). Each output string will be separated into different lines. If sound is set to true (defaults to false), a sound will be played when sent.
Certain ASCII characters will have special effects when printed out to the chat window or console by this function. These can either be given using decimal ( |
chatprintf(player_t player, string output, [boolean sound])
|
nil | Outputs text in the chat window (or the console if it cannot be output in the chat window). Unlike chatprint, the text will only be output for the player supplied in player. Each output string will be separated into different lines. If sound is set to true (defaults to false), a sound will be played when sent.
Certain ASCII characters will have special effects when printed out to the chat window or console by this function. These can either be given using decimal ( |
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 " |
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. |
IsPlayerAdmin(player_t player)
|
boolean | Returns true if the player is an admin, false if not. |
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 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.: |
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:
|
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 is 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 Object (the Object causing the damage). The source Object is where inflictor came from, if not the inflictor itself. |
P_HomingAttack(mobj_t source, mobj_t target)
|
nil | The source Object faces the target Object 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" Object 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 |
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" Object 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 |
P_Move(mobj_t actor, int speed)
|
boolean, mobj_t
|
Moves the actor Object in its 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" Object 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" Object 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 Objects 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_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:
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 Note: This function is not designed to be used to kill players directly; use |
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 Note that this function does not actually affect |
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 |
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 the 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:
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". |
P_Slopes
| Function | Return value(s) | Description |
|---|---|---|
P_GetZAt(pslope_t slope, fixed x, fixed y)
|
fixed | Returns the corresponding Z position on the slope for the XY coordinates given. |
R_Data
| Function | Return value(s) | Description |
|---|---|---|
R_TextureNumForName(string name)
|
int | Returns the texture number for the texture whose name is supplied in name. For a list of textures by number, see List of textures by number. |
R_CheckTextureNumForName(string name)
|
int | If a texture with the name given by name exists, returns its texture number. Otherwise, returns -1. |
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_Frame2Char(int frame)
|
string, int | Returns the frame number's text character as both a string and its ASCII value.
e.g.: |
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.
Note that this function only works with music formats supported by the Game Music Emu library. For other music formats, it has no effect. |
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_DoReborn(int playernum)
|
nil | Respawns the player at the given playernum. |
G_ExitLevel([int nextmap, [boolean skipstats]])
|
nil | Alternative versions:
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_SetCustomExitVars([int nextmap, [boolean skipstats]])
|
nil | Alternative versions:
Changes the settings that will apply when the current level is exited, but unlike |
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])
|
|
Options for type are "all" and "mobj"; the default type set if not given is "mobj".
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 Objects will necessarily have a respective map Thing, and not all map Things will necessarily have a respective Object. |
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:
|
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.: |
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:
|
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:
|
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. Example: |
string.lower(string s)
|
string | Alternative syntax: s:lower()
Converts string s to lowercase characters. Example: |
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. Example: |
string.reverse(string s)
|
string | Alternative syntax: s:reverse()
Reverses string s. Example: |
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. Example: |
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.
|