MM:S API Differences

Metamod:Source broke API compatibility when adding Orange Box support. The old API was not maintainable. This article describes the changes from the 1.4 API to the 1.6 API (core-legacy versus core).

If you want to write a Metamod:Source plugin that works against both engines, ultimately you must take care to make sure it compiles against both APIs.

Metamod API History

Metamod:Source contains two APIs, the "1.6 API" (contained in core) and the "1.4 API" (contained in core-legacy).

As the name suggests, the 1.4 API is legacy and is only used on the Episode 1 engines and older. The 1.6 API is used on all new engines, including Orange Box (for TF and DoDS) and Left 4 Dead.

Unfortunately, the APIs are not compatible. Some functions were removed and others were renamed. For this reason it is not easily possible to compile a single binary that works on both. However, there is an advanced loading API that allows you to to route load requests to alternate binaries. This allows you to distribute unified packages. This is explained later in this article.

What to Use

• 1.4 API, contained in core-legacy. This is the API you should use if you're building a plugin to run on the following Source engines:
  • Episode 1 (CS:S, and third party mods).
  • Original (The Ship)
• 1.6 API, contained in core. This is the API you should use if you're building against the following Source engines:
  • Orange Box (Team Fortress, Day of Defeat, Garry's Mod)
  • Left 4 Dead

Renamed Calls

Transparent

The following functions were renamed. These changes are masked by the META_REGCMD and META_REGCVAR macros and should not affect anyone.

• RegisterConCmdBase() -> RegisterConCommandBase()
• UnregisterConCmdBase() -> UnregisterConCommandBase()

Breaking

oslink.h was renamed to metamod_oslink.h. This file is not a public file and should not be included, so it may be removed in the future.

The following functions have received simple renamings, however, old code will be affected.

• pGlobals() -> GetCGlobals
• engineFactory() -> GetEngineFactory()
• serverFactory() -> GetServerFactory()
• physicsFactory() -> GetPhysicsFactory()
• fileSystemFactory() -> GetFileSystemFactory()

For example, GET_V_IFACE_CURRENT would change from this:

GET_V_IFACE_CURRENT(engineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);

To this:

GET_V_IFACE_CURRENT(GetEngineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);

Removed Calls

A few API calls have been completely removed.

• RemotePrintingAvailable() - Unused, no purpose.
• GetCvarBaseAccessor() - Unused, no purpose.
• SetLastMetaReturn() - Did nothing.
• GetLastMetaReturn() - Did nothing.

SH_GET_CALLCLASS and SH_RELEASE_CALLCLASS have been removed. For more information, see the updated SH_CALL syntax.

Changed Calls

• IPluginManager::Query() and IPluginManager::QueryHandle() now store return values using optional pointers instead of references. This change was requested by a few people.

SH_CALL and SH_MCALL are changed - the concept of "CallClasses" has been removed, and these macros are now much simpler. See the updated SH_CALL syntax.

Miscellaneous

PLAPI_VERSION has been renamed to METAMOD_PLAPI_VERSION. The version numbers for 1.1 to 1.4 can be described as:

• API Major: 1
• API Minor: 0, 1, 2, 3, 4, or 5
• Plugin API: 7, 8, 9, or 10
• Plugin API Minimum: 7
• SourceHook Interface: 4
• SourceHook Implementation: 3
• SourceHook Version: 4.3

Version 1.5.0 (unureleased) had the following version numbers:

• API Major: 1
• API Minor: 6
• Plugin API: 11 or 12
• Plugin API Minimum: 7
• SourceHook Interface: 4
• SourceHook Implementation: 4
• SourceHook Version: 4.4

Version 1.6.0 has the following version numbers:

• API Major: 2
• API Minor: 0
• Plugin API: (13 while alpha), 14
• Plugin API Minimum: 14
• SourceHook Interface: 5
• SourceHook Implementation: 5
• SourceHook Version: 5.0

Major versions change only when the API is compatibly broken. Minor versions are incremented on non-breaking API changes. SourceHook's interface version is a major version, and its implementation version is a minor version. However, SourceHook's minor version is not reset to 0 on major increments.

Additionally, all Metamod:Source public headers are now in a namespace called SourceMM. This namespace is integrated by default. To disable this auto-integration, define METAMOD_NO_AUTO_NAMESPACE at compile time.

Additions

• IMetamodListener now has a new OnUnlinkConCommandBase callback.
• ISmmAPI::Format and ISmmAPI::FormatArgs are new platform-safe replacements for snprintf and vsnprintf.
• ISmmAPI::GetSourceEngineBuild() returns a constant describing the Source engine version.
• ISmmAPI::GetVSPInfo() returns information about the Valve Server Plugin interface, if enabled through Metamod:Source.

SourceHook has many new changes, the greatest of which is "global hooks," which can hook a function on any number of instances of that derived class. See SourceHook Development for more information.

Advanced Loading

Metamod:Source 1.6.0 provides an alternative method of implementing a plugin's loading and instantiation process. This method allows authors to implement very simple loader interfaces which can pass different plugin implementations based on the current Metamod:Source version. For example, the loader can detect engine version A versus engine version B, and load an alternate library.

This interface is exposed in ISmmPluginExt.h, and to avoid linkage to any unnecessary externals, does not include any other Metamod:Source headers. It is assumed that developers will know how to interpret the header file's specifications.

Since earlier versions do not expose any such callback, it can be assumed that if the callback is called before CreateInterface is called, then the plugin is being loaded by a version of Metamod:Source less than 1.6.0.

Sample Port

An example of a plugin that has been fully ported to both Metamod:Source 1.6.0 is Stripper:Source (SVN here).

Note that this plugin uses the new "extended loading" API available in Metamod:Source 1.6.0. The thin-loader library runs on any Metamod:Source version, and will correctly pick one of 6 child plugins to load. This allows Stripper:Source to be distributed as one package with no configuration hassle.

Is there 1.6 API for the original engine?

No. There are no immediate plans to do this because they are not compatible, and it would confuse people.