Using Hooks

As mentioned in Hooks, the TARDIS uses its own entity-based hook system. This means that the TARDIS calls all sorts of events or hooks on the interior and exterior entities, and sometimes may even pass parameters.

Obviously this was built with extensions in mind, meaning that any module, even extension-defined ones, can take advantage of this system.

This page contains reference and examples for using all the hook functions.

ENT:AddHook(hookName, hookID, function)

This function adds a hook to the entity that loads the current module. The loading entity will depend on where the module is located (gmod_tardis/modules or gmod_tardis_interior/modules)

You should avoid calling this inside other hooks unless you REALLY know what you're doing.

Arguments

String hookName - The name of the hook or event. You can find this in the hook lists.

String hookID - The name or ID of this specific listener to the hook. It's used by ENT:RemoveHook(). This ID has to be unique even among other extensions, so it's advisable that you prepend your extension's name on it (i.e. "MyExtension-HookID")

Function function(self, ...) This is the function that will be executed when the hook is called via ENT:CallHook(). The arguments to this function are parameters that ENT:CallHook() will pass. The first argument is always the current entity the module is hooking into.

Examples

Play a sound when the TARDIS has materialized

--/lua/entities/gmod_tardis/sv_matsound.lua
ENT:AddHook("StopMat","MyExtension-OnMatSound",function(self) --self = the exterior
    self:EmitSound("garrysmod/save_load1.wav")
end)

Prevent the TARDIS from taking off

--/lua/entities/gmod_tardis/sv_dontdemat.lua
ENT:AddHook("CanDemat","MyExtension-GrumpyTARDISNoDemat",function(self)
    self:GetCreator():ChatPrint("No demat here!")
    return false
end)

The above example shows an "override" hook. By returning false here, we're telling the TARDIS not to do whatever it was going to. Most hooks that start with Can will do this.

It's recommened you don't return anything unless you explicitly want to override other behaviour. For instance, returning true would override all other listeners and dematerialise no matter what, even doing so with no power or health.

Hooks with multiple arguments

--lua/entities/gmod_tardis_interior/sv_someoneusedapart.lua
ENT:AddHook("PartUsed","MyExtension-PartUsed", function(self, part, ply)
    --self = the interior, part = the part that was used, ply = player who used it
    ply:ChatPrint("You used the "..part.name.."!")
end)

ENT:CallHook(hookName, args...)

This function calls the hooks added via ENT:AddHook(). It's how you would add custom events. You can call this function inside hooks, or from parts.

Arguments

String hookName - The name of the hook to call. They are listed on Hooks. args... - This is any argument or data you want to pass to said hook. This is where the data you can access in the function() part of ENT:AddHook() comes from. You can have any number of these.

Examples

--Snippet from lua/entities/gmod_tardis_interior/sh_controlsequences.lua
--Line 55 to 64
if SERVER then
    ENT:AddHook("PartUsed","HandleControlSequence",function(self,part,a)
        local sequences = TARDIS:GetControlSequence(self.metadata.Interior.Sequences)
        if sequences == nil then return end
        local id = part.ID
        local active = self:GetData("cseq-active",false)
        local step = self:GetData("cseq-step")
        if active==false and sequences[id] then
            --Here we call all the hooks added to CanStartControlSequence.
            local allowed = self:CallHook("CanStartControlSequence")
            --If any of them returned false, the sequence can't be started.
            if allowed==false then return end

Passing extra data

--Snippet from lua/entities/gmod_tardis/init.lua
--Line 34 to 40
--What this code does is essentially redirect the "native" ENTITY:PhysicsCollide and ENT:OnTakeDamage function overrides to the hook system so any module can access it.
function ENT:PhysicsCollide(colData, collider)
	self:CallHook("PhysicsCollide", colData, collider)
end
function ENT:OnTakeDamage(dmginfo)
	if self:CallHook("ShouldTakeDamage",dmginfo)==false then return end
	self:CallHook("OnTakeDamage", dmginfo)
end

ENT:RemoveHook(hookName, hookID)

This removes hooks. The only reason you'd need to call this is to properly remove a hook, since just deleting the ENT:AddHook() call won't do. You should also avoid calling this inside hooks or functions unless you REALLY know what you're doing.

Arguments

String hookName - The name of the hook or event. You can find this in the hook lists.

String hookID - The name or ID of the hook you want to remove.