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_Blocked

function Action (int entity, int other);

SDKHook_BlockedPost

function void (int entity, int other);

SDKHook_CanBeAutobalanced

function bool (int client, bool origRet);

SDKHook_EndTouch

function Action (int entity, int other);

SDKHook_EndTouchPost

function void (int entity, int other);

SDKHook_FireBulletsPost

function void (int client, int shots, const char[] weaponname);

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

SDKHook_GetMaxHealth

function Action (int entity, int &maxhealth);

 (ep2v and later)

SDKHook_GroundEntChangedPost

function void (int entity);

SDKHook_OnTakeDamage

function Action (int victim, int &attacker, int &inflictor, float &damage, int &damagetype);
function Action (int victim, int &attacker, int &inflictor, float &damage, int &damagetype, int &weapon, float damageForce[3], float damagePosition[3]);
function Action (int victim, int &attacker, int &inflictor, float &damage, int &damagetype, int &weapon, float damageForce[3], float damagePosition[3], int damagecustom);

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

function void (int victim, int attacker, int inflictor, float damage, int damagetype);
function void (int victim, int attacker, int inflictor, float damage, int damagetype, int weapon, const float damageForce[3], const float damagePosition[3]);
function void (int victim, int attacker, int inflictor, float damage, int damagetype, int weapon, const float damageForce[3], const float damagePosition[3], int damagecustom);

Trigged after SDKHook_OnTakeDamage, but before SDKHook_OnTakeDamageAlive

SDKHook_OnTakeDamageAlive

function Action (int victim, int &attacker, int &inflictor, float &damage, int &damagetype);
function Action (int victim, int &attacker, int &inflictor, float &damage, int &damagetype, int &weapon, float damageForce[3], float damagePosition[3]);
function Action (int victim, int &attacker, int &inflictor, float &damage, int &damagetype, int &weapon, float damageForce[3], float damagePosition[3], int damagecustom);

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

function void (int victim, int attacker, int inflictor, float damage, int damagetype);
function void (int victim, int attacker, int inflictor, float damage, int damagetype, int weapon, const float damageForce[3], const float damagePosition[3]);
function void (int victim, int attacker, int inflictor, float damage, int damagetype, int weapon, const float damageForce[3], const float damagePosition[3], int damagecustom);

Triggered after the player took damage.

SDKHook_PreThink

function void (int client);

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

SDKHook_PreThinkPost

function void (int client);

SDKHook_PostThink

function void (int client);

SDKHook_PostThinkPost

function void (int client);

SDKHook_Reload

function Action (int weapon);

SDKHook_ReloadPost

function void (int weapon, bool bSuccessful);

SDKHook_SetTransmit

function Action (int entity, int client);

SDKHook_ShouldCollide

function bool (int entity, int collisiongroup, int contentsmask, bool originalResult);

SDKHook_Spawn

function Action (int entity);

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

function void (int entity);

Triggers after the hooked entity was spawned.

SDKHook_StartTouch

function Action (int entity, int other);

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_StartTouchPost

function void (int entity, int other);

SDKHook_Think

function Action (int entity);

SDKHook_ThinkPost

function void (int entity);

SDKHook_Touch

function Action (int entity, int other);

SDKHook_TouchPost

function void (int entity, int other);

SDKHook_TraceAttack

function Action (int victim, int &attacker, int &inflictor, float &damage, int &damagetype, int &ammotype, int hitbox, int hitgroup);

SDKHook_TraceAttackPost

function void (int victim, int attacker, int inflictor, float damage, int damagetype, int ammotype, int hitbox, int hitgroup);

SDKHook_Use

function Action (int entity, int activator, int caller, UseType type, float value);

SDKHook_UsePost

function void (int entity, int activator, int caller, UseType type, float value);

SDKHook_VPhysicsUpdate

function void (int entity);

Triggers when the hooked entity is about to update.

SDKHook_VPhysicsUpdatePost

function void (int entity);

SDKHook_WeaponCanSwitchTo

function Action (int client, int weapon);

SDKHook_WeaponCanSwitchToPost

function void (int client, int weapon);

SDKHook_WeaponCanUse

function Action (int client, int weapon);

SDKHook_WeaponCanUsePost

function void (int client, int weapon);

SDKHook_WeaponDrop

function Action (int client, int weapon);

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

function void (int client, int weapon);

Triggers after the hooked weapon was dropped.

SDKHook_WeaponEquip

function Action (int client, int weapon);

Triggers when the hooked weapon is about to be equipped.

SDKHook_WeaponEquipPost

function void (int client, int weapon);

Triggers after the hooked weapon was equipped.

SDKHook_WeaponSwitch

function Action (int client, int weapon);

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

SDKHook_WeaponSwitchPost

function void (int client, int weapon);

Triggers after the hooked weapon was switched for another one.