Lua/Global variables

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

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.

Server-side

In the event of a netgame, these variables either cannot be manually changed, or are constantly synchronized by the server. Therefore, in normal circumstances, their value across different clients is consistent, and it is thus safe to use them to make logical comparisons without worrying about desynchronization.

Name	Variable type	Accessibility	Description
udmf	boolean	Read-only	Returns true if the map is in UDMF, false if not.
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.
stagefailed	boolean	Read-only	TODO.
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.
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.
metalrecording	boolean	Read-only	Returns true if Metal Sonic recording is active, 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.
usedCheats	boolean	Read-only	Returns true if cheat commands found here have been used, 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.
redscore	number	Read+Write	The number of Red Team score have in Team Match and CTF.
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.
redflag	mobj_t	Read-only	This refers to the current Red Team flag's mobj in CTF, becomes nil when a player picked up the flag.
blueflag	mobj_t	Read-only	This refers to the current Blue Team flag's mobj in CTF, becomes nil when a player picked up the flag.
rflagpoint	mapthing_t	Read-only	This refers to the current Red Team flag's spawnpoint in CTF, normally to respawn the flag when tossed for a long time or when falling into a bottomless pit.
bflagpoint	mapthing_t	Read-only	This refers to the current Blue Team flag's spawnpoint in CTF, normally to respawn the flag when tossed for a long time or when falling into a bottomless pit.
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.
skincolor_blueteam	number	Read+Write	The skin color of the Blue Team in Team Match and CTF.
skincolor_redring	number	Read+Write	The skin color of the Red Team thrown ring in Team Match and CTF.
skincolor_bluering	number	Read+Write	The skin color of the Blue Team thrown ring in Team Match and CTF.
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.
use1upSound	UINT8	Read-only	When set, the game always plays a 1up sound effect, no matter the client-side setting.
maxXtraLife	UINT8	Read-only	Defines maximum amount of extra lifes the player can get per 100 rings. By default, only 2 extra lifes per 100 rings.
useContinues	UINT8	Read-only	When set, continues avaliable outside of no-save sessions. By default, continues are only avaliable on no-save game sessions.
shareEmblems	UINT8	Read-only	When set, the gamedata being synced with the server's gamedata. By default, this is not the case.
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).
globalweather	number	Read-only	The current weather type set globally.
globallevelskynum	number	Read-only	The current sky set globally.
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.
token	number	Read+Write	The number of Special Stage Tokens collected in the current level.
gravity	number	Read+Write	The current global gravity value. The default value is FRACUNIT/2.
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.13, this will return 13.
VERSIONSTRING	string	Read-only	The game's version string. For SRB2 v2.2.13, this will return "v2.2.13".

Client-side

These variables are not constantly synchronized by the server and can be different across clients either by accident or design. It is not safe to use them in logical comparisons that can affect player positioning, as that will most likely result in the desynchronization of a netgame.

Name	Variable type	Accessibility	Description
curWeather	number	Read-only	The current weather type set locally.
levelskynum	number	Read-only	The current sky set locally.
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.
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. 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.
displayplayer	player_t	Read+Write	The player visible on screen.
secondarydisplayplayer	player_t	Read-only	The secondary player, when splitscreen mode is active.
isserver	boolean	Read-only	Returns true if the game is hosting a server, false if not.
isdedicatedserver	boolean	Read-only	Returns true if the game is a dedicated server, false if not.
camera	camera_t	Userdata: Read-only Userdata variables: Read+Write	The primary camera in-game.
camera2	camera_t	Userdata: Read-only Userdata variables: Read+Write	The secondary camera in-game, only on splitscreen.
mouse	mouse_t	Read-only	The first player's mouse.
mouse2	mouse_t	Read-only	The second player's mouse.
menuactive	boolean	Read-only	Returns true if a menu is currently active, false if not.

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	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	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	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	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
spr2names	string number	spr2names[SPR2_NAME] spr2names["NAME"]	#spr2names → Number of sprite2 slots used	Converts a sprite2 prefix number to a string consisting of the 4-letter sprite2 name, or vice versa. SPR2_NAME is an integer that is expected to be the SPR2_* constant for the sprite2 prefix number in question. Likewise, "NAME" must be a four-letter prefix belonging to an existing sprite2.
players	player_t	players[playernum]	#players → Number of player slots	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	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.
polyobjects	polyobj_t	polyobjects[i]	#polyobjects → Number of polyobjects in map	This table is used to look up the properties of a polyobject.
mapheaderinfo	mapheader_t	mapheaderinfo[i]	#mapheaderinfo → Number of map slots	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
skincolors	skincolor_t	skincolors[SKINCOLOR_NAME]	#skincolors → Number of skin color slots used Increases as more is freeslotted	This table is used to look up or modify attributes for a specific skin color, where SKINCOLOR_NAME is an integer that is expected to be the SKINCOLOR_* constant for the skin color in question.
gamekeydown	boolean	gamekeydown[keynum]	#gamekeydown → Number of keys	This table is used to look up or modify the pressed state for a specific key.
tags	table/userdata	tags.iterate()	#tags → Number of unique tags	This table is used to look up for unique tags on the map around all sectors, things and lines.