Lua/Hooks

This article or section is outdated and has not been fully updated to reflect the current version of SRB2. Please help the Wiki by correcting or removing any misinformation, as well as adding any new information to the page.

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.

Mobjs with fuse 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.

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.

Boss 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.

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.

Follow mobjs 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.

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.

Mobj collisions 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.

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.

Mobj colisions against linedefs 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.

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.

Mobj collising being blocked 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.

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.

Mobj colisions from the moving object 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.

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.
• 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.

Currently only exists in 2.2.14 nightly.

AddonLoaded

Hook format: addHook("AddonLoaded", functionname)

Function format: function()

Executes once every time any addon loads. This hook is useful most for compatibility between mods, and also this is the only hook that allows adding new hooks.

This hook is only executed locally, and thus isn't network-safe. Use at your own risk.