<cat>Dev.Lua</cat>⤶ <cat>Dev.Game</cat>⤶ # What is the hook library? The hook library allows scripts to interact with game or user created events. It allows you to "hook" a function onto an event created with <page>hook.Run</page> or <page>hook.Call</page> and run code when that events happens that either works independently or modifies the event's arguments. This is the preferred method instead of overriding functions to add your own code into it. # Using the hook library ## Adding hooks To add a hook you use the <page>hook.Add</page> function. This function takes the following arguments: 1. **Event Name** - This is the name of the event to run your hook on. 1. **Hook ID** - This is an identifier unique to the hook you are adding and can be used to remove the hook later. 1. **Hook Function** - This is the function that is ran upon the event. Below is an example of adding a hook to print to the console whenever a player spawns: ``` hook.Add("PlayerSpawn", "Spawn_Notification", function(ply) print(ply:Name() .. " has spawned!") end) ``` It can also be written this way ``` local function spawnPrint(ply) print(ply:Name() .. " has spawned!") end hook.Add("PlayerSpawn", "Spawn_Notification", spawnPrint) ``` This will print "{PlayerName} has spawned!" in to the console whenever a player spawns. <note>Hook ID's can be strings, panels or entities. If a panel or entity is given and becomes invalid, the hook is removed</note> <note>Hooks added with <page>hook.Add</page> are not ordered in any way</note> ## Hook functions When a hook is called, it is given arguments specific to its event. Information for each hook can be found on this wiki at and . Some hooks will be given no arguments at all. ## Gamemodes and hooks Functions under the GM (or GAMEMODE) table are also treated as hooks. When an event is being ran, all hooks defined using <page>hook.Add</page> are called before the Gamemode function. This means that the following code within a gamemode will also print to the console whenever a player spawns: ``` function GM:PlayerSpawn(ply) print(ply:Name() .. " has spawned!") end ``` ## Returning from hooks When a value is returned from a hook, other hooks for the same event do not run. This means that you are able to override other hooks and gamemode functions. <note>You should return values only when needed, `return` and `return false` are different.</note> To see if the returned value of the hook will affect it the wiki page of that hook should have `Returns` section. This example shows the use of the <page>SANDBOX:PlayerSpawnProp</page> event. This event expects hooks to return true if the player is allowed to spawn a prop and false otherwise. If nothing is returned it'll run the next hook. ``` hook.Add("PlayerSpawnProp", "Admin_Props", function(ply, model) if (ply:IsAdmin()) then return true end return false end) ``` This code will only allow admins to spawn props. As it is always returning a value, it overrides other hooks. ## Adding your own events You can add your own events by simply calling <page>hook.Run</page> or <page>hook.Call</page>. You shouldn't need to create a hook for every event that happens in your addons as that would be useless but important things such as a gamemode checking for a map switch or events that you want external scripts to edit should have hooks. The following example calls all hooks that are hooked to the "PerformMultiplication" event and supplied an argument to each hook. ``` hook.Add("PerformMultiplication", "Multiply_Obob", function(a, b) return (a * b) end) local returnedValue = hook.Run("PerformMultiplication", 3, 4) print(returnedValue) ``` This example will output 12 <note>It is advised not to trigger default hooks unless you know what you are doing</note>