Hooking

Source2Mod has one way to hook anything, the same in C++ and in SourcePawn:

Hook = Point (what) + Target (on which object) + Handler (with its context)

g_pSource2ModHooks->Hook(point, target, handler, post, filter) in C++, Source2ModHooks.Hook / HookInstance / HookClass in a script. The core resolves the function from its gamedata, places the detour and runs your handler; every call returns an id for Unhook, and what a plugin still holds when it unloads the core drops for it.

#include "source2mod/ISource2ModHooks.h"

bool MyPlugin::Load(PluginId id, ISource2ModAPI* api, char* error, size_t maxlen, bool late)
{
    SOURCE2MOD_SAVEVARS();

    // Half damage for every player pawn. Pre: the original sees the change.
    g_pSource2ModHooks->Hook(HookPoint::TakeDamage, HookTarget::Class("CCSPlayerPawn"),
        [](TakeDamageContext& ctx, bool post) -> HookReturn<std::int64_t>
        {
            ctx.info->m_flDamage /= 2;
            return Action::Ignore;
        });

    // Every tick, after the game's own work.
    g_pSource2ModHooks->Hook(HookPoint::GameFrame, HookTarget::All(), SOURCE2MOD_MEMBER(this, &MyPlugin::OnGameFrame), true);

    // One input of one kind of entity.
    g_pSource2ModHooks->Hook(HookPoint::AcceptInput, HookTarget::All(), OnRelayTrigger, false, HookFilter{ "logic_relay", "Trigger" });

    return true;
}

public void OnPluginStart()
{
	// Half damage for every player pawn. Pre: the original sees the change.
	Source2ModHooks.HookClass(HookPoint_TakeDamage, "CCSPlayerPawn", OnTakeDamage);

	// Every tick, after the game's own work.
	Source2ModHooks.Hook(HookPoint_GameFrame, OnGameFrame, true);

	// One input of one kind of entity.
	Source2ModHooks.Hook(HookPoint_AcceptInput, OnRelayTrigger, false, "logic_relay", "Trigger");
}

public Source2ModAction OnTakeDamage(TakeDamageContext ctx, bool post, int &result)
{
	CTakeDamageInfo info = ctx.info;
	info.m_flDamage /= 2.0;
	return Action_Ignore;
}

No KHOOK_INIT(), no signature, no prototype of your own: a plugin that hooks this way follows the core's gamedata through game updates and needs only a core update when Valve moves a function. That is the stable tier.

Points

A point is what is hooked. Each one hands its handler a context of its own, so the compiler (or spcomp) checks the handler against the point.

C++ spells them HookPoint::TakeDamage, SourcePawn HookPoint_TakeDamage; the numbers are the same (HookPointId). Every point and its context is on Hook points.

Targets

A target is on which object. The object is the function's this — for a free function, its first argument.

A virtual is hooked once, on the vtable, and the core compares the object before a handler runs. Engine callbacks take All() only: Hook() returns 0 for another target in C++, and HookInstance on an engine point is a script error. A hook on one entity goes with the entity.

Filters

A point whose object is an entity can be narrowed further by the entity's designer name ("player", "logic_relay"); AcceptInput also by the input's name. Both are compared before the handler runs; nullptr or "" matches anything.

g_pSource2ModHooks->Hook(HookPoint::AcceptInput, HookTarget::All(), OnRelayTrigger, false, HookFilter{ "logic_relay", "Trigger" });

Source2ModHooks.Hook(HookPoint_AcceptInput, OnRelayTrigger, false, "logic_relay", "Trigger");

How a hooked call runs

Once a function is hooked, every call to it goes through the same loop:

1. Every pre handler runs, in registration order, with the function's own arguments.
2. Each handler answers an action.
3. Unless a pre handler superseded it, the original function runs.
4. Every post handler runs — the original has already returned by now.
5. The call returns: the original's value, or the one a handler supplied.

Several handlers on one point: Supersede stops the chain, otherwise the strongest action wins. A value a handler returns lands in the context right away, so the next handler sees it. There is no Handled: Ignore is the answer of a handler that only looks. In C++ Action is KHook::Action; in SourcePawn it is Source2ModAction (Action_Ignore, Action_Override, Action_Supersede). Writing handlers covers the answers in detail.

Source2Mod's other listeners — command listeners, game events, net messages, entity outputs, sounds — answer the same Action.

Ids, unhooking and unloading

Nothing has to be undone in Unload() / OnPluginEnd(): what a plugin still holds when it unloads, the core drops for it.

A typed game-function point is one detour per function, placed the first time a plugin hooks it and kept until the server shuts down; without handlers it only checks an empty list. A Function point's hook goes in at once — KHook falls back to its worker thread only when the function is running at that moment.

KHook underneath

Source2Mod hooks through KHook, Metamod:Source 2.0's detour library, on the one engine Metamod runs for the whole server. It does not run a hook engine of its own: CallOriginal and Supersede walk the handler chain of the engine that owns the patch, and two engines patching the same address cannot see through each other. One engine means one chain per address, so the core's hooks, your plugin's hooks and the hooks of the Metamod plugins next to you compose correctly.

C++ plugins can still use KHook directly — KHOOK_VIRTUAL, KHOOK_MEMBER, KHOOK_FUNCTION from source2mod/ISource2ModKHook.h — for the rare hook ISource2ModHooks does not cover. A plugin with KHook hooks of its own is raw tier in s2m info and needs a rebuild whenever KHook or the engine changes; see Raw KHook.

Before you hook

Check whether Source2Mod already has a listener for it. These are hooked once in the core and survive game updates without gamedata of your own:

Coming from SourceHook, SDKHooks and DHooks

See the ISource2ModHooks reference for every type, the contexts and ISource2ModFunctions.