Difference between revisions of "MM:S API Differences"

From AlliedModders Wiki
Jump to: navigation, search
m
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
Metamod:Source 1.6.0 makes several API changes which may affect pluginsThese changes are fully documented below.
+
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 <tt>core</tt>) and the "1.4 API" (contained in <tt>core-legacy</tt>).
 +
 
 +
As the name suggests, the 1.4 API is legacy and is only used on the Episode 1 engines and olderThe 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=
 +
*[http://www.metamodsource.net/dox-1.4.3/ 1.4 API], contained in <tt>core-legacy</tt>.  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)
 +
*[http://www.metamodsource.net/dox/ 1.6 API], contained in <tt>core</tt>. 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=
 
=Renamed Calls=
 
==Transparent==
 
==Transparent==
The following functions have received simple renamings, which should be transparent from the <tt>META_REGCMD</tt> and <tt>META_REGCVAR</tt> macros.
+
The following functions were renamed.  These changes are masked by the <tt>META_REGCMD</tt> and <tt>META_REGCVAR</tt> macros and should not affect anyone.
 
*<tt>RegisterConCmdBase()</tt> -> <tt>RegisterConCommandBase()</tt>
 
*<tt>RegisterConCmdBase()</tt> -> <tt>RegisterConCommandBase()</tt>
 
*<tt>UnregisterConCmdBase()</tt> -> <tt>UnregisterConCommandBase()</tt>
 
*<tt>UnregisterConCmdBase()</tt> -> <tt>UnregisterConCommandBase()</tt>
 +
  
 
==Breaking==
 
==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.
+
<tt>oslink.h</tt> was renamed to <tt>metamod_oslink.h</tt>.  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.
 
The following functions have received simple renamings, however, old code will be affected.
Line 23: Line 43:
 
To this:
 
To this:
 
<cpp>GET_V_IFACE_CURRENT(GetEngineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);</cpp>
 
<cpp>GET_V_IFACE_CURRENT(GetEngineFactory, engine, IVEngineServer, INTERFACEVERSION_VENGINESERVER);</cpp>
 +
  
 
=Removed Calls=
 
=Removed Calls=
Line 32: Line 53:
  
 
<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]].
 
<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=
 
=Changed Calls=
Line 37: Line 59:
  
 
<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]].
 
<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=
 
=Miscellaneous=
Line 49: Line 70:
 
*SourceHook Version: 4.3
 
*SourceHook Version: 4.3
  
Versiono 1.5.0 (unureleased) had the following version numbers:
+
Version 1.5.0 (unureleased) had the following version numbers:
 
*API Major: 1
 
*API Major: 1
 
*API Minor: 6
 
*API Minor: 6
Line 76: Line 97:
 
*<tt>ISmmAPI::Format</tt> and <tt>ISmmAPI::FormatArgs</tt> are new platform-safe replacements for <tt>snprintf</tt> and <tt>vsnprintf</tt>.
 
*<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::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.
+
*<tt>ISmmAPI::GetVSPInfo()</tt> 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.
 
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.
 
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.
  
Line 93: Line 115:
  
  
=Where is 1.6.0 for the Original Engine?=
+
=Is there 1.6 API for the original engine?=
Metamod:Source 1.6's original upgrade path was very confusingAfter 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.
+
NoThere are no immediate plans to do this because they are not compatible, and it would confuse people.
 
 
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.
 
*[http://www.sourcemm.net/autobuilds/1.6.0/ 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.
 
  
 
[[Category:Metamod:Source Development]]
 
[[Category:Metamod:Source Development]]

Latest revision as of 02:30, 26 November 2008

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.