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, with the exception of redscore and bluescore.

Name Variable type Description
gamemap number The map number of the map currently being played.
maptol number The TypeOfLevel of the map currently being played. See Constants > TypeOfLevel flags.
ultimatemode boolean Returns true if playing in Ultimate mode, false if not.
mariomode boolean Returns true if the map is in Mario mode, false if not.
twodlevel boolean Returns true if the map is in 2D mode, false if not.
circuitmap boolean Returns true if the map is a Circuit map, false if not.
stoppedclock boolean Returns true if the timer was stopped, false if not.
netgame boolean Returns true if currently in a netgame, false if not.
multiplayer boolean Returns true if currently playing a multiplayer game, false if not.
modeattacking boolean Returns true if playing in Record Attack mode, false if not.
splitscreen boolean Returns true if playing in two-player mode, false if not.
gamecomplete boolean Returns true if the game has been completed in the current savefile, false if not.
marathonmode number The current Marathon Mode flags. See Constants > Marathon Mode flags.
devparm boolean Returns true if the game is being run with the command line parameter -debug, false if not.
modifiedgame boolean Returns true if the game has been modified and the modification does not have a custom gamedata file, false if not.
menuactive boolean Returns true if a menu is currently active, false if not.
paused boolean Returns true if the game is currently paused, false if not.
bluescore number The number of Blue Team score have in Team Match and CTF.
redscore number The number of Red Team score have in Team Match and CTF.
timelimit number The time limit before a round ends.
pointlimit number The number of points required before a round can end.
spstage_start number The map number of the first map in the Single Player campaign.
spmarathon_start number The map number of the first map of Marathon Mode.
sstage_start number The map number of the first Single Player Special Stage.
sstage_end number 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 The map number of the first Coop Special Stage.
smpstage_end number The map number of the final Coop Special Stage. This will always be equal to smpstage_start + 6.
titlemap number The map number used as the background for the title screen.
titlemapinaction boolean Returns true if a titlemap is currently active, false if not.
bootmap number The map number to warp to immediately when starting the game.
tutorialmap number The map number of the tutorial map.
tutorialmode boolean Returns true if playing in tutorial mode, false if not.
skincolor_redteam number The skin color of the Red Team in Team Match and CTF
skincolor_blueteam number The skin color of the Blue Team in Team Match and CTF
skincolor_redring number The skin color of the Red Team thrown ring in Team Match and CTF
skincolor_bluering number The skin color of the Blue Team thrown ring in Team Match and CTF
invulntics number How long the Invincibility power-up lasts for.
sneakertics number How long the Super Sneakers power-up lasts for.
flashingtics number How long a player flashes and is invincible after taking damage.
tailsflytics number How long Tails can fly before getting tired.
underwatertics number How long the player can stay underwater before drowning.
spacetimetics number How long the player can survive in a space countdown before suffocating
extralifetics number How long the extra life music plays.
nightslinktics number How long it takes for a NiGHTS link to fade out.
gameovertics number How long the game stays at a Game Over screen before switching to the continue screen or the title screen.
ammoremovaltics number How long the ammo removal warning will be displayed when shooting a weapon ring without regular rings in Match and related gametypes.
gametype number The current gametype being played. See Constants > Gametypes.
gametyperules number The rules of the current gametype being played as a set of GTR_* flags. See Game modes > Custom gametypes.
leveltime number 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 Time of how long the special stage can last for, in tics. Default is 90*TICRATE (90 seconds).
curWeather number 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 The current weather type set globally.
levelskynum number 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 The current sky set globally.
mapmusname string 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 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 Position in which the music starts at.
consoleplayer player_t 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 The player visible on screen. 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 The secondary player.
isserver boolean 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 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 The server's host player.
emeralds number 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.
gravity number The current global gravity value. The default value is FRACUNIT/2.
VERSION number The game's major version number. For SRB2 v2.2.'x', this will return 202.
SUBVERSION number The game's subversion number. For SRB2 v2.2.6, this will return 6.
VERSIONSTRING string The game's version string. For SRB2 v2.2.6, this will return "v2.2.6".
token number The number of Special Stage Tokens collected in the current level.

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 modify attributes for a specific sprite2, where SPR2_NAME is an integer that is expected to be the SPR2_* constant for the sprite2 in question. 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 structures
Tutorials Freeslots and Object resourcesCustom player ability