Lua/Global variables

From SRB2 Wiki
< Lua
Jump to: navigation, search
ToDoIcon.png To do
Document the new things 2.2.5 brought.

This is a list of all pre-defined global variables and tables that are accessible by Lua.

Variables

This is a list of all non-table global variables. Note that these variables are read-only to Lua, unless stated otherwise.

Name Variable type Accessibility Description
gamemap number Read-only The map number of the map currently being played.
maptol number Read-only The TypeOfLevel of the map currently being played. See Constants > TypeOfLevel flags.
gamestate number Read-only The game's current "state". See Constants > Game states.
ultimatemode boolean Read-only Returns true if playing in Ultimate mode, false if not.
mariomode boolean Read-only Returns true if the map is in Mario mode, false if not.
twodlevel boolean Read-only Returns true if the map is in 2D mode, false if not.
circuitmap boolean Read-only Returns true if the map is a Circuit map, false if not.
stoppedclock boolean Read+Write Returns true if the timer was stopped, false if not. Can be modified by Lua.
netgame boolean Read-only Returns true if currently in a netgame, false if not.
multiplayer boolean Read-only Returns true if currently playing a multiplayer game, false if not.
modeattacking boolean Read-only Returns true if playing in Record Attack or NiGHTS Mode, false if not.
splitscreen boolean Read-only Returns true if playing in two-player mode, false if not.
gamecomplete boolean Read-only Returns true if the game has been completed in the current savefile, false if not.
marathonmode number Read-only The current Marathon Mode flags. See Constants > Marathon Mode flags.
devparm boolean Read-only Returns true if the game is being run with the command line parameter -debug, false if not.
modifiedgame boolean Read-only Returns true if the game has been modified and the modification does not have a custom gamedata file, false if not.
menuactive boolean Read-only Returns true if a menu is currently active, false if not.
paused boolean Read-only Returns true if the game is currently paused, false if not.
bluescore number Read+Write The number of Blue Team score have in Team Match and CTF. Can be modified by Lua.
redscore number Read+Write The number of Red Team score have in Team Match and CTF. Can be modified by Lua.
timelimit number Read-only The time limit before a round ends.
pointlimit number Read-only The number of points required before a round can end.
spstage_start number Read-only The map number of the first map in the Single Player campaign.
spmarathon_start number Read-only The map number of the first map of Marathon Mode.
sstage_start number Read-only The map number of the first Single Player Special Stage.
sstage_end number Read-only The map number of the final Single Player Special Stage, including the unlockable Black Hole Zone. This will always be equal to sstage_start + 7.
smpstage_start number Read-only The map number of the first Coop Special Stage.
smpstage_end number Read-only The map number of the final Coop Special Stage. This will always be equal to smpstage_start + 6.
titlemap number Read-only The map number used as the background for the title screen.
titlemapinaction boolean Read-only Returns true if a titlemap is currently active, false if not.
bootmap number Read-only The map number to warp to immediately when starting the game.
tutorialmap number Read-only The map number of the tutorial map.
tutorialmode boolean Read-only Returns true if playing in tutorial mode, false if not.
skincolor_redteam number Read+Write The skin color of the Red Team in Team Match and CTF. Can be modified by Lua.
skincolor_blueteam number Read+Write The skin color of the Blue Team in Team Match and CTF. Can be modified by Lua.
skincolor_redring number Read+Write The skin color of the Red Team thrown ring in Team Match and CTF. Can be modified by Lua.
skincolor_bluering number Read+Write The skin color of the Blue Team thrown ring in Team Match and CTF. Can be modified by Lua.
invulntics number Read-only How long the Invincibility power-up lasts for.
sneakertics number Read-only How long the Super Sneakers power-up lasts for.
flashingtics number Read-only How long a player flashes and is invincible after taking damage.
tailsflytics number Read-only How long Tails can fly before getting tired.
underwatertics number Read-only How long the player can stay underwater before drowning.
spacetimetics number Read-only How long the player can survive in a space countdown before suffocating
extralifetics number Read-only How long the extra life music plays.
nightslinktics number Read-only How long it takes for a NiGHTS link to fade out.
gameovertics number Read-only How long the game stays at a Game Over screen before switching to the continue screen or the title screen.
ammoremovaltics number Read-only How long the ammo removal warning will be displayed when shooting a weapon ring without regular rings in Match and related gametypes.
gametype number Read-only The current gametype being played. See Constants > Gametypes.
gametyperules number Read-only The rules of the current gametype being played as a set of GTR_* flags. See Game modes > Custom gametypes.
leveltime number Read-only The amount of time that has passed in the current level since it has been loaded, measured in tics. In most gametypes, this is normally equal to the time displayed on the HUD (when converted to tics). However, in Race and Competition modes, leveltime includes the 4-second pre-timer, meaning that leveltime will be 4*TICRATE tics ahead of the HUD's displayed time once the latter has started running. Note that leveltime will continue to increase after the level is finished, even after the HUD time has stopped, until the tally screen appears. The actual time displayed on the player's HUD is set by player.realtime (see player_t).
sstimer number Read-only Time of how long the special stage can last for, in tics. Default is 90*TICRATE (90 seconds).
curWeather number Read-only The current weather type set locally. Note: This value is only calculated by the game locally for each player, and is not synchronized in netgames. Use at your own risk.
globalweather number Read-only The current weather type set globally.
levelskynum number Read-only The current sky set locally. Note: This value is only calculated by the game locally for each player, and is not synchronized in netgames. Use at your own risk.
globallevelskynum number Read-only The current sky set globally.
mapmusname string Read+Write The name of the main music track currently used for playback, if there is no active jingle track being played back. This is by default the music set by current map's level header, but it will be modified when the console command tunes is used, or linedef type 413 is executed in the map. Note: if a jingle track is active, this does not change to the name of the currently playing jingle music track. S_ChangeMusic also does not modify this variable. Can be modified by Lua.
mapmusflags number Read+Write The flags set for the main music track currently used for playback, if there is no active jingle track being played back:
  • The lowest 12 bits (bits 0–11) are the subtrack number; this can be retrieved by checking mapmusflags & 0x0FFF
  • If the 14th bit (mapmusflags & 0x4000) is set, the music track will start from the beginning if you attempt to change the music to the same track, instead of having no effect
  • If the 15th bit (mapmusflags & 0x8000) is set, the music track will be reset when the current level is reloaded.

Can be modified by Lua. Note: if a jingle track is active, this does not change to the flags set for the currently playing jingle track. S_ChangeMusic also does not modify this variable.

mapmusposition number Read-only Position in which the music starts at.
consoleplayer player_t Read-only The local player. Note: This value is only calculated by the game locally for each player, and is not synchronized in netgames. Use at your own risk.
displayplayer player_t Read+Write The player visible on screen. Can be modified by Lua. Note: This value is only calculated by the game locally for each player, and is not synchronized in netgames. Use at your own risk.
secondarydisplayplayer player_t Read-only The secondary player.
isserver boolean Read-only Returns true if the game is hosting a server, false if not. Note: This value is only calculated by the game locally for each player, and is not synchronized in netgames. Use at your own risk.
isdedicatedserver boolean Read-only Returns true if the game is a dedicated server, false if not. Note: This value is only calculated by the game locally for each player, and is not synchronized in netgames. Use at your own risk.
server player_t Read-only The server's host player.
emeralds number Read+Write This variable stores which Chaos Emeralds have been obtained in the current Single Player or Co-op session, as a set of EMERALDn flags. See Chaos Emerald > Technical information. Can be modified by Lua.
gravity number Read+Write The current global gravity value. The default value is FRACUNIT/2. Can be modified by Lua.
VERSION number Read-only The game's major version number. For SRB2 v2.2.'x', this will return 202.
SUBVERSION number Read-only The game's subversion number. For SRB2 v2.2.9, this will return 9.
VERSIONSTRING string Read-only The game's version string. For SRB2 v2.2.9, this will return "v2.2.9".
token number Read+Write The number of Special Stage Tokens collected in the current level. Can be modified by Lua.

Tables

This is a list of all global variables that are tables. Most of these serve as global arrays that give access to the userdata available for Lua.

Name Array type Usage # (Length) Description
mobjinfo mobjinfo_t mobjinfo[MT_NAME] #mobjinfo
→ Number of Object type slots (673)
This table is used to look up or modify attributes for a specific Object type, where MT_NAME is an integer that is expected to be the MT_* constant for the Object type in question.

Example usage:

mobjinfo[MT_RING_BOX].reactiontime = 20
local playerh = mobjinfo[MT_PLAYER].height
-- Example usage with mobj_t variables, using "mobj" as an example:
mobj.state = mobjinfo[mobj.type].spawnstate
-- mobj.info is a shortcut for mobjinfo[mobj.type],
--  i.e., mobj.info.VARIABLE == mobjinfo[mobj.type].VARIABLE
--  so this last example could be written more concisely as "mobj.state = mobj.info.spawnstate"

Whole entries for mobjinfo[] can be recreated from scratch if needed (see Lua/Freeslots and Object resources).

states state_t states[S_NAME] #states
→ Number of state slots (4519)
This table is used to look up or modify attributes for a specific state, where S_NAME is an integer that is expected to be the S_* constant for the state in question.

Example usage:

states[S_SPOS_STND].sprite = SPR_RBUZ
local standtics = states[S_PLAY_STND].tics
-- Example usage with mobj_t variables, using "mobj" as an example:
local st = states[mobj.state]
st.action(mobj, st.var1, st.var2)
-- calls the action for mobj's current state

Whole entries for states[] can be recreated from scratch if needed (see Lua/Freeslots and Object resources).

sfxinfo
(alt.: S_sfx)
sfxinfo_t sfxinfo[sfx_name] #sfxinfo
→ Number of sound slots (1209)
This table is used to look up or modify attributes for a specific sound, where sfx_name is an integer that is expected to be the sfx_* constant for the sound in question.

Whole entries for sfxinfo[] can be recreated from scratch if needed (see Lua/Freeslots and Object resources).

sprnames string

number
sprnames[SPR_NAME]

sprnames["NAME"]
#sprnames
→ Number of sprite set slots (522)
Converts a sprite prefix number to a string consisting of the 4-letter sprite name, or vice versa. SPR_NAME is an integer that is expected to be the SPR_* constant for the sprite prefix number in question. Likewise, "NAME" must be a four-letter prefix belonging to an existing sprite set.

Example usage:

print(sprnames[SPR_NULL]) -- prints "NULL"
print(sprnames["NULL"]) -- prints 0 (the value of SPR_NULL)
-- Example usage with mobj_t variables, using "mobj" as an example:
print("sprite = SPR_"..sprnames[mobj.sprite])
-- prints out prefix of mobj's sprite
players player_t players[playernum] #players
→ Number of player slots (32)
This table is used to look up the properties of a player, where playernum is an integer between 0 and 31.
For example, players[0] is the player_t userdata for player 1, players[1] for player 2, and so on.
skins skin_t skins[skinnum]
or skins["skinname"]
#skins
→ Number of skin slots (32)
This table is used to look up the properties of a skin, where skinnum is an integer between 0 and 31. Alternatively, skinname is the skin's name attribute, which can be given instead of the skin number.

Example usage:

print(skins[0].name) -- prints "sonic"
print(skins["sonic"].name) -- also prints "sonic"
S_StartSound(nil, skins[0].soundsid[SKSTHOK]) -- plays sfx_thok
-- Example usage with mobj_t variables, using "mobj" as an example:
print("my character's name is "..skins[mobj.skin].realname)
-- prints out the "real" name for the mobj's skin
mobj.color = skins[mobj.skin].prefcolor
-- changes mobj's color to skin's prefcolor
mapthings mapthing_t mapthings[i] #mapthings
→ Number of Things in map
This table is used to look up the properties of a Thing.
vertexes vertex_t vertexes[i] #vertexes
→ Number of vertices in map
This table is used to look up the properties of a vertex.
lines line_t lines[i] #lines
→ Number of linedefs in map
This table is used to look up the properties of a linedef.
sides side_t sides[i] #sides
→ Number of sidedefs in map
This table is used to look up the properties of a sidedef.
subsectors subsector_t subsectors[i] #subsectors
→ Number of subsectors in map
This table is used to look up the properties of a subsector.
sectors sector_t sectors[i] #sectors
→ Number of sectors in map
This table is used to look up the properties of a sector.
mapheaderinfo mapheader_t mapheaderinfo[i] #mapheaderinfo
→ Number of map slots (1035)
This table is used to look up the properties of a level header.
hudinfo hudinfo_t hudinfo[HUD_NAME] #hudinfo
→ Number of HUD items (30)
This table is used to look up or modify attributes for a specific HUD item, where HUD_NAME is an integer that is expected to be the HUD_* constant for the HUD item in question.
spriteinfo spriteinfo_t spriteinfo[SPR_NAME]

spriteinfo["NAME"]
#spriteinfo
→ Number of sprite slots used (395) Increases as more is freeslotted
This table is used to access the pivots of each of a sprite's frames, where SPR2_NAME is an integer expected to be the SPR_* constant for the sprite in question. Likewise, "NAME" must be a four-letter prefix belonging to an existing sprite set. Each of the entries of this table contain an array of spriteframepivot_t userdata, each index corresponding to a frame of animation the sprite possesses.

Example usage:

--Editing pivot properties for frame A of SPR_BUS2
spriteinfo[SPR_BUS2] = {
    pivot = {
        A = {x = 18, y = 60},
    },
}

--Editing pivot properties for frames B to E of SPR_BUS2
spriteinfo[SPR_BUS2].pivot["B"] = {x = 420, y = 69}
spriteinfo[SPR_BUS2].pivot["C"] = spriteinfo[SPR_BUS2].pivot["B"]
spriteinfo[SPR_BUS2].pivot["D"].x = 128
spriteinfo[SPR_BUS2].pivot["E"].y = 64
spr2defaults playersprite_t spr2defaults[SPR2_NAME] #spr2defaults
→ Number of sprite2 slots used (59) Increases as more is freeslotted
This table is used to look up or set the sprite to fallback to on a specific sprite2, if a character is missing such sprite, where SPR2_NAME is an integer that is expected to be the SPR2_* constant for the sprite2 in question. Likewise, "NAME" must be a four-letter prefix belonging to an existing sprite set. Note that only custom sprite2 defaults can be modified.

Example usage:

-- Okay usage of spr2defaults
spr2defaults[SPR2_RAIL] = SPR2_ROLL
-- Will cause an error to be shown on attempt to modify
spr2defaults[SPR2_WAIT] = SPR2_SKID
  Lua [view]
Language features SyntaxMetatables
SRB2 data ActionsConstantsFunctionsGlobal variablesHooksUserdata structures
SRB2Kart data Kart Userdata structuresKart FunctionsKart Hooks
Tutorials Freeslots and Object resourcesCustom player ability