Hooks

Hooks are a form of events that scripts can hook into. When you register a hook, the function you’ve registered will be called whenever the associated event occurs.

Multiple scripts can hook into the same hook, and the same script can hook the same hook multiple times. Map scripts will always come first when hooks that both map scripts and plugins can use are executed.

1 Hook return code

All hooks have to return a code to indicate whether they’ve handled the event or not.

If a hook has handled the event, it should return HOOK_HANDLED. Otherwise, it should return HOOK_CONTINUE.

2 Hook definition and usage

All hooks are defined in the namespace “Hooks”.

All hooks have funcdefs defined for them that have the syntax <name>Hook, where <name> is the name of the constant without any namespaces prepended. For example, the Hooks::Game::MapChange hook has the funcdef MapChangeHook. This can be used to register object methods as hooks.

You can get an up to date list of hook by typing as_dumphooks <filename> in the console. You must be the server admin to be able to do this. The filename should not have an extension. The file extension is .txt.

2.1 Registering hooks

To register a hook, you must use the g_Hooks global object. This object is defined as follows:

CModuleHookManager g_Hooks;

(The actual definition uses a global property accessor, but it behaves like a variable as shown above)

Registering a hook is done as follows:

HookReturnCode MapChange( const string& in szNextMap )
{
    // Handle map change
}

g_Hooks.RegisterHook( Hooks::Game::MapChange, @MapChange );

Removing a hook is done much like registering it:

g_Hooks.RemoveHook( Hooks::Game::MapChange, @MapChange );

It is also possible to remove all of the hook functions registered for a particular hook in the current script by calling RemoveHook with just the hook ID parameter:

g_Hooks.RemoveHook( Hooks::Game::MapChange );

2.2 Stop Modes

Hooks can have one of a few stop modes. This mode defines when hook execution should stop.

Name	Action
ON_HANDLED	As soon as a hook has returned HOOK_HANDLED, stop execution.
MODULE_HANDLED	As soon as a single script has return HOOK_HANDLED from any of its hooks, stop execution.
CALL_ALL	Regardless of the return code, execute all hooks.

3 Available hooks

3.1 Player Hooks

Hooks::Player::

Constant	Signature	Description	Stop Mode	Availability
CanPlayerUseReservedSlot	HookReturnCode Function( edict_t@ pEntity, const string& in szPlayerName, const string& in szIPAddress, bool& out bAllowJoin )	Called when a player connects to the server, and the number of slots left on the server is <= the number of reserved slots. Set bAllowJoin to true to allow the player to join (default false). Note: At this point in time the player’s CBasePlayer instance does not yet exist. Do not try to use it, as it will not work.	ON_HANDLED	Plugins only
ClientConnected	HookReturnCode Function( edict_t@ pEntity, const string& in szPlayerName, const string& in szIPAddress, bool& out bDisallowJoin, string& out szRejectReason )	Called when a player connects to the server. if bDisallowJoin is set to false, the player is disconnected. szRejectReason is shown to the player if disconnected. the maximum length of the reject reason string is 127 characters. Note: At this point in time the player’s CBasePlayer instance does not yet exist. Do not try to use it, as it will not work.	CALL_ALL	Plugins only
ClientPutInServer	HookReturnCode Function( CBasePlayer@ pPlayer )	Called when a player has finished connecting and is put into the world. It is safe to send network messages to the player at this point. The player’s CBasePlayer instance is created right before this hook is executed.	CALL_ALL	All
ClientDisconnect	HookReturnCode Function( CBasePlayer@ pPlayer )	Called when a player disconnects. Note that this is only called if the player was fully connected, meaning the player went through ClientPutInServer. This is never called for the local host, since it can’t disconnect before shutting the server itself down.	CALL_ALL	All
ClientSay	HookReturnCode Function( SayParameters@ pParams )	Called when a player says something in game chat. The SayParameters class can be used to manipulate input and veto the message.	ON_HANDLED	All
GetPlayerSpawnSpot	HookReturnCode Function( CBasePlayer@ pPlayer, CBaseEntity@& out ppEntSpawnSpot )	Called when the game is trying to find a spawn spot for a player. To specify a spawn spot (or no spawn spot), set ppEntSpawnSpot to the spot you wish to use, and return HOOK_HANDLED. Setting null will cause the game to spawn the player dead.
PlayerSpawn	HookReturnCode Function( CBasePlayer@ pPlayer )	Called when a player (re)spawns. Player render settings and equipment changes are unavailable at this point.	CALL_ALL	All
PlayerCanRespawn	HookReturnCode Function( CBasePlayer@ pPlayer, bool& out bCanRespawn )	Called when the game wants to know if the player should be able to respawn or not. Set bCanRespawn to false to disallow, default true.	ON_HANDLED	All
PlayerTakeDamage	HookReturnCode PlayerTakeDamageHook( DamageInfo@ pDamageInfo )	Called when a player takes damage. Note that the victim entity can’t be changed at this point.		All
PlayerKilled	HookReturnCode Function( CBasePlayer@ pPlayer, CBaseEntity@ pAttacker, int iGib )	Called when a player is killed. pAttacker is the entity responsible for killing the player, and may be null. iGib is one of the GIB enum values, indicating whether or not the player should be gibbed or not.		All
PlayerUse	HookReturnCode Function( CBasePlayer@ pPlayer, uint& out uiFlags )	Called when the game is processing player button input. Note that this occurs even if the player has not pressed any keys. uiFlags is used to skip player use processing after the hook returns. Setting the flag PlrHook_SkipUse will skip processing.		All
PlayerPreThink	HookReturnCode Function( CBasePlayer@ pPlayer, uint& out uiFlags )	Called when the player is processing pre think events. uiFlags is used to skip pre think processing after the hook returns. Setting the flag PlrHook_SkipVehicles will skip vehicle processing.
PlayerPostThink	HookReturnCode Function( CBasePlayer@ pPlayer )	Called when the player is processing post think events.
PlayerPreDecal	HookReturnCode Function( CBasePlayer@, const TraceResult& in, bool& out bResult)	Called when a player attempts to spraypaint a decal onto a surface. The given trace result contains the surface information. Set bResult to false if the player shouldn’t be able to spray.
PlayerDecal	HookReturnCode Function( CBasePlayer@ pPlayer, const TraceResult& in trace )	Called when a player is spraypainting a decal onto a surface. The given trace result contains the surface information.
PlayerEnteredObserver	HookReturnCode Function( CBasePlayer@ pPlayer )	Called when a player enters observer mode.
PlayerLeftObserver	HookReturnCode Function( CBasePlayer@ pPlayer )	Called when a player leaves observer mode.

3.2 Game Hooks

Constant	Signature	Description	Stop Mode	Availability
MapChange	HookReturnCode Function( const string& in szNextMap )	When the map changes, this hook is called. Note that this happens when the world is destroyed. There may still be entities that exist at this point. This is caused by engine limitations.	CALL_ALL	All
EntityCreated	HookReturnCode EntityCreatedHook( CBaseEntity@ pEntity )	Called when a new entity is created. At this point the entity is not spawned yet and may not be fully initialized.	ON_HANDLED	All

3.3 EntityCreated

Constant: Game::EntityCreated

Signature: HookReturnCode EntityCreatedHook( CBaseEntity@ pEntity )

Availability: All

Stop Mode: ON_HANDLED

Called when a new entity is created. At this point the entity is not spawned yet and may not be fully initialized.

3.4 WeaponPrimaryAttack

Constant: Weapon::WeaponPrimaryAttack

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, CBasePlayerWeapon@ pWeapon )

Availability: All

Stop Mode: ON_HANDLED

Called when a player fires a weapon’s primary attack.

3.5 WeaponSecondaryAttack

Constant: Weapon::WeaponSecondaryAttack

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, CBasePlayerWeapon@ pWeapon )

Availability: All

Stop Mode: ON_HANDLED

Called when a player fires a weapon’s secondary attack.

3.6 WeaponTertiaryAttack

Constant: Weapon::WeaponTertiaryAttack

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, CBasePlayerWeapon@ pWeapon )

Availability: All

Stop Mode: ON_HANDLED

Called when a player fires a weapon’s tertiary attack.

3.7 CanCollectHook

Constant: PickupObject::CanCollect

Signature: HookReturnCode Function( CBaseEntity@ pPickup, CBaseEntity@ pOther, bool& out bResult )

Availability: All

Stop Mode: ON_HANDLED

Called when a pickup object is about to be collected by a player. Note that basic checks are done before this hook is called. Set bResult to false if the player shouldn’t be able to pick up the object.

3.8 CollectedHook

Constant: PickupObject::Collected

Signature: HookReturnCode Function( CBaseEntity@ pPickup, CBaseEntity@ pOther )

Availability: All

Stop Mode: CALL_ALL

Called when a pickup object is collected by a player.

3.9 MaterializeHook

Constant: PickupObject::Materialize

Signature: HookReturnCode Function( CBaseEntity@ pPickup )

Availability: All

Stop Mode: CALL_ALL

Called when a pickup object materializes.

3.10 WeaponReloadHook

Constant: Weapon::WeaponReloadHook

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, CBasePlayerWeapon@ pWeapon )

Availability: All

Stop Mode: CALL_ALL

Called a player reloads a weapon (or calls BaseClass::Reload()).

3.11 MonsterKilledHook

Constant: Monster::MonsterKilledHook

Signature: HookReturnCode Function( CBaseMonster@ pMonster, CBaseEntity@ pAttacker, int iGib )

Availability: All

Stop Mode: CALL_ALL

Called when a monster is killed (This hook isn’t called for monster_sentry/monster_barnacle).
This hook may have spam issues.

3.12 MonsterTakeDamageHook

Constant: Monster::MonsterTakeDamage

Signature: HookReturnCode Function( DamageInfo@ pDamageInfo )

Availability: All

Stop Mode: CALL_ALL

Called when a monster takes damage.

3.13 PlayerRevivedHook

Constant: Player::PlayerRevived

Signature: HookReturnCode Function( CBasePlayer@ pPlayer )

Availability: All

Stop Mode: CALL_ALL

Called when a player is revived. At this point all the revival process is finished.