Hooks

TTT has some Lua hooks of its own, besides the default GMod hooks (which can be found on the wiki). They are used in the same way.

This page attempts to document all of them. Some of the details may be out of date, so if you suspect it is I recommend checking the code.

Shared hooks

These are called both on the client and the server.

TTTPrepareRound (no parameters)

Called when the “Preparing” phase begins.

TTTBeginRound (no parameters)

Called when Traitors/Detectives have been selected and the round is active.

TTTEndRound (result)

Called when the round ends. The “result” parameter will be equal to one of the values: WIN_TRAITOR, WIN_INNOCENT or WIN_TIMELIMIT. So if result == WIN_TRAITOR, the Traitors have won the round.

The “result” parameter currently only exists on the server even though the hook is shared. It will always be nil on the client. If you need the round result on the client, you will have to send it yourself.

TTTPlayerSpeedModifier (ply, slowed, mv)

Called when a player’s (“ply”) walking speed is computed. The “slowed” parameter indicates if they are using ironsights. The “mv” parameter is the CMoveData object. The value returned by this hook is used as a multiplier of the default speeds, so returning 1.5 will let all players move 50% faster. Note that maps may not expect players to be faster.

NOTE: This hook was originally TTTPlayerSpeed and server-only. It was renamed and made shared in order to allow player movement prediction to work properly. For this to work you must hook it on both client and server with the same implementation so that it returns the same values.

Server hooks

TTTCheckForWin (no parameters)

Called repeatedly during the round. The default implementation checks for the normal TTT win conditions (traitors dead, innocents dead, time running out). You can use this hook to add your own win conditions (or replace the existing ones). The hook must return WIN_NONE if the round should keep going. Otherwise, it must return WIN_TRAITOR, WIN_INNOCENT or WIN_TIMELIMIT.

TTTDelayRoundStartForVote (no parameters)

Called just before starting the Preparation phase. If this hook returns true, the start of that phase will be delayed by 30 seconds. You can return a second value that will override the 30 seconds with your own delay. You can use this for custom map voting systems and such.

TTTPlayerColor (no parameters)

Called to determine what colour the playermodels should be for the upcoming round. Return a Color object. The default implementation uses the ttt_playercolor_mode convar, so if you use this hook this any colour you return will override that setting (returning nil will allow the default code to run).

TTTPlayerSetColor (ply)

Called after player model is set, will set the player color if not overridden.

TTTPlayerRadioCommand (ply, cmd_name, cmd_target)

Called when a player tries to use a quickchat/radio command. If this hook returns true, the command will not be sent, ie. it will get blocked. You can use this for anti-spam measures or to replace or modify a message. The “ply” parameter is of course the player using the command, “cmd_name” is the identifier of the command (such as “quick_yes” for the “Yes.” command), and “cmd_target” is the target part of the command (an entity index if it’s a player or identified corpse, an identifier like “quick_nobody” if not).

TTTKarmaLow (ply)

Called when a player is about to be kicked/banned because their karma has gone below the the autokick/ban level specified in the server’s configuration. Return false to prevent the player from being kicked/banned. Karma is checked at the end of a round, so if their karma continues to be low, this hook will be called after every round.

TTTKarmaGivePenalty (ply, penalty, victim)

Called when someone (ply) attacks someone (victim) and they are given a penalty. Return true to prevent the penalty from being given (for example after modifying the player’s karma yourself).

TTTOrderedEquipment (ply, equipment, is_item)

Called when a player has bought a piece of equipment. The “equipment” parameter will be either the weapon classname (e.g., “weapon_ttt_knife”) or an item ID (e.g., EQUIP_ARMOR). The “is_item” parameter tells you which one it is.

TTTFoundDNA (ply, dna_owner, ent)

Called when a player finds the DNA of “dna_owner” on the entity “ent” (most likely a corpse, but can be a weapon).

TTTPlayerUsedHealthStation (ply, ent_station, healed)

Called when a player uses a health station.

TTTBodyFound (ply, deadply, rag)

Called when a player (“ply”) finds the body (“rag”) of a dead player (“deadply”). Note that the dead player may have disconnected after dying.

TTTOnCorpseCreated (corpse)

Called after a dead player’s corpse has been created and initialized. Modify the corpse table to add/change corpse information, perhaps for use in search-related hooks.

TTTCanSearchCorpse (ply, corpse, is_covert, is_long_range, was_traitor)

Called when a player tries to search a corpse. Return false to prevent it. By default always returns true. The “corpse” parameter is a table with a lot of information about the player’s death, check the code to see exactly what’s in there.

TTTCanIdentifyCorpse (ply, corpse, was_traitor)

Called when a player has searched a body and tries to identify it (showing all other players that the dead player is indeed dead). Note that for non-traitors, the attempt to identify is triggered automatically, while traitors can do a covert search and choose to identify the corpse. This hook will be called for both cases. Return false to prevent identification. By default always returns true.

Client hooks

TTTScoreboardColorForPlayer (ply)

Called to determine what colour a player’s name should be on the scoreboard. Hence, it must return a Color object, or return nil (or nothing at all). The “ply” parameter contains a player object, so you can for example check the player’s SteamID and give certain people a special colour. Note that TTT also uses this hook for the default colours, so you should return nil for players that you do not want to do anything special with.

TTTScoreboardColumns (pnl)

Called when the scoreboard is initialized. Additional custom columns can be added by calling “pnl:AddColumn(heading, func)”, where “pnl” is the panel passed to this hook as an argument, “label” is your column heading text, and “func” is a function you define that will be called to get up-to-date text for the column. The function is called for each row as “func(ply, label)”, where “ply” is the player on that row and “label” is the DLabel object (which can be used to set text colour).

For example, to show user IDs on the scoreboard, you would do the following in this hook:

pnl:AddColumn("ID", function(ply) return ply:UserID() end)

Called to show a context menu when the player right-clicks a player in the scoreboard. The “menu” parameter is a DermaMenu that you can add options to that the player can click. By default there is no context menu when right clicking, it will only appear if you add options in this hook.

TTTScoreGroup (ply)

Called to determine if the player should be listed in a different scoreboard group than they would normally be in. If this hook returns something other than nil, it must be one of: GROUP_TERROR, GROUP_NOTFOUND, GROUP_FOUND, or GROUP_SPEC. These correspond to the four groups in the scoreboard of living, dead but not found, confirmed dead, and spectators.

TTTScoreGroups (parent_panel, player_group_panels)

Called when initializing the scoreboard. The parent_panel is the panel containing the player group panels. In this hook you could add additional panels for new player groups, combined with TTTScoreGroup to place players in those groups.

TTTSettingsTabs (dtabs)

Called after TTT’s settings window has been created. The “dtabs” parameter is a DPropertySheet panel object you can use to add your own tab to the settings window.

TTTEquipmentTabs (dtabs)

Same as TTTSettingsTabs, but for the equipment purchasing menu.

TTTBoughtItem (is_item, equipment)

Called when the player buys something. The “is_item” parameter is false if you buy a weapon, true if you buy an item. The “equipment” parameter is either is the weapon classname (e.g., “weapon_ttt_knife”) or an item ID (e.g., EQUIP_ARMOR).

TTTBodySearchPopulate (processed, raw)

Called whenever the player searches a dead body and receives its data from the server. The “processed” parameter contains the search information after TTT has prepared it for display (formatting timestamps, translating strings, etc). The second table contains the raw unprocessed search data. If you are adding a new kind of search data, TTT’s default processing will not add it to the “processed” table, and you can use this hook to inspect the “raw” data and modify the “processed” table to contain your additions or changes.

TTTBodySearchEquipment (search, equip_num)

Called whenever you search a body and the client receives the data from the server. The “search” parameter contains the raw search data received from the server. The “equip_num” parameter is the raw number containing the bit flags of the equipment the dead player had. In default TTT the “search” table contains some keys like “eq_armor” and “eq_radar”, derived from “equip_num”, which are later used to display that the corpse contains body armor and such. You can use this hook to add any custom items you have added to the “search” table. Then, you can use TTTBodySearchPopulate (see above) to add an icon for that equipment in the search results.

TTTLanguageChanged (from, to)

Called when you change your language. Meant for interface elements that need to update themselves in some way in response to the change.