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

2024-06-12T22:47:30Z

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

New page

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 Standalone - Revision history

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