MM:S API Differences

2007-10-16T21:16:26Z

Mani: /* Breaking */

Metamod:Source 1.6.0 makes several API changes which may affect plugins. These changes are fully documented below.

=Renamed Calls=
==Transparent==
The following functions have received simple renamings, which should be transparent from the <tt>META_REGCMD</tt> and <tt>META_REGCVAR</tt> macros.
*<tt>RegisterConCmdBase()</tt> -> <tt>RegisterConCommandBase()</tt>
*<tt>UnregisterConCmdBase()</tt> -> <tt>UnregisterConCommandBase()</tt>

==Breaking==
<tt>oslink.h</tt> was renamed to <tt>metamod_oslink.h</tt>. 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.
*<tt>pGlobals()</tt> -> <tt>GetCGlobals</tt>
*<tt>engineFactory()</tt> -> <tt>GetEngineFactory()</tt>
*<tt>serverFactory()</tt> -> <tt>GetServerFactory()</tt>
*<tt>physicsFactory()</tt> -> <tt>GetPhysicsFactory()</tt>
*<tt>fileSystemFactory()</tt> -> <tt>GetFileSystemFactory()</tt>

For example, <tt>GET_V_IFACE_CURRENT</tt> would change from this:

<cpp>GET_V_IFACE_CURRENT(engineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);</cpp>

To this:
<cpp>GET_V_IFACE_CURRENT(GetEngineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);</cpp>

=Removed Calls=
A few API calls have been completely removed.
*<tt>RemotePrintingAvailable()</tt> - Unused, no purpose.
*<tt>GetCvarBaseAccessor()</tt> - Unused, no purpose.
*<tt>SetLastMetaReturn()</tt> - Did nothing.
*<tt>GetLastMetaReturn()</tt> - Did nothing.

<tt>SH_GET_CALLCLASS</tt> and <tt>SH_RELEASE_CALLCLASS</tt> have been removed. For more information, see the [[SourceHook_Development#Bypassing_Hooks|updated SH_CALL syntax]].

=Changed Calls=
*<tt>IPluginManager::Query()</tt> and <tt>IPluginManager::QueryHandle()</tt> now store return values using optional pointers instead of references. This change was requested by a few people.

<tt>SH_CALL</tt> and <tt>SH_MCALL</tt> are changed - the concept of "CallClasses" has been removed, and these macros are now much simpler. See the [[SourceHook_Development#Bypassing_Hooks|updated SH_CALL syntax]].

=Miscellaneous=
<tt>PLAPI_VERSION</tt> has been renamed to <tt>METAMOD_PLAPI_VERSION</tt>. 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 <tt>SourceMM</tt>. This namespace is integrated by default. To disable this auto-integration, define <tt>METAMOD_NO_AUTO_NAMESPACE</tt> at compile time.

=Additions=
*<tt>IMetamodListener</tt> now has a new <tt>OnUnlinkConCommandBase</tt> callback.
*<tt>ISmmAPI::Format</tt> and <tt>ISmmAPI::FormatArgs</tt> are new platform-safe replacements for <tt>snprintf</tt> and <tt>vsnprintf</tt>.
*<tt>ISmmAPI::GetSourceEngineBuild()</tt> returns a constant describing the Source engine version.
*<tt>ISmmAPI::GetVSPInfo()</tt> 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 <tt>ISmmPluginExt.h</tt>, 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 <tt>CreateInterface</tt> 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 [http://www.bailopan.net/stripper Stripper:Source] ([http://svn.alliedmods.net/viewvc.cgi/sourcemm/stripper/?root=dvander 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.

[[Category:Metamod:Source Development]]

AlliedModders Wiki - User contributions [en]

MM:S API Differences