Metamod:Source

This project is owned by the Consortium that controls this wiki. Changes to this main page are allowed but patrolled.

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 "Metamod:Source 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.

Where to Download

Metamod:Source is hosted on Source Forge or can be accessed via the Metamod:Source Home Page.

Naming Conventions

The name "SourceMM" is no longer used.

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.

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 PM concentrated on fleshing out SourceHook, BAILOPAN and 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 Metamod:Source. The fake interface then directly wrapped calls to the real GameDLL.

Version 1.1

On October 21, 2005, the first major revision of Metamod:Source was released, featuring SourceHook v4.4, internal event listeners, dropped reliance on STL, and rewritten GameDLL hooking code. The 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 MM:S's detection was improved for compatibility and speed. Furthermore, Metamod:Source stopped wrapping the GameDLL interfaces and began using SourceHook to hook them.

Version 1.2

On January 7th, 2006, Metamod:Source was updated for SourceHook v4.3, but received no major API changes.

Version 1.3

On August 16th, 2006, Metamod:Source was updated for SourceHook v4.4, minor API changes, bug fixes, and a sync to the latest HL2SDK.

Version 1.4

On April 5th, 2007, Metamod:Source was updated with API for Valve Server Plugin interface hooking and crash-safe user message enumeration. An experimental gameinfo.txt update tool was also added. No SourceHook changes were made in this release.

Version 1.6

Metamod:Source received a near complete overhaul to abstract engine-specific code to support Orange Box. Additionally, SourceHook received a massive overhaul and is now v5.0, adding global hooks and various major API simplifications. It is the first backwards compatibility break since 1.1.

Version 1.7

Major update -- it is a single version that runs on all Source engines, including Left 4 Dead. There is no longer an automated installer.

Version 1.7.1

Added support for Dark Messiah

Version 1.8

Major update that adds a number of new features for both users and developers. The first official release that supports the Left 4 Dead 2 engine. For developers, backport of a few New API features to the Legacy API. This includes SourceHook's extremely useful "VP hooks" feature.

Version 1.8.1

Updated to work with the latest L4D2, TF, and DoD:Source updates

Version 1.8.4

• Added support for Alien Swarm.
• Added support for L4D and L4D2 on Mac OS X.
• Fixed wrong engine detection on early Orange Box engines.
• Fixed a crash when hooking some functions compiled by very new GCC versions.

Version 1.8.5

Small bug-fix release to work with the latest Orange Box engine update (TF2, CS:S, DOD:S, HL2DM, and Garry's Mod).

Version 1.8.6

Small bug-fix release to work with the latest Orange Box engine update (TF2, CS:S, DOD:S, HL2DM, and Garry's Mod). Added support for Bloody Good Time.

Version 1.8.7

Small bug-fix release to work with the latest Orange Box engine update (TF2, CS:S, DOD:S, HL2DM, and Garry's Mod).

Version 1.9

The first official release that supports the Counter-Strike: Global Offensive engine. In addition, CS:S is now treated as a separate engine from 'EP2V'.

Version 1.9.1

• Fixed core-legacy crash on hook from making wrong page writable.
• Updated loader to attempt to guess correct tier0/vstdlib filenames on linux, fixing load on ep2v engine.
• Recompiled against new hl2sdk-ob-valve to fix vdf plugin loading on ep2v engine.

Version 1.9.2

• Fixed load issues on CS:GO after protobuf networking game update (bug 5578).
• Fixed load issues on CS:S under linux after game update.

Version 1.10

Major update that adds support for a new engines, reorganizes others, and contains general bugfixes. The first official release that supports the Dota 2 engine. In addition, the 'EP2V' engine is no more. TF2, DoD:S, and HL2:DM now each act as their own. Nuclear Dawn is also now separate from Left 4 Dead 2.

Version 1.10.1

• Added support for Source SDK 2013 mods, Insurgency, Contagion, and Blade Symphony.
• Updated Dota 2 support to add Linux and Mac OS X support.
• Improved engine detection when '-game' launch param is not present

Version 1.10.2

Fixes a regression from 1.10.1 causing engine detection on Alien Swarm to fail, as well as improving detection for some games when the '-game' command line parameter is not present (such as when using the SRCDS GUI).

Version 1.10.3

Resolves issues with recent game updates to Team Fortress 2 and Counter-Strike: Global Offensive.

Version 1.10.4

Resolves issues with recent game updates to Team Fortress 2.

Version 1.10.5

• Added support for Black Mesa.
• Updated support for recent CS:GO game updates.
• Fixed game detection issues on Nuclear Dawn.

Version 1.10.6

Small update to restore support for TF2, CS:S, DoD:S, HL2:DM, and Source SDK Base 2013 after their recent updates.

Move to Rolling Release Model

As of Apr 27, 2017 Metamod:Source, like SourceMod, is now officially on a rolling release cycle.

• There won't be any more "point" releases (1.10.7, etc). Instead, we're going to continue to make an effort to keep the stable branch stable, and better relay information about what has changed in each build.
• Major releases with potential API breakage will still occur and will still have release notes, along with continued updates even after the branch is considered to be stable.
• Some of the recent, potentially-breaking changes in the Dev branch include support for Source 2, support for 64-bit dedicated servers, and removal of the old v1.4 "ep1" plugin API. (The newer v1.6 API is now used for The Ship and Source SDK 2006 mods).

Version 1.11

• Fixed linking errors with some compilers when MM:S plugins call functions in tier1 interface.h
• Added support for the following engine variants: Source SDK 2013, Blade Symphony, Insurgency, Contagion, Black Mesa, and Day of Infamy.
• Updated Dota 2 support for the move to Source 2 from Source. (Currently broken due to other game changes since then).
• Added 64-bit support for games with supported 64-bit dedicated server versions, including 64-bit support in SourceHook.
• Ported Episode 1 build from Core Legacy API to Core API.
• Removed support for plugins using the "Core Legacy" API.
• Updated AMBuild dependency to version 2.2.

Version 1.12

• Improved 64-bit support
• Improved support for mods running on the 2025 refresh of Source SDK 2013
• Improved support for HL1DM
• Added support for Military Conflict: Vietnam and Pirates, Vikings, and Knights II

Version 2.0

Currently in development, where Source 2 support continues to be refined, among other larger changes.

Design Considerations

Metamod

Originally, Metamod:Source 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 Metamod:Source 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 Metamod:Source might not directly control. For example, when a Metamod:Source 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 MM:S plugins also have different ways of attaching and detaching server cvars and concmds.

By keeping the plugin system isolated, Metamod:Source 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

Metamod:Source 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 Metamod:Source has a number of features that don't exist in a hooking system style like Metamod's, and it achieves something closer to 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 Metamod:Source, see Documentation.

The Future

While Metamod:Source is a stable/production product, more features are on the horizon. There are distant plans for a detouring library and a library for efficiently automated signature scanning.

License

Metamod:Source is licensed under the zLib/libpng License. It is free to use for both open-source and proprietary projects.

External Links

• Metamod:Source Website
• Metamod Website
• SourceMod Website
• Doxygen of Metamod:Source