MM:S API Differences

Portability between Source engine versions is tricky. Each SDK can change fundamental calls, and Metamod:Source itself has compatibility breaks. This article documents everything you need to know.

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

Renamed Calls

Transparent

The following functions have received simple renamings, which should be transparent from the META_REGCMD and META_REGCVAR macros.

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

Breaking

oslink.h was renamed to metamod_oslink.h. This file is not a public file, however, it has some useful macros and a few plugins used it.

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

Versiono 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 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.

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.

Where is 1.6.0 for the Original Engine?

Metamod:Source 1.6's original upgrade path was very confusing. After the community's initial response, we have slightly altered the upgrade path. Metamod:Source 1.4 will always remain the stable, supported branch for development on the original Source engine. Metamod:Source 1.6 is intended for all engines on Orange Box or later. Thus, the download link for "Metamod:Source 1.6.0 on the Original Source Engine" has been removed.

Of course, Metamod:Source 1.6.0 features many API and SourceHook improvements. If you are a developer who wishes to take advantage of these improvements on the original engine, there are two methods of retrieving binaries:

• Build them from source code.
• Look in the package folder.

It is recommended that developers do not release plugins compiled against 1.6.0 for the original Source engine. It is provided for technical interest only, and thus the majority of people in the community will be running Metamod:Source 1.4.x, which is incompatible.

When Valve deprecates the original Source engine, Metamod:Source 1.4 will continue to be the stable branch for that platform. However, at that point, the vast majority of users will be running the Orange Box engine.