AlliedModders Wiki - User contributions [en]

DHooks (SourceMod Scripting)

2024-06-12T23:32:32Z

Mooshua: Create basic dhooks page

DHooks is a hooking and detouring extension for SourceMod plugins. Whereas most existing hook extensions provide a selection of hooks, DHooks allows you to specify the exact hook yourself. DHooks is included with SourceMod starting from 1.12 and newer versions of 1.11.

== DynamicHooks ==

DynamicHooks use SourceHook as a backend, and can only hook virtual tables. To create a DynamicHook, you specify it's virtual offset, hook mode, and return type. You then add each argument individually using the methodmap.

DynamicHooks can hook either a raw thispointer (as an Address), the gamerules object, or an entity index.

<cpp>
// Create the initial hook configuration.
DynamicHook hook = new DynamicHook(/* offset */ 0, HookType_Raw, ReturnType_Void, ThisPointer_Address);
{
hook.AddParam(HookParamType_CharPtr);

// Choose a custom pass type of register
// (DHooks will try to automatically detect the register)
hook.AddParam(HookParamType_CharPtr, -1, DHookPass_ByRef, DHookRegister_XMM6);
}

// Hook an entity by it's entity index
hook.HookEntity(HookMode_Post, /*ent index*/ edict, /* callbacks and more ... */);

// Hook a raw address
hook.HookRaw(HookMode_Post, /*address*/ thisptr, /* callback here.... */);
</cpp>

== Gamedata ==

DHooks parses the <tt>Functions</tt> block of a gamedata file. You can include an OS name in most places to limit values to a specific OS.

Functions are referenced by name, which must be unique across the install

{{Sad|Dhooks handles names globally, so if two functions have the same name in different gamedata files they will conflict!}}

"FunctionName"
{
"signature" ""
"address" ""
"offset" ""

"callconv" "cdecl/thiscall/stdcall/fastcall"
"hooktype" "entity/gamerules/raw"

"return" ""
"this" "ignore/entity/address"

"arguments"
{
arg_name
{
"type" ""
"size" ""
"flags" "byval/byref/odtor/octor/oassignop/ocopyctor/ounalign"
"register" "theres a lot"
}
}
}

You can call <tt>FromConf</tt> on a hook to load the appropriate function from a gamedata file:
<cpp>
// Must have an offset, no address or signature
DynamicHook.FromConf(gamedata, "FunctionName");

// Must have a signature or address!
DynamicDetour.FromConf(gamedata, "FunctionName");
</cpp>

[[Category:SourceMod Scripting]]

Category:SourceMod Documentation

2024-06-12T23:04:11Z

Mooshua:

{{ForSysadmins|SourceMod}}

'''Installation'''
*[[Installing SourceMod]]
*[[Upgrading SourceMod]]

'''Configuration'''
*[[SourceMod Configuration|General Overview]]
*[[Adding Admins (SourceMod)|Adding Admins]]
*[[Adding Groups (SourceMod)|Adding Groups]]
*[[Overriding Command Access (SourceMod)|Overriding Command Access]]
*[[SQL Admins (SourceMod)|SQL Admins]]
*[[Admin Menu Configuration (SourceMod)|Admin Menu Configuration]]
*[[Dynamic Admin Menu (SourceMod) | Dynamic Admin Menu Configuration]]
*[[Reserved Slots (SourceMod)|Reserved Slots]]
*[[Map Management Plugins (SourceMod)|Map Management Plugins]]
*[[Multiple_or_Forked_Servers_(SourceMod)|Multiple or Forked Servers]]

'''Information'''
*[[Admin Commands (SourceMod)|Admin Commands]]
*[[Public Commands (SourceMod)|Public Commands]]
*[[Base Plugins (SourceMod)|Base Plugin List]]
*[[War Mode (SourceMod)|War Mode]]

[[Category:SourceMod]]

Category:SourceMod Scripting

2024-06-12T23:03:46Z

Mooshua:

{{ForDevelopers}}

This category contains articles about scripting for SourceMod with SourcePawn.

===Introductions===
*[[Introduction to SourcePawn 1.7]] - Learning language syntax.
*[[SourcePawn Transitional Syntax]] - Learning transitional syntax.
*[[Introduction to SourceMod Plugins]] - Writing your "first plugin."
*[https://sm.alliedmods.net/new-api/ API Reference] - Searchable scripting API reference.

===Basic API===
*[[AutoConfigs (SourceMod Scripting)|AutoConfigs]] - Automatic .cfg creation for cvars.
*[[Commands (SourceMod Scripting)|Commands]] - Console commands/input.
*[[ConVars (SourceMod Scripting)|ConVars]] - Console variables (cvars).
*[[Events (SourceMod Scripting)|Events]] - Half-Life 2 Game Events.
*[[KeyValues (SourceMod Scripting)|KeyValues]] - KeyValues file parsing/writing.
*[[Menu API (SourceMod)|Menus]] - Building and drawing menus.
*[[SQL (SourceMod Scripting)|SQL]] - Using databases (MySQL, SQLite).
*[[Timers (SourceMod Scripting)|Timers]] - Timed callbacks.
*[[DataPacks|DataPacks]] - A good way to store asynchronous data.
*[[Translations (SourceMod Scripting)|Translations]] - Internationalization.
*[[Entity References (SourceMod)|Entity References]] - A safe way of storing entities.
*[[Checking Admin Flags (SourceMod Scripting)|Checking Admin Flags]] - Limit commands to certain users

===Advanced API===
*[[Admin API (SourceMod)|Administration API]] - Using the Admin Cache.
*[[Admin Menu (SourceMod Scripting)|Admin Menu API]] - Attaching to the Admin Menu.
*[[Creating Natives (SourceMod Scripting)|Creating Natives]] - Exposing API to other plugins.
*[[Function Calling API (SourceMod Scripting)|Function Calling API]] - Calling external functions.
*[[Optional Requirements (SourceMod Scripting)|Optional Requirements]] - Managing dependencies.
*[[SDKTools (SourceMod Scripting)|SDKTools]] - Using the powerful SDK abstraction layer.
*[[TempEnts (SourceMod SDKTools)|Temporary Entities]] - Using temporary entities.

===Information===
*[[Format Class Functions (SourceMod Scripting)|Format Class Functions]] - All about text formatting.
*[[Handles (SourceMod Scripting)|Handles]] - Overview of Handles and some common types.
*[[Optimizing Plugins (SourceMod Scripting)|Optimizing Plugins]] - Optimization hints.
*[[Tags (Scripting)|Tags]] - All about tags.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Explanation of Vector types.

===Resources===
*[https://sm.alliedmods.net/new-api/ API Reference] - Searchable scripting API reference.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Game events listings for popular mods.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Temporary entities for popular mods.
*[[SourceMod Profiler]] - Performance tracking and optimizing.
*[[Vice_keys]] - Decryption keys for ctx files
*[[Weapon Names(Source)]] - Weapon Names / weapon entity names
[[Category:SourceMod]]
[[Category:SourceMod Development]]

Category:SourceMod Development

2024-06-12T23:03:27Z

Mooshua:

{{ForAdvancedDevelopers|SourceMod}}

This category contains articles about developing for SourceMod extensions. [[:Category:SourceMod_Scripting|Click here for the scripting category]].

==Scripting==
*[[:Category:SourceMod_Scripting|Scripting Tutorials]]
*[https://sm.alliedmods.net/new-api/ Scripting Reference]

==Introductions==
*[[SourceMod SDK]]
*[[Writing Extensions]]
*[[Writing Extensions from Metamod:Source Plugins]]
*[http://docs.sourcemod.net/dox Doxygen of SourceMod API]

==Detailed Tutorials==
*[[Admin API (SourceMod)|Administration API]]
*[[Compiling SourceMod]]
*[[Handle API (SourceMod)|Handle System API]]
*[[Menu API (SourceMod)|Menu System API]]
*[[Natives (SourceMod Development)|Writing Native Functions]]
*[[Finding Virtual Offsets]]

==Resources==

*[[Virtual_Offsets_(Source_Mods)|Virtual Offsets List]]
*[[Entity Properties]]
*[[Game Events (Source)|Game Events]]
*[[Mod TempEnt List (Source)|Temporary Entity Lists]]
*[[Useful Signatures (Source)|Useful Signatures]]
*[[:Category:Metamod:Source Development|Metamod:Source Development]]
*[[:Category:Game_Resources|Mod Specific Resources]]
*[[User_Messages|User Messages]]

[[Category:SourceMod]]

Template:ForAdvancedDevelopers

2024-06-12T23:02:36Z

Mooshua: Created page with "<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: Orange; border-style:solid; background-color: Moccasin; max-width: 60rem;"> File:Wires.png|frameless|128p..."

<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: Orange; border-style:solid; background-color: Moccasin; max-width: 60rem;">
[[File:Wires.png|frameless|128px|left|link=|alt=]]
<b style="font-size: 20px">
For Internal Development
</b>
<p>
This page is geared towards helping developers learn how to use the behind-the-scenes parts of {{{1|SourceMod}}} itself.
If you're looking to contribute to or extend {{{1|SourceMod}}}, this is probably the page for you!
Look inside and see the wires that make {{{1|SourceMod}}} tick
</p>
</div>

File:Wires.png

2024-06-12T22:58:57Z

Mooshua: Look Inside Wires Copyright Unknown

== Summary ==
Look Inside
Wires

Copyright Unknown

SourceHook Development

2024-06-12T22:48:17Z

Mooshua: Move embedding to it's own page: SourceHook Standalone

SourceHook is a powerful API (Application Programming Interface) for detouring (hooking) virtual functions. Unlike static detours, SourceHook needs only to swap addresses in and out of an object's virtual table. This makes it fast and generally very platform-safe.

SourceHook is coupled with Don Clugston's [http://www.codeproject.com/cpp/FastDelegate.asp FastDelegate] headers. Virtual hooks can be detoured to any static function of the same prototype, or any member function (of any class) as long as the prototype matches.

All code in SourceHook is part of the SourceHook namespace. Thus, it may be prudent to declare this before using SourceHook structures or types:

<cpp>using namespace SourceHook;</cpp>

=Simple Hooks=
SourceHook has the following steps of operation:

* Declare the prototype of the function you are going to hook. This generates compile-time code that is able to pinpoint exactly how to go about hooking the function.
* Hook the function - as a member function of another class or a regular static function.
* Before the hooked function is called, all of the "pre" hook handlers attached to it are called. Each hook can set a special flag, the highest of which is chosen as a final operation. This flag specifies whether the original function should be called or not.
* Once all the hooks have been called, SourceHook decides whether to call the original function. Another set of hooks are called directly after, called "post" hook handlers. You can specify whether each hook is a post or pre hook - it simply changes whether it's called before or after the original call is made.
* After you are done using a hook, you must safely remove it before the object is destroyed (otherwise, memory will be leaked).

==Declaration==
As an example, take the following class prototype:
<cpp>
class IVEngineServer
{
public:
/*...*/
virtual void LogPrint( const char *msg ) = 0;
virtual bool IsDedicated() = 0;
};

extern IVEngineServer *engine;
</cpp>

The first step is to figure out how to declare its prototype to SourceHook. This function is void, and has one parameter. The declaration macro follows these formats:

*{{bcode|SH_DECL_HOOK}}n - n is the number of parameters
**The parameters are: Class name, member function name, attributes, overloaded?, the return type, and a list of the parameter types.
*{{bcode|SH_DECL_HOOKn_void}} - n is the number of parameters
**_void specifies that the function does not return a value. The format is the same as above except the "return type" parameter is missing.
*'''Note:''' Not covered here are the SH_DECL_HOOKn[_void]_vafmt hooks. These can hook string-formattable variable argument lists. You do not pass the string format or ellipses parameter. SourceHook will automatically format the string for your hook.

Our macro will look like this:
<pre>
SH_DECL_HOOK1_void(IVEngineServer, LogPrint, SH_NOATTRIB, 0, const char *);
SH_DECL_HOOK0(IVEngineServer, IsDedicated, SH_NOATTRIB, 0, bool);
</pre>

Broken down for the first line:
*There is 1 parameter.
*The function has no return value.
*<tt>IVEngineServer</tt> is the class containing the function.
*<tt>LogPrint</tt> is the function being hooked.
*The function as no attributes (for example, it is not const).
*The function is not overloaded.
*The first (and only) argument is a <tt>const char *</tt>

The second line is similar, except the parameter immediately after the overload parameter specifies the return type. There are no further parameters since it was declared with 0.

==Getting an Interface Instance==

Before you can use an interface, you need to retrieve an instance of it. This is done with either the <tt>GET_V_IFACE_ANY</tt> or <tt>GET_V_IFACE_CURRENT</tt> macros. Both take the same arguments. <tt>GET_V_IFACE_CURRENT</tt> is recommended if it works. <tt>GET_V_IFACE_ANY</tt> should also work, but may be missing newer functionality.

Normally this initialization needs to be done when your MM:S plugin or SourceMod Extension starts.

You also need to know which factory produces the interface you need. There are only 4 factories: <tt>GetEngineFactory</tt>, <tt>GetServerFactory</tt>, <tt>GetPhysicsFactory</tt>, and <tt>GetFilesystemFactory</tt>. Normally you'll want Engine or Server.

You'll also need to know the constant that the game uses for that particular class. This is usually found in the hl2sdk for your game. In the case of <tt>IVEngineServer</tt>, this is <tt>INTERFACEVERSION_VENGINESERVER</tt> located in public/eiface.h.

So, to retrieve the Interface so you can do something with it, it'd look something like this:
<pre>
IVEngineServer *engine;

// For SourceMod, use the first signature
//bool MyExtension::OnMetamodLoad(ISmmAPI *ismm, char *error, size_t maxlen, bool late)
bool MyPlugin::Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlen, bool late)
{
GET_V_IFACE_CURRENT(GetEngineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);
}
</pre>

The error and maxlen arguments '''must''' be named error and maxlen respectively, or else certain macros will fail.

Note that MyPlugin should be replaced with your plugin's class.

==Hook Functions==
Hooks can be declared either ''pre'' or ''post''. A ''pre'' hook will intercept the original function before it is called. Pre-hooks can return one of four ''hook actions'':
*<tt>MRES_IGNORED</tt> - The original function will be called.
*<tt>MRES_HANDLED</tt> - Same as <tt>MRES_IGNORED</tt>, except subsequent hooks can assume this means something important was changed.
*<tt>MRES_OVERRIDE</tt> - The original function will be called, but the new return value will be used instead of the one from the original function.
*<tt>MRES_SUPERCEDE</tt> - The original function will not be called. The new return value (if any) will be used instead.

These enum constants are defined in <tt><sourcehook.h></tt>, and are made available to Metamod:Source plugin developers via <tt><ISmmPlugin.h></tt>.

Once all pre-hooks have been processed, SourceHook takes an action based on the "highest" hook action returned (<tt>MRES_IGNORED</tt> being lowest, <tt>MRES_SUPERCEDE</tt> being highest). Once the action has been processed, all ''post'' hooks are called. That is to say, even if the original function is never called, post hooks are still processed. Because a post hook as no chance at true interception, it is important to realize that depending on the information being detoured, the data may be modified or destroyed. Similarly, a post hook's returned action and value is ignored.

A hook's action is signalled via one of two macros:
*<tt>RETURN_META</tt> - Only usable from <tt>void</tt> functions. Signals the action to take, then returns.
*<tt>RETURN_META_VALUE</tt> - Only usable from non-<tt>void</tt> functions. Signals the action to take, then returns the supplied value.

There are two methods of adding or removing hooks. Hooks can be bound to '''static''' or '''member''' functions. Both have a similar syntax. Their macros are:
*<tt>SH_STATIC(Function)</tt> - Hook to a static function.
*<tt>SH_MEMBER(Instance, Function)</tt> - Hook to a member function.

<b>It is important to realize that a simple hook will only be invoked when used on the same instance.</b> That is to say, if there are 500 instances of object X, and a hook is added to function X::Y in instance #8, then the hook will only be invoked from instance #8. <b>Multiple hooks can be declared on the same instance, and multiple instances can be bound to the same hook, but one hook will only be invoked for the instances it was hooked to.</b>

To have hooks that work across all instances, and thus do not need to be delegated per-instance, see the "Global Hooks" section. As of SourceHook v5, it is safe to remove hooks on a destroyed instance, as the instance is not actually dereferenced. However, its virtual table must still be accessible.

==Adding Hooks==
The macro to add hooks is <tt>SH_[ADD|REMOVE]_HOOK</tt>. The syntax is:

<cpp>SH_[ADD|REMOVE]_HOOK(Interface, Function, Instance, Hook, [post? true,false])</cpp>

An example of adding a <tt>LogPrint</tt> hook:
<cpp>void Hook_LogPrint(const char *msg)
{
if (strcmp(msg, "If this string matches the function will be blocked") == 0)
{
RETURN_META(MRES_SUPERCEDE);
}

/* Not needed, but good style */
RETURN_META(MRES_IGNORED);
}

void StartHooks()
{
log_hook = SH_ADD_HOOK(IVEngineServer, LogPrint, engine, SH_STATIC(Hook_LogPrint), false);
}

void StopHooks()
{
SH_REMOVE_HOOK(IVEngineServer, LogPrint, engine, SH_STATIC(Hook_LogPrint), false);
}</cpp>

The syntax is similar for hooking to member functions. Example equivalent to the above:
<cpp>
class MyHooks
{
public:
void Hook_LogPrint(const char *msg)
{
if (strcmp(msg, "If this string matches the function will be blocked") == 0)
{
RETURN_META(MRES_SUPERCEDE);
}

/* Not needed, but good style */
RETURN_META(MRES_IGNORED);
}

void StartHooks()
{
SH_ADD_HOOK(IVEngineServer, LogPrint, engine, SH_MEMBER(this, &MyHooks::Hook_LogPrint), false);
}

void StopHooks()
{
SH_REMOVE_HOOK(IVEngineServer, LogPrint, engine, SH_MEMBER(this, &MyHooks::Hook_LogPrint), false);
}
};</cpp>

=Manual Hooks=
In some cases, it may be necessary to support multiple, incompatible ABI branches of an interface. For example, suppose you need to hook an application that may supply either version of these interfaces:

Interface v1:
<cpp>
class Interface
{
public:
virtual void Function1() =0;
virtual bool Function2(int clam) =0;
};</cpp>

Interface v2:
<cpp>
class Interface
{
public:
virtual bool Function2(int clam) =0;
};</cpp>

Obviously, these two interfaces are backwards incompatible. Manual hooks allow you to precisely define the structure of the virtual table, bypassing the compiler's rules. These rules can be re-configured at runtime.

==Declaration==
Declaring a manual hook is similar to declaring a normal/simple hook. The syntax is:

<cpp>SH_DECL_MANUALHOOK<n>[_void](UniqueName, vtblIndex, vtblOffs, thisOffs, [return and param types])</cpp>

The <tt>UniqueName</tt> is a unique identifier for the hook. The <tt>vtblIndex</tt> is the index into the virtual table at which the function lies. In most compilers, this index starts from 0. The <tt>vtblOffs</tt> and <tt>thisOffs</tt> fields are used for multiple inheritance and are almost always 0 in modern compiler single inheritance.

An example of hooking the two functions from the first interface version:
<cpp>SH_DECL_MANUALHOOK0_void(MHook_Function1, 0, 0, 0);
SH_DECL_MANUALHOOK1(MHook_Function2, 1, 0, 0, bool, int);</cpp>

==Reconfiguring==
A manual hook can be ''reconfigured'', which will update its set offsets. Reconfiguration automatically removes all hooks on the manual hook. Let's say we want to reconfigure the <tt>Function2</tt> hook in the case of the second version being detected:

<cpp>
void SwitchToNewerHooks()
{
SH_MANUALHOOK_RECONFIGURE(MHook_Function2, 0, 0, 0);
}
</cpp>

Note that the hook was referenced by its unique identifier.

==Adding Hooks==
Adding or removing hook binds is done via the following extra macros:
*<tt>SH_ADD_MANUALHOOK</tt>
*<tt>SH_REMOVE_MANUALHOOK</tt>

These work similar to the original functions. Example:
<cpp>extern Interface *iface;

bool Hook_Function2(int clam)
{
RETURN_META_VALUE(MRES_IGNORED, false);
}

void StartHooks()
{
SH_ADD_MANUALHOOK(MHook_Function2, iface, SH_STATIC(Hook_Function2), false);
}

void StopHooks()
{
SH_REMOVE_MANUALHOOK(MHook_Function2, iface, SH_STATIC(Hook_Function2), false);
}</cpp>

Similarly, a member function version would use <tt>SH_MEMBER</tt> instead.

=Extended Removal Syntax=
The syntax described in the above sections is new as of SourceHook v4.5. <tt>SH_REMOVE_HOOK</tt> is, for all intents and purposes, optional. There is another way to remove hooks.

Each <tt>SH_ADD</tt> macro returns a non-zero <tt>int</tt> on success. The same integer can be passed to the <tt>SH_REMOVE_HOOK_ID</tt> macro, and the hook will be removed. This alternate removal syntax can simplify code that uses multiple successive or dynamic hooks.

Global hooks, described in a later section, require usage of <tt>SH_REMOVE_HOOK_ID</tt> - that is, there is no helper macro to simplify removing a global hook.

=Old Macros=
SourceHook v5.0 deprecates older macros that were used in earlier versions. The macros are:
*<tt>SH_ADD_HOOK_STATICFUNC</tt> - Wrapper for <tt>SH_ADD_HOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_REMOVE_HOOK_STATICFUNC</tt> - Wrapper for <tt>SH_REMOVE_HOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_ADD_HOOK_MEMFUNC</tt> - Wrapper for <tt>SH_ADD_HOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_REMOVE_HOOK_MEMFUNC</tt> - Wrapper for <tt>SH_REMOVE_HOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_ADD_MANUALHOOK_STATICFUNC</tt> - Wrapper for <tt>SH_ADD_MANUALHOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_REMOVE_MANUALHOOK_STATICFUNC</tt> - Wrapper for <tt>SH_REMOVE_MANUALHOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_ADD_MANUALHOOK_MEMFUNC</tt> - Wrapper for <tt>SH_ADD_MANUALHOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_REMOVE_MANUALHOOK_MEMFUNC</tt> - Wrapper for <tt>SH_REMOVE_MANUALHOOK</tt> and <tt>SH_MEMBER</tt>.

These macros are fairly self explanatory. The parameter where the <tt>SH_STATIC</tt> or <tt>SH_MEMBER</tt> macro would normally go is instead filled with the parameters to that macro.

This syntax is considered deprecated, but it is still supported. Code written with these macros will continue to compile against older SourceHook versions. If you are writing a plugin which must work against Metamod:Source 1.4 and 1.6, you will want to use the older macros for simplicity.

=Global Hooks=
<b>Note:</b> Global Hooks are only available in SourceHook v4.5 or later.

Global hooks are unlike normal hooks in that the hook is invoked for ALL instances, rather than solely the given the instance the hook was bound to. It is important to realize that this feature can be deceiving. Consider the following example:

<cpp>
class CBaseEntity
{
public:
virtual void SetHealth(int health) =0;
};

class CBaseCat : public CBaseEntity
{
public:
virtual void SetHealth();
};

class CBaseKitten : public CBaseCat
{
public:
virtual void SetHealth();
};</cpp>

In this example, <tt>CBaseCat</tt> and <tt>CBaseKitten</tt> instances have ''separate virtual tables''. Although they both derive from <tt>CBaseEntity</tt>, they are separate virtual objects. <b>Therefore, a global hook on <tt>CBaseEntity</tt> will receive no invocations, and a hook on <tt>CBaseCat</tt> will receive only <tt>CBaseCat</tt> instances, as long as the instance is not a class derived from <tt>CBaseCat</tt></b>.

With this understanding in place, there are two separate syntaxes - one for simple hooks and one for manual hooks. Additionally, there are two ways of declaring the virtual interface to use:
*An instance of the class can be passed.
*The direct address to the virtual table can be passed.

They are essentially equivalent, although one may be more advantageous than the other (for example, if no instances are known, but the vtable address can be extracted via pattern searching).

It is also important to note that global hooks are just a different method of "filtering." They fall into either the "simple" or "manual" category, and are otherwise exactly the same to those hooks. Thus there are no separate return/declaration macros for global hooks.

The macro <tt>META_IFACEPTR</tt> is especially useful for global hooks. See [[SourceHook_Development#Interface_Pointers_from_Hooks|Interface Pointers from Hooks]] near the end.

Lastly, global hooks exclusively use the extended hooking syntax. That means there exists only <tt>SH_ADD</tt> macros. <tt>SH_HOOK_REMOVE_ID</tt> must be used and the hook ID generated via <tt>SH_ADD</tt> must be cached.

All examples will use the following code as a basis:
<cpp>
class Player
{
public:
virtual void TakeDamage(int damage) =0;
};

void Hook_TakeDamage(int damage);
</cpp>

==Simple Hooks==
Two extra macros exist for adding a global hook:

<cpp>
SH_ADD_VPHOOK(Interface, Function, Instance, Handler, Post)
SH_ADD_DVPHOOK(Interface, Function, VirtualTable, Handler, Post)
</cpp>

An example:
<cpp>
extern void *player_vtable;
HookId takedamage_hook = 0;

void StartHooks()
{
takedamage_hook = SH_ADD_DVPHOOK(Player, TakeDamage, player_vtable, SH_STATIC(Hook_TakeDamage), false);
}

void StopHooks()
{
if (takedamage_hook)
{
SH_REMOVE_HOOK_ID(takedamage_hook);
}
}</cpp>

==Manual Hooks==
Similarly, manual hooks are straightforward:
<cpp>
SH_DECL_MANUALHOOK1_void(MHook_TakeDamage, 0, 0, 0, int);

extern void *player_vtable;
int takedamage_hook = 0;

void StartHooks()
{
takedamage_hook = SH_ADD_MANUALDVPHOOK(MHook_TakeDamage, player_vtable, SH_STATIC(Hook_TakeDamage), false);
}

void StopHooks()
{
if (takedamage_hook)
{
SH_REMOVE_HOOK_ID(takedamage_hook);
}
}</cpp>

=Modifying Parameters=
Consider another variation of the hooking process. There is a hook on function X, which has one parameter. The hook wants to change the value of this parameter transparently. For example:
*Caller passes 5 into X.
*Hook changes the 5 to a 6.
*Hooked function receives a 6 and continues normally.

SourceHook has a method for achieving this. As an added bonus, the new parameters are passed to subsequent hooks. That means the replacement process is as transparent as possible. For this example, we'll use the following code, with an assumed hook on <tt>Player::TakeDamage</tt> to the <tt>Hook_TakeDamage</tt> function.

<cpp>
class Player
{
public:
virtual void TakeDamage(int damage);
};

void Hook_TakeDamage(int damage);</cpp>

Our objective is to multiply the damage by 2.

==Simple Hooks==
For simple hooks, changing parameters looks similar to an <tt>SH_CALL</tt>. The macros are:

<cpp>RETURN_META_NEWPARAMS(Action, HookFunction, ([params]))
RETURN_META_VALUE_NEWPARAMS(Action, Value, HookFunction, ([params]))
</cpp>

Example:
<cpp>
void Hook_TakeDamage(int damage)
{
RETURN_META_NEWPARAMS(MRES_IGNORED, &Player::TakeDamage, (damage * 2));
}</cpp>

Note that the parenthesis enclosing the parameters are required.

==Manual Hooks==
Manual hooks require slightly different macros. They are:

<cpp>RETURN_META_MNEWPARAMS(Action, UniqueName, ([params]));
RETURN_META_VALUE_MNEWPARAMS(Action, Value, UniqueName, ([params]));</cpp>

Example:
<cpp>
SH_DECL_MANUALHOOK1_void(MHook_Player_TakeDamage, 0, 0, 0, int);

void Hook_TakeDamage(int damage)
{
RETURN_META_MNEWPARAMS(MRES_IGNORED, MHook_Player_TakeDamage, (damage *2));
}</cpp>

Note that the parenthesis enclosing the parameters are required.

=Bypassing Hooks=
Often, either to avoid certain functionality or to avoid infinite recursion, it is necessary to bypass all hooks on a hooked function, such that only the original function is called. For instance, a previous blocked certain messages sent through <tt>LogPrint</tt>. In order to send that message, the hook needs to be bypassed.

To way to do this is to use the <tt>SH_CALL</tt> macro:
<cpp>SH_CALL(Instance, HookFunction)(params)</cpp>

Example:
<cpp>SH_CALL(engine, &IVEngineServer::LogPrint)("Secret Message");</cpp>

Similarly, manual hooks have <tt>SH_MCALL</tt>:

<cpp>SH_DECL_MANUALHOOK1(MHook_Function2, 1, 0, 0, bool, int);

bool Function2_Bypass(int clam)
{
return SH_MCALL(iface, MHook_Function2)(clam);
}</cpp>

==Deprecated Syntax==
The syntax described above is used in SourceHook v5.0 and v4.5. An older syntax, using a "CallClass" data type, was used in SourceHook v4.4 and lower. This syntax was deprecated in v4.5 and completely removed in v5.0. Upgrading from SourceHook v4.4 means that code referencing <tt>SH_GET_CALLCLASS</tt> or <tt>SH_REMOVE_CALLCLASS</tt> must be removed, and <tt>SH_CALL</tt> simply needs an instance pointer instead.

=Other Macros=
SourceHook contains a large variety of extra macros. This section is a grab bag of the more commonly used ones.

==Interface Pointers from Hooks==
Let's say you have the following hook:

<cpp>class Player
{
public:
virtual void TakeDamage(int damage);
float GetDamageModifier();
};

void Hook_TakeDamage(int damage);
</cpp>

How can you get the <tt>Player</tt> instance while in the hook? This can be achieved via the <tt>META_IFACEPTR</tt> macro. Example:

<cpp>void Hook_TakeDamage(int damage)
{
Player *pPlayer = META_IFACEPTR(Player);

int new_damage = (int)((pPlayer->GetDamageModifier() + 0.3) * (float)damage);

RETURN_META_NEWPARAMS(MRES_IGNORED, &Player::TakeDamage, (new_damage));
}</cpp>

Note that the class name should be passed to <tt>META_IFACEPTR</tt>, not the pointer type.

==Ignoring Reference Returns==
There is a special macro, <tt>RETURN_META_NOREF</tt>, for ignoring a return value for reference-returning functions. Example:

<cpp>
class ISomething
{
public:
virtual int & GetSomething() =0;
};

int & Hook_GetSomething()
{
RETURN_META_NOREF(MRES_IGNORED, int &);
}</cpp>

=Automatic hookmanager generation=
Normally, the SH_DECL_ macros generate a so-called "hook manager", a function which is invoked instead of the original function and then calls the hooks and processes their return and <tt>META_RES</tt> values.

It is also possible to let SourceHook auto-generate the hook manager. This is neccessary if the function prototype is unknown at compile time (for example if hooks can be defined from third-party plugins of your plugin).

Example Usage from a Metamod:Source plugin:
<cpp>
#include "sourcehook_pibuilder.h"

// We want to hook a void (int, float) function

// Request IHookManagerAutoGen interface
SourceHook::IHookManagerAutoGen *hmag =
static_cast<SourceHook::IHookManagerAutoGen *>(ismm->MetaFactory(MMIFACE_SH_HOOKMANAUTOGEN, NULL, NULL));

// (check for hmag == NULL)

// Build prototype information (using CProtoInfoBuilder helper class).
SourceHook::CProtoInfoBuilder protoInfo(SourceHook::ProtoInfo::CallConv_ThisCall);
protoInfo.AddParam(sizeof(int), SourceHook::PassInfo::PassType_Basic, SourceHook::PassInfo::PassFlag_ByVal,
NULL, NULL, NULL, NULL);
protoInfo.AddParam(sizeof(float), SourceHook::PassInfo::PassType_Float, SourceHook::PassInfo::PassFlag_ByVal,
NULL, NULL, NULL, NULL);

// Generate the hook manager
HookManagerPubFunc generatedHookMan = hmag->MakeHookMan(protoInfo, 0 /* vtable offset */, 0 /* vtable index */);

// Add the hook
int hookid = g_SHPtr->AddHook(g_PLID, SourceHook::ISourceHook::Hook_Normal/Hook_VP/Hook_DVP, iface_ptr, thisptr_offs,
generatedHookMan, handler, post);

// ... (use the hook)

// After you're done using the hook (cleanup)
// Remove the hook
g_SHPtr->RemoveHookByID(hookid);

// Release hook manager
hmag->ReleaseHookMan(generatedHookMan);
</cpp>
<tt>CProtoInfoBuilder::AddParam</tt> has 7 parameters:
* size: size of the type. This is sizeof(type) even if it is passed by reference!
* passtype: this can be PassType_Basic for integer types (char/short/int/...), PassType_Float for floating-point types (float/double) and PassType_Object for unions, structs and classes.
* passflags: flags. Has to contain either PassFlag_ByVal or PassFlag_ByRef.
* pNormalCtor: for PassType_Object, set this to the pointer to the user-defined default constructor of the object, if it has one.
* pCCtor: for PassType_Object, set this to the pointer to the user-defined copy constructor of the object, if it has one.
* pODtor: for PassType_Object, set this to the pointer to the user-defined destructor of the object, if it has one.
* pAssignOperator: for PassType_Object, set this to the pointer to the user-defined assignment operator of the object, if it has one.

If you are hooking a non-void function, also call <tt>CProtoInfoBuilder::SetReturnType</tt>. It has the same arguments as <tt>AddParam</tt>.

The <tt>handler</tt> parameter of <tt>ISourceHook::AddHook</tt> is a pointer to the ISHDelegate interface.
In C++, you construct ISHDelegates like this:
<cpp>
class MyDelegate : public SourceHook::ISHDelegate
{
public:
// vtable index 0
virtual bool IsEqual(ISHDelegate *pOtherDeleg)
{
// pOtherDeleg is guaranteed to be from the same plugin.
// This function is only used for compat with the old SH_REMOVE_HOOK method.
// if you don't want to use that with your hooks, you can simply return false here.
// if for some reason you need it, a good idea could be comparing the vtable pointer:
return *reinterpret_cast<void**>(this) == *reinterpret_cast<void**>(pOtherDeleg);

// But in general I'd just return false!
}

// vtable index 1
virtual void DeleteThis()
{
delete this; // Called from SourceHook when this instance is not needed
// and should be deleted.
}

// vtable index 2
virtual ret_type Call(params)
{
// your code.
// SH_DECL_ macros pass execution to the actual user's handler through a FastDelegate
// which is stored as a member variable of the delegate class.
}
};
</cpp>

The first parameter of the CProtoInfoBuilder constructor (see example code above) is the calling convention in an extended sense. At the moment it can be either CallConv_ThisCall or (CallConv_ThisCall | CallConv_HasVafmt). The second value means that the function has printf-like string formatting. Then, the finaly ''const char *, ...'' arguments will be added automatically, and the Deleagte::Call method should have one more parameter: ''const char *formattedString''.

pNormalCtor/pCCtor/pODtor/pAssignOperator should be found using offsets / sigscanning. If you are a C++ plugin and know the type at compile time, you can also use the following class:
<cpp>
// Address of constructor/destructor
// (using wrappers)
template <class T>
class Ctor_Thunk
{
public:
void NormalConstructor()
{
new(this) T;
}

void CopyConstructor(const T &other)
{
new(this) T(other);
}

void Destructor()
{
reinterpret_cast<T*>(this)->~T();
}

const T& AssignOp(const T &other)
{
return (*reinterpret_cast<T*>(this) = other);
}
};

template <class T>
void *FindFuncAddr(T mfp)
{
union
{
T a;
void *b;
} u;
u.a = mfp;
return u.b;
}

// Usage:
FindFuncAddr(&Ctor_Thunk<type>::NormalConstructor)
// (if the type is a reference type, use it without & here)
</cpp>

[[Category:Metamod:Source Development]]
[[Category:SourceHook]]

SourceHook Standalone

2024-06-12T22:47:30Z

Mooshua: Created page with "SourceHook can be embedded and run standalone of Metamod if you want to integrate it into another platform. SourceHook independent of metamod is a lightweight and powerful in..."

SourceHook can be embedded and run standalone of Metamod if you want to integrate it into another platform.
SourceHook independent of metamod is a lightweight and powerful instrumentation library for polymorphic C++ classes, and comes with many features needed to implement your own C++ modding platform out-of-the-box.

To make sure SourceHook's conflict resolution is able to run unimpeded, you need to make sure only one instance of SourceHook exists in the entire process!
Once the global SourceHook implementation has been created, you can pass the <tt>ISourceHook</tt> pointer around to allow plugins to interface with SourceHook.

== Usage ==

Each hook has an associated <tt>g_PLID</tt>/<tt>PluginId</tt> that groups hooks from the same plugin together.
The g_PLID doesn't need to be anything particularly; SourceHook doesn't care, it's just sugar that allows you to de-register, pause, and unpause entire plugins remotely.

In all consuming plugins, g_PLID should be provided and tracked by whatever management code you have, and <tt>ISourceHook::UnloadPlugin</tt> should be called with the corresponding PluginId when a plugin is being unloaded.

== Examples ==

To instantiate the SourceHook engine, you must create a <tt>CSourceHookImpl</tt> instance. Example:

<cpp>
/* Normally, just <sourcehook.h> is included, but this is needed to instantiate the engine. */
#include <sourcehook/sourcehook_impl.h>

SourceHook::Impl::CSourceHookImpl g_SourceHook;
</cpp>

To actually use SourceHook, it is necessary to have two global variables:
*<tt>g_PLID</tt> - A unique integer that identifies the library using SourceHook. This is used for removing all hooks a library is using.
*<tt>g_SHPtr</tt> - A pointer to the <tt>SourceHook::ISourceHook</tt> interface.

Example header file:
<cpp>
#include <sourcehook/sourcehook.h>

extern SourceHook::ISourceHook *g_SHPtr;
extern int g_PLID;</cpp>

Example addition to the global code:
<cpp>
SourceHook::ISourceHook *g_SHPtr = &g_SourceHook;
int g_PLID = 0;</cpp>

==Multiple Libraries/Shared Hooks==
If SourceHook is going to be used across multiple libraries in the same process, it is essential that only one instance of SourceHook be present. Of course, that is only logical, since otherwise the instances would be replacing each other's virtual patches.

In order to support this, each separate library must be given the <tt>ISourceHook</tt> pointer and a unique <tt>g_PLID</tt> value. <tt>CSourceHookImpl</tt> provides a few useful functions for managing hooks on "child" libraries or otherwise linked code.

*<tt>PausePlugin()</tt> - Silences any hooks from an ID, such that those hooks will not be called.
*<tt>UnpausePlugin()</tt> - Un-silences any silenced hooks from an ID.
*<tt>UnloadPlugin()</tt> - Clean-up any left-over hooks from an ID.

[[Category:SourceHook]]

SourceHook

2024-06-12T22:38:44Z

Mooshua: Expand!

{{Stub}}

SourceHook is a versatile library for hooking virtual functions. SourceHook was designed for declaring single hooks against a given virtual function and a specific <tt><i>this</i></tt> pointer.

For more information about SourceHook's features and API, see [[SourceHook Development]].

== Mechanism ==

SourceHook replaces methods within a class's virtual table to redirect execution to SourceHook itself.
Virtual hooking is comparatively simple compared to detours; all a hooking library needs to do is ensure ABI compatibility with the method being swapped. Detours, on the other hand, require disassembling the first block of a subroutine to generate a trampoline that executes the original code!

== Compatibility ==
Compatibility for arguments is fairly trivial--you just need to have the right type and pointer type (eg, lvalue ref, rvalue ref, pointer, pass-by-value...)

For return types, it gets a bit tricky. For 64-bit support, you need to make sure that your return type exactly matches the type in the game, or else different code could be emitted by your compiler that is incompatible with the game.

== Implementation ==
SourceHook is split into two parts: the '''implementation''' (within metamod itself) and the '''hook manager''' (within your plugin!)
The implementation keeps track of all plugins that are trying to hook a particular method, and the hook manager is responsible for calling each plugin's hook.
Your plugin's SourceHook macros or templates create a hook manager for the method being hooked, and this hook manager directly replaces the original implementation in the virtual table.

Only one plugin's hook manager is used. When there are multiple, SourceHook picks the first one, prioritizing newer hook manager version numbers for compatibility.
Even if an old plugin that no longer supports the current SourceHook implementation is running on the system, as long as a newer hook manager exists SourceHook will use it instead, providing fairly remarkable compatibility. (The plugins themselves, on the other hand...)

This also means if even one hook manager is out of date and no longer has ABI compatibility with the original, then crashes could occur.

[[Category:SourceHook]]

Category:Metamod:Source Development

2024-06-12T22:26:11Z

Mooshua:

{{ForDevelopers|Metamod}}

Need help? Join #sourcemod or #metamod on irc.gamesurge.net, or post on the [http://forums.alliedmods.net/forumdisplay.php?f=75 forums].

*<b>Documentation</b>
**[[Metamod:Source Environment|Setting up your Environment]]
**[[Metamod:Source Development|Overview of Writing Metamod:Source Plugins]]
**[[Sample Plugins (Metamod:Source)|Example Plugins]]
**[[SourceHook Development|SourceHook Overview]]
**[[Metamod:Source VDF Files]]
**[http://www.metamodsource.net/dox/ Metamod:Source 1.6.0 API]
**[http://www.metamodsource.net/dox-1.4.3/ Metamod:Source 1.4.3 API]

*<b>Compatibility/Porting</b>
**[[MM:S API Differences]] (Explains <tt>core</tt> versus <tt>core-legacy</tt>)
**[[Porting to Orange Box]]
**[[Porting to Left 4 Dead]]
**[[Porting to Swarm and CSGO]]
**[[Gameinfo Deprecation]]

*<b>Half-Life 2 Resources</b>
**[[Virtual Offsets (Source Mods)]]
**[[Game Events (Source)]]
**[[Signature Scanning]]
**[[:Category:SourceMod Development]]

Template:ForDevelopers

2024-06-12T22:25:41Z

Mooshua: Created page with "<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: LightSeaGreen; border-style:solid; background-color: Azure; max-width: 60rem;"> File:Silly goose.png|fram..."

<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: LightSeaGreen; border-style:solid; background-color: Azure; max-width: 60rem;">
[[File:Silly goose.png|frameless|64px|left|link=|alt=]]
<b style="font-size: 20px">
For Developers & Modders
</b>
<p>
This page is geared towards helping developers learn how to create and modify {{{1|SourceMod}}} plugins.
To learn how to install and manage {{{1|SourceMod}}} itself, check out the '''documentation''' categories for system-administrator geared articles.
</p>
</div>

Category:Metamod:Source Documentation

2024-06-12T22:22:13Z

Mooshua: Add "for sysadmins" banner

{{ForSysadmins|Metamod}}

*<b>Installation and Setup</b>
**[[Installing Metamod:Source]]
**[[Configuring Metamod:Source]]
*<b>Usage</b>
**[[Console Commands (Metamod:Source)|Console Commands]]
**[[:Category:Metamod:Source Development|Development]]
*<b>Information</b>
**[[Gameinfo Deprecation]]
**[[Metamod:Source VDF Files]]
**[[Supported Games (Metamod:Source)|Supported Games]]
**[[Frequently Asked Questions (Metamod:Source)|FAQ]]
**[[Open Source Plugins for Metamod:Source|Open Source Plugins]]
*<b>Development</b>
**[[:Category:Metamod:Source Development|Metamod:Source Development]]

Template:ForSysadmins

2024-06-12T22:21:15Z

Mooshua: Created page with "<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: LightPink; border-style:solid; background-color: MistyRose; max-width: 60rem;"> File:FlorkSunglasses.png|..."

<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: LightPink; border-style:solid; background-color: MistyRose; max-width: 60rem;">
[[File:FlorkSunglasses.png|frameless|64px|left|link=|alt=]]
<b style="font-size: 20px">
For System Administrators
</b>
<p>
This page is geared towards helping a sysadmin install, manage, and maintain a {{{1|SourceMod}}} installation.
If you're looking to create, develop, or modify {{{1|SourceMod}}} plugins, check out the '''development''' pages for relevant documentation.
</p>
</div>

File:FlorkSunglasses.png

2024-06-12T22:13:41Z

Mooshua: Flork wearing some sunglasses. This is used to spice up templates and add some flair '''This image is licensed under the Emotes.gg Basic License: https://emoji.gg/licenses'''

== Summary ==
Flork wearing some sunglasses. This is used to spice up templates and add some flair

'''This image is licensed under the Emotes.gg Basic License: https://emoji.gg/licenses'''

SourceHook Development

2024-06-12T22:10:26Z

Mooshua: Recategorize

SourceHook is a powerful API (Application Programming Interface) for detouring (hooking) virtual functions. Unlike static detours, SourceHook needs only to swap addresses in and out of an object's virtual table. This makes it fast and generally very platform-safe.

SourceHook is coupled with Don Clugston's [http://www.codeproject.com/cpp/FastDelegate.asp FastDelegate] headers. Virtual hooks can be detoured to any static function of the same prototype, or any member function (of any class) as long as the prototype matches.

All code in SourceHook is part of the SourceHook namespace. Thus, it may be prudent to declare this before using SourceHook structures or types:

<cpp>using namespace SourceHook;</cpp>

=Simple Hooks=
SourceHook has the following steps of operation:

* Declare the prototype of the function you are going to hook. This generates compile-time code that is able to pinpoint exactly how to go about hooking the function.
* Hook the function - as a member function of another class or a regular static function.
* Before the hooked function is called, all of the "pre" hook handlers attached to it are called. Each hook can set a special flag, the highest of which is chosen as a final operation. This flag specifies whether the original function should be called or not.
* Once all the hooks have been called, SourceHook decides whether to call the original function. Another set of hooks are called directly after, called "post" hook handlers. You can specify whether each hook is a post or pre hook - it simply changes whether it's called before or after the original call is made.
* After you are done using a hook, you must safely remove it before the object is destroyed (otherwise, memory will be leaked).

==Declaration==
As an example, take the following class prototype:
<cpp>
class IVEngineServer
{
public:
/*...*/
virtual void LogPrint( const char *msg ) = 0;
virtual bool IsDedicated() = 0;
};

extern IVEngineServer *engine;
</cpp>

The first step is to figure out how to declare its prototype to SourceHook. This function is void, and has one parameter. The declaration macro follows these formats:

*{{bcode|SH_DECL_HOOK}}n - n is the number of parameters
**The parameters are: Class name, member function name, attributes, overloaded?, the return type, and a list of the parameter types.
*{{bcode|SH_DECL_HOOKn_void}} - n is the number of parameters
**_void specifies that the function does not return a value. The format is the same as above except the "return type" parameter is missing.
*'''Note:''' Not covered here are the SH_DECL_HOOKn[_void]_vafmt hooks. These can hook string-formattable variable argument lists. You do not pass the string format or ellipses parameter. SourceHook will automatically format the string for your hook.

Our macro will look like this:
<pre>
SH_DECL_HOOK1_void(IVEngineServer, LogPrint, SH_NOATTRIB, 0, const char *);
SH_DECL_HOOK0(IVEngineServer, IsDedicated, SH_NOATTRIB, 0, bool);
</pre>

Broken down for the first line:
*There is 1 parameter.
*The function has no return value.
*<tt>IVEngineServer</tt> is the class containing the function.
*<tt>LogPrint</tt> is the function being hooked.
*The function as no attributes (for example, it is not const).
*The function is not overloaded.
*The first (and only) argument is a <tt>const char *</tt>

The second line is similar, except the parameter immediately after the overload parameter specifies the return type. There are no further parameters since it was declared with 0.

==Getting an Interface Instance==

Before you can use an interface, you need to retrieve an instance of it. This is done with either the <tt>GET_V_IFACE_ANY</tt> or <tt>GET_V_IFACE_CURRENT</tt> macros. Both take the same arguments. <tt>GET_V_IFACE_CURRENT</tt> is recommended if it works. <tt>GET_V_IFACE_ANY</tt> should also work, but may be missing newer functionality.

Normally this initialization needs to be done when your MM:S plugin or SourceMod Extension starts.

You also need to know which factory produces the interface you need. There are only 4 factories: <tt>GetEngineFactory</tt>, <tt>GetServerFactory</tt>, <tt>GetPhysicsFactory</tt>, and <tt>GetFilesystemFactory</tt>. Normally you'll want Engine or Server.

You'll also need to know the constant that the game uses for that particular class. This is usually found in the hl2sdk for your game. In the case of <tt>IVEngineServer</tt>, this is <tt>INTERFACEVERSION_VENGINESERVER</tt> located in public/eiface.h.

So, to retrieve the Interface so you can do something with it, it'd look something like this:
<pre>
IVEngineServer *engine;

// For SourceMod, use the first signature
//bool MyExtension::OnMetamodLoad(ISmmAPI *ismm, char *error, size_t maxlen, bool late)
bool MyPlugin::Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlen, bool late)
{
GET_V_IFACE_CURRENT(GetEngineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);
}
</pre>

The error and maxlen arguments '''must''' be named error and maxlen respectively, or else certain macros will fail.

Note that MyPlugin should be replaced with your plugin's class.

==Hook Functions==
Hooks can be declared either ''pre'' or ''post''. A ''pre'' hook will intercept the original function before it is called. Pre-hooks can return one of four ''hook actions'':
*<tt>MRES_IGNORED</tt> - The original function will be called.
*<tt>MRES_HANDLED</tt> - Same as <tt>MRES_IGNORED</tt>, except subsequent hooks can assume this means something important was changed.
*<tt>MRES_OVERRIDE</tt> - The original function will be called, but the new return value will be used instead of the one from the original function.
*<tt>MRES_SUPERCEDE</tt> - The original function will not be called. The new return value (if any) will be used instead.

These enum constants are defined in <tt><sourcehook.h></tt>, and are made available to Metamod:Source plugin developers via <tt><ISmmPlugin.h></tt>.

Once all pre-hooks have been processed, SourceHook takes an action based on the "highest" hook action returned (<tt>MRES_IGNORED</tt> being lowest, <tt>MRES_SUPERCEDE</tt> being highest). Once the action has been processed, all ''post'' hooks are called. That is to say, even if the original function is never called, post hooks are still processed. Because a post hook as no chance at true interception, it is important to realize that depending on the information being detoured, the data may be modified or destroyed. Similarly, a post hook's returned action and value is ignored.

A hook's action is signalled via one of two macros:
*<tt>RETURN_META</tt> - Only usable from <tt>void</tt> functions. Signals the action to take, then returns.
*<tt>RETURN_META_VALUE</tt> - Only usable from non-<tt>void</tt> functions. Signals the action to take, then returns the supplied value.

There are two methods of adding or removing hooks. Hooks can be bound to '''static''' or '''member''' functions. Both have a similar syntax. Their macros are:
*<tt>SH_STATIC(Function)</tt> - Hook to a static function.
*<tt>SH_MEMBER(Instance, Function)</tt> - Hook to a member function.

<b>It is important to realize that a simple hook will only be invoked when used on the same instance.</b> That is to say, if there are 500 instances of object X, and a hook is added to function X::Y in instance #8, then the hook will only be invoked from instance #8. <b>Multiple hooks can be declared on the same instance, and multiple instances can be bound to the same hook, but one hook will only be invoked for the instances it was hooked to.</b>

To have hooks that work across all instances, and thus do not need to be delegated per-instance, see the "Global Hooks" section. As of SourceHook v5, it is safe to remove hooks on a destroyed instance, as the instance is not actually dereferenced. However, its virtual table must still be accessible.

==Adding Hooks==
The macro to add hooks is <tt>SH_[ADD|REMOVE]_HOOK</tt>. The syntax is:

<cpp>SH_[ADD|REMOVE]_HOOK(Interface, Function, Instance, Hook, [post? true,false])</cpp>

An example of adding a <tt>LogPrint</tt> hook:
<cpp>void Hook_LogPrint(const char *msg)
{
if (strcmp(msg, "If this string matches the function will be blocked") == 0)
{
RETURN_META(MRES_SUPERCEDE);
}

/* Not needed, but good style */
RETURN_META(MRES_IGNORED);
}

void StartHooks()
{
log_hook = SH_ADD_HOOK(IVEngineServer, LogPrint, engine, SH_STATIC(Hook_LogPrint), false);
}

void StopHooks()
{
SH_REMOVE_HOOK(IVEngineServer, LogPrint, engine, SH_STATIC(Hook_LogPrint), false);
}</cpp>

The syntax is similar for hooking to member functions. Example equivalent to the above:
<cpp>
class MyHooks
{
public:
void Hook_LogPrint(const char *msg)
{
if (strcmp(msg, "If this string matches the function will be blocked") == 0)
{
RETURN_META(MRES_SUPERCEDE);
}

/* Not needed, but good style */
RETURN_META(MRES_IGNORED);
}

void StartHooks()
{
SH_ADD_HOOK(IVEngineServer, LogPrint, engine, SH_MEMBER(this, &MyHooks::Hook_LogPrint), false);
}

void StopHooks()
{
SH_REMOVE_HOOK(IVEngineServer, LogPrint, engine, SH_MEMBER(this, &MyHooks::Hook_LogPrint), false);
}
};</cpp>

=Manual Hooks=
In some cases, it may be necessary to support multiple, incompatible ABI branches of an interface. For example, suppose you need to hook an application that may supply either version of these interfaces:

Interface v1:
<cpp>
class Interface
{
public:
virtual void Function1() =0;
virtual bool Function2(int clam) =0;
};</cpp>

Interface v2:
<cpp>
class Interface
{
public:
virtual bool Function2(int clam) =0;
};</cpp>

Obviously, these two interfaces are backwards incompatible. Manual hooks allow you to precisely define the structure of the virtual table, bypassing the compiler's rules. These rules can be re-configured at runtime.

==Declaration==
Declaring a manual hook is similar to declaring a normal/simple hook. The syntax is:

<cpp>SH_DECL_MANUALHOOK<n>[_void](UniqueName, vtblIndex, vtblOffs, thisOffs, [return and param types])</cpp>

The <tt>UniqueName</tt> is a unique identifier for the hook. The <tt>vtblIndex</tt> is the index into the virtual table at which the function lies. In most compilers, this index starts from 0. The <tt>vtblOffs</tt> and <tt>thisOffs</tt> fields are used for multiple inheritance and are almost always 0 in modern compiler single inheritance.

An example of hooking the two functions from the first interface version:
<cpp>SH_DECL_MANUALHOOK0_void(MHook_Function1, 0, 0, 0);
SH_DECL_MANUALHOOK1(MHook_Function2, 1, 0, 0, bool, int);</cpp>

==Reconfiguring==
A manual hook can be ''reconfigured'', which will update its set offsets. Reconfiguration automatically removes all hooks on the manual hook. Let's say we want to reconfigure the <tt>Function2</tt> hook in the case of the second version being detected:

<cpp>
void SwitchToNewerHooks()
{
SH_MANUALHOOK_RECONFIGURE(MHook_Function2, 0, 0, 0);
}
</cpp>

Note that the hook was referenced by its unique identifier.

==Adding Hooks==
Adding or removing hook binds is done via the following extra macros:
*<tt>SH_ADD_MANUALHOOK</tt>
*<tt>SH_REMOVE_MANUALHOOK</tt>

These work similar to the original functions. Example:
<cpp>extern Interface *iface;

bool Hook_Function2(int clam)
{
RETURN_META_VALUE(MRES_IGNORED, false);
}

void StartHooks()
{
SH_ADD_MANUALHOOK(MHook_Function2, iface, SH_STATIC(Hook_Function2), false);
}

void StopHooks()
{
SH_REMOVE_MANUALHOOK(MHook_Function2, iface, SH_STATIC(Hook_Function2), false);
}</cpp>

Similarly, a member function version would use <tt>SH_MEMBER</tt> instead.

=Extended Removal Syntax=
The syntax described in the above sections is new as of SourceHook v4.5. <tt>SH_REMOVE_HOOK</tt> is, for all intents and purposes, optional. There is another way to remove hooks.

Each <tt>SH_ADD</tt> macro returns a non-zero <tt>int</tt> on success. The same integer can be passed to the <tt>SH_REMOVE_HOOK_ID</tt> macro, and the hook will be removed. This alternate removal syntax can simplify code that uses multiple successive or dynamic hooks.

Global hooks, described in a later section, require usage of <tt>SH_REMOVE_HOOK_ID</tt> - that is, there is no helper macro to simplify removing a global hook.

=Old Macros=
SourceHook v5.0 deprecates older macros that were used in earlier versions. The macros are:
*<tt>SH_ADD_HOOK_STATICFUNC</tt> - Wrapper for <tt>SH_ADD_HOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_REMOVE_HOOK_STATICFUNC</tt> - Wrapper for <tt>SH_REMOVE_HOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_ADD_HOOK_MEMFUNC</tt> - Wrapper for <tt>SH_ADD_HOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_REMOVE_HOOK_MEMFUNC</tt> - Wrapper for <tt>SH_REMOVE_HOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_ADD_MANUALHOOK_STATICFUNC</tt> - Wrapper for <tt>SH_ADD_MANUALHOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_REMOVE_MANUALHOOK_STATICFUNC</tt> - Wrapper for <tt>SH_REMOVE_MANUALHOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_ADD_MANUALHOOK_MEMFUNC</tt> - Wrapper for <tt>SH_ADD_MANUALHOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_REMOVE_MANUALHOOK_MEMFUNC</tt> - Wrapper for <tt>SH_REMOVE_MANUALHOOK</tt> and <tt>SH_MEMBER</tt>.

These macros are fairly self explanatory. The parameter where the <tt>SH_STATIC</tt> or <tt>SH_MEMBER</tt> macro would normally go is instead filled with the parameters to that macro.

This syntax is considered deprecated, but it is still supported. Code written with these macros will continue to compile against older SourceHook versions. If you are writing a plugin which must work against Metamod:Source 1.4 and 1.6, you will want to use the older macros for simplicity.

=Global Hooks=
<b>Note:</b> Global Hooks are only available in SourceHook v4.5 or later.

Global hooks are unlike normal hooks in that the hook is invoked for ALL instances, rather than solely the given the instance the hook was bound to. It is important to realize that this feature can be deceiving. Consider the following example:

<cpp>
class CBaseEntity
{
public:
virtual void SetHealth(int health) =0;
};

class CBaseCat : public CBaseEntity
{
public:
virtual void SetHealth();
};

class CBaseKitten : public CBaseCat
{
public:
virtual void SetHealth();
};</cpp>

In this example, <tt>CBaseCat</tt> and <tt>CBaseKitten</tt> instances have ''separate virtual tables''. Although they both derive from <tt>CBaseEntity</tt>, they are separate virtual objects. <b>Therefore, a global hook on <tt>CBaseEntity</tt> will receive no invocations, and a hook on <tt>CBaseCat</tt> will receive only <tt>CBaseCat</tt> instances, as long as the instance is not a class derived from <tt>CBaseCat</tt></b>.

With this understanding in place, there are two separate syntaxes - one for simple hooks and one for manual hooks. Additionally, there are two ways of declaring the virtual interface to use:
*An instance of the class can be passed.
*The direct address to the virtual table can be passed.

They are essentially equivalent, although one may be more advantageous than the other (for example, if no instances are known, but the vtable address can be extracted via pattern searching).

It is also important to note that global hooks are just a different method of "filtering." They fall into either the "simple" or "manual" category, and are otherwise exactly the same to those hooks. Thus there are no separate return/declaration macros for global hooks.

The macro <tt>META_IFACEPTR</tt> is especially useful for global hooks. See [[SourceHook_Development#Interface_Pointers_from_Hooks|Interface Pointers from Hooks]] near the end.

Lastly, global hooks exclusively use the extended hooking syntax. That means there exists only <tt>SH_ADD</tt> macros. <tt>SH_HOOK_REMOVE_ID</tt> must be used and the hook ID generated via <tt>SH_ADD</tt> must be cached.

All examples will use the following code as a basis:
<cpp>
class Player
{
public:
virtual void TakeDamage(int damage) =0;
};

void Hook_TakeDamage(int damage);
</cpp>

==Simple Hooks==
Two extra macros exist for adding a global hook:

<cpp>
SH_ADD_VPHOOK(Interface, Function, Instance, Handler, Post)
SH_ADD_DVPHOOK(Interface, Function, VirtualTable, Handler, Post)
</cpp>

An example:
<cpp>
extern void *player_vtable;
HookId takedamage_hook = 0;

void StartHooks()
{
takedamage_hook = SH_ADD_DVPHOOK(Player, TakeDamage, player_vtable, SH_STATIC(Hook_TakeDamage), false);
}

void StopHooks()
{
if (takedamage_hook)
{
SH_REMOVE_HOOK_ID(takedamage_hook);
}
}</cpp>

==Manual Hooks==
Similarly, manual hooks are straightforward:
<cpp>
SH_DECL_MANUALHOOK1_void(MHook_TakeDamage, 0, 0, 0, int);

extern void *player_vtable;
int takedamage_hook = 0;

void StartHooks()
{
takedamage_hook = SH_ADD_MANUALDVPHOOK(MHook_TakeDamage, player_vtable, SH_STATIC(Hook_TakeDamage), false);
}

void StopHooks()
{
if (takedamage_hook)
{
SH_REMOVE_HOOK_ID(takedamage_hook);
}
}</cpp>

=Modifying Parameters=
Consider another variation of the hooking process. There is a hook on function X, which has one parameter. The hook wants to change the value of this parameter transparently. For example:
*Caller passes 5 into X.
*Hook changes the 5 to a 6.
*Hooked function receives a 6 and continues normally.

SourceHook has a method for achieving this. As an added bonus, the new parameters are passed to subsequent hooks. That means the replacement process is as transparent as possible. For this example, we'll use the following code, with an assumed hook on <tt>Player::TakeDamage</tt> to the <tt>Hook_TakeDamage</tt> function.

<cpp>
class Player
{
public:
virtual void TakeDamage(int damage);
};

void Hook_TakeDamage(int damage);</cpp>

Our objective is to multiply the damage by 2.

==Simple Hooks==
For simple hooks, changing parameters looks similar to an <tt>SH_CALL</tt>. The macros are:

<cpp>RETURN_META_NEWPARAMS(Action, HookFunction, ([params]))
RETURN_META_VALUE_NEWPARAMS(Action, Value, HookFunction, ([params]))
</cpp>

Example:
<cpp>
void Hook_TakeDamage(int damage)
{
RETURN_META_NEWPARAMS(MRES_IGNORED, &Player::TakeDamage, (damage * 2));
}</cpp>

Note that the parenthesis enclosing the parameters are required.

==Manual Hooks==
Manual hooks require slightly different macros. They are:

<cpp>RETURN_META_MNEWPARAMS(Action, UniqueName, ([params]));
RETURN_META_VALUE_MNEWPARAMS(Action, Value, UniqueName, ([params]));</cpp>

Example:
<cpp>
SH_DECL_MANUALHOOK1_void(MHook_Player_TakeDamage, 0, 0, 0, int);

void Hook_TakeDamage(int damage)
{
RETURN_META_MNEWPARAMS(MRES_IGNORED, MHook_Player_TakeDamage, (damage *2));
}</cpp>

Note that the parenthesis enclosing the parameters are required.

=Bypassing Hooks=
Often, either to avoid certain functionality or to avoid infinite recursion, it is necessary to bypass all hooks on a hooked function, such that only the original function is called. For instance, a previous blocked certain messages sent through <tt>LogPrint</tt>. In order to send that message, the hook needs to be bypassed.

To way to do this is to use the <tt>SH_CALL</tt> macro:
<cpp>SH_CALL(Instance, HookFunction)(params)</cpp>

Example:
<cpp>SH_CALL(engine, &IVEngineServer::LogPrint)("Secret Message");</cpp>

Similarly, manual hooks have <tt>SH_MCALL</tt>:

<cpp>SH_DECL_MANUALHOOK1(MHook_Function2, 1, 0, 0, bool, int);

bool Function2_Bypass(int clam)
{
return SH_MCALL(iface, MHook_Function2)(clam);
}</cpp>

==Deprecated Syntax==
The syntax described above is used in SourceHook v5.0 and v4.5. An older syntax, using a "CallClass" data type, was used in SourceHook v4.4 and lower. This syntax was deprecated in v4.5 and completely removed in v5.0. Upgrading from SourceHook v4.4 means that code referencing <tt>SH_GET_CALLCLASS</tt> or <tt>SH_REMOVE_CALLCLASS</tt> must be removed, and <tt>SH_CALL</tt> simply needs an instance pointer instead.

=Other Macros=
SourceHook contains a large variety of extra macros. This section is a grab bag of the more commonly used ones.

==Interface Pointers from Hooks==
Let's say you have the following hook:

<cpp>class Player
{
public:
virtual void TakeDamage(int damage);
float GetDamageModifier();
};

void Hook_TakeDamage(int damage);
</cpp>

How can you get the <tt>Player</tt> instance while in the hook? This can be achieved via the <tt>META_IFACEPTR</tt> macro. Example:

<cpp>void Hook_TakeDamage(int damage)
{
Player *pPlayer = META_IFACEPTR(Player);

int new_damage = (int)((pPlayer->GetDamageModifier() + 0.3) * (float)damage);

RETURN_META_NEWPARAMS(MRES_IGNORED, &Player::TakeDamage, (new_damage));
}</cpp>

Note that the class name should be passed to <tt>META_IFACEPTR</tt>, not the pointer type.

==Ignoring Reference Returns==
There is a special macro, <tt>RETURN_META_NOREF</tt>, for ignoring a return value for reference-returning functions. Example:

<cpp>
class ISomething
{
public:
virtual int & GetSomething() =0;
};

int & Hook_GetSomething()
{
RETURN_META_NOREF(MRES_IGNORED, int &);
}</cpp>

=Automatic hookmanager generation=
Normally, the SH_DECL_ macros generate a so-called "hook manager", a function which is invoked instead of the original function and then calls the hooks and processes their return and <tt>META_RES</tt> values.

It is also possible to let SourceHook auto-generate the hook manager. This is neccessary if the function prototype is unknown at compile time (for example if hooks can be defined from third-party plugins of your plugin).

Example Usage from a Metamod:Source plugin:
<cpp>
#include "sourcehook_pibuilder.h"

// We want to hook a void (int, float) function

// Request IHookManagerAutoGen interface
SourceHook::IHookManagerAutoGen *hmag =
static_cast<SourceHook::IHookManagerAutoGen *>(ismm->MetaFactory(MMIFACE_SH_HOOKMANAUTOGEN, NULL, NULL));

// (check for hmag == NULL)

// Build prototype information (using CProtoInfoBuilder helper class).
SourceHook::CProtoInfoBuilder protoInfo(SourceHook::ProtoInfo::CallConv_ThisCall);
protoInfo.AddParam(sizeof(int), SourceHook::PassInfo::PassType_Basic, SourceHook::PassInfo::PassFlag_ByVal,
NULL, NULL, NULL, NULL);
protoInfo.AddParam(sizeof(float), SourceHook::PassInfo::PassType_Float, SourceHook::PassInfo::PassFlag_ByVal,
NULL, NULL, NULL, NULL);

// Generate the hook manager
HookManagerPubFunc generatedHookMan = hmag->MakeHookMan(protoInfo, 0 /* vtable offset */, 0 /* vtable index */);

// Add the hook
int hookid = g_SHPtr->AddHook(g_PLID, SourceHook::ISourceHook::Hook_Normal/Hook_VP/Hook_DVP, iface_ptr, thisptr_offs,
generatedHookMan, handler, post);

// ... (use the hook)

// After you're done using the hook (cleanup)
// Remove the hook
g_SHPtr->RemoveHookByID(hookid);

// Release hook manager
hmag->ReleaseHookMan(generatedHookMan);
</cpp>
<tt>CProtoInfoBuilder::AddParam</tt> has 7 parameters:
* size: size of the type. This is sizeof(type) even if it is passed by reference!
* passtype: this can be PassType_Basic for integer types (char/short/int/...), PassType_Float for floating-point types (float/double) and PassType_Object for unions, structs and classes.
* passflags: flags. Has to contain either PassFlag_ByVal or PassFlag_ByRef.
* pNormalCtor: for PassType_Object, set this to the pointer to the user-defined default constructor of the object, if it has one.
* pCCtor: for PassType_Object, set this to the pointer to the user-defined copy constructor of the object, if it has one.
* pODtor: for PassType_Object, set this to the pointer to the user-defined destructor of the object, if it has one.
* pAssignOperator: for PassType_Object, set this to the pointer to the user-defined assignment operator of the object, if it has one.

If you are hooking a non-void function, also call <tt>CProtoInfoBuilder::SetReturnType</tt>. It has the same arguments as <tt>AddParam</tt>.

The <tt>handler</tt> parameter of <tt>ISourceHook::AddHook</tt> is a pointer to the ISHDelegate interface.
In C++, you construct ISHDelegates like this:
<cpp>
class MyDelegate : public SourceHook::ISHDelegate
{
public:
// vtable index 0
virtual bool IsEqual(ISHDelegate *pOtherDeleg)
{
// pOtherDeleg is guaranteed to be from the same plugin.
// This function is only used for compat with the old SH_REMOVE_HOOK method.
// if you don't want to use that with your hooks, you can simply return false here.
// if for some reason you need it, a good idea could be comparing the vtable pointer:
return *reinterpret_cast<void**>(this) == *reinterpret_cast<void**>(pOtherDeleg);

// But in general I'd just return false!
}

// vtable index 1
virtual void DeleteThis()
{
delete this; // Called from SourceHook when this instance is not needed
// and should be deleted.
}

// vtable index 2
virtual ret_type Call(params)
{
// your code.
// SH_DECL_ macros pass execution to the actual user's handler through a FastDelegate
// which is stored as a member variable of the delegate class.
}
};
</cpp>

The first parameter of the CProtoInfoBuilder constructor (see example code above) is the calling convention in an extended sense. At the moment it can be either CallConv_ThisCall or (CallConv_ThisCall | CallConv_HasVafmt). The second value means that the function has printf-like string formatting. Then, the finaly ''const char *, ...'' arguments will be added automatically, and the Deleagte::Call method should have one more parameter: ''const char *formattedString''.

pNormalCtor/pCCtor/pODtor/pAssignOperator should be found using offsets / sigscanning. If you are a C++ plugin and know the type at compile time, you can also use the following class:
<cpp>
// Address of constructor/destructor
// (using wrappers)
template <class T>
class Ctor_Thunk
{
public:
void NormalConstructor()
{
new(this) T;
}

void CopyConstructor(const T &other)
{
new(this) T(other);
}

void Destructor()
{
reinterpret_cast<T*>(this)->~T();
}

const T& AssignOp(const T &other)
{
return (*reinterpret_cast<T*>(this) = other);
}
};

template <class T>
void *FindFuncAddr(T mfp)
{
union
{
T a;
void *b;
} u;
u.a = mfp;
return u.b;
}

// Usage:
FindFuncAddr(&Ctor_Thunk<type>::NormalConstructor)
// (if the type is a reference type, use it without & here)
</cpp>

=Embedding=
Embedding SourceHook in your own application or library is very easy. The <tt>sourcehook.cpp</tt> file must be compiled or linked into your project. To instantiate the SourceHook engine, you must create a <tt>CSourceHookImpl</tt> instance. Example:

<cpp>
/* Normally, just <sourcehook.h> is included, but this is needed to instantiate the engine. */
#include <sourcehook/sourcehook_impl.h>

SourceHook::Impl::CSourceHookImpl g_SourceHook;
</cpp>

To actually use SourceHook, it is necessary to have two global variables:
*<tt>g_PLID</tt> - A unique integer that identifies the library using SourceHook. This is used for removing all hooks a library is using.
*<tt>g_SHPtr</tt> - A pointer to the <tt>SourceHook::ISourceHook</tt> interface.

Example header file:
<cpp>
#include <sourcehook/sourcehook.h>

extern SourceHook::ISourceHook *g_SHPtr;
extern int g_PLID;</cpp>

Example addition to the global code:
<cpp>
SourceHook::ISourceHook *g_SHPtr = &g_SourceHook;
int g_PLID = 0;</cpp>

==Multiple Libraries/Shared Hooks==
If SourceHook is going to be used across multiple libraries in the same process, it is essential that only one instance of SourceHook be present. Of course, that is only logical, since otherwise the instances would be replacing each other's virtual patches.

In order to support this, each separate library must be given the <tt>ISourceHook</tt> pointer and a unique <tt>g_PLID</tt> value. <tt>CSourceHookImpl</tt> provides a few useful functions for managing hooks on "child" libraries or otherwise linked code.

*<tt>PausePlugin()</tt> - Silences any hooks from an ID, such that those hooks will not be called.
*<tt>UnpausePlugin()</tt> - Un-silences any silenced hooks from an ID.
*<tt>UnloadPlugin()</tt> - Clean-up any left-over hooks from an ID.

[[Category:Metamod:Source Development]]
[[Category:SourceHook]]

Category:SourceHook

2024-06-12T22:09:12Z

Mooshua: Recategorize

SourceHook is Metamod's built in virtual hooking and conflict mediation library. SourceHook is used by plugins to instrument and modify game code without causing compatibility issues for other plugins.

[[Category:Metamod:Source Development]]

Installing Metamod:Source

2024-06-09T16:30:20Z

Mooshua: /* Source 2 */ add some notes to the instructions

This article will guide you through a [[Metamod:Source]] installation.

=Normal Installation=

''Not applicable for Source 2. See GameInfo section below''

Valve sometimes makes changes in their games that break Metamod:Source between releases. When this happens, you may need to install a snapshot versions of Metamod:Source. You can see if this is required on the [[Required Versions (SourceMod)|Required Versions]] page.

<ol>
<li>[http://www.metamodsource.net/ Download] Metamod:Source.</li>
<li>Extract the package to your game folder. For example, for Counter-Strike:Source, you would have <code>cstrike/addons/metamod</code> after extracting. If you are uploading to FTP, extract the files locally before transferring to your server's game folder.</li>
<li>Restart your server.</li>
<li>Type "meta version" in your server console (or RCon). You should see a line like: "Loaded As: Valve Server Plugin." If the command is not recognized, see the sections below.</li>
</ol>

When using a Linux server, you may see the following messages:

* An error indicating that it could not be loaded due to "wrong ELF class: ELFCLASS64". If you are using a 32-bit dedicated server installation, this is normal behavior; as long as <code>meta version</code> is recognized, Metamod:Source is installed.
* An error indicating that it could not be loaded because "/path/to/server_install/bin/libgcc_s.so.1: version `GCC_7.0.0` not found (required by /some_system_path_to/libstdc++.so.6". This is because Valve ships their own copies of those libraries. As modern systems will have newer versions, you can safely delete the listed file from the server install. Do not delete the file in the system path (usually <code>lib</code> or <code>lib32</code>).
* If you are running a 64-bit operating system yourself, you may need to install the system's 32-bit libraries.
** On Debian / Ubuntu, you can do this with <code>apt install gcc-multilib</code>.
* You may find more information about any load failures under a <code>metamod-fatal.log</code> in metamod's <code>bin</code> folder.

==Custom VDF File==
'''Note: This is normally not needed - Metamod:Source 1.10.0 and later include a <code>metamod.vdf</code> file for easier installation on most games.'''

If you have trouble getting it to load, [http://www.metamodsource.net/?go=vdf go here] to generate a VDF file specific to your game. This file should be placed into your server's <code>addons</code> directory.

Known setups that require this step:
<ol>
<li>Left 4 Dead 1</li>
<li>3rd party mods using the Source SDK Base.</li>
<li>Listen servers (created with the in-game "Create Server" option) for non-english game clients.</li>
</ol>

=Adjust gameinfo file=

'''Adjusting gameinfo for Source 1 is normally not needed. If you do not understand what this is, do NOT do this unless instructed to. The above instructions are sufficient to install Metamod:Source for 99% of servers. For Source 2, this is, however, the only supported loading method. See [[#Source_2|Source 2]] for more info.'''

==Source 1==
Metamod:Source 1.4.2 and lower used an older method for loading itself. The advantage of this method was that Metamod:Source could be loaded before the actual game mod, which gave it a small amount of extra functionality. This functionality was never used by plugin developers, and Steam updates kept overwriting <code>gameinfo</code> files, so we switched to a different loading mechanism.

However this loading mechanism may still be desirable if you run into backwards compatibility issues, or you have a plugin which takes advantage of the early-loading mechanism. If this is your case, here are the <code>gameinfo</code> directions below:

<ul>
<li>Open the file in the mod folder called <code>gameinfo.txt</code>. You will see a few lines at the bottom like this:
<pre>
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}
</pre></li>
<li>Add a line after the <code>{</code> sign but before all of the <code>Game</code> entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>If you're using Windows, you may need to use a backwards slash (\) instead.
<li>You're done! To test whether it worked, restart your game server and type <code>meta version</code> in the server console. You should see a line that says <code>Loaded as: GameDLL (gameinfo.txt)</code>.
If it doesn't recognize the command, the installation probably failed. If the <code>Loaded as:</code> line says something else, <code>gameinfo</code> was probably not modified correctly.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

==Source 2==
Source 2 does not have server plugins, so you will need to load Metamod the old-fashioned way: replacing the server library with Metamod's stub loader.

{{Sad|You will need to redo these changes every time a developer pushes a change that modifies gameinfo.gi}}

<ul>
<li>Open the file in the mod folder called <code>gameinfo.gi</code>. In CS2 this is <code>csgo/gameinfo.gi</code>.
<li>Note that even though it says <code>DO NOT EDIT THIS FILE DIRECTLY</code> and advises to edit <code>csgo_core/gameinfo.gi</code>, editing that file does not correctly load Metamod.
<li>Look for the <code>SearchPaths</code> section of code.
<li>Add a line after the <code>{</code> sign but before all of the <code>Game</code> entries that looks like this, replacing <code>csgo</code> (for CS2) with your game name found in lines beneath it:
<pre>Game csgo/addons/metamod</pre>
{{CommonMistake|Make sure the Metamod entry is the '''first''' in the searchpaths list! This list is ordered and placing it anywhere else will prevent Metamod from loading}}
<li>Using <code>GameBin</code> instead of <code>Game</code> does not work.
<li>In Windows, the backslash is no longer required for paths.</li>
<li>You're done! To test whether it worked, restart your game server and type <code>meta version</code> in the server console. You should see a line that says <code>Metamod:Source version 2.x.x</code>.
If it doesn't recognize the command, the installation probably failed. Try updating your game to the latest version and using the latest version of Source 2.</li>
<li>For more information or documentation, see [[:Category:Metamod:Source Documentation]]</li>
</ul>

[[Category:Metamod:Source Documentation]]

Events (SourceMod Scripting)

2024-05-19T19:57:08Z

Mooshua:

:''To view all the events, click [[Game Events (Source)|here]].''

Events are short, named messages sent by the server. Although they are used for internal message passing, they are also networked to clients.

Events are used for internal messages (such as when the server starts) and game events (such as when players take damage or spawn). Events are a simple way to hook events that SourceMod does not have dedicated support for, such as player spawns.
However, game events are '''mod-defined''', so you will need to ensure your behavior is correct for every mod you support, or you will have compatibility issues.

All event natives are found in <tt>scripting/include/events.inc</tt>.

=Introduction=
Events are documented in <tt>.res</tt> files under a mod's <tt>resource</tt> folder. The "default" events are located in <tt>hl2/resource/gameevents.res</tt> and <tt>hl2/resource/serverevents.res</tt>. Mods can extend these events with their own.

For example, let's look at <tt>player_death</tt> from <tt>hl2/resource/gameevents.res</tt>:
<pre>"player_death"
{
"userid" "short" // user ID who died
"attacker" "short" // user ID who killed
}</pre>

Counter-Strike:Source extends this definition in <tt>cstrike/resource/modevents.res</tt>:
<pre>"player_death"
{
"userid" "short" // user ID who died
"attacker" "short" // user ID who killed
"weapon" "string" // weapon name killer used
"headshot" "bool" // signals a headshot
}</pre>

Note that the event is structured in the following format:
<pre>"name"
{
"key1" "valueType1"
"key2" "valueType2"
...
}</pre>

=Sending Events=
Events are very easy to send. For example, let's say we want to send a death message using the <tt>player_death</tt> event from above. For Counter-Strike:Source, this would look like:

<sourcepawn>void SendDeathMessage(int attacker, int victim, const char[] weapon, bool headshot)
{
Event event = CreateEvent("player_death");
if (event == null)
{
return;
}

event.SetInt("userid", GetClientUserId(victim));
event.SetInt("attacker", GetClientUserId(attacker));
event.SetString("weapon", weapon);
event.SetBool("headshot", headshot);
event.Fire();
}</sourcepawn>

Notes:
*You don't need to call <tt>CloseHandle()</tt>, <tt>FireEvent()</tt> does this for us.
*Even though "userid" and "attacker" are shorts, we set them as ints. The term "short" is only used to tell the engine how many bytes of the integer are needed to be networked.
*It is possible for event creation to fail; this can happen if the event does not exist, or nothing is hooking the event. Thus, you should always make sure <tt>CreateEvent</tt> calls return a valid Event handle.
*Most events use client userids instead of client indexes.
*By default, <tt>FireEvent()</tt> broadcasts messages to clients. This can be prevented by passing <tt>dontBroadcast</tt> as true.

=Hooking Events=
When hooking an event, there are three modes to choose from:
*<tt>Pre</tt> - Hook the event before it is fired.
*<tt>Post</tt> - Hook the event after it is fired.
*<tt>Post_NoCopy</tt> - Hook the event, but do not save any of its information (special optimization).

Hooking an event is usually done for one of the following goals. To get an idea of which mode to use, see the list below each goal:
*Blocking the event (preventing it from being fired)
**'''Always <tt>Pre</tt>'''
*Rewriting the event (changing its parameters)
**'''Always <tt>Pre</tt>'''
*Acting upon the event (doing something once the event is completed)
**'''<tt>Pre</tt>''' if your action must come before the mod's action.
**'''<tt>Post</tt>''' if your action must come after the mod's action.
**'''<tt>PostNoCopy</tt>''' if your action is <tt>Post</tt> and only requires the event name.

As always, you do not need to unhook events when your plugin unloads. They are automatically removed.

==Blocking Events==
Blocking events is the easiest thing to do. Let's say we want to block death events that are headshots:

<sourcepawn>public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath, EventHookMode_Pre);
}

public Action Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
if (event.GetBool("headshot"))
{
return Plugin_Handled;
}
return Plugin_Continue;
}</sourcepawn>

{{CommonMistake|Blocking an event only blocks other parts of the game from receiving the event; the source of the event may still take action (such as by damaging players)!}}

==Rewriting Events==
Rewriting events is just as easy -- events can be modified in pre hooks. For example, say we want to remove headshots from all events:

<sourcepawn>public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath, EventHookMode_Pre);
}

public Action Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
event.SetBool("headshot", false);
return Plugin_Continue;
}</sourcepawn>

==Post Hooks==
{{CommonMistake|Post hooks run after the game has handled the event, but the event source may still take action after the event has finished!
This is a potentially sneaky source of recursion and stack overflow crashes, so watch out!
}}
Post hooks are default, and will usually be the most common usage. For example, say we want to print a message to every client that dies:

<sourcepawn>public void OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath);
}

public void Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
char weapon[64];
int victimId = event.GetInt("userid");
int attackerId = event.GetInt("attacker");
bool headshot = event.GetBool("headshot");
event.GetString("weapon", weapon, sizeof(weapon));

char name[64];
int victim = GetClientOfUserId(victimId);
int attacker = GetClientOfUserId(attackerId);
GetClientName(attacker, name, sizeof(name));

PrintToConsole(victim,
"You were killed by \"%s\" (weapon \"%s\") (headshot \"%d\")",
name,
weapon,
headshot);
}</sourcepawn>

This will print a message to a player's console telling them who killed them, with what weapon, and whether it was a headshot or not.

Note that the return value for post hooks is ignored, so the <tt>Action</tt> tag is not needed.

==PostNoCopy Hooks==
Lastly, there are some hooks where the only piece of information needed is the name of the event. <tt>PostNoCopy</tt> is a special optimization for this case. When transitioning from <tt>Pre</tt> to <tt>Post</tt>, SourceMod must duplicate the event and all of its key/value pairs. <tt>PostNoCopy</tt> prevents that sequence from happening.

For example, let's say we want to find when a certain sequence of events is called.

<sourcepawn>public void OnPluginStart()
{
HookEvent("game_newmap", GameEvents, EventHookMode_PostNoCopy);
HookEvent("game_start", GameEvents, EventHookMode_PostNoCopy);
HookEvent("game_end", GameEvents, EventHookMode_PostNoCopy);
HookEvent("game_message", GameEvents, EventHookMode_PostNoCopy);
}

public void GameEvents(Event event, const char[] name, bool dontBroadcast)
{
PrintToServer("Event has been fired (event \"%s\") (nobcast \"%d\")", name, dontBroadcast);
}</sourcepawn>

Note that like normal <tt>Post</tt> hooks, there is no return value needed. However, the <tt>event</tt> parameter for <tt>PostNoCopy</tt> will '''always''' be equal to <tt>null</tt>. Thus, the <tt>name</tt> parameter must be used instead of <tt>event.GetName</tt>.

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Template:Sad

2024-05-19T19:44:42Z

Mooshua: Created page with "<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: grey; border-style:solid;"> alt= <span style="display:table-..."

<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: grey; border-style:solid;">
[[File:sadness.png|frameless|32px|left|link=|alt=]]
<span style="display:table-cell">
{{{1}}}
</span>
</div>

File:Sadness.png

2024-05-19T19:44:25Z

Mooshua: A sad little flork. This image will be used in templates when features have been removed or when other sad things occur that require extra work from developers.

== Summary ==
A sad little flork.

This image will be used in templates when features have been removed or when other sad things occur that require extra work from developers.

Vectors Explained (Scripting)

2024-05-19T19:41:30Z

Mooshua:

=Introduction=
Vectors in general tend to be rather confusing until they are explained. There are three different types you will see. Position Vectors, Velocity Vectors, and Angle Vectors. While in most basic cases you will probably only use one of these at a time, it doesn't hurt to know what the other two parameters are there for. Here is an example of the native 'TeleportEntity' to show you what it looks like:

<pawn>
native int TeleportEntity(int entity, const float origin[3], const float angles[3], const float velocity[3]);
</pawn>

=== Positions ===
'''Position Vector''': The first Vector in this native, declared as origin[3], is the Position Vector. This simply tells us the entities absolute position in the world. The position vector could look something like {15.0, 30.0, 15.0} and this would mean the entity is 15 units along the X axis, 30 units along the Y axis, and 15 units along the Z axis.

=== Angles ===
'''Angles''' specify the ''angles'' of the rotation, not the actual vector of the rotation! (Essentially, it's an arctangent of each direction component.)
Angles are specified as <code>{pitch/up, yaw/left, roll/spin}}</code>. Angles are specified as a `float[3]` array.
Angles can be turned into a vector (and back into an angle!) using the angle natives: <code>GetAngleVectors</code> and <code>GetVectorAngles</code>.

Most angles are sanitized between -180 and 180 within the source engine (for up/down on players this is -89/89!), however some weird physics shenanigans and cheating clients can exceed these values so always ensure your angles are well formed before using them.

{{CommonMistake|Make sure to use <code>GetAngleVectors</code> before using the angles value to transform world space!}}

=== Velocity ===
'''Velocity''', or a '''Vector''', is a true vector in the sense that it is ''only a direction and magnitude''. The velocity represents motion, usually the amount of motion that will occur in one tick. The position of an object on the next tick will be the sum of the current position and the object's velocity.

==Velocity Vectors==
<pawn>
float vecOrigin[3], vecVelocity[3], vecResult[3];

AddVectors(vecOrigin, vecVelocity, vecResult);
</pawn>

Template:CommonMistake

2024-05-19T19:36:33Z

Mooshua: Remove documentation :(

Template:CommonMistake

2024-05-19T19:29:05Z

Mooshua: Add {{CommonMistake}}

<div style="padding: 0.75em 1.5em; border-width: 2px; border-color: grey; border-style:solid;">
[[File:silly_goose.png|frameless|32px|left|link=|alt=]]
<span style="display:table-cell">
{{{1}}}
</span>
</div>

{{documentation|content=
If you see people making a mistake a lot, document it with a common mistake!

{{CommonMistake| Did you make sure to put the key in the ignition first?}}
{{CommonMistake| Don't touch that dial! We'll be right back after this message from our sponsors}}
}}

File:Silly goose.png

2024-05-19T19:22:29Z

Mooshua: Are you a silly little goose? This image will be used in templates to explain common mistakes. It's just a little charm :)

== Summary ==
Are you a silly little goose?

This image will be used in templates to explain common mistakes. It's just a little charm :)

SDKHooks

2024-05-10T05:37:54Z

Mooshua: Add sourcemod scripting category

==Introduction==
SDKHooks was previously an external extension to Sourcemod. It was rolled in [https://wiki.alliedmods.net/Sourcemod_1.5.0_API_Changes#SDKHooks Sourcemod 1.5] and it does not need to be manually installed anymore.

==Hooks==
Some information on various hooks below.

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

===SDKHook_OnTakeDamageAlive===
This hook works in a similar way to SDKHook_OnTakeDamage but it gives the [https://bugs.alliedmods.net/show_bug.cgi?id=6249#c7 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}}

[https://forums.alliedmods.net/showthread.php?p=2309798#post2309798 OnTakeDamageAlive is also only called for players.]

==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

[[Category:SourceMod Scripting]]

SourceHook Development

2024-05-10T05:36:13Z

Mooshua: Add metamod-dev category

SourceHook is a powerful API (Application Programming Interface) for detouring (hooking) virtual functions. Unlike static detours, SourceHook needs only to swap addresses in and out of an object's virtual table. This makes it fast and generally very platform-safe.

SourceHook is coupled with Don Clugston's [http://www.codeproject.com/cpp/FastDelegate.asp FastDelegate] headers. Virtual hooks can be detoured to any static function of the same prototype, or any member function (of any class) as long as the prototype matches.

All code in SourceHook is part of the SourceHook namespace. Thus, it may be prudent to declare this before using SourceHook structures or types:

<cpp>using namespace SourceHook;</cpp>

=Simple Hooks=
SourceHook has the following steps of operation:

* Declare the prototype of the function you are going to hook. This generates compile-time code that is able to pinpoint exactly how to go about hooking the function.
* Hook the function - as a member function of another class or a regular static function.
* Before the hooked function is called, all of the "pre" hook handlers attached to it are called. Each hook can set a special flag, the highest of which is chosen as a final operation. This flag specifies whether the original function should be called or not.
* Once all the hooks have been called, SourceHook decides whether to call the original function. Another set of hooks are called directly after, called "post" hook handlers. You can specify whether each hook is a post or pre hook - it simply changes whether it's called before or after the original call is made.
* After you are done using a hook, you must safely remove it before the object is destroyed (otherwise, memory will be leaked).

==Declaration==
As an example, take the following class prototype:
<cpp>
class IVEngineServer
{
public:
/*...*/
virtual void LogPrint( const char *msg ) = 0;
virtual bool IsDedicated() = 0;
};

extern IVEngineServer *engine;
</cpp>

The first step is to figure out how to declare its prototype to SourceHook. This function is void, and has one parameter. The declaration macro follows these formats:

*{{bcode|SH_DECL_HOOK}}n - n is the number of parameters
**The parameters are: Class name, member function name, attributes, overloaded?, the return type, and a list of the parameter types.
*{{bcode|SH_DECL_HOOKn_void}} - n is the number of parameters
**_void specifies that the function does not return a value. The format is the same as above except the "return type" parameter is missing.
*'''Note:''' Not covered here are the SH_DECL_HOOKn[_void]_vafmt hooks. These can hook string-formattable variable argument lists. You do not pass the string format or ellipses parameter. SourceHook will automatically format the string for your hook.

Our macro will look like this:
<pre>
SH_DECL_HOOK1_void(IVEngineServer, LogPrint, SH_NOATTRIB, 0, const char *);
SH_DECL_HOOK0(IVEngineServer, IsDedicated, SH_NOATTRIB, 0, bool);
</pre>

Broken down for the first line:
*There is 1 parameter.
*The function has no return value.
*<tt>IVEngineServer</tt> is the class containing the function.
*<tt>LogPrint</tt> is the function being hooked.
*The function as no attributes (for example, it is not const).
*The function is not overloaded.
*The first (and only) argument is a <tt>const char *</tt>

The second line is similar, except the parameter immediately after the overload parameter specifies the return type. There are no further parameters since it was declared with 0.

==Getting an Interface Instance==

Before you can use an interface, you need to retrieve an instance of it. This is done with either the <tt>GET_V_IFACE_ANY</tt> or <tt>GET_V_IFACE_CURRENT</tt> macros. Both take the same arguments. <tt>GET_V_IFACE_CURRENT</tt> is recommended if it works. <tt>GET_V_IFACE_ANY</tt> should also work, but may be missing newer functionality.

Normally this initialization needs to be done when your MM:S plugin or SourceMod Extension starts.

You also need to know which factory produces the interface you need. There are only 4 factories: <tt>GetEngineFactory</tt>, <tt>GetServerFactory</tt>, <tt>GetPhysicsFactory</tt>, and <tt>GetFilesystemFactory</tt>. Normally you'll want Engine or Server.

You'll also need to know the constant that the game uses for that particular class. This is usually found in the hl2sdk for your game. In the case of <tt>IVEngineServer</tt>, this is <tt>INTERFACEVERSION_VENGINESERVER</tt> located in public/eiface.h.

So, to retrieve the Interface so you can do something with it, it'd look something like this:
<pre>
IVEngineServer *engine;

// For SourceMod, use the first signature
//bool MyExtension::OnMetamodLoad(ISmmAPI *ismm, char *error, size_t maxlen, bool late)
bool MyPlugin::Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlen, bool late)
{
GET_V_IFACE_CURRENT(GetEngineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);
}
</pre>

The error and maxlen arguments '''must''' be named error and maxlen respectively, or else certain macros will fail.

Note that MyPlugin should be replaced with your plugin's class.

==Hook Functions==
Hooks can be declared either ''pre'' or ''post''. A ''pre'' hook will intercept the original function before it is called. Pre-hooks can return one of four ''hook actions'':
*<tt>MRES_IGNORED</tt> - The original function will be called.
*<tt>MRES_HANDLED</tt> - Same as <tt>MRES_IGNORED</tt>, except subsequent hooks can assume this means something important was changed.
*<tt>MRES_OVERRIDE</tt> - The original function will be called, but the new return value will be used instead of the one from the original function.
*<tt>MRES_SUPERCEDE</tt> - The original function will not be called. The new return value (if any) will be used instead.

These enum constants are defined in <tt><sourcehook.h></tt>, and are made available to Metamod:Source plugin developers via <tt><ISmmPlugin.h></tt>.

Once all pre-hooks have been processed, SourceHook takes an action based on the "highest" hook action returned (<tt>MRES_IGNORED</tt> being lowest, <tt>MRES_SUPERCEDE</tt> being highest). Once the action has been processed, all ''post'' hooks are called. That is to say, even if the original function is never called, post hooks are still processed. Because a post hook as no chance at true interception, it is important to realize that depending on the information being detoured, the data may be modified or destroyed. Similarly, a post hook's returned action and value is ignored.

A hook's action is signalled via one of two macros:
*<tt>RETURN_META</tt> - Only usable from <tt>void</tt> functions. Signals the action to take, then returns.
*<tt>RETURN_META_VALUE</tt> - Only usable from non-<tt>void</tt> functions. Signals the action to take, then returns the supplied value.

There are two methods of adding or removing hooks. Hooks can be bound to '''static''' or '''member''' functions. Both have a similar syntax. Their macros are:
*<tt>SH_STATIC(Function)</tt> - Hook to a static function.
*<tt>SH_MEMBER(Instance, Function)</tt> - Hook to a member function.

<b>It is important to realize that a simple hook will only be invoked when used on the same instance.</b> That is to say, if there are 500 instances of object X, and a hook is added to function X::Y in instance #8, then the hook will only be invoked from instance #8. <b>Multiple hooks can be declared on the same instance, and multiple instances can be bound to the same hook, but one hook will only be invoked for the instances it was hooked to.</b>

To have hooks that work across all instances, and thus do not need to be delegated per-instance, see the "Global Hooks" section. As of SourceHook v5, it is safe to remove hooks on a destroyed instance, as the instance is not actually dereferenced. However, its virtual table must still be accessible.

==Adding Hooks==
The macro to add hooks is <tt>SH_[ADD|REMOVE]_HOOK</tt>. The syntax is:

<cpp>SH_[ADD|REMOVE]_HOOK(Interface, Function, Instance, Hook, [post? true,false])</cpp>

An example of adding a <tt>LogPrint</tt> hook:
<cpp>void Hook_LogPrint(const char *msg)
{
if (strcmp(msg, "If this string matches the function will be blocked") == 0)
{
RETURN_META(MRES_SUPERCEDE);
}

/* Not needed, but good style */
RETURN_META(MRES_IGNORED);
}

void StartHooks()
{
log_hook = SH_ADD_HOOK(IVEngineServer, LogPrint, engine, SH_STATIC(Hook_LogPrint), false);
}

void StopHooks()
{
SH_REMOVE_HOOK(IVEngineServer, LogPrint, engine, SH_STATIC(Hook_LogPrint), false);
}</cpp>

The syntax is similar for hooking to member functions. Example equivalent to the above:
<cpp>
class MyHooks
{
public:
void Hook_LogPrint(const char *msg)
{
if (strcmp(msg, "If this string matches the function will be blocked") == 0)
{
RETURN_META(MRES_SUPERCEDE);
}

/* Not needed, but good style */
RETURN_META(MRES_IGNORED);
}

void StartHooks()
{
SH_ADD_HOOK(IVEngineServer, LogPrint, engine, SH_MEMBER(this, &MyHooks::Hook_LogPrint), false);
}

void StopHooks()
{
SH_REMOVE_HOOK(IVEngineServer, LogPrint, engine, SH_MEMBER(this, &MyHooks::Hook_LogPrint), false);
}
};</cpp>

=Manual Hooks=
In some cases, it may be necessary to support multiple, incompatible ABI branches of an interface. For example, suppose you need to hook an application that may supply either version of these interfaces:

Interface v1:
<cpp>
class Interface
{
public:
virtual void Function1() =0;
virtual bool Function2(int clam) =0;
};</cpp>

Interface v2:
<cpp>
class Interface
{
public:
virtual bool Function2(int clam) =0;
};</cpp>

Obviously, these two interfaces are backwards incompatible. Manual hooks allow you to precisely define the structure of the virtual table, bypassing the compiler's rules. These rules can be re-configured at runtime.

==Declaration==
Declaring a manual hook is similar to declaring a normal/simple hook. The syntax is:

<cpp>SH_DECL_MANUALHOOK<n>[_void](UniqueName, vtblIndex, vtblOffs, thisOffs, [return and param types])</cpp>

The <tt>UniqueName</tt> is a unique identifier for the hook. The <tt>vtblIndex</tt> is the index into the virtual table at which the function lies. In most compilers, this index starts from 0. The <tt>vtblOffs</tt> and <tt>thisOffs</tt> fields are used for multiple inheritance and are almost always 0 in modern compiler single inheritance.

An example of hooking the two functions from the first interface version:
<cpp>SH_DECL_MANUALHOOK0_void(MHook_Function1, 0, 0, 0);
SH_DECL_MANUALHOOK1(MHook_Function2, 1, 0, 0, bool, int);</cpp>

==Reconfiguring==
A manual hook can be ''reconfigured'', which will update its set offsets. Reconfiguration automatically removes all hooks on the manual hook. Let's say we want to reconfigure the <tt>Function2</tt> hook in the case of the second version being detected:

<cpp>
void SwitchToNewerHooks()
{
SH_MANUALHOOK_RECONFIGURE(MHook_Function2, 0, 0, 0);
}
</cpp>

Note that the hook was referenced by its unique identifier.

==Adding Hooks==
Adding or removing hook binds is done via the following extra macros:
*<tt>SH_ADD_MANUALHOOK</tt>
*<tt>SH_REMOVE_MANUALHOOK</tt>

These work similar to the original functions. Example:
<cpp>extern Interface *iface;

bool Hook_Function2(int clam)
{
RETURN_META_VALUE(MRES_IGNORED, false);
}

void StartHooks()
{
SH_ADD_MANUALHOOK(MHook_Function2, iface, SH_STATIC(Hook_Function2), false);
}

void StopHooks()
{
SH_REMOVE_MANUALHOOK(MHook_Function2, iface, SH_STATIC(Hook_Function2), false);
}</cpp>

Similarly, a member function version would use <tt>SH_MEMBER</tt> instead.

=Extended Removal Syntax=
The syntax described in the above sections is new as of SourceHook v4.5. <tt>SH_REMOVE_HOOK</tt> is, for all intents and purposes, optional. There is another way to remove hooks.

Each <tt>SH_ADD</tt> macro returns a non-zero <tt>int</tt> on success. The same integer can be passed to the <tt>SH_REMOVE_HOOK_ID</tt> macro, and the hook will be removed. This alternate removal syntax can simplify code that uses multiple successive or dynamic hooks.

Global hooks, described in a later section, require usage of <tt>SH_REMOVE_HOOK_ID</tt> - that is, there is no helper macro to simplify removing a global hook.

=Old Macros=
SourceHook v5.0 deprecates older macros that were used in earlier versions. The macros are:
*<tt>SH_ADD_HOOK_STATICFUNC</tt> - Wrapper for <tt>SH_ADD_HOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_REMOVE_HOOK_STATICFUNC</tt> - Wrapper for <tt>SH_REMOVE_HOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_ADD_HOOK_MEMFUNC</tt> - Wrapper for <tt>SH_ADD_HOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_REMOVE_HOOK_MEMFUNC</tt> - Wrapper for <tt>SH_REMOVE_HOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_ADD_MANUALHOOK_STATICFUNC</tt> - Wrapper for <tt>SH_ADD_MANUALHOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_REMOVE_MANUALHOOK_STATICFUNC</tt> - Wrapper for <tt>SH_REMOVE_MANUALHOOK</tt> and <tt>SH_STATIC</tt>.
*<tt>SH_ADD_MANUALHOOK_MEMFUNC</tt> - Wrapper for <tt>SH_ADD_MANUALHOOK</tt> and <tt>SH_MEMBER</tt>.
*<tt>SH_REMOVE_MANUALHOOK_MEMFUNC</tt> - Wrapper for <tt>SH_REMOVE_MANUALHOOK</tt> and <tt>SH_MEMBER</tt>.

These macros are fairly self explanatory. The parameter where the <tt>SH_STATIC</tt> or <tt>SH_MEMBER</tt> macro would normally go is instead filled with the parameters to that macro.

This syntax is considered deprecated, but it is still supported. Code written with these macros will continue to compile against older SourceHook versions. If you are writing a plugin which must work against Metamod:Source 1.4 and 1.6, you will want to use the older macros for simplicity.

=Global Hooks=
<b>Note:</b> Global Hooks are only available in SourceHook v4.5 or later.

Global hooks are unlike normal hooks in that the hook is invoked for ALL instances, rather than solely the given the instance the hook was bound to. It is important to realize that this feature can be deceiving. Consider the following example:

<cpp>
class CBaseEntity
{
public:
virtual void SetHealth(int health) =0;
};

class CBaseCat : public CBaseEntity
{
public:
virtual void SetHealth();
};

class CBaseKitten : public CBaseCat
{
public:
virtual void SetHealth();
};</cpp>

In this example, <tt>CBaseCat</tt> and <tt>CBaseKitten</tt> instances have ''separate virtual tables''. Although they both derive from <tt>CBaseEntity</tt>, they are separate virtual objects. <b>Therefore, a global hook on <tt>CBaseEntity</tt> will receive no invocations, and a hook on <tt>CBaseCat</tt> will receive only <tt>CBaseCat</tt> instances, as long as the instance is not a class derived from <tt>CBaseCat</tt></b>.

With this understanding in place, there are two separate syntaxes - one for simple hooks and one for manual hooks. Additionally, there are two ways of declaring the virtual interface to use:
*An instance of the class can be passed.
*The direct address to the virtual table can be passed.

They are essentially equivalent, although one may be more advantageous than the other (for example, if no instances are known, but the vtable address can be extracted via pattern searching).

It is also important to note that global hooks are just a different method of "filtering." They fall into either the "simple" or "manual" category, and are otherwise exactly the same to those hooks. Thus there are no separate return/declaration macros for global hooks.

The macro <tt>META_IFACEPTR</tt> is especially useful for global hooks. See [[SourceHook_Development#Interface_Pointers_from_Hooks|Interface Pointers from Hooks]] near the end.

Lastly, global hooks exclusively use the extended hooking syntax. That means there exists only <tt>SH_ADD</tt> macros. <tt>SH_HOOK_REMOVE_ID</tt> must be used and the hook ID generated via <tt>SH_ADD</tt> must be cached.

All examples will use the following code as a basis:
<cpp>
class Player
{
public:
virtual void TakeDamage(int damage) =0;
};

void Hook_TakeDamage(int damage);
</cpp>

==Simple Hooks==
Two extra macros exist for adding a global hook:

<cpp>
SH_ADD_VPHOOK(Interface, Function, Instance, Handler, Post)
SH_ADD_DVPHOOK(Interface, Function, VirtualTable, Handler, Post)
</cpp>

An example:
<cpp>
extern void *player_vtable;
HookId takedamage_hook = 0;

void StartHooks()
{
takedamage_hook = SH_ADD_DVPHOOK(Player, TakeDamage, player_vtable, SH_STATIC(Hook_TakeDamage), false);
}

void StopHooks()
{
if (takedamage_hook)
{
SH_REMOVE_HOOK_ID(takedamage_hook);
}
}</cpp>

==Manual Hooks==
Similarly, manual hooks are straightforward:
<cpp>
SH_DECL_MANUALHOOK1_void(MHook_TakeDamage, 0, 0, 0, int);

extern void *player_vtable;
int takedamage_hook = 0;

void StartHooks()
{
takedamage_hook = SH_ADD_MANUALDVPHOOK(MHook_TakeDamage, player_vtable, SH_STATIC(Hook_TakeDamage), false);
}

void StopHooks()
{
if (takedamage_hook)
{
SH_REMOVE_HOOK_ID(takedamage_hook);
}
}</cpp>

=Modifying Parameters=
Consider another variation of the hooking process. There is a hook on function X, which has one parameter. The hook wants to change the value of this parameter transparently. For example:
*Caller passes 5 into X.
*Hook changes the 5 to a 6.
*Hooked function receives a 6 and continues normally.

SourceHook has a method for achieving this. As an added bonus, the new parameters are passed to subsequent hooks. That means the replacement process is as transparent as possible. For this example, we'll use the following code, with an assumed hook on <tt>Player::TakeDamage</tt> to the <tt>Hook_TakeDamage</tt> function.

<cpp>
class Player
{
public:
virtual void TakeDamage(int damage);
};

void Hook_TakeDamage(int damage);</cpp>

Our objective is to multiply the damage by 2.

==Simple Hooks==
For simple hooks, changing parameters looks similar to an <tt>SH_CALL</tt>. The macros are:

<cpp>RETURN_META_NEWPARAMS(Action, HookFunction, ([params]))
RETURN_META_VALUE_NEWPARAMS(Action, Value, HookFunction, ([params]))
</cpp>

Example:
<cpp>
void Hook_TakeDamage(int damage)
{
RETURN_META_NEWPARAMS(MRES_IGNORED, &Player::TakeDamage, (damage * 2));
}</cpp>

Note that the parenthesis enclosing the parameters are required.

==Manual Hooks==
Manual hooks require slightly different macros. They are:

<cpp>RETURN_META_MNEWPARAMS(Action, UniqueName, ([params]));
RETURN_META_VALUE_MNEWPARAMS(Action, Value, UniqueName, ([params]));</cpp>

Example:
<cpp>
SH_DECL_MANUALHOOK1_void(MHook_Player_TakeDamage, 0, 0, 0, int);

void Hook_TakeDamage(int damage)
{
RETURN_META_MNEWPARAMS(MRES_IGNORED, MHook_Player_TakeDamage, (damage *2));
}</cpp>

Note that the parenthesis enclosing the parameters are required.

=Bypassing Hooks=
Often, either to avoid certain functionality or to avoid infinite recursion, it is necessary to bypass all hooks on a hooked function, such that only the original function is called. For instance, a previous blocked certain messages sent through <tt>LogPrint</tt>. In order to send that message, the hook needs to be bypassed.

To way to do this is to use the <tt>SH_CALL</tt> macro:
<cpp>SH_CALL(Instance, HookFunction)(params)</cpp>

Example:
<cpp>SH_CALL(engine, &IVEngineServer::LogPrint)("Secret Message");</cpp>

Similarly, manual hooks have <tt>SH_MCALL</tt>:

<cpp>SH_DECL_MANUALHOOK1(MHook_Function2, 1, 0, 0, bool, int);

bool Function2_Bypass(int clam)
{
return SH_MCALL(iface, MHook_Function2)(clam);
}</cpp>

==Deprecated Syntax==
The syntax described above is used in SourceHook v5.0 and v4.5. An older syntax, using a "CallClass" data type, was used in SourceHook v4.4 and lower. This syntax was deprecated in v4.5 and completely removed in v5.0. Upgrading from SourceHook v4.4 means that code referencing <tt>SH_GET_CALLCLASS</tt> or <tt>SH_REMOVE_CALLCLASS</tt> must be removed, and <tt>SH_CALL</tt> simply needs an instance pointer instead.

=Other Macros=
SourceHook contains a large variety of extra macros. This section is a grab bag of the more commonly used ones.

==Interface Pointers from Hooks==
Let's say you have the following hook:

<cpp>class Player
{
public:
virtual void TakeDamage(int damage);
float GetDamageModifier();
};

void Hook_TakeDamage(int damage);
</cpp>

How can you get the <tt>Player</tt> instance while in the hook? This can be achieved via the <tt>META_IFACEPTR</tt> macro. Example:

<cpp>void Hook_TakeDamage(int damage)
{
Player *pPlayer = META_IFACEPTR(Player);

int new_damage = (int)((pPlayer->GetDamageModifier() + 0.3) * (float)damage);

RETURN_META_NEWPARAMS(MRES_IGNORED, &Player::TakeDamage, (new_damage));
}</cpp>

Note that the class name should be passed to <tt>META_IFACEPTR</tt>, not the pointer type.

==Ignoring Reference Returns==
There is a special macro, <tt>RETURN_META_NOREF</tt>, for ignoring a return value for reference-returning functions. Example:

<cpp>
class ISomething
{
public:
virtual int & GetSomething() =0;
};

int & Hook_GetSomething()
{
RETURN_META_NOREF(MRES_IGNORED, int &);
}</cpp>

=Automatic hookmanager generation=
Normally, the SH_DECL_ macros generate a so-called "hook manager", a function which is invoked instead of the original function and then calls the hooks and processes their return and <tt>META_RES</tt> values.

It is also possible to let SourceHook auto-generate the hook manager. This is neccessary if the function prototype is unknown at compile time (for example if hooks can be defined from third-party plugins of your plugin).

Example Usage from a Metamod:Source plugin:
<cpp>
#include "sourcehook_pibuilder.h"

// We want to hook a void (int, float) function

// Request IHookManagerAutoGen interface
SourceHook::IHookManagerAutoGen *hmag =
static_cast<SourceHook::IHookManagerAutoGen *>(ismm->MetaFactory(MMIFACE_SH_HOOKMANAUTOGEN, NULL, NULL));

// (check for hmag == NULL)

// Build prototype information (using CProtoInfoBuilder helper class).
SourceHook::CProtoInfoBuilder protoInfo(SourceHook::ProtoInfo::CallConv_ThisCall);
protoInfo.AddParam(sizeof(int), SourceHook::PassInfo::PassType_Basic, SourceHook::PassInfo::PassFlag_ByVal,
NULL, NULL, NULL, NULL);
protoInfo.AddParam(sizeof(float), SourceHook::PassInfo::PassType_Float, SourceHook::PassInfo::PassFlag_ByVal,
NULL, NULL, NULL, NULL);

// Generate the hook manager
HookManagerPubFunc generatedHookMan = hmag->MakeHookMan(protoInfo, 0 /* vtable offset */, 0 /* vtable index */);

// Add the hook
int hookid = g_SHPtr->AddHook(g_PLID, SourceHook::ISourceHook::Hook_Normal/Hook_VP/Hook_DVP, iface_ptr, thisptr_offs,
generatedHookMan, handler, post);

// ... (use the hook)

// After you're done using the hook (cleanup)
// Remove the hook
g_SHPtr->RemoveHookByID(hookid);

// Release hook manager
hmag->ReleaseHookMan(generatedHookMan);
</cpp>
<tt>CProtoInfoBuilder::AddParam</tt> has 7 parameters:
* size: size of the type. This is sizeof(type) even if it is passed by reference!
* passtype: this can be PassType_Basic for integer types (char/short/int/...), PassType_Float for floating-point types (float/double) and PassType_Object for unions, structs and classes.
* passflags: flags. Has to contain either PassFlag_ByVal or PassFlag_ByRef.
* pNormalCtor: for PassType_Object, set this to the pointer to the user-defined default constructor of the object, if it has one.
* pCCtor: for PassType_Object, set this to the pointer to the user-defined copy constructor of the object, if it has one.
* pODtor: for PassType_Object, set this to the pointer to the user-defined destructor of the object, if it has one.
* pAssignOperator: for PassType_Object, set this to the pointer to the user-defined assignment operator of the object, if it has one.

If you are hooking a non-void function, also call <tt>CProtoInfoBuilder::SetReturnType</tt>. It has the same arguments as <tt>AddParam</tt>.

The <tt>handler</tt> parameter of <tt>ISourceHook::AddHook</tt> is a pointer to the ISHDelegate interface.
In C++, you construct ISHDelegates like this:
<cpp>
class MyDelegate : public SourceHook::ISHDelegate
{
public:
// vtable index 0
virtual bool IsEqual(ISHDelegate *pOtherDeleg)
{
// pOtherDeleg is guaranteed to be from the same plugin.
// This function is only used for compat with the old SH_REMOVE_HOOK method.
// if you don't want to use that with your hooks, you can simply return false here.
// if for some reason you need it, a good idea could be comparing the vtable pointer:
return *reinterpret_cast<void**>(this) == *reinterpret_cast<void**>(pOtherDeleg);

// But in general I'd just return false!
}

// vtable index 1
virtual void DeleteThis()
{
delete this; // Called from SourceHook when this instance is not needed
// and should be deleted.
}

// vtable index 2
virtual ret_type Call(params)
{
// your code.
// SH_DECL_ macros pass execution to the actual user's handler through a FastDelegate
// which is stored as a member variable of the delegate class.
}
};
</cpp>

The first parameter of the CProtoInfoBuilder constructor (see example code above) is the calling convention in an extended sense. At the moment it can be either CallConv_ThisCall or (CallConv_ThisCall | CallConv_HasVafmt). The second value means that the function has printf-like string formatting. Then, the finaly ''const char *, ...'' arguments will be added automatically, and the Deleagte::Call method should have one more parameter: ''const char *formattedString''.

pNormalCtor/pCCtor/pODtor/pAssignOperator should be found using offsets / sigscanning. If you are a C++ plugin and know the type at compile time, you can also use the following class:
<cpp>
// Address of constructor/destructor
// (using wrappers)
template <class T>
class Ctor_Thunk
{
public:
void NormalConstructor()
{
new(this) T;
}

void CopyConstructor(const T &other)
{
new(this) T(other);
}

void Destructor()
{
reinterpret_cast<T*>(this)->~T();
}

const T& AssignOp(const T &other)
{
return (*reinterpret_cast<T*>(this) = other);
}
};

template <class T>
void *FindFuncAddr(T mfp)
{
union
{
T a;
void *b;
} u;
u.a = mfp;
return u.b;
}

// Usage:
FindFuncAddr(&Ctor_Thunk<type>::NormalConstructor)
// (if the type is a reference type, use it without & here)
</cpp>

=Embedding=
Embedding SourceHook in your own application or library is very easy. The <tt>sourcehook.cpp</tt> file must be compiled or linked into your project. To instantiate the SourceHook engine, you must create a <tt>CSourceHookImpl</tt> instance. Example:

<cpp>
/* Normally, just <sourcehook.h> is included, but this is needed to instantiate the engine. */
#include <sourcehook/sourcehook_impl.h>

SourceHook::Impl::CSourceHookImpl g_SourceHook;
</cpp>

To actually use SourceHook, it is necessary to have two global variables:
*<tt>g_PLID</tt> - A unique integer that identifies the library using SourceHook. This is used for removing all hooks a library is using.
*<tt>g_SHPtr</tt> - A pointer to the <tt>SourceHook::ISourceHook</tt> interface.

Example header file:
<cpp>
#include <sourcehook/sourcehook.h>

extern SourceHook::ISourceHook *g_SHPtr;
extern int g_PLID;</cpp>

Example addition to the global code:
<cpp>
SourceHook::ISourceHook *g_SHPtr = &g_SourceHook;
int g_PLID = 0;</cpp>

==Multiple Libraries/Shared Hooks==
If SourceHook is going to be used across multiple libraries in the same process, it is essential that only one instance of SourceHook be present. Of course, that is only logical, since otherwise the instances would be replacing each other's virtual patches.

In order to support this, each separate library must be given the <tt>ISourceHook</tt> pointer and a unique <tt>g_PLID</tt> value. <tt>CSourceHookImpl</tt> provides a few useful functions for managing hooks on "child" libraries or otherwise linked code.

*<tt>PausePlugin()</tt> - Silences any hooks from an ID, such that those hooks will not be called.
*<tt>UnpausePlugin()</tt> - Un-silences any silenced hooks from an ID.
*<tt>UnloadPlugin()</tt> - Clean-up any left-over hooks from an ID.

[[Category:Metamod:Source Documentation]]

Porting to x64

2024-05-08T23:04:26Z

Mooshua: Add ABI shenanigans

== Overview ==

Many plugins are already compatible with the x64 architecture, but many that manipulate game memory (such as with hooks or patches) will require extensive revisions to run under the new 64-bit servers.
Overall, if your plugin:
* Uses the address natives or the Address type,
* Uses dhooks
* Uses sdkcalls or sdktools (''not sdkhooks'')

...you will need to update your plugin for 64 bits.

Extensions may be good to go with just a recompile for 64-bits, but some may need more extensives changes.

== I'm having an issue! ==

In general, '''prototypes need to be exactly correct''' (including class statics like copy/destruct/constructors) as there are now significantly more quirks that will cause ABIs to be laid out differently.

Here are some things to check for that may be tripping you up:

* The type you thought was an ''int'' was actually a ''size_t''!
* The type you put down as an int or pointer was actually a ''float''!
* Handling pointers as ''int''s when they should be ''void*'' or ''size_t'' (why would you do this??)
* '''The calling convention has changed.''' Make sure to account for this in detours and patches. Make sure your prototypes are exactly correct!
* '''In patches:''' Did you forget the 64-bit opcode prefix when assembling your patch? EAX and RAX are accessed using different opcode prefixes!

=== Linux Calling Convention Quirks ===

Linux uses the System-V x64 ABI. There are many great sources of documentation all over the internet: [https://wiki.osdev.org/System_V_ABI OSDev Wiki] [https://en.wikipedia.org/wiki/X86_calling_conventions#x86-64_calling_conventions Wikipedia]
* All calling conventions are now an up to 8-register fastcall depending on the types (!!)
* RCX can be a thisptr, first argument, or stack return pointer depending on the context
* '''Integer arguments and float arguments are passed in different registers!''' (generic for ints, SIMD registers for floats)
* Varargs are now more complex to call when floats are included in the vararg

The exact value of return types with C++ shenanigans (destructors, etc) still needs to be figured out by someone. However, in general.
* The return argument is always passed in RCX, and will bump the thisptr to RDX (todo: confirm this)
* Some return types that are 128-bits will be returned in both RAX and RDX??

=== MSVC Calling Convention Quirks ===
Microsoft has some excellent official documentation [https://learn.microsoft.com/en-us/cpp/build/x64-calling-convention?view=msvc-170 in their MSVC docs].

* All calling conventions are now a four-register fastcall
* RCX can be a thisptr OR the first arg! It is not always a thisptr now. RCX can also be the return value (see below), bumping the thisptr to RDX.
* '''Integer arguments and float arguments are passed in different registers!''' (generic for ints, SIMD registers for floats)
* All objects larger than 8 bytes are now passed exclusively by reference (even on the stack??)
* Float arguments passed to varargs need to be put in both the generic and SIMD register for the appropiate argument index. Varargs are still fastcalls... somehow...
* '''setjmp has new behavior''' and destroys objects as if the scope has been exited. (if you ''are'' using setjmp, good luck)

Return types also have their usual obscure shenanigans. More specifically,
* The return argument is always passed in RCX, and will bump the thisptr to RDX (todo: confirm this)
* Returns with all types larger than 8 bytes occur on the stack
* Returns with any type that has a user-defined base classes, virtual methods, constructor, destructor, or copy operation happens on the stack (''regardless of size'')

== Porting Plugins ==

=== Gamedata ===

All signatures will need to be updated, and likely many offsets. "linux" is for 32-bit linux and "linux64" is for 64-bit linux.

Todo: What is the equivalent for windows?

=== Address Natives ===

New address natives that support 64-bits are still under development

=== DHooks ===

DHooks does not support 64-bits at all for the time being. It will need heavy revisions to work under the new architecture, starting with better SourceHook support for the 64-bit architecture (see: hookmangen)

=== SDKCalls ===

SDKCalls will need to be updated to learn how to accept a thisptr. However, all non-raw calls (eg, those to entities or gamerules that does not require a thisptr) should be fine as long as none of the arguments are 64-bits (including 64-bit ints!)

[[Category:SourceMod Documentation]]

Porting to x64

2024-05-08T22:38:21Z

Mooshua: Fix category naming???

Porting to x64

2024-05-08T22:35:28Z

Mooshua: Initial draft of porting page