Metamod:Source: the plugin environment under the Source engine

A plugin environment, not a plugin

Metamod:Source is a C++ plugin environment and detour library for the Source engine. That single line sets the scope of the project.

A plugin environment is the layer that sits between the game server and the plugins. The game server has to be started in a particular way for the layer to be loaded, the layer provides a stable API that plugins compile against, and the layer can intercept and redirect calls inside the engine itself, which is what the detour library half refers to. Metamod does not add gameplay, it adds the place where gameplay extensions live.

The relationship to SourceMod is worth being clear about, since the two names get used interchangeably. Metamod:Source is the environment itself. SourceMod is the plugin framework built on top of it, with its own scripting language and its own API, and the SourceHook page linked from the README is the detouring library that plugins use to hook engine functions. So Metamod is the layer, SourceMod is one of the things people build on that layer, and SourceHook is the mechanism.

The project lives in the AlliedModders organisation, and the same name appears on the repository, the wiki and the download site. The topic tags are hacktoberfest, metamod, modding and source-engine, which places it squarely in the server side of the Source modding scene.

The primary language recorded for the repository is Pascal, which is a peculiarity worth flagging rather than reading too much into. It reflects what the language statistics tool counts, and it is a reminder that a language statistic on a build-tooling repository tells you very little about how the shipped binary is written. The project describes itself as C++.

The licence is one GitHub cannot classify, with the terms in a LICENSE.txt file at the repository root, and the site is metamodsource.net.

The build needs ambuild2, a Python configure step and the engine SDKs

The build instructions in the README are short enough to follow exactly, and each step exists for a reason.

The first requirement is ambuild2, from the alliedmodders/ambuild repository. The script for the build itself lives in the repository root as AMBuildScript, which is what ambuild reads, and the configuration script is configure.py, which is what generates the build files. That split is the ambuild model: a Python configuration script produces a build graph, and ambuild2 executes it.

The checkout step is:

git clone --recurse-submodules https://github.com/alliedmodders/metamod-source

The submodules are needed, and the second script fetches the rest of the dependencies:

cd ..
metamod-source/support/checkout-deps.sh
cd metamod-source

The script lives in the `support/` directory, and what it does is fetch the engine SDK dependencies. This is the part that makes the project what it is. The Source engine is not open source, so its headers and libraries are distributed as SDK packages, and a plugin environment that hooks engine internals has to be compiled against those exact headers. The build therefore depends on artefacts that are not in the repository.

Then the configuration and the build:

mkdir build
cd build
python ../configure.py

followed by:

ambuild

The pattern is build out of tree. The build directory is separate from the source tree, the configuration script is run from inside it with a relative path back to the source, and ambuild is then run in the same directory. Nothing is written into the source tree, which is what lets the same checkout be configured for several SDKs in separate build directories.

The README also documents stable and development build snapshots on the download site, on separate branches, which is the escape hatch for anyone who needs a binary rather than a build. The wiki links cover general documentation, SourceHook development and Metamod:Source development.

Building for one SDK instead of all of them

The two extra commands in the README are the ones that matter for anyone who has actually tried this build, because the default configuration is slow.

The dependency script accepts a single SDK name:

cd ..
metamod-source/support/checkout-deps.sh -s episode1
cd metamod-source

and the configuration script accepts the same kind of restriction:

mkdir build
cd build
python ../configure.py --sdks episode1

The example given is `episode1`, so the SDK set covers more than one engine generation. The point of the option is that fetching and compiling against several SDKs is a substantial cost, and a developer working on one engine branch should not pay it every time.

The two commands take the same argument, which is convenient but also slightly easy to get wrong. The dependency script fetches what the configure step will then look for, so the names have to agree. Doing one without the other gives you either missing dependencies or a configuration that cannot find an SDK it expects.

The `hl2sdk-manifests/` directory at the repository root is where the list of known SDKs and their versions lives, and the fact that it is a directory rather than a file suggests there are several manifest formats, since the SDKs have been distributed in more than one way over the years. The `versionlib/` directory at the root is the version library, which is the shared component that knows how to report and compare version numbers, and `product.version` is the version file for the project itself.

For the version numbers themselves, the release history shows the scheme in use. The latest listed releases are 2.0.0.1483 and 2.0.0.1482, both from 2026-10-18, and 1.12.0.1228 from 2026-10-17. The trailing number increments on every build, which is what a CI-driven release process looks like, and the 1.12 to 2.0 jump alongside it is the kind of major version change that the project handles with a branch for stable snapshots and one for master.

What the directory layout tells you

The top level listing is short and each entry names a distinct concern, which makes it a reasonable map of the codebase.

`core/` is the core of the plugin environment, and `loader/` is the part that gets loaded into the game server process. That division is the architectural point of the whole project: a loader has to be small, has to be loaded early, and has to be able to bring the rest of the system up. The `public/` directory holds the headers that plugins compile against, which is the API surface, and `public/` being public rather than `include/` is the AlliedModders convention across their projects.

`third_party/` holds vendored dependencies, `versionlib/` the version handling, and `support/` the scripts and helpers, including the dependency checkout script that the build depends on. `cruft/` is a directory name that means what it says, older code kept around for reference rather than built. `samples/` holds the sample plugins, split into `s1_sample_mm/` and `s2_sample_mm/`, which given the naming are the two stages of the plugin lifecycle, a single-header plugin and a multi-file one.

Those samples are the most useful thing in the tree for a new contributor, because a plugin environment is a strange thing to learn from documentation alone. A sample that compiles against the public headers shows you the shape of a plugin, what the entry point looks like and what the environment provides, and there are two of them so you can see the difference between the minimal case and the fuller one.

The CI configuration is visible as well, with a `.travis.yml` and an `appveyor.yml`. Both are the older generation of CI services, which for a project of this vintage is consistent, and the `pushbuild.txt` file at the root is the build script for the push build, the CI build that produces the numbered release artefacts.

Who this is for, and what a game server operator actually gets

It is worth being clear about the two audiences the project has, because they use it very differently.

The first is the server operator. They want a Metamod binary and a plugin framework on top of it, and they do not care how the detouring works. The download page offers stable build snapshots and development build snapshots on separate branches, and a stable build is what an operator should be running. The wiki is where the general documentation lives.

The second is the developer writing a plugin. For them the project is an API, the public headers, plus the SourceHook detouring library documented separately. The samples directory is the starting point, and the Metamod:Source Development wiki category is where the internals are explained.

A third audience exists and the hacktoberfest topic tag points at it: contributors who want a small, well-defined change to make. That is a deliberate signal about how the project is maintained.

The comparison worth drawing is with the alternative of not having a plugin environment at all. A Source server without one is a fixed piece of software. Adding one gives you the ability to change behaviour at runtime, and to do it without recompiling the server, which is what makes plugins like anti-cheat adjustments, gameplay tweaks, logging tools and admin conveniences possible on a running server.

The cost is real and it is worth naming. The plugin environment sits inside the game server process, so a fault in a plugin takes the server with it, and the environment has to be trusted to keep the server stable while it rewrites calls the engine makes. Metamod's release history, with two builds on the same day and a fourth digit that increments on every push, is the shape of a project that is constantly being adjusted against a moving target, since the Source engine itself changes and the environment has to keep up.

For a server operator, the practical questions are which SDKs you need, whether you are running the stable branch or the development branch, and what the plugin ecosystem you want requires. For a developer, they are which SDK you are targeting and whether the public API covers what you need, or whether you are going to have to detour into the engine with SourceHook.

Editorial conclusion

Adopt Metamod:Source if you run a Source engine game server and need a plugin layer, since it is the environment the SourceMod ecosystem is built on rather than a plugin itself. Do not expect a build from a single checkout to work without the SDK dependency script, because the compiler flags, headers and libraries come from the engine SDKs that support/checkout-deps.sh fetches, and check first which SDKs you actually need, since the default configuration pulls several of them and the script and configure.py both accept a single SDK name to keep the build time down.

Frequently asked questions

Official sources

1. alliedmodders/metamod-source on GitHub
2. Issues
3. Project website
4. README
5. Releases