Lua/Hooks
To do Add in descriptions for new hook types!!! |
A Lua hook is an event that occurs within SRB2 that Lua functions may be bound to. When such an event occurs, all functions bound to the hook are executed in the order that they were added. Hooks are the main points of connection between SRB2's source code and custom Lua code – they are what allows users to insert custom game logic into SRB2 via Lua.
A function is bound to a hook by calling the addHook
function:
--A local function hooked
local function my_mobj_thinker_handler()
end
addHook("MobjThinker", my_mobj_thinker_handler, MT_PLAYER)
--An inline function hooked
addHook("MobjThinker", function()
--do things
end
, MT_PLAYER)
This function takes three arguments: a string denoting the hook to add this function to, the function being hooked, and a third argument whose type and purpose varies depending on the hook (and which is omitted for some hooks). Some hooks use the return value of the hooked function to determine what should be done next, while other hooks do not use it. As seen in the above example, the hooked function can either be defined as a local function and then passed to addHook
, or it can be defined inline during the call to addHook
. The latter is useful for short functions that are only used once in the context of this particular addHook
call, but if the function is long or needs to be used again elsewhere in the Lua script, the former method is preferred.
List of hooks
Global
IntermissionThinker
Hook format: addHook("IntermissionThinker", functionname)
Function format: function(boolean stagefailed)
Executes every tic during the 'Character got through the act' screen.
LinedefExecute
Hook format: addHook("LinedefExecute", functionname, string hookname)
Function format: function(line_t line, mobj_t mobj, sector_t sector)
Executes when called by a linedef executor of linedef type 443 placed in a map. line
is the linedef that triggered the function, mobj
is the Object that triggered the linedef executor, and sector
is the triggering sector the Object touched, if it exists.
The third argument to addHook
is the name of the linedef execution hook – the function is only executed if this name is written across the front textures of the linedef with type 443 that triggered the hook.
MapChange
Hook format: addHook("MapChange", functionname)
Function format: function(int mapnum)
Executes as soon as the game receives a command to load a map. This can occur after the map
command is used, when the game warps to the next level after finishing another, or when starting a new game (whether in Single Player, multiplayer, Record Attack, etc). mapnum
is the number of the new map being loaded. Despite the hook's name, it is executed even if the game was not already in a map before.
MapLoad
Hook format: addHook("MapLoad", functionname)
Function format: function(int mapnum)
Executes as soon as everything (i.e.: the geometry, Objects, and special effects) in the map specified in mapnum
has been loaded. It is important to note that all thinkers (including functions for the ThinkFrame
hook) are run twice before functions for this hook are executed.
ThinkFrame
Hook format: addHook("ThinkFrame", functionname)
Function format: function()
Executes once every game tic, after Object and Player thinkers have been run for the current tic, and before PostThinkFrame
.
PreThinkFrame
Hook format: addHook("PreThinkFrame", functionname)
Function format: function()
Executes once every game tic, before all other thinkers have been run for the current tic. This timing is especially useful for editing player inputs, because at that point no thinkers have used them yet.
PostThinkFrame
To do Explain what this does in more detail. |
Hook format: addHook("PostThinkFrame", functionname)
Function format: function()
Executes once every game tic, after all other thinkers (including Object, Player, ThinkFrame
, overlays, precipitation), and texture, timelimit
, and pointlimit
gamelogic have been run for the current tic, and directly before rendering the frame.
GameQuit
To do Check if this is correct. |
Hook format: addHook("GameQuit", functionname)
Function format: function(boolean quitting)
Executes when the player returns to the title screen from a game, and when the application is about to exit to desktop. If quitting
is true, then the application is exiting.
This hook is only executed locally, and thus isn't network-safe. Use at your own risk.
Bot
BotAI
Hook format: addHook("BotAI", functionname, [string skinname])
Function format: function(mobj_t player, mobj_t bot)
Function return value: 8 boolean values/Table of boolean values
Executes every tic as the key input for bot movement is being created, allowing scripts to modify bot behavior. player
is the mobj_t
of the player the bot follows, and bot
is the bot's mobj_t
. The function should return the key input for the bot, either as eight boolean values or as one table of boolean values. Each value is associated with one key and indicates whether the respective key is being pressed in the current tic or not; in order, the values are forward
, backward
, left
, right
, strafeleft
, straferight
, jump
, and spin
. If returning a table, these names must be used as the keys for the table entries; unused keys can be omitted. If returning separate boolean values, the values must be placed in the above order.
The third argument to addHook
is a string denoting the name of the skin for bot
to run this hook for. Note that this will not work if the character's skin name is not written as all-lowercase in the S_SKIN
. If omitted, it will run for all skins.
BotTiccmd
Hook format: addHook("BotTiccmd", functionname)
Function format: function(player_t bot, ticcmd_t cmd)
Function return value: Boolean (override default behavior?)
Executes every tic as the input for bot movement is being created, allowing scripts to modify bot behavior. bot
is the player_t
of the bot being manipulated, and cmd
is the ticcmd_t
for the bot in the current tic, which can be altered by this function to change the bot behavior. If the function returns true
, the game's default behavior is overridden; otherwise, it is performed after executing the function.
BotRespawn
Hook format: addHook("BotRespawn", functionname)
Function format: function(mobj_t player, mobj_t bot)
Function return value: Boolean (force respawn?)
Executes every tic as a bot is deciding whether to respawn. player
is the mobj_t
of the player the bot follows, and bot
is the bot's mobj_t
. If the function returns true
, the bot will attempt to respawn; if the function returns false
the bot will not attempt to respawn. Otherwise, the game's default behavior is used.
Multiplayer
HurtMsg
Hook format: addHook("HurtMsg", functionname, [int objecttype])
Function format: function(player_t player, mobj_t inflictor, mobj_t source, int damagetype)
Function return value: Boolean (override default behavior?)
Used to create custom hurt messages for players to be displayed in the chat window in multiplayer, or to change an existing one. Executes when a player is being damaged during the use of P_DamageMobj
. player
is the player that was hurt, inflictor
is the Object that hurt the player, and source
is the Object responsible for the inflictor's existence. Note that inflictor
and/or source
may be nil
, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true
, the message normally printed to the console when taking damage in multiplayer is overridden; if it returns false
/nil
, the message is printed in addition to running the function.
The third argument to addHook
determines what Object type for inflictor
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
NetVars
Hook format: addHook("NetVars", functionname)
Function format: function(function(variable) network)
Executes whenever a new player joins a netgame. Determines what variables to write to or load from $$$.sav
, the file used to synchronize the current game state for joining players with that of the host. network
is a function that can be called with any local variable, using the format variable = network(variable)
. This will handle both sides of network synchronization for this particular variable.
Only numbers, strings, booleans, userdata and tables that contain only these types are supported. Recursive tables (tables that contain tables that contain tables, etc) are supported.
PlayerJoin
Hook format: addHook("PlayerJoin", functionname)
Function format: function(int playernum)
Executes when a player joins a netgame. playernum
is the number of the joining player. Note that the player has not yet been spawned at the time this hook is called, and so the player data (in this case, players[playernum]
) cannot be accessed.
PlayerQuit
Hook format: addHook("PlayerQuit", functionname)
Function format: function(player_t player, int reason)
Executes when player
quits while in a netgame. Note that the player will still be valid and accessible when this hook is called, and the player's Object can still be accessed. The reason for quitting the game is given by the reason
argument, in the form of a KR_*
constant; see Constants > Kick reasons for possible values.
PlayerMsg
Hook format: addHook("PlayerMsg", functionname)
Function format: function(player_t source, int type, player_t target, string msg)
Function return value: Boolean (override default behavior?)
Executes when a player sends a chat message in a server. source
is the player that sent the message, type
is the type of message sent (0 for say
, 1 for sayteam
, 2 for sayto
, 3 for csay
), target
is the player the message was sent to if sayto
was used, and msg
is the message that was sent. If the function returns true
, the game will not send the message itself and instead only execute the function; if it returns false
/nil
, it will execute the function and then send the message normally.
TeamSwitch
Hook format: addHook("TeamSwitch", functionname)
Function format: function(player_t player, int team, boolean fromspectators, boolean autobalance, boolean scramble)
Function return value: Boolean (allow team switching?, nil
= use default behavior)
Executes when player
attempts to change teams in a netgame, including entering the game and spectating. team
is the team the player is attempting to switch to, fromspectators
indicates whether the player is attempting to enter the game, and autobalance
and scramble
indicate if the change is being forced by the autobalance mechanic or a manual team scramble, respectively. Returning true
allows the player to switch teams, while returning false
disallows it. Returning nil
will allow the game to use the default behavior.
ViewpointSwitch
Hook format: addHook("ViewpointSwitch", functionname)
Function format: function(player_t player, player_t nextviewedplayer, boolean forced)
Function return value: Boolean (allow view of the player?, nil
= use default behavior)
Executes when player
attempts to watch another player in a netgame via the button F12. nextviewedplayer
is the player about to be watched, and forced
indicates whether the view was forcibly switched (e.g. the current player being watched has left the netgame). Returning true
forces the view to be changed, while returning false
skips the player about to be viewed. Returning nil
will allow the game to use the default behavior.
This hook is only executed locally, and thus isn't network-safe. Use at your own risk.
SeenPlayer
Hook format: addHook("SeenPlayer", functionname)
Function format: function(player_t player, player_t seenplayer)
Function return value: Boolean (allow player name to be displayed?, nil
= use default behavior)
Executes when player
is pointing the camera to another player in order to see their name. Depends on the seenames
variable to function. seenplayer
is the player being pointed at. Returning true
will allow their name to be displayed on screen, while returning false
will force it not to be displayed. Returning nil
will allow the game to use the default behavior.
This hook is only executed locally, and thus isn't network-safe. Use at your own risk.
Player
PlayerThink
Hook format: addHook("PlayerThink", functionname)
Function format: function(player_t player)
Similar to MobjThinker: Executes once per tic for the player as it runs its thinker. If you need to override the player's control inputs, it is highly recommended to do so in a PlayerCmd hook instead, as some of the inputs have already been consumed by the game when PlayerThink is called.
PlayerCanDamage
Hook format: addHook("PlayerCanDamage", functionname)
Function format: function(player_t player, mobj_t mobj)
Determines whether the player can damage another object; generally performed when a player and object collide with another. If returning true, the player is forced to attack the object. When returned false, the player is forced to not attack the object. Returning no argument continues the game's usual checks.
PlayerSpawn
Hook format: addHook("PlayerSpawn", functionname)
Function format: function(player_t player)
Executes when a player spawns in a map or is respawned. player
is the player in question. It is important to note that, when a map is loaded, players are always spawned after all other Things in the map have been loaded.
PlayerHeight
Hook format: addHook("PlayerHeight", functionname)
Function format: function(player_t player)
Function return value: Fixed-point number (the new player's height)
The function should return a fixed-point number which the player object's height will be set to. If the function returns nil or a negative value, the game will use default checks to determine the player height.
PlayerCanEnterSpinGaps
Hook format: addHook("PlayerCanEnterSpinGaps", functionname)
Function format: function(player_t player)
Function return value: Boolean (should the player fit into the gap?)
The function should return a boolean which can forcibly allow or block gap passage, returning true
allows players to fit into any gap that is smaller than their skin's height field, while returning false
will prevent the player from fitting into any gap that is smaller than their skin's height field.
ShieldSpawn
Hook format: addHook("ShieldSpawn", functionname)
Function format: function(player_t player)
Function return value: Boolean (override default behavior?)
Executes when a player obtains a shield. player
is the player in question. Keep in mind that this hook's functionality extends to all uses of P_SpawnShieldOrb
.
Player abilities
AbilitySpecial
Hook format: addHook("AbilitySpecial", functionname)
Function format: function(player_t player)
Function return value: Boolean (override default behavior?)
Executes when a player uses their special ability after jumping, when the Jump key is pressed a second time. player
is the player in question. Returning true
will override the player's regular ability, and returning false
/nil
will run the function alongside the existing ability.
JumpSpecial
Hook format: addHook("JumpSpecial", functionname)
Function format: function(player_t player)
Function return value: Boolean (override default behavior?)
Executes when a player presses the Jump key. player
is the player in question. Returning true
will override the regular effect of the player's Jump key, and returning false
/nil
will run the function alongside the existing effect.
JumpSpinSpecial
Hook format: addHook("JumpSpinSpecial", functionname)
Function format: function(player_t player)
Function return value: Boolean (override default behavior?)
Executes when a player presses the Spin key during a jump. player
is the player in question. Returning true
will override the player's regular ability, and returning false
/nil
will run the function alongside any existing ability. Even when returning true
, this hook's action will be interrupted by both the super transformation (when conditions are met) and shield abilities (provided the SF_NOSHIELDABILITY
flag is not present).
SpinSpecial
Hook format: addHook("SpinSpecial", functionname)
Function format: function(player_t player)
Function return value: Boolean (override default behavior?)
Executes when a player presses the Spin key. player
is the player in question. Returning true
will override the regular effect of the player's Spin key, and returning false
/nil
will run the function alongside the existing effect. Note that this hook will execute even if the player is not on the ground.
ShieldSpecial
Hook format: addHook("ShieldSpecial", functionname)
Function format: function(player_t player)
Function return value: Boolean (override default behavior?)
Executes when a player uses their shield ability, including both jump+spin activation as well as the whirlwind shield's emergency jump. player
is the player in question. If the function returns true
then the shield's default action will be overwritten, however returning false/nil
will run the function alongside the existing ability. Note that if one simply wishes to disable shield abilities, the skin flag SF_NOSHIELDABILITY
should be used instead.
Mobj
MapThingSpawn
Hook format: addHook("MapThingSpawn", functionname, [int objecttype])
Function format: function(mobj_t mobj, mapthing_t mapthing)
Function return value: Boolean (override default behavior?)
This hook executes when a Thing in a map spawns its corresponding Object. mobj
is the Object being spawned, and mapthing
is the Thing in the map that spawns mobj
. If the function returns true
, the default spawning behavior is overridden; otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type for mobj
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
Note that this hook runs after the MobjSpawn hook for the spawned Object.
MobjSpawn
Hook format: addHook("MobjSpawn", functionname, [int objecttype])
Function format: function(mobj_t mobj)
Function return value: Boolean (override default behavior?)
Executes when an Object is spawned, i.e., when P_SpawnMobj
is used. mobj
is the Object being spawned. Note that for Objects spawned on the map via Things, mobj.spawnpoint
is not set before this hook is called. If the function returns true
, the default spawning behavior is overridden; otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
MobjRemoved
Hook format: addHook("MobjRemoved", functionname, [int objecttype])
Function format: function(mobj_t mobj)
Function return value: Boolean (override default behavior?)
Executes when an Object is being removed, i.e., when P_RemoveMobj
is used. mobj
is the Object being removed. If the function returns true
, the default removal behavior is overridden; otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
MobjThinker
Hook format: addHook("MobjThinker", functionname, [int objecttype])
Function format: function(mobj_t mobj)
Function return value: Boolean (override default behavior?)
Executes once per tic for each Object as it runs its thinker. mobj
is the Object in question. If the function returns true
, the default thinker is overridden (does not apply to player Objects); otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
Mobj thinkers not bound to a specific Object type are slated for removal and should not be used for the sake of future compatibility as well as general performance.
MobjFuse
Hook format: addHook("MobjFuse", functionname, [int objecttype])
Function format: function(mobj_t mobj)
Function return value: Boolean (override default behavior?)
Executes when an Object's fuse has run out. mobj
is the Object in question. If the function returns true
, the default behavior (sending the Object to its XDeathState
) is suppressed; otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
BossThinker
Hook format: addHook("BossThinker", functionname, [int objecttype])
Function format: function(mobj_t mobj)
Function return value: Boolean (override default behavior?)
Executes once per tic for bosses only, after its normal thinker has been run. mobj
is the boss Object in question. Note that suppressing the default behavior of an Object in a MobjThinker
hook will stop this hook from being called. If the function returns true
, the default boss behavior will be overridden; otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
Mobj interactions
ShouldDamage
Hook format: addHook("ShouldDamage", functionname, [int objecttype])
Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage, int damagetype)
Function return value: Boolean (should damage?, nil
= use default behavior)
Executes when an Object decides whether to be damaged or not during the use of P_DamageMobj
. target
is the Object being damaged, inflictor
is the Object that damaged it, and source
is the Object responsible for the inflictor's existence. Note that inflictor
and/or source
may be nil
, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true
, the Object is forced to be damaged, and if the function returns false
, it is forced to not be damaged. Otherwise (return
, return nil
or simply no return value), SRB2's default checks are used to determine whether the Object is damaged.
The third argument to addHook
determines what Object type for target
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
MobjDamage
Hook format: addHook("MobjDamage", functionname, [int objecttype])
Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage, int damagetype)
Function return value: Boolean (override default behavior?)
Executes when an Object is being damaged during the use of P_DamageMobj
. target
is the Object being damaged, inflictor
is the Object that damaged it, and source
is the Object responsible for the inflictor's existence. Note that inflictor
and/or source
may be nil
, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true
, the default damage behavior is overridden; otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type for target
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
MobjDeath
Hook format: addHook("MobjDeath", functionname, [int objecttype])
Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damagetype)
Function return value: Boolean (override default behavior?)
Executes when an Object is killed, i.e., when P_KillMobj
is used. target
is the Object being killed, inflictor
is the Object that killed it, and source
is the Object responsible for the inflictor's existence. Note that inflictor
and/or source
may be nil
, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true
, the default death behavior is overridden; otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type for target
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
BossDeath
Hook format: addHook("BossDeath", functionname, [int objecttype])
Function format: function(mobj_t mobj)
Function return value: Boolean (override default behavior?)
Executes when a boss is killed, i.e., when the action A_BossDeath
is used. mobj
is the boss Object in question. This determines after-death effects performed immediately after the boss checks if it can raise a capsule or end the level, regardless of whether or not it has done so. For example, by default bosses will flee like the Egg Mobile, which this hook can choose to override or not. If the function returns true
, the default after-death behavior will be overridden; otherwise, it will be performed after executing the function.
The third argument to addHook
determines what Object type to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
FollowMobj
Hook format: addHook("FollowMobj", functionname, [int objecttype])
Function format: function(player_t player, mobj_t followmobj)
Function return value: Boolean (override default behavior?)
Executes when SRB2 handles a followmobj of type objecttype
in the function P_PlayerAfterThink — this occurs after most thinkers for the tic have been run, but before any ThinkFrame hooks have been executed. If objecttype
is omitted, or set to MT_NULL
, this hook will run for followmobjs of any type. If the function returns an expression that evaluates as true
, the default followmobj behavior is overridden; otherwise, the default behavior will run after the hook is executed.
Mobj collision
MobjCollide
Hook format: addHook("MobjCollide", functionname, [int objecttype])
Function format: function(mobj_t thing, mobj_t tmthing)
Function return value: Boolean (do Objects collide?, nil
= use default behavior)
Determines whether and how collision should be handled between two Objects during the use of P_CheckPosition
. thing
is the Object being collided with, and tmthing
is the moving Object colliding with thing
. If the function returns true
, the Objects have collided, and if the function returns false
, they have not. Otherwise (return
, return nil
or simply no return value), SRB2's default checks are used to determine collision. Note that height checks are not performed between the Objects before this hook is called, and should be manually performed for accurate results.
The third argument to addHook
determines what Object type for thing
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
MobjLineCollide
Hook format: addHook("MobjLineCollide", functionname, [int objecttype])
Function format: function(mobj_t mobj, line_t line)
Function return value: Boolean (does the Object collide with the line?, nil
= use default behavior)
Executes when an Object attempts to cross a linedef. mobj
is the Object traversing the linedef, and line
is the linedef being traversed. Returning true
to this function will force the Object to be stopped by the linedef, while returning false
will force the Object to cross it. Returning nil
will allow SRB2's default checks to determine collision.
The third argument to addHook
determines what Object type for mobj
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
MobjMoveBlocked
Hook format: addHook("MobjMoveBlocked", functionname, [int objecttype])
Function format: function(mobj_t mobj, thing thing, line_t line)
Function return value: Boolean (override default behavior?)
Executes when an Object's X/Y movement is blocked — it doesn't matter what stopped you. mobj
is the Object in question. thing
is the object that stopped you, if applicable. Otherwise, line
is the linedef that stopped you. If the function returns true, the default removal behavior is overridden.
The third argument to addHook
determines what mobj
type to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
MobjMoveCollide
Hook format: addHook("MobjMoveCollide", functionname, [int objecttype])
Function format: function(mobj_t tmthing, mobj_t thing)
Function return value: Boolean (do Objects collide?, nil
= use default behavior)
Similar to MobjCollide
, except the check is performed for the moving Object, not for the Object being moved into.
The third argument to addHook
determines what Object type for tmthing
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
TouchSpecial
Hook format: addHook("TouchSpecial", functionname, [int objecttype])
Function format: function(mobj_t special, mobj_t toucher)
Function return value: Boolean (override default behavior?)
Determines what happens when a player touches an Object of the specified Object type. The Object must have the MF_SPECIAL
flag. special
is the Object being touched, and toucher
is the Object representing the player touching it. If the function returns true
, the default touching behavior is overridden; otherwise, it will be performed after executing the function. The default behavior for most Objects is to play its DeathSound
and use P_KillMobj
to go to the Object's DeathState
, but this depends on the Object. Unlike the MobjCollide
hook, height checks are performed before this hook is called.
The third argument to addHook
determines what Object type for special
to run this hook for (should be one of the MT_*
constants). If omitted or set to MT_NULL
, it will run for all Object types.
Music
MusicChange
Hook format: addHook("MusicChange", functionname)
Function format: function(string oldname, string newname, int mflags, boolean looping, int position, int prefadems, int fadeinms)
Function return value: String/Boolean, Int, Boolean, Integer, Integer, Integer (see below.)
Executes when the currently playing music is about to be changed, i.e., when S_ChangeMusic
is used. oldname
is the name of the music that it will change from, newname
is what the music will be changed to, mflags
defines the music flags being used (see S_ChangeMusic for more information), looping
defines if the song will loop or not, position
defines the song's current play time (in milliseconds), prefadems
defines the duration in milliseconds to fade-out of the current song before changing to the new song, and fadeinms
defines the duration in milliseconds of the fade-in of the song once it starts.
It is possible to override all parameters, or prevent a song from overriding another, like such:
- The first value to return can be a boolean or string.
- If it's a boolean, passing
true
will stop the overriding song from playing at all. - If it's a string, it should be a music name.
- If it's a boolean, passing
- The second value is an integer, specifically
MUSIC_*
flags. - The third value is a boolean, indicating if the song should loop or not.
- The fourth value is an integer, millisecond position to start at upon song change.
- The fifth value is an integer, milliseconds to fade out of the current song before changing to the new song.
- The sixth value is an integer, milliseconds to fade into the new song.
Thus, a return statement like return false, mflags, looping, 5000, 0, 3000
will let the music override happen, using the same flags, start 5 seconds into the song, allow fade-in and let it happen for 3 seconds.
This hook is only executed locally, and thus isn't network-safe. Use at your own risk.
ShouldJingleContinue
To do Check if this is correct. |
Hook format: addHook("ShouldJingleContinue", functionname, string musname)
Function format: function(player_t player, string musname)
Executes when SRB2 evaluates whether a jingle of type JT_OTHER
should continue playing. Jingles are evaluated only when P_RestoreMusic
is called. If this function returns false or nil, the jingle will stop; otherwise, it will continue.
This hook is only executed locally, and thus isn't network-safe. Use at your own risk.
Controls
KeyDown
Hook format: addHook("KeyDown", functionname)
Function format: function(keyevent_t keyevent)
Function return value: Boolean (override default behavior?)
Executes when a keyboard key is being pressed. If the function returns true
, the default behavior of the key is overridden; otherwise, it will be performed after executing the function.
This hook is only executed locally, and thus isn't network-safe. Use at your own risk.
KeyUp
Hook format: addHook("KeyUp", functionname)
Function format: function(keyevent_t keyevent)
Function return value: Boolean (override default behavior?)
Executes when a keyboard key is released. If the function returns true
, the default behavior of the key is overridden; otherwise, it will be performed after executing the function.
This hook is only executed locally, and thus isn't network-safe. Use at your own risk.
PlayerCmd
Hook format: addHook("PlayerCmd", functionname)
Function format: function(player_t player, ticcmd_t cmd)
Executes once per tic for the local client before their button inputs are sent to the server (or executed in singleplayer), and as such, this hook is only executed locally.
player
is the local player, and cmd
is a ticcmd_t
userdata representing the button information performed locally this tic.
Other
HUD
Hook format: addHook("HUD", functionname, string hudtype)
Function format: function(v, camera_t camera, player_t player)
Alternative format: function(v, player_t player)
Functions exactly the same as hud.add
, adding a new HUD element to the game. The list of valid hudtype
options is here.
Lua | [view] | |
Language features | Syntax • Metatables | |
SRB2 data | Actions • Constants • Functions • Global variables • Hooks • Userdata structures | |
SRB2Kart data | Kart Userdata structures • Kart Functions • Kart Hooks • Kart Global Variables and Constants | |
Tutorials | Freeslots and Object resources • Custom player ability |