Lua/Global variables

From SRB2 Wiki
< Lua
Jump to navigation Jump to search
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.
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.
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 (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
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 (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.
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 (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
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.
  Lua [view]
Language features SyntaxMetatables
SRB2 data ActionsConstantsFunctionsGlobal variablesHooksUserdata structures
SRB2Kart data Kart Userdata structuresKart FunctionsKart HooksKart Global Variables and Constants
Tutorials Freeslots and Object resourcesCustom player ability