SDKHooks

Introduction

SDKHooks was previously an external extension to Sourcemod. It was rolled in Sourcemod 1.5 and it does not need to be manually installed anymore. SDKHooks extension provides hooks, functions and natives.

Take Damage

Native SDKHooks_TakeDamage allows you to force an entity to take damage: void SDKHooks_TakeDamage(int entity, int inflictor, int attacker, float damage, int damageType=DMG_GENERIC, int weapon=-1, const float damageForce[3]=NULL_VECTOR, const float damagePosition[3]=NULL_VECTOR, bool bypassHooks = true);
Damage types are available in the sdkhooks.inc file - sdkhooks.inc
The weapon parameter is not used by all games and damage sources.

Hooking an entity

SDKHooks provides 3 functions related to hooking entities: SDKHook, SDKHookEx and SDKUnhook

SDKHook

SDKHook is used to hook entities: void SDKHook(int entity, SDKHookType type, SDKHookCB callback);
The first parameter is the entity index.
The second parameter is the hook type, some of which are listed in the Hooks section below but you can always find the full list in the sdkhooks.inc file. Online version available here.
The third parameter is the callback function, that will be run, when the hook is triggered.

The callback function signature changes depending on the hook type. You can see all the callback function signatures in the sdkhooks.inc file - sdkhooks.inc
Example callback function signature for the OnTakeDamage hook: function Action (int victim, int &attacker, int &inflictor, float &damage, int &damagetype, int &weapon, float damageForce[3], float damagePosition[3], int damagecustom);
Note the callback return type:

• void - event cannot be changed at this point
• Action - event can be changed or stopped where possible

SDKHookEx

SDKHookEx is exactly the same as SDKHook, with only 1 difference: Unlike SDKHook, it has a boolean return value telling you whether the hook was successful.

SDKUnhook

SDKUnhook removes/unhooks the hook from the entity: void SDKUnhook(int entity, SDKHookType type, SDKHookCB callback);
It has the same parameters as SDKHook.

It is rarely used, because:

• SDKHooks blocks hooking the same hook (for the same entity) twice
• Hooks are unhooked automatically upon destruction/removal of the entity

Hooks

Some information on various hooks below:

SDKHook_FireBulletsPost

Not all games use FireBullets so this hook will not trigger in such games.

SDKHook_GetMaxHealth

 (ep2v and later)

SDKHook_OnTakeDamage

inflictor (3rd argument) is the entity that inflicts the damage. If a player directly damages another, inflictor should be equal to the attacking player id. An example of an indirect damage would be a grenade.

Under CSS

Non-regular cases for SDKHook_OnTakeDamage In the scenario where a player throw a grenade to another player then quickly disconnect, the attacker (2nd argument) will become the inflictor (3rd argument).

In the scenario where a player fall; the attacker, which is also the inflictor, will be 0 (the world).

In the scenario where a terrorist plants the bomb, when the bomb explodes, the attacker (2nd argument) will be the same as the inflictor (3rd argument) which will have the Classname "planted_c4".

Some damage types A normal HEGrenade and the C4 inflict damage of type DMG_BLAST.

A fall inflicts damage of type DMG_FALL.

A grenade impact (for instance a flash hitting a teammate) will inflict damage of type DMG_CLUB.

A normal gun bullet and the knife will inflict damage of type (DMG_BULLET | DMG_NEVERGIB) (non-headshot) or (DMG_BULLET | DMG_NEVERGIB | (1 << 30) ) (headshot).

A single attack can trigger many SDKHook_OnTakeDamage; when a gun throws pullets for instance (shotgun and glock in burst-mode notably).

(Regarding SM/Admin damaged; maybe place this is another section if someone can be sure that this would occur on all mods)

sm_slap does not trigger SDKHook_OnTakeDamage.

sm_burn will trigger two different callback : an entity with the classname "entityflame" will deal once 0 damage of type DMG_BURN and once 1 damage of type (DMG_BURN | DMG_DIRECT) every tick.

Regarding SDKHook_OnTakeDamage and SDKHook_OnTakeDamageAlive

SDKHook_OnTakeDamage/Post is triggered when hitting a teammate with mp_friendlyfire 0 (except in TF2), but not SDKHook_OnTakeDamageAlive.

Under TF2

Under TF2, the SDKHook_OnTakeDamage hook isn't 100% accurate, it's damage parameter is the weapon's base damage. the DMG_CRIT flag is for both crits and minicrits. Weapon spread and minicrit/crit damage is calculated after this call (in SDKHook_OnTakeDamageAlive/Post).

Some damage types Shotgun = DMG_BUCKSHOT | DMG_SLOWBURN

Rocket Launcher = DMG_SLOWBURN | DMG_RADIATION | DMG_BLAST

If a crit, |= DMG_CRIT

SDKHook_OnTakeDamagePost

Trigged after SDKHook_OnTakeDamage, but before SDKHook_OnTakeDamageAlive

SDKHook_OnTakeDamageAlive

This hook works in a similar way to SDKHook_OnTakeDamage but it gives the actual, calculated damage amount done to the player. The pre-hook will fire after an OnTakeDamage pre-hook, and the post-hook will fire before an OnTakeDamage post-hook. The health is subtracted in between pre and post unless the hook is blocked. PR 149

OnTakeDamageAlive is also only called for players.

SDKHook_OnTakeDamageAlivePost

Triggered after the player took damage.

SDKHook_PreThink

Called before OnGameFrame(), but only for the hooked entity.

SDKHook_Spawn

Triggers when the hooked entity is about to spawn. Entity creation and spawn are not the same thing. Some entity properties are not available until the entity spawns.

SDKHook_SpawnPost

Triggers after the hooked entity was spawned.

SDKHook_StartTouch

Triggers when the hooked entity is about to be touched by another entity. Not all entities can trigger/fire touch events. Adjusting collision groups for the entity can fix that.

SDKHook_VPhysicsUpdate

Triggers when the hooked entity is about to update.

SDKHook_WeaponDrop

Triggers when the hooked weapon is about to be dropped.

Under TF2

When a weapon is dropped in tf2, a new entity is created called tf_dropped_weapon and this new entity is not the same entity as the one that player had equipped nor do they share entity IDs. They share the m_iAccountID property however, which contains the steam ID of the owner of the weapon that dropped it. You cannot prevent weapon drop through this hook in TF2.

SDKHook_WeaponDropPost

Triggers after the hooked weapon was dropped.

SDKHook_WeaponEquip

Triggers when the hooked weapon is about to be equipped.

SDKHook_WeaponEquipPost

Triggers after the hooked weapon was equipped.

SDKHook_WeaponSwitch

Triggers when the hooked weapon is about to be switched for another one.

SDKHook_WeaponSwitchPost

Triggers after the hooked weapon was switched for another one.