Hooks - TDMP-Team/TDMP-Lua-Modding-API GitHub Wiki

TDMP Hooks are made for "talking" between different Teardown mods, since all of them are placed in their own environment, and they may return string value. Some of hooks also being called by TDMP itself. In short words: Calls callback function in all existing mods, if they've registered one

How to use hooks

You should include file from modding API, to make it easier to work with

#include "tdmp/hooks.lua

Hook_AddListener

Hook_AddListener(string eventName, string id, function callback)

Adds a new listener to the eventName event. Note that listener should be added outside any functions for better modding support. You still can add your listener inside of init function if you really want to. If you'll return a string value, then Hook_Run would return it as well. See Hook_Run example for more info.

  1. string eventName - The event which you want to listen to
  2. string id - Unique name of your hook. You can override any registered listeners with the same names.
  3. function callback(string jsonData) - function to be called when event runs

Example:

-- Each time when player is damaged by a bullet, prints in console SteamID of victim, part of a body which was hitten, and how much damage applied
Hook_AddListener("TDMP_PlayerDamaged", "PrintStuffWhenDamageSomebody", function(jsonData)
	local data = json.decode(jsonData)

	DebugPrint(data.ID .. " was damaged in " .. data.Hit .. "(" .. data.Damage .. ")")
end)

Hook_Run

Hook_Run(string eventName, table hookData[optional], bool noPack[optional])

Runs all registered hooks to eventName. If any called hook returned string value, then it Hook_Run would return it too. See example for more sense

  1. string eventName - The event to call hooks for
  2. table hookData[optional] - Any custom data to be passed to the hooks. NOTE: It would be packed as json if noPack is false or nil
  3. bool noPack[optional] - If true, hookData won't be packed as json, instead, it would be passed just as regular string

Example:

-- Runs our custom event called "MyXbuttonWasPressed!" when local player pressed X key, pushing our local steamid, and prints out a returned value, if there's any
function tick()
	if InputPressed("x") then
		local foo = Hook_Run("MyXbuttonWasPressed!", TDMP_LocalSteamID, true)

		if foo then
			DebugPrint("Our hook returned: " .. foo)
		end
	end
end

-- Example of other mod dealing with that hook
Hook_AddListener("MyXbuttonWasPressed", "someUniqueName", function(someValue)
	DebugPrint("Hook was called! Passed value is: " .. someValue)

	return tostring(math.random(1,100))
end)

How to override default/existing hooks

If you want to override any default TDMP's hook listeners or somebody else's hook listener, you'll have to call Hook_AddListener inside of init function, and set id to exact the same as the one you want to override, example:

function init()
	-- overrides TDMP's shooting hook, which being called when using Ballistics:Shoot function.
	Hook_AddListener("Shoot", "TDMP_DefaultShoot", function(shootData)
		-- TDMP's "Shoot" hook won't be called anymore and weapons won't work as well
		-- You can add here your own shooting method, but you can't call TDMP's one anymore
	end)
end

Default hooks

List of default hooks which TDMP calls. First word is a table key, second is parameter type

TDMP_BulletFlyBy

Calls when TDMP bullet flying by the local player's head. It pushes table with these parameters:

  • [1] Vector = current bullet pos
  • [2] Vector = next bullet pos, if it won't hit anything
  • [3] Vector = where bullet was shot from
  • [4] string = bullet's owner (if any)
  • [5] var = bullet's custom data (if any)

TDMP_PlayerDamaged

Calls when TDMP projectile damaged a player. Pushes table with these parameters:

  • Pos Vector = current bullet pos
  • Damage float = how much damage was applied to a player
  • Hit string = which part of body was shot? Can be Legs, Body or Head
  • ID string = steamId of a player who was damaged

TDMP_ProjectileHit

Calls when TDMP projectile hit something but not a player. Pushes table with these parameters:

  • Pos Vector = current projectile pos
  • ShotFrom Vector = where projectile was originally shot from
  • Owner string = steamId of projectile's owner (if any)
  • Data var = projectile's custom data (if any)
  • Life number = projectile's life (How many voxels/walls to penetrate)
  • Type number = projectile's type from Ballistics.Type enum
  • Hit Vector = projectile's hit position

Shoot

Calls each time when Ballistics:Shoot being called. You can override that hook for making your own ballistics system handle the process. It passes table from Ballistics:Shoot function, which you can find on Ballistics page

ConnectedToServer

Calls when local player has connected to the server.

ServerConnectionClosed

Calls when server has closed connection (i.e. host left)

PlayerDisconnected

Calls when player has disconnected. Pushes player's steamid as a string

PlayerConnected

Calls when player has connected. Pushes player's steamid as a string

PlayerBodyCreated

Calls each time when player's body was created.

  • [1] string = SteamID of player who's body was created
  • [2] number = player's id in TDMP table

PlayerCorpseCreated

Calls each time when player's corpse (ragdoll) was created.

  • [1] string = SteamID of player who's body was created
  • [2] number = player's id in TDMP table

PlayerDied

Calls when player has died.

  • [1] string = SteamID of player who's body was created
  • [2] number = player's id in TDMP table

PlayerSpawnedEntity

Calls when player has spawned something using Spawn menu.

  • [1] string = SteamID of player who's body was created
  • [2] table = table of spawned entities (i.e. result of Spawn function)
  • [3] table = table of network identifiers for each created body and vehicle

PlayerModelChanged

Calls when player has changed their model using TDMP's menu.

  • [1] string = SteamID of player who changed model
  • [2] table = model info

WeatherChanged

Calls when player has changed weather using TDMP menu

  • [1] string = new weather, can be one of these: sunset, sunny, night, sunrise, foggy, rain, rainynight, snowy, snowynight
  • [2] string = steamid of player who changed the weather. Serverside only