Lua/Hooks

From SRB2 Wiki
< Lua
Jump to: navigation, search

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

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 all other thinkers (including Object thinkers) have been run for the current tic, and before rendering the frame.

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.

Netplay

HurtMsg

Hook format: addHook("HurtMsg", functionname, [int objecttype])

Function format: function(player_t player, mobj_t inflictor, mobj_t source)

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.

PlayerJoin

Hook format: addHook("PlayerJoin", functionname)

Function format: function(int playernum)

Executes when a player joins a netgame. playernum is the node 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.

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.

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.

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 in mid-air, unless they are currently holding down the Jump key. 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, if they have one.

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.

Object

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.

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.

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.

MobjDamage

Hook format: addHook("MobjDamage", functionname, [int objecttype])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage)

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)

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.

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

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.

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.

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.

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.

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.

ShouldDamage

Hook format: addHook("ShouldDamage", functionname, [int objecttype])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage)

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.

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.

  Lua [view]
Language features SyntaxMetatables
SRB2 data ActionsConstantsFunctionsGlobal variablesHooksUserdata structures
Tutorials Freeslots and Object resourcesCustom player ability