AlliedModders Wiki - User contributions [en]

Installing Metamod:Source

2006-01-24T22:29:17Z

Mrmagu:

This article will guide you through a [[SourceMM]] installation.

If you don't already have Metamod:Source bundled with a plugin, you can install it manually with the directions below.

<ol>
<li>'''Download''' the appropriate package for your server: there is a Linux tarball and Windows zip file. You can get this from the [http://www.sourcemm.net/ SourceMM Website].</li>
<li>'''Open''' the package, you will either have "server_i486.so" or "server.dll".</li>
<li>'''Find '''your "mod folder" on your server. This will be something like "cstrike" or "hl2mp".</li>
<li>'''Make''' a folder in your mod folder called "addons", if it doesn't already exist. Make a folder inside addons called "metamod", and a folder inside "metamod" called "bin".</li>
<li>'''Create''' a new, blank, text file called "metaplugins.ini".</li>
<li>'''Upload''' the files to your server:
<ul><li>Upload the server.dll or server_i486.so file to your addons/metamod/bin Folder.</li>
<li>Upload the metaplugins.ini file to your addons/metamod folder.</li>
<li>WARNING! - Do not replace the mod's server.dll/server_i486.so (usually in "<mod>\bin"). This will cause your mod to stop working.</li>
</ul>
<li>'''Open''' the file in the mod folder called "gameinfo.txt". 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 before all of the "Game" entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>'''You're''' done! To test whether it worked, restart your game server and type "meta" in the [[server console]]. You should get a menu.
<li>'''For''' more information, documentation, and troubleshooting, see [[:Category:Documentation (SourceMM)]]</li>
<li>'''Optional''' Cvars:
<tt>mm_pluginsfile</tt> - Sets the path and name of the plugins file, defaulting to "addons/metamod/metaplugins.ini". It is relative to the mod directory.</li>
</ol>

[[Category:Documentation (SourceMM)]]

User:Mrmagu

2006-01-22T23:44:03Z

Mrmagu:

is a nub :]

<hr style="border:0;border-top:1px solid #969696;" />

User:Mrmagu

2006-01-19T20:46:08Z

Mrmagu:

is a nub :] and wants someone to add the damn syntax highlighter extention already :)

C++ Highlighted test.. 

<cpp>
#ifndef SIGSCAN_H
#define SIGSCAN_H

// test
class CSigScan {
private:
/* Private Variables */
/* Base Address of the server module in memory */
static unsigned char *base_addr;
/* The length to the module's ending address */
static size_t base_len;

/* The signature to scan for */
unsigned char *sig_str;
/* A mask to ignore certain bytes in the signature such as addresses
The mask should be as long as all the bytes in the signature string
Use '?' to ignore a byte and 'x' to check it
Example"xxx????xx" - The first 3 bytes are checked, then the next 4 are
ignored, then the last 2 are checked */
char *sig_mask;
/* The length of sig_str and sig_mask (not including a terminating null for sig_mask) */
size_t sig_len;

/* Private Functions */
void* FindSignature(void);

public:
/* Public Variables */

/* sigscan_dllfunc is a pointer of something that resides inside the gamedll so we can get
the base address of it. From a SourceMM plugin, just set this to ismm->serverFactory(0)
in Load(). From a Valve Server Plugin, you must set this to an actual factory returned
from gameServerFactory and hope that a SourceMM plugin did not override it. */
static void *(*sigscan_dllfunc)(const char *pName, int *pReturnCode);

/* If the scan was successful or not */
char is_set;
/* Starting address of the found function */
void *sig_addr;

/* Public Functions */
CSigScan(void)sig_str(NULL), sig_mask(NULL), sig_len(0), sig_addr(NULL) {}
~CSigScan(void);

static bool GetDllMemInfo(void);
void Init(unsigned char *sig, char *mask, size_t len);
};

void InitSigs(void);

/* Sig Functions */
class CBaseAnimating;
void CBaseAnimating_Ignite(CBaseAnimating *cba, float flFlameLifetime);

#endif
</cpp>

User:Mrmagu

2006-01-19T20:10:22Z

Mrmagu: highlight test

is a nub :] and wants someone to add the damn syntax highlighter extention already :)

C++ Highlighted test.. 

<cpp>
#ifndef SIGSCAN_H
#define SIGSCAN_H

// test
class CSigScan {
private:
/* Private Variables */
/* Base Address of the server module in memory */
static unsigned char *base_addr;
/* The length to the module's ending address */
static size_t base_len;

/* The signature to scan for */
unsigned char *sig_str;
/* A mask to ignore certain bytes in the signature such as addresses
The mask should be as long as all the bytes in the signature string
Use '?' to ignore a byte and 'x' to check it
Example"xxx????xx" - The first 3 bytes are checked, then the next 4 are
ignored, then the last 2 are checked */
char *sig_mask;
/* The length of sig_str and sig_mask (not including a terminating null for sig_mask) */
size_t sig_len;

/* Private Functions */
void* FindSignature(void);

public:
/* Public Variables */

/* sigscan_dllfunc is a pointer of something that resides inside the gamedll so we can get
the base address of it. From a SourceMM plugin, just set this to ismm->serverFactory(0)
in Load(). From a Valve Server Plugin, you must set this to an actual factory returned
from gameServerFactory and hope that a SourceMM plugin did not override it. */
static void *(*sigscan_dllfunc)(const char *pName, int *pReturnCode);

/* If the scan was successful or not */
char is_set;
/* Starting address of the found function */
void *sig_addr;

/* Public Functions */
CSigScan(void)sig_str(NULL), sig_mask(NULL), sig_len(0), sig_addr(NULL) {}
~CSigScan(void);

static bool GetDllMemInfo(void);
void Init(unsigned char *sig, char *mask, size_t len);
};

void InitSigs(void);

/* Sig Functions */
class CBaseAnimating;
void CBaseAnimating_Ignite(CBaseAnimating *cba, float flFlameLifetime);

#endif
</cpp>

Metamod:Source

2006-01-17T23:46:49Z

Mrmagu: /* Documentation */

:{{owned_project}}
==Introduction==
Metamod:Source is an API manager and interception handler that sits in between the Half-Life 2 Engine (Source) and a subsequent Game Modification (MOD). It can dynamically load "SourceMM Plugins", written in C++, to intercept, override, and hook Engine and GameDLL API interfaces. It also allows for inter-plugin communication. As a backend it contains [[SourceHook]], a powerful library for safely manipulating virtual table hooks.

[[Category:Half-Life 2]]
[[Category:SourceMM]]

==Naming Conventions==
Metamod:Source refers to the overall product and concept behind SourceMM. SourceMM is the actual implementation and codebase. For practical purposes the names are interchangeable, however, "Metamod:Source" is preferred for public relations/marketing purposes and SourceMM is preferred for programming purposes.

==History==
Metamod:Source is derived from the [[Metamod]] concept of intercepting calls between a game's engine and mod library. While not based on the same code, the API is designed to be similar and familiar to [[Half-Life 1]] programmers.

====SourceMod Core1====
Initially, the [[SourceMod]] project was started as the next-generation continuation of the [[AMX Mod X]] project. It was designed to be a meta-interface layer for inter-communicating plugins. However, as development continued, it was soon realized that the [[Valve Server Plugin]] interface would not be sufficient to provide proper engine access.

[[User:PM|Pavol Marko]] (core1 developer) decided to add "SourceHook" to SourceMod core1. It was embedded as a large library for hooking specific virtual table functions. After multiple revisions (see [[SourceHook]] history), it became apparent that 1)SourceHook needed to be game and interface generic, and 2)SourceMod and SourceHook needed to be split into two separate projects. The logic behind this was that SourceHook needed to be a layer above [[Valve Server Plugins]], in order to properly manage hooks with the least possibility of conflicts. Furthermore, SourceMod should be a plugin to the SourceHook interface, rather than managing it. This decision can be likened to [[Admin-Mod]]'s early decision to split into the first [[Metamod]] project.

====SourceHook Finalized====
After four major revisions, [[SourceHook]] was mature enough to be used in a production environment. While [[User:PM|PM]] concentrated on fleshing out [[SourceHook]], [[User:BAILOPAN|BAILOPAN]] and [[User::Damaged Soul|DS]] created the GameDLL wrapper portion.

====Version 1.0====
On May 6, 2005, Metamod:Source 1.0 was released with SourceHook v4.1 as a backend. GameDLL wrapping was achieved by providing the engine with fake copies of the IServerGame* interfaces. Once the true GameDLL location was known it would be loaded by SourceMM. The fake interface then directly wrapped calls to the real GameDLL.

====Version 1.1====
On October 21, 2005, the first major revision of SourceMM was released, featuring SourceHook v4.4, internal event listeners, dropped reliance on STL, and rewritten GameDLL hooking code. The [[Day of Defeat|Day of Defeat:Source]] release by [[Valve Software]] revealed that the binary interface between the engine and mod wasn't necessarily public or current, and SourceMM's detection was improved for compatibility and speed. Furthermore, SourceMM stopped wrapping the GameDLL interfaces and began using SourceHook to hook them.

====Version 1.2====
On January 7th, 2006, SourceMM was updated for SourceHook v4.5, but received no major API changes.

==Design Considerations==
====Metamod====
Originally, SourceMM was a plugin co-existing with SourceMod. However, there are factories, pointers, and certain capabilities not possible from a [[Valve Server Plugin]]. Furthermore, the [[Half-Life 2]] engine does not properly unload VSPs, making debugging and resource unloading more difficult. Eventually it was decided the added functionality and fine-tuned control outweighed the extra cost of having to configure an intercepting binary.

====Plugins====
Plugins are specific to Metamod:Source. This means that [[Valve Server Plugins]] and [[SourceMM Plugins]] are entirely separate in the API characteristics. While it is certainly possible to expose the necessary interfaces to VSPs, it creates an added layer of complexity for dealing with things that SourceMM might not directly control. For example, when a SourceMM plugin is removed at runtime, all of the necessary hooks are also removed. A VSP has no clear callback for detecting this event, therefore it would be more difficult to ensure proper unloading. VSP and SMM plugins also have different ways of attaching and detaching server [[Cvars|cvars]] and [[Console commands|concmds]].

By keeping the plugin system isolated, SourceMM can also provide a unique set of console commands and API. For example, plugins can listen for certain Metamod:Source-specific events and provide communication channels with other plugins.

====Hooking====
SourceMM is powered by [[SourceHook]], a versatile library for hooking virtual functions. The original [[Half-Life 1]] engine used structs of function pointers which could easily be modified as they passed from one library to another. However, HL2 is comprised almost entirely of pure virtual interfaces. SourceHook was designed for declaring single hooks against a given virtual function and a this pointer, which is not only faster than a blanket hooking system like Metamod's, but more flexible and precise.

Hooking under SourceMM has a number of features that don't exist in a hooking system style like Metamod's, and it achieves something closer to [[Detours|detours]], rather than Metamod, which is hardcoded. For example
*You can change parent parameters during a hooked call
*You can hook member functions, both by a pre-existing declaration or given vtable offset
*You can call the original function and still fire its associated hooks, or you can call it without firing hooks in order to prevent infinite recursion

==Documentation==
For more information on installing, configuring, and coding for SourceMM, see [[:Category:Documentation (SourceMM)|Documentation]].

==The Future==
While SourceMM is a stable/production product, more features are on the horizon. There are distant plans for a [[Detours|detouring]] library and a library for efficiently automated [[Signature Scanning|signature scanning]].

==License==
SourceMM is licensed under the [[zLib/libpng License]]. It is free to use for both open-source and proprietary projects.

==External Links==
*[http://www.sourcemm.net/ Metamod:Source Website]
*[http://www.metamod.org/ Metamod Website]
*[http://www.sourcemod.net/ SourceMod Website]

Sample Plugins (Metamod:Source)

2006-01-17T17:39:02Z

Mrmagu: /* Where to Get */

This guide briefly explains about and how to compile the sample plugins for SourceMM.

=Sample Plugins=
==stub_mm==
This plugin is a bare-minimum example of what you need to build a SourceMM plugin. It implements the ISmmPlugin class, exposes it as a DLL, and nothing more. As a single example, it also hooks ServerActivate in IServerGameDLL. "Stub" was designed such that a developer could open it and quickly modify it to begin a plugin.

*meta_hooks.h - Definition of main hooks
*stub_mm.cpp - Main plugin file and implementation
*stub_mm.h - Main plugin header

==sample_mm==
This plugin attempts to recreate all of the functionality a Server Plugin has. Server Plugins receive twelve callbacks, three of which are GameDLL overridable. In order to replicate this functionality, sample_mm hooks eleven of the callbacks as either post or pre handlers. Furthermore, it also demonstrates how to build a CallClass for calling original functions. Every hook produces a log message so you can see when events occur.

Sample_mm fully replicates every callback a Server Plugin is capable of receiving, except for NetworkIDValidated. This callback has no known representation in the engine, is not very useful, and can be replicated easily with GameFrame() (in the future, we might demonstrate this). If you are having trouble porting a Server Plugin over, or are wondering how you can keep the same features, this plugin will show you where to start.

*meta_hooks.h - Definition of main hooks
*SamplePlugin.cpp - Main plugin file and implementation
*SamplePLugin.h - Main plugin header

=Where to Get=
You can find the source code to the sample plugins in either the source code package or [http://www.tcwonline.org/cgi-bin/viewcvs.cgi/sourcemm/ CVS]. They are located in the main source code folder in "stub_mm" and "sample_mm".

=Compiling=
==Windows==
These plugins have been compiled and tested with Microsoft Visual Studio 7.1 (.NET 2003). Before you compile, you must have these directories in your include options. To set these, go to Tools, Options, Projects, VC++ Directories.

*From the Include Files menu, add these HL2SDK paths:
**public
**public/dlls
**public/engine
**public/tier0
**public/tier1
**public/vstdlib
**tier1
*From the Library Files menu, add these HL2SDK paths:
**lib/public
*From the Include Files menu, add these SourceMM paths:
**sourcemm
**sourcemm/sourcehook
**sourcemm/sourcemm

You can then open the .vcproj project file. Go to Build, Set Active Configuration, and select Release. You can then select Build from the Build menu, which will produce a .dll file in the Release folder in the project folder.

==Linux==
To build on Linux, you must have a copy of Source Dedicated Server installed. Open the project Makefile and edit the following lines at the top:

*SRCDS - Location of main srcds installation
*SMM_ROOT - Location of folder containing sourcemm and sourcehook
*HL2SDK - Location of HL2SDK

Once done, you can just type "make" to run the build scripts. The binary will appear in ./Release/.

[[Category:Documentation (SourceMM)]]

Installing Metamod:Source

2006-01-17T17:32:13Z

Mrmagu:

This article will guide you through a [[SourceMM]] installation.

If you don't already have Metamod:Source bundled with a plugin, you can install it manually with the directions below.

<ol>
<li>'''Download''' the appropriate package for your server: there is a Linux tarball and Windows zip file. You can get this from the [http://www.sourcemm.net/ SourceMM Website].</li>
<li>'''Open''' the package, you will either have "server_i486.so" or "server.dll".</li>
<li>'''Find '''your "mod folder" on your server. This will be something like "cstrike" or "hl2mp".</li>
<li>'''Make''' a folder in your mod folder called "addons", if it doesn't already exist. Make a folder inside addons called "metamod", and a folder inside "metamod" called "bin".</li>
<li>'''Create''' a new, blank, text file called "metaplugins.ini".</li>
<li>'''Upload''' the files to your server:
<ul><li>Upload the server.dll or server_i486.so file to your addons/metamod/bin Folder.</li>
<li>Upload the metaplugins.ini file to your addons/metamod folder.</li>
<li>WARNING! - Do not replace the mod's server.dll/server_i486.so (usually in "<mod>\bin"). This will cause your mod to stop working.</li>
</ul>
<li>'''Open''' the file in the mod folder called "gameinfo.txt". 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 before all of the "Game" entries that looks like this:<pre>GameBin |gameinfo_path|addons/metamod/bin
</pre>
</li>
<li>'''You're''' done! To test whether it worked, restart your game server and type "meta" in the [[server console]]. You should get a menu.
<li>'''For''' more information, documentation, and troubleshooting, see [[:Category:Documentation (SourceMM)]]</li>
<li>'''Optional''' Cvars:
<tt>mm_pluginsfile</tt> - Sets the path and name of the plugins file, defaulting to "addons/metamod/plugins.ini". It is relative to the mod directory.</li>
</ol>

[[Category:Documentation (SourceMM)]]

Metamod:Source Development

2006-01-17T12:25:35Z

Mrmagu:

This article is an introduction to [[SourceMM]] coding.

{{qnotice|The majority of this documentation should be merged or moved into an article about [[SourceHook]].}}

{{qnotice|This article probably needs some better formatting.}}

=Requirements=
You must have the Valve [[HL2SDK]], available from your [[Steam]] Menu. For Windows, you must have [[Microsoft Visual Studio]] 7.0 or 7.1 (we have not tried 6.0). For [[Linux]], Valve requires you use at least [[GCC]] 3.4.1. You should also have a copy of the [[Metamod:Source]] source code (sourcemm/sourcehook and sourcemm/sourcemm).

For [[Microsoft Visual Studio]], you should make sure that you have the following HL2SDK paths in your include settings (Tools -> Options -> Projects, VC++ Directories, Include Files), as well as the "sourcehook" and "sourcemm" folders:
*dlls
*public
*public\vsdtlib
*public\tier1
*public\tier0
*public\engine
*public\dlls
*tier1
*lib\public (this should be in your Library Paths!)

=Plugin API=
In order to write a plugin, you must implement the ISmmPlugin interface, similar to IServerPluginCallbacks. Each Metamod:Source release has a minimum required interface version and a current version. The minimum version is guaranteed to be upward compatible to the current, however, it may be lacking some features.

Once you've implemented the interface, you must also have a global singleton of your plugin available. There are a few macros to assist you in properly exposing the interface as a DLL and setting up the API states.

*{{bcode|PLUGIN_GLOBALVARS}}() - Place in header. Declares the global variables that some API calls require (such as g_SHPtr and g_PLAPI).
*{{bcode|PLUGIN_EXPOSE}}(class, singleton) - Place in .cpp file. Declares the external CreateInterface function which exposes the API.
*{{bcode|PLUGIN_SAVEVARS}}() - Use first thing in ISmmPlugin::Load(), saves the global variables sent from SourceMM.

The actual plugin API you must implement as of this writing is version 004. To see a description of each of the functions, you can view the doxygen information here. Note that the Load, Unload, Pause, and Unpause functions allow you to refuse the action and copy an error message (you should check to make sure error is not NULL - it can be).

=SourceHook (Hooking)=
SourceHook is the engine used to intercept function calls, much like Metamod. The difference with SourceHook is that it can intercept any virtual function in any class that, at compile time, you have the header for. 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 can safely remove it.

For example, let's say you wanted to intercept log messages in VEngineServer. Observe the prototype:
<pre>
virtual void LogPrint( const char *msg ) = 0;
</pre>
This is a virtual, public function of a class we have an instance of (let's say in IVEngineServer *m_Engine) and that we have the header for. It can be intercepted.

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 *);
</pre>
This line must appear outside of a function. It means "Declare a hook prototype for LogPrint in IVEngineServer, which is a void function that has one parameter, which is a const char *".

Next we must actually hook the function. You can do this wherever you want to begin the interception. The two macros for hooking look like this:

*{{bcode|SH_ADD_HOOK_STATICFUNC}}(class, memberfunction, instance_pointer, handler, post Hooks a virtual function to a static/global function.
**class - The name of the class
**memberfunction - The name of the member function
**instance - A pointer to an instance of the class
**handler - Your function that will be called on hooking
**post - true for post operation, false for pre operation
*{{bcode|SH_ADD_HOOK_MEMFUNC}}(class, memberfunction, instance, myinstance, myfunction, post) Hooks a virtual function to a member function of another class.
**class - The name of the class
**memberfunction - The name of the member function
**instance - An pointer to an instance of the class
**myinstance - A pointer to an instance of the class that has the handler member function
**myfunction - The name of the handler member function in your class
**post - true for post operation, false for pre-operation

Let's continue with the example. To hook LogPrint to a function in your class, CMetaHooks (instance, g_MetaHooks), you would use:
<pre>
SH_ADD_HOOK_MEMFUNC(IVEngineServer, LogPrint, m_Engine, &g_MetaHooks, &CMetaHooks::LogPrint, false);
</pre>
To remove the hook (either once it will no longer be unused, or at unload time):
<pre>
SH_REMOVE_HOOK_MEMFUNC(IVEngineServer, LogPrint, m_Engine &g_MetaHooks, &CMetaHooks::LogPrint, false);
</pre>
Now, your function contents will look something like this:
<pre>
void CMetaHooks::LogPrint(const char *msg)
{
//Code here
RETURN_META(MRES_IGNORED);
}
</pre>
Note this return statement. This style of returning is similar to Metamod's, where you can set four different flags to indicate how you would like SourceHook to proceed. In Metamod, this return statement was required. In SourceMM, it is only required if you wish to set a return state other than MRES_IGNORED.

*{{bcode|MRES_IGNORED}} - No states were changed, act as though nothing happened. Original function is still called.
*{{bcode|MRES_HANDLED}} - Something changed, but the original function was still called. This can be used to tell another plugin that you did something.
*{{bcode|MRES_OVERRIDE}} - The original function will still be called, but your return value will override whatever it returns.
*{{bcode|MRES_SUPERCEDE}} - The original function is not called, and your return value will be what is returned to the caller.

Note, that if you need to return a value, there is another macro. For example:
<pre>
RETURN_META_VALUE(MRES_SUPERCEDE, value);
</pre>
This is required for non-void functions, athough the return value is ignored using MRES_IGNORED or MRES_HANDLED.

Alternatively, you can hook to static member functions which has a slightly easier syntax. The DECL_HOOK line does not change. To add the hook:
<pre>
SH_ADD_HOOK_STATICFUNC(IVEngineServer, LogPrint, m_Engine, LogPrint_handler, false);
</pre>
Removing the hook:
<pre>
SH_REMOVE_HOOK_STATICFUNC(IVEngineServer, LogPrint, m_Engine, LogPrint_handler, false);
</pre>
Declaring the handler:
<pre>
void LogPrint_handler(const char *msg)
{
//Code here
RETURN_META(MRES_IGNORED);
}
</pre>
Note that vafmt functions hooked with SourceHook assume that the vafmt is for a printf style string, and that the vafmt occurs at the end. When setting the parameters, you do not include the '...' notation, and SourceHook will vafmt the input string for you (meaning you also don't specify ... in your hooked function).

=Calling Original Functions=
Often it will be necessary for you to call a function that's hooked, however, you don't want the hooks to be included in the calling. For example, if you want to entirely supercede a function and call it yourself from within a hook. To do this, you must request a call class. This is similar to MDLL_x() from Metamod for Half-Life 1.

Continuing with the above example, let's say we want to supercede the original call and log a different message. Assume we also have the pointer m_Engine which is a <tt>IVEngineServer *</tt>.
<pre>
CallClass<IVEngineServer> *Engine_CC = SH_GET_CALLCLASS(m_Engine);

SH_CALL(Engine_CC, &IVEngineServer::LogPrint)("This is a log message!\n");

//When you are done with the pointer..
SH_RELEASE_CALLCLASS(Engine_CC);
</pre>

Because of the complex nature of inheritance, instance pointers, and vtables, this syntax can be quite daunting. You may wish to make macros for specific functions or classes you use quite often, to reduce the amount of typing. For example:
<pre>
//Assuming you have a global pointer g_Engine...
#define ENGCALL(func) SH_CALL(g_Engine, &IVEngineServer::func)

//Then you can do:
ENGCALL(LogPrint)("This is a test!");
</pre>

The syntax of calling class construction is:
*<tt>CallClass<class> *ptr = SH_GET_CALLCLASS(instance);</tt>
**Returns an object which allows you to call the original function. Class is the name of the class which is the target, instance is an instance of that class.
*<tt>SH_CALL(cc_ptr, &class::func)([params])</tt>
**Pass the pointer returned from SH_GET_CALLCLASS as cc_ptr. The target function you call must be passed as a pointer-to-member-function, which takes the form &Class::Function as seen in previous examples. You must then complete the function call by adding a parenthetical parameter expression, even for void functions, which would be ().

=Other Macros=
All of the macros take g_PLAPI as the first parameter. For more information on this, see the global variables section.

*{{bcode|META_CONPRINT}}(const char *msg)
*{{bcode|META_CONPRINTF}}(const char *fmt, ...)
**These two functions are recommended over Msg() for printing to the server console. Msg() does not relay commands back through rcon, and as of this writing Valve does not expose the function which does. To be able to display text through the rcon console (much like HL1), you should use these functions. If SourceMM is unable to extract the function properly, it will automatically default to Msg.
*{{bcode|META_LOG}}(g_PLAPI, const char *msg, ...)
**Logs a message through IVEngineServer::LogPrint(). A newline is automatically added, and msg is formatted as a sprintf() style string.
*{{bcode|META_REGCVAR}}(var)
**Registers a ConCommandBase pointer through SourceMM. The correct way to use this is to create an IConCommandBaseAccessor, and inside RegisterConCommandBase, call the macro on the given ConComandBase. This will ensure that SourceMM correctly detects and unloads your cvars and concommands at the appopriate time. Otherwise, unloading your plugin will cause a crash.
*{{bcode|META_UNREGCVAR}}(var)
**Unregisters a ConCommandBase pointer. This is not needed if you have set up your IConCommandBaseAccessor correctly (and called ConCommandBaseMngr::OneTimeInit()).

=Events System=
The Events System is based on IMetamodListener. By implementing the IMetamodListener class and using g_SMAPI->AddListener, you can watch for certain, low-traffic events. These events are split into three categories:

*Plugin Events let you listen for plugin pauses and unloads. This is important if you're relying on information from another plugin, as you can handle cases where a live plugin has become invalid.
*Game Events are simple events that SourceMM is already hooking and makes available. These are LevelShutdown and LevelInit right now.
*Query Events occur when a factory is used. The four main factories (Engine, GameDLL, FileSystem, and Physics) are all overridable. You should simply return a non-NULL result to override, and fill the return code with IFACE_OK if available. There is no way to handle the case of two plugins overriding right now. The final factory is the Metamod Factory, which is the factory that Metamod:Source adds to the runtime space for plugins. By default, it only contains the interfaces for the PluginManager and SourceHook. Plugins can use this to add new interfaces. Other plugins request these interfaces through g_SMAPI->MetaFactory().

=Global Variables=
These global variables are saved by PLUGIN_EXPOSE and PLUGIN_SAVEVARS. They are declared with PLUGIN_GLOBALVARS.

*{{bcode|g_PLAPI}}
**ISmmPlugin * pointer to your global class singleton.
*{{bcode|g_PLID}}
**The internal PluginId of your plugin.
*{{bcode|g_SHPtr}}
**The SourceHook::ISourceHook * pointer to SourceHook's interface.
*{{bcode|g_SMAPI}}
**The ISmmAPI * pointer to SourceMM's interface.

=Compiling=
To see more about compiling, see the Sample Plugin Compiling section.

Modifying the default Makefiles for your own projects:

*<tt>OPT_FLAGS</tt> - Optimization flags
*<tt>DEBUG_FLAGS</tt> - Debug flags
*<tt>CPP</tt> - C++ Compiler
*<tt>OBJETS</tt> - List of C++ files to compile
*<tt>LINK</tt> - Linker Options
*<tt>CFLAGS</tt> - Base Compiler Flags
*<tt>BINARY</tt> - Output Binary Name

Makefile commands:

*clean - Cleans all build files
*debug - Builds debug version

=1.1 Changes - Late Loading, Events=
SourceMM 1.1 changed quite a few things internally, and externally made many breaking changes. These include:

*ISmmPlugin::Load() has removed the factory list parameter (the factory system was replaced with the event system). Also, a boolean parameter was added, specifying whether the plugin was loaded late or not.
*ISmmPlugin::Load() is now called BEFORE DLLInit(), rather than after. This means it might not have all information it needs -- for example, IGameEvents won't be parsed yet. You will need to do things like this in ISmmPlugin:AllPluginsLoaded() instead, as it is guaranteed to occur when all DLLs are initialized.
*ISmmPlugin now has default functions -- you don't have to implement all of them.
*SourceHook was modified to use interfaces rather than straight struct pointers. This breaking changes will ensure that future SourceHook modifications do not break older plugins.
*SourceHook was modified to be re-entrant.
*SourceHook now has a tiny template library with it. This removes the necessity to link against libstdc++.so.*, which harms binary compatibility across linux distributions.
*SourceMM's GameDLL code was completely rewritten. It will now work with newer mods much easier, and issues like the DoD:S release will be much easier to deal with (if at all). It also removes a few important speed bottlenecks.
*An events system was added.

=1.2 Changes - Changing Parameters, Manual Hooking=
SourceMM 1.2 now supports changing the parameters in a hook chain. For example, say the GameDLL has a function called IGameDLL::PrintString(const char *str). You can hook this, let it continue, but change the "str" parameter passed in to the rest of the hooks and the GameDLL. To do this, use the following macros:

*<tt>RETURN_META_NEWPARAMS</tt>
*<tt>RETURN_META_VALUE_NEWPARAMS</tt>

Example:
<pre>
class ISomething
{
virtual void Function1(int num) =0;
virtual bool Function2(bool what, int hi) =0;
}

void MyHook1(int num)
{
//if num is 0,
// we will change the num parameter in the rest of the hooks, and the gamedll, to be 1.
if (num == 0)
RETURN_META_NEWPARAMS(MRES_IGNORED, &ISomething::Function1, (1))
RETURN_META(MRES_SUPERCEDE);
}

bool MyHook2(bool what, int hi)
{
//change the "what" and "hi" parameters to be false and 3 respectively
//also, return true, but specify that the value is ignored
RETURN_META_VALUE_NEWPARAMS(MRES_IGNORED, true, &ISomething::Function2, (false, 3));
}
</pre>
SourceHook also supports manual hooking of functions. This means you must know the virtual table index, the virtual table offset (for polymorphism), and the "this" pointer offset. Luckily, the polymorphic offsets are usually zero. This type of hook is ideal when supporting different ABI, for example, across different gamedlls. The API is almost identical:

*<tt>SH_DECL_MANUALHOOKn[_void|_vafamt]</tt> -
**Declares the manual hook. A unique name must be given to each manual hook.
*<tt>SH_[ADD|REMOVE]_MANUALHOOK_[STATIC|MEM]FUNC</tt> -
**Adds or removes a static or member function hook on a manually declared hook.
*<tt>SH_MANUALHOOK_RECONFIGURE</tt> -
**Reconfigures the indexes and offsets of a manual hook.

An example is below, using the ISomething class from above.

<pre>
SH_DECL_MANUALHOOK2(_M_Function1, 1, 0, 0, bool, bool, int);

void OnLoad(ISomething *pSomething)
{
//we reference the static function by its unique handle we gave it
//the parameters are otherwise the same - this pointer, hook handler, and post/non-post
SH_ADD_MANUALHOOK_STATICFUNC(_M_Function1, pSomething, MyHook1, false);
}

void OnUnload(ISomething *pSomething)
{
SH_REMOVE_MANUALHOOK_STATICFUNC(_M_Function1, pSomething, MyHook1, false);
}
</pre>

For more examples of the above features, you can look in SourceHook CVS's [http://www.tcwonline.org/cgi-bin/viewcvs.cgi/sourcemm/sourcehook/test/ test suite], which demonstrates a variety of hooking scenarios.

[[Category:SourceHook]]
[[Category:Documentation (SourceMM)]]

User:Mrmagu

2006-01-17T11:52:23Z

Mrmagu:

is a nub :] and wants someone to add the damn syntax highlighter extention already :)

C++ Highlighted test.. 

#ifndef SIGSCAN_H
#define SIGSCAN_H 
class CSigScan {
private:
/* Private Variables */
/* Base Address of the server module in memory */
static unsigned char *base_addr;
/* The length to the module's ending address */
static size_t base_len; 
/* The signature to scan for */
unsigned char *sig_str;
/* A mask to ignore certain bytes in the signature such as addresses
 The mask should be as long as all the bytes in the signature string
 Use '?' to ignore a byte and 'x' to check it
 Example"xxx????xx" - The first 3 bytes are checked, then the next 4 are
 ignored, then the last 2 are checked */
char *sig_mask;
/* The length of sig_str and sig_mask (not including a terminating null for sig_mask) */
size_t sig_len; 
/* Private Functions */
void* FindSignature(void); 
public:
/* Public Variables */ 
/* sigscan_dllfunc is a pointer of something that resides inside the gamedll so we can get
 the base address of it. From a SourceMM plugin, just set this to ismm->serverFactory(0)
 in Load(). From a Valve Server Plugin, you must set this to an actual factory returned
 from gameServerFactory and hope that a SourceMM plugin did not override it. */
static void *(*sigscan_dllfunc)(const char *pName, int *pReturnCode); 
/* If the scan was successful or not */
char is_set;
/* Starting address of the found function */
void *sig_addr; 
/* Public Functions */
CSigScan(void)sig_str(NULL), sig_mask(NULL), sig_len(0), sig_addr(NULL) {}
~CSigScan(void); 
static bool GetDllMemInfo(void);
void Init(unsigned char *sig, char *mask, size_t len);
}; 
void InitSigs(void); 
/* Sig Functions */
class CBaseAnimating;
void CBaseAnimating_Ignite(CBaseAnimating *cba, float flFlameLifetime); 
#endif

User:Mrmagu

2006-01-16T05:20:45Z

Mrmagu:

is a nub :]

C++ Highlighted test.. 

#ifndef SIGSCAN_H
#define SIGSCAN_H 
class CSigScan {
private:
/* Private Variables */
/* Base Address of the server module in memory */
static unsigned char *base_addr;
/* The length to the module's ending address */
static size_t base_len; 
/* The signature to scan for */
unsigned char *sig_str;
/* A mask to ignore certain bytes in the signature such as addresses
 The mask should be as long as all the bytes in the signature string
 Use '?' to ignore a byte and 'x' to check it
 Example"xxx????xx" - The first 3 bytes are checked, then the next 4 are
 ignored, then the last 2 are checked */
char *sig_mask;
/* The length of sig_str and sig_mask (not including a terminating null for sig_mask) */
size_t sig_len; 
/* Private Functions */
void* FindSignature(void); 
public:
/* Public Variables */ 
/* sigscan_dllfunc is a pointer of something that resides inside the gamedll so we can get
 the base address of it. From a SourceMM plugin, just set this to ismm->serverFactory(0)
 in Load(). From a Valve Server Plugin, you must set this to an actual factory returned
 from gameServerFactory and hope that a SourceMM plugin did not override it. */
static void *(*sigscan_dllfunc)(const char *pName, int *pReturnCode); 
/* If the scan was successful or not */
char is_set;
/* Starting address of the found function */
void *sig_addr; 
/* Public Functions */
CSigScan(void)sig_str(NULL), sig_mask(NULL), sig_len(0), sig_addr(NULL) {}
~CSigScan(void); 
static bool GetDllMemInfo(void);
void Init(unsigned char *sig, char *mask, size_t len);
}; 
void InitSigs(void); 
/* Sig Functions */
class CBaseAnimating;
void CBaseAnimating_Ignite(CBaseAnimating *cba, float flFlameLifetime); 
#endif

User:Mrmagu

2006-01-16T05:13:00Z

Mrmagu:

is a nub :]

C++ Highlighted test.. 

#ifndef SIGSCAN_H
#define SIGSCAN_H

class CSigScan {
private:
/* Private Variables */
/* Base Address of the server module in memory */
static unsigned char *base_addr;
/* The length to the module's ending address */
static size_t base_len;

/* The signature to scan for */
unsigned char *sig_str;
/* A mask to ignore certain bytes in the signature such as addresses
 The mask should be as long as all the bytes in the signature string
 Use '?' to ignore a byte and 'x' to check it
 Example"xxx????xx" - The first 3 bytes are checked, then the next 4 are
 ignored, then the last 2 are checked */
char *sig_mask;
/* The length of sig_str and sig_mask (not including a terminating null for sig_mask) */
size_t sig_len;

/* Private Functions */
void* FindSignature(void);

public:
/* Public Variables */

/* sigscan_dllfunc is a pointer of something that resides inside the gamedll so we can get
 the base address of it. From a SourceMM plugin, just set this to ismm->serverFactory(0)
 in Load(). From a Valve Server Plugin, you must set this to an actual factory returned
 from gameServerFactory and hope that a SourceMM plugin did not override it. */
static void *(*sigscan_dllfunc)(const char *pName, int *pReturnCode);

/* If the scan was successful or not */
char is_set;
/* Starting address of the found function */
void *sig_addr;

/* Public Functions */
CSigScan(void)sig_str(NULL), sig_mask(NULL), sig_len(0), sig_addr(NULL) {}
~CSigScan(void);

static bool GetDllMemInfo(void);
void Init(unsigned char *sig, char *mask, size_t len);
};

void InitSigs(void);

/* Sig Functions */
class CBaseAnimating;
void CBaseAnimating_Ignite(CBaseAnimating *cba, float flFlameLifetime);

#endif

User:Mrmagu

2006-01-16T01:10:13Z

Mrmagu: About

is a nub :]