Hooks

From Sven Co-op
Jump to navigation Jump to search

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 CanPlayerUseReservedSlot

Constant: Player::CanPlayerUseReservedSlot

Signature: HookReturnCode Function( edict_t@ pEntity, const string& in szPlayerName, const string& in szIPAddress, bool& out bAllowJoin )

Availability: Plugins only

Stop Mode: ON_HANDLED

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.

3.2 ClientConnected

Constant: Player::ClientConnected

Signature: HookReturnCode Function( edict_t@ pEntity, const string& in szPlayerName, const string& in szIPAddress, bool& out bDisallowJoin, string& out szRejectReason )

Availability: Plugins only

Stop Mode: CALL_ALL

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.

3.3 ClientPutInServer

Constant: Player::ClientPutInServer

Signature: HookReturnCode Function( CBasePlayer@ pPlayer )

Availability: All

Stop Mode: CALL_ALL

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.

3.4 ClientDisconnect

Constant: Player::ClientDisconnect

Signature: HookReturnCode Function( CBasePlayer@ pPlayer )

Availability: All

Stop Mode: CALL_ALL

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.

3.5 ClientSay

Constant: Player::ClientSay

Signature: HookReturnCode Function( [SayParameters](SayParameters)@ pParams )

Availability: All

Stop Mode: ON_HANDLED

Called when a player says something in game chat. The SayParameters class can be used to manipulate input and veto the message.

3.6 MapChange

Constant: Game::MapChange

Signature: HookReturnCode Function( const string& in szNextMap )

Availability: All

Stop Mode: CALL_ALL

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.

3.7 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.8 PlayerSpawn

Constant: Player::PlayerSpawn

Signature: HookReturnCode Function( CBasePlayer@ pPlayer )

Availability: All

Stop Mode: CALL_ALL

Called when a player (re)spawns. Player render settings and equipment changes are unavailable at this point.

3.9 PlayerCanRespawn

Constant: Player::PlayerCanRespawn

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, bool& out bCanRespawn )

Availability: All

Stop Mode: ON_HANDLED

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.

3.10 PlayerKilled

Constant: Player::PlayerKilled

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, CBaseEntity@ pAttacker, int iGib )

Availability: All

Stop Mode: CALL_ALL

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.

3.11 [[#playeruse|]]PlayerUse

Constant: Player::PlayerUse

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, uint& out uiFlags )

Availability: All

Stop Mode: ON_HANDLED

Called when the game is processing player use input. Note that this occurs even if the player has not pressed their use key. uiFlags is used to skip player use processing after the hook returns. Setting the flag PlrHook_SkipUse will skip processing.

3.12 PlayerPreThink

Constant: Player::PlayerPreThink

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, uint& out uiFlags )

Availability: All

Stop Mode: ON_HANDLED

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.

3.13 PlayerPostThink

Constant: Player::PlayerPostThink

Signature: HookReturnCode Function( CBasePlayer@ pPlayer )

Availability: All

Stop Mode: CALL_ALL

Called when the player is processing post think events.

3.14 PlayerTakeDamage

Constant: Player::PlayerTakeDamage

Signature: HookReturnCode PlayerTakeDamageHook( DamageInfo@ pDamageInfo )

Availability: All

Stop Mode: MODULE_HANDLED

Called when a player takes damage. Note that the victim entity can’t be changed at this point.

3.15 GetPlayerSpawnSpot

Constant: Player::GetPlayerSpawnSpot

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, CBaseEntity@& out ppEntSpawnSpot )

Availability: All

Stop Mode: MODULE_HANDLED

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.

3.16 PlayerPreDecal

Constant: Player::PlayerPreDecal

Signature: HookReturnCode Function( CBasePlayer@, const TraceResult& in, bool& out bResult)

Availability: Plugins only

Stop Mode: CALL_ALL

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.

3.17 PlayerDecal

Constant: Player::PlayerDecal

Signature: HookReturnCode Function( CBasePlayer@ pPlayer, const TraceResult& in trace )

Availability: Plugins only

Stop Mode: CALL_ALL

Called when a player is spraypainting a decal onto a surface. The given trace result contains the surface information.

3.18 PlayerEnteredObserver

Constant: Player::PlayerEnteredObserver

Signature: HookReturnCode PlayerEnteredObserverHook( CBasePlayer@ pPlayer )

Availability: All

Stop Mode: CALL_ALL

Called when a player enters observer mode.

3.19 PlayerLeftObserver

Constant: Player::PlayerLeftObserver

Signature: HookReturnCode PlayerLeftObserverHook( CBasePlayer@ pPlayer )

Availability: All

Stop Mode: CALL_ALL

Called when a player leaves observer mode.

3.20 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.21 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.22 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.23 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.24 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.25 MaterializeHook

Constant: PickupObject::Materialize

Signature: HookReturnCode Function( CBaseEntity@ pPickup )

Availability: All

Stop Mode: CALL_ALL

Called when a pickup object materializes.

3.26 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.27 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.28 MonsterTakeDamageHook

Constant: Monster::MonsterTakeDamage

Signature: HookReturnCode Function( DamageInfo@ pDamageInfo )

Availability: All

Stop Mode: CALL_ALL

Called when a monster takes damage.

3.29 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.

Retrieved from "https://wiki.svencoop.com/index.php?title=Hooks&oldid=1067"