Lua/Hooks

From SRB2 Wiki
< Lua
Jump to: navigation, search

A Lua hook in SRB2 is an event which a Lua function may be bound to. All bound functions on a hook are fired in the order that they are added when the event triggers. Hooks allow you to structure the scripts of your mod in a way such that they do not execute unnecessarily and they bind cleanly with the internal code.

A function may be bound to a hook by 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 that varies depending on the hook.

List of hooks

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 synchronise the current game state for joining players with that of the host's. network is a function that can be called with any local variable in the format variable = network(variable), and will handle both sides of networking.

MapChange

Hook format: addHook("MapChange", functionname)

Function format: function(int mapnum)

Executes as soon as the game starts changing to the map corresponding to mapnum. Despite the name, this includes loading a map upon starting a new game, whether in Single Player, multiplayer, Record Attack, etc.

MapLoad

Hook format: addHook("MapLoad", functionname)

Function format: function(int mapnum)

Executes as soon as everything in the map (i.e.: the geometry, objects, and special effects) corresponding to 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.

PlayerJoin

Hook format: addHook("PlayerJoin", functionname)

Function format: function(int playernum)

Executes when a player joins. playernum is the node of the joining player. Note that the player (in this case, players[playernum]) is not actually in-game at the time this hook is called, and cannot be accessed.

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.

MobjSpawn

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

Function format: function(mobj_t mobj)

Executes for objects upon spawn, i.e. when P_SpawnMobj is used. mobj is the object being spawned. Note that mobj.spawnpoint is not set before this hook is called for objects placed on the map. If the argument returns true, override default behavior; otherwise, perform it.

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)

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 or return nil or simply no return value), use the native code's checks to determine collision. Note that height checks are not performed between the objects before this hook is called, and should be manually checked 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.

MobjMoveCollide

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

Function format: function(mobj_t tmthing, mobj_t thing)

Similar to MobjCollide, except the check is performed for the moving thing, not for the thing 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)

Determines what happens when a player touches the specified object type. (The object must have the MF_SPECIAL flag.) special is the object being touched, and toucher is the mobj of the player touching it. If the argument returns true, override default behavior; otherwise, perform it. (Default behavior for most objects is to play 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.

MobjFuse

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

Function format: function(mobj_t mobj)

Executes when an object's fuse runs out. mobj is the object in question. If the function returns true, the default behavior (sending the object to XDeathState) is suppressed.

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)

Executes once per tic, per object as the object runs its thinker. mobj is the object in question. If the argument returns true, override default behavior (does not apply to player objects); otherwise, perform it.

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)

Executes once per tic for bosses only, after its normal thinker has been run. mobj is the object in question. Note that suppressing default behavior of an object in a MobjThinker hook will stop this hook from being called. If the argument returns true, override default behavior; otherwise, perform it.

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.

ShouldDamage

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

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

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 or checked 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 or return nil or simply no return value), use the native code's checks 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)

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 or checked to prevent errors. If the argument returns true, override default behavior; otherwise, perform it.

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)

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 or checked to prevent errors. If the argument returns true, override default behavior; otherwise, perform it.

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)

Executes when a boss is killed, i.e. when the action A_BossDeath is used. This determines after-death effects immediately after the boss checks if it can raise a capsule or end the level, whether or not it does; for instance by default bosses will flee like the Egg Mobile, which this hook can choose to either override or run with. If the argument returns true, override default behavior; otherwise, perform it.

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)

Executes when an object is being removed, i.e. when P_RemoveMobj is used. mobj is the object being removed. If the argument returns true, override default behavior; otherwise, perform it.

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.

JumpSpecial

Hook format: addHook("JumpSpecial", functionname)

Function format: function(player_t player)

Executes when the player presses the jump key. Returning true will override the action of the player's jump key, and returning false/nil will run the code alongside the current effect.

AbilitySpecial

Hook format: addHook("AbilitySpecial", functionname)

Function format: function(player_t player)

Executes when an ability is used after jumping, when the jump key is pressed a second time. Returning true will override the player's current ability, and returning false/nil will run the code alongside the existing ability.

SpinSpecial

Hook format: addHook("SpinSpecial", functionname)

Function format: function(player_t player)

Executes when the player presses the spin key. Returning true will override the action of the player's spin key, and returning false/nil will run the code alongside the current effect. Unlike the spindash however, SpinSpecial will by default execute even if you aren't on the ground.

JumpSpinSpecial

Hook format: addHook("JumpSpinSpecial", functionname)

Function format: function(player_t player)

Executes when the player presses the spin key in mid-air, provided not currently holding down jump. Returning true will override the player's current ability, and returning false/nil will run the code alongside the existing ability if they have one.

BotTiccmd

Hook format: addHook("BotTiccmd", functionname)

Function format: function(player_t bot, ticcmd_t cmd)

Executes 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 to alter. If the argument returns true, override default behavior; otherwise, perform it.

BotAI

Hook format: addHook("BotAI", functionname, [string skinname])

Function format: function(mobj_t player, mobj_t bot)

Executes as the input for bot movement is being created, allowing scripts to modify bot behavior. player is the player's mobj_t, and bot is the bot's mobj_t. The function should return either eight boolean values or one table of boolean values, corresponding to forward, backward, left, right, strafeleft, straferight, jump, and spin. (If returning a table, those are used as the keys for each table entry; if returning separate values, place the values in that 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.

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 placed in a map. line is the linedef that triggered the function, mobj is the object that triggered it, and sector is the triggering sector the object touched if it exists. See Linedef type 443 for more information.

The third argument to addHook is a string denoting what front texture name for Linedef type 443 to run this hook for.

PlayerMsg

Hook format: addHook("PlayerMsg", functionname)

Function format: function(player_t source, int type, player_t target, string msg)

Executes when a player sends a message in a server. source is the player that sent the message, type is the type of message sent (0 if say, 1 if sayteam, 2 if sayto, 3 if csay), target is the player the message was sent to if sayto was used, and msg is the message that was sent. Returning true will override the message being sent with the code in the block, and returning false/nil will execute the code and send the message normally.

HurtMsg

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

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

Used to create custom hurt messages for players, or to change an existing one. Executes when an object is being damaged during the use of P_DamageMobj. player is the player that was hurt, inflictor is the mobj that hurt the player, and source is the mobj 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 or checked to prevent errors. Returning true will override the message printed to the console by taking damage in multiplayer, and returning false will run alongside it instead.

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.

PlayerSpawn

Hook format: addHook("PlayerSpawn", functionname)

Function format: function(player_t player)

Executes when the player spawns in a map, or when the player is respawned in multiplayer. 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.

  Lua [view]

BasicsFunctionsGlobal variablesHooksUserdata structures

Tutorials:

Freeslots and Object resourcesCustom player ability