Sample Plugins (Metamod:Source)

Metamod:Source comes with two sample plugins: stub and sample. This article is a brief overview of how to read and compile them. They are intended as a baseline for developing your own plugins, though they are certainly not required for your own development.

Metamod:Source is a C++ environment, but this is not a C++ tutorial. You should have sufficient knowledge of computer organization (memory, pointers, addressing) and intermediate experience with C++. Most importantly, you should be willing to dive into header files to research API definitions (which is necessary for the HL2SDK regardless).

Make sure to read the overview article, Metamod:Source Development.

Introduction

Before you begin, you should set up your Metamod:Source Environment. If you fail to complete this step, it is unlikely much else in this article will work for you.

The two sample plugins provided are:

• stub_mm - Bare-bones plugin that does almost nothing.
• sample_mm - More complete example plugin which implements a few things that Valve's serverplugin_sample does, such as hooking functions, creating ConVars, console commands, and showing dialog boxes.

The Engine Divide

The Orange Box and Episode 1 engines are not compatible, and thus there is a division:

• Metamod:Source 1.4/Episode 1
• Metamod:Source 1.6/Orange Box

Unfortunately, there is a "lag period" where not all games have moved to the new engine. It is likely that this lag period will continue for at least another twelve months (this writing is as of February 2008). As such, we are writing all of our plugin code such that it compiles against both platforms. It is your choice whether to do this as well. As the usage of Metamod:Source 1.4 and the original engine decays, we will begin removing the legacy cruft from the sample plugins. That probably won't happen until Valve has a stable port of CS:S to Orange Box.

As such, you will notice various idiosyncracies in the sample plugins. For example, METAMOD_PLAPI_VERSION exists in Metamod:Source 1.6 or later, so it is used to decide between GetEngineFactory (1.6) or engineFactory (1.4). Similarly, the sample plugins use two macros:

• ENGINE_ORANGEBOX - Orange Box build
• ENGINE_ORIGINAL - Original/Episode 1 build

These two macros are used in a few places to toggle functionality compatible for the given build.

For more information, see:

• Upgrading Plugins to Metamod:Source 1.6.0
• Porting to Orange Box

Compiling

Windows

Both plugins have a Visual Studio 2005 project file in their msvc8 folders. Each plugin has four build modes:

• Release - Orange Box - Release mode, Orange Box, MM:S 1.6
• Debug - Orange Box - Debug mode, Orange Box, MM:S 1.6
• Release - Original - Release mode, Original/Episode1, MM:S 1.4
• Debug - Original - Debug mode, Original/Episode1, MM:S 1.4

There exists normal "Release" and "Debug" build modes -- you should not use them, as they are not configured.

Linux

On Linux, you cannot simply type "make" in the folder containing the Makefile. You must specify a combination of parameters:

• ENGINE - Required. Must be either "orangebox" or "original".
• DEBUG - Optional. Can be empty (Release mode) or "true" (Debug mode).

Binaries and object files will be written to one of the following folders:

• Release.orangebox
• Debug.orangebox
• Release.original
• Debug.original

Examples of building one of the example plugins:

#MM:S 1.4/Episode 1, debug mode
make DEBUG=true ENGINE=original
#MM:S 1.6/Orange Box, release mode
make ENGINE=orangebox
#Cleaning the MM:S 1.4 build
make clean ENGINE=original

Note that you may need to edit the folder locations at the top of the Makefile, in case you set up your paths differently.

Stub Plugin

The stub plugin is a very simple, bare-bones plugin. It has little, if anything, beyond an implementation of the required API callbacks.

It hooks one function, IServerGameDLL::ServerActivate, which is a callback fired after IServerGameDLL::LevelInit.

Note that for the most part, stub_mm is free of compatibility cruft, whereas sample_mm tries to abstract more. This is so stub_mm doesn't appear to be "hiding" anything -- it's laid out very simply.

Sample Plugin

The full sample plugin is a bit more complicated, as it contains some of the examples from Valve's serverplugin_sample. It also may be a bit messy to read because of the engine compatibility wrappers in it.

Compatibility Wrappers

The first file of importance is engine_wrappers.h, which is full of compatibility shims. For example:

• engineFactory became GetEngineFactory from 1.4 to 1.6
• serverFactory became GetServerFactory from 1.4 to 1.6
• ISmmAPI::Format did not exist in 1.4, so we created a simple #define to use snprintf instead. You could also use Valve's Q_snprintf if you desired.
• Valve renamed VENGINE_CVAR_INTERFACE_VERSION to CVAR_INTERFACE_VERSION from Episode 1 to Orange Box.
• The syntax to SH_CALL changed from 1.4 to 1.6 (which we have demonstrated for completeness and will be explained later).

Also note the CCommand class. This is a wrapper around the IVEngineServer::Cmd_Arg* functions, which were removed in Orange Box. Valve replaced it with a newer, more re-entrant set of functions based around CCommand. Rather than create two codebases, we've simply wrapped the old functions in the new API. The functionality isn't exactly the same (becaose of re-entrancy), but it works nicely for our purposes. You can read more about this trick in Porting to Orange Box.

Overview

BaseAccessor

This is a singleton class responsible for registering anything extending from ConCommandBase (ConVar and ConCommand). You only need one, and it should wrap META_REGCVAR.

Note that the accessor is invoked differently based on the engine version. For Orange Box, g_pCVar is assigned and ConVar_Register is called, whereas on Episode 1, only ConCommandBaseMgr::OneTimeInit is needed.

CallClasses

SourceHook has a feature where you can invoke a virtual function while bypassing all hooks on it. In SourceHook v4 (Metamod:Source 1.4 and lower), SH_CALL required a special object called a call class. This was removed in SourceHook v5. However, to be compatible with both MM:S 1.4 and 1.6, the sample plugin creates and destroys a call class when necessary.

For more information on this syntax and what it means, see: Sourcehook Development#Bypassing_Hooks.

Note that the ENGINE_CALL macro is in engine_wrappers.h, and wraps SH_CALL based on the MM:S version.

VSP Listening

Some of the sample functionality requires an IServerPluginCallbacks pointer, and Metamod:Source can provide one for you.

In Metamod:Source 1.4, you had to implement IMetamodListener, and do something like this:

		ismm->AddListener(this, this);
		ismm->EnableVSPListener();

Then you had to wait for the callback to give you a correct pointer. In Metamod:Source 1.6, you can attempt to get the point immediately with:

if ((vsp_callbacks = ismm->GetVSPInfo(NULL)) == NULL)

Hooked Functions

The sample plugin hooks most of the functions available to IServerPluginCallbacks, in order to show you how to re-implement Valve's functionality.

Recall a few concepts:

• In SourceHook, hooks can either be "pre" (pre-empting the final call), or "post" (occurring after the pre hooks and final call, if any).
• In Valve Server Plugins, only hooks labeled with PLUGIN_RESULT can override functionality. SourceHook, however, can override the functionality of any function. The default action is to continue (or pass-through), though there are options to override and supercede (see the Sourcehook Development#Hook_Functions for more information).
• A hook with a return value must return a value, or else the compiler will complain. However, unless you use RETURN_META_VALUE with MRES_SUPERCEDE or MRES_OVERRIDE, the value will not affect anything.

The following are generic hooks that Valve Server Plugins cannot override, so in the example they're hooked as post.

• IServerGameDLL::LevelInit: Translates to LevelInit.
• IServerGameDLL::ServerActivate: Translates to ServerActivate.
• IServerGameDLL::GameFrame: Translates to GameFrame.
• IServerGameDLL::LevelShutdown: Translates to LevelShutdown. (This is not actually hooked false in the example, but you probably shouldn't try overriding it.)
• IServerGameClients::ClientActive: Translates to ClientActive. Not a very useful callback, not recommended for real work.
• IServerGameClients::ClientDisconnect: Translates to ClientDisconnect. Called when the client disconnects.
• IServerGameClients::ClientPutInServer: Translates to ClientPutInServer. Called when the client is put in-game and is fully instantiated (that is, IPlayerInfoManager will return valid results).
• IServerGameClients::SetCommandClient: Translates to SetCommandClient. Called when a console command bound to a ConCommand is invoked, to tell all listeners which client typed the command. The index supplied is the client index minus one (that is, -1 for the server console, 0 for the first client, et cetera).

The following hooks are pre-empted, and thus can be overridden or superseded:

• IServerGameClients::ClientSettingsChanged: Translates to ClientSettingsChanged. Called when a client's info buffer changes (that is, anything from IVEngineServer::GetClientConVarValue). Overriding it will prevent the game from being notified.
• IServerGameClients::ClientConnect: Translates to ClientConnect. Called when a client is connecting. You can override/supersede with a value of false to reject the client (note, of course, you should fill the rejection message buffer).
• IServerGameClients::ClientCommand: Translates to ClientCommand. Called when the client types unrecognized text in their client console. If you don't override this function, the original game's handler will be called. If the game doesn't recognize the text, it will print "Unknown command" or something similar. Therefore, if you wish to block this text from appearing, you should supercede when you recognize the text. The sample plugin shows how to do this for a few commands.

The VDF Files

Note that both stub_mm and sample_mm come with their own VDF files. These are example files that load their respective binaries from the addons folder. Make two notes about this:

• VDF files go in Metamod's folder. That is, addons/metamod (or whatever mm_basedir is). They are not Valve Server Plugin files and they cannot go in the addons folder.
• If your plugin has more than one file, or it creates other files, it may be prudent to place it in its own sub-folder. The sample plugins are small and thus we placed the binaries in addons for simplicity. The extended convention for more complicated plugins is:
  • addons/NAME/bin/NAME_mm.dll or addons/NAME/bin/NAME_mm_i486.so. For example, addons/sourcemod/bin/sourcemod_mm is SourceMod's VDF path, since it has a large directory structure.
  • Note: This convention is not required, but it is recommended.