Writing Extensions from Metamod:Source Plugins - Revision history

BAILOPAN at 14:33, 24 March 2008

2008-03-24T14:33:54Z

Vittu: /* Doing Something Useful */ fixed Writing Extensions link

2007-11-13T21:23:49Z

‎Doing Something Useful: fixed Writing Extensions link

BAILOPAN at 19:37, 13 November 2007

2007-11-13T19:37:17Z

BAILOPAN at 19:35, 13 November 2007

2007-11-13T19:35:18Z

BAILOPAN at 19:34, 13 November 2007

2007-11-13T19:34:57Z

BAILOPAN at 07:31, 10 November 2007

2007-11-10T07:31:03Z

BAILOPAN at 07:28, 10 November 2007

2007-11-10T07:28:38Z

BAILOPAN at 07:28, 10 November 2007

2007-11-10T07:28:01Z

BAILOPAN at 07:27, 10 November 2007

2007-11-10T07:27:42Z

BAILOPAN: New page: SourceMod's "External Extensions" feature lets developers implement an extension simply by passing in an object instance, rather than implementing a full library file. This is typical...

2007-11-10T07:24:50Z

New page: SourceMod's "External Extensions" feature lets developers implement an extension simply by passing in an object instance, rather than implementing a full library file. This is typical...

New page

[[SourceMod]]'s "External Extensions" feature lets developers implement an extension simply by passing in an object instance, rather than implementing a full library file. This is typically done from [[Metamod:Source]] plugins which wish to:

*Enable optional, third party extensibility via SourceMod's scripting layer.
*For whatever reason, do not want to move their "standalone" plugin to a full SourceMod extension.
*Or any of the above, in the presence of SourceMod, without actually requiring it to be loaded.

=Overview=
Attaching to SourceMod will be fairly easy for any developer who has authored a Metamod:Source plugin. However, unlike Metamod:Source, SourceMod has fairly stricter design standards and a much richer API set. It is unacceptable to not account for details such as unloading, and special attention must be taken care to free and manage SourceMod resources properly. To leak memory or crash SourceMod plugins

The general steps are:
<ol>
<li>Implement the <tt>IExtensionInterface</tt> interface, from <tt>public/IExtensionSys.h</tt>.</li>
<li>In <tt>ISmmPlugin::AllPluginsLoaded()</tt>, perform the attach if possible.</li>
<li>Detect SourceMod loads in <tt>IMetamodListener::OnMetamodQuery()</tt>.</li>
<li>Store global pointers once bound, such as the self-referencing <tt>IExtension *</tt>.</li>
<li>On <tt>ISmmPlugin::Unload()</tt>, detach from SourceMod.</li>
</ol>

Note that SourceMod requires each extension to have a unique name. This is not necessarily a file name, although usually it resembles one. This name is to used, in conjunction with include files, to make sure plugin requirements are met when they load.

=Detailed Steps=
The information below is for a more detailed overview. The sample SDK provides a full implementation that is recommended over simply copying and pasting the sample code provided here. The sample SDK is explained further on.

==Implementing the Extension==
Implementing the actual Extension itself means simply inheriting the <tt>IExtensionInterface</tt> class as noted earlier. For example:

<cpp>
class MyExtension : public IExtensionInterface
{
public:
virtual bool OnExtensionLoad(IExtension *me,
IShareSys *sys,
char *error,
size_t maxlength,
bool late);
virtual void OnExtensionUnload();
virtual void OnExtensionsAllLoaded();
virtual void OnExtensionPauseChange(bool pause);
virtual bool QueryRunning(char *error, size_t maxlength);
virtual bool IsMetamodExtension();
virtual const char *GetExtensionName();
virtual const char *GetExtensionURL();
virtual const char *GetExtensionTag();
virtual const char *GetExtensionAuthor();
virtual const char *GetExtensionVerString();
virtual const char *GetExtensionDescription();
virtual const char *GetExtensionDateString();
};
</cpp>

Most functions are self explanatory. A few important notes:
*<tt>OnExtensionLoad</tt> is used to provide essential interfaces: <tt>IShareSys</tt> (acquires/shares objects in the SourceMod heirarchy), and <tt>IExtension</tt> (self-referencing pointer used for identification and unloading).
*<tt>OnExtensionLoad</tt> is also used to query for any extra interfaces that the extension requires. For example, if the [[Handle API (SourceMod)|Handle System]] is needed, it would be queried and its pointer cached. If it couldn't be found, then <tt>OnExtensionLoad</tt> would return false to deny loading.
*<tt>OnExtensionUnload()</tt> is used to free resources. If a resource (interface) is being used from another extension, and that extension is unloaded, separate cases must be taken care of because of dynamic unloadability. These (unusual) cases are explained further in the [[Writing Extensions]] article.
*<tt>IsMetamodExtension()</tt> must return false. No exceptions. Only pure-SourceMod extensions which optionally bind to Metamod:Source can return true here.

Examples:
<cpp>
IShareSys *sharesys = NULL;
IExtension *myself = NULL;

bool MyExtension::OnExtensionLoad(IExtension *me,
IShareSys *sys,
char *error,
size_t maxlength,
bool late)
{
sharesys = sys;
myself = me;

/* Get anything important we rely on */

return true;
}</cpp>

==Binding to SourceMod==
Binding to SourceMod requires a few steps:
<ol>
<li>Acquire the <tt>IExtensionManager</tt> interface.</li>
<li>If it exists, bind the extension.</li>
<li>If not, wait for SourceMod to load.</li>
</ol>

<tt>IExtensionSys.h</tt> provides a macro, <tt>SOURCEMOD_INTERFACE_EXTENSIONSYS</tt>, which can be used via <tt>ISmmAPI::MetamodQuery()</tt>. If you do not recall, that is the facility Metamod:Source uses for inter-plugin communication. An example implementation of binding to SourceMod might look like:

<cpp>
bool SM_LoadExtension(char *error, size_t maxlength)
{
if ((smexts = (IExtensionManager *)g_SMAPI->MetaFactory(
SOURCEMOD_INTERFACE_EXTENSIONS,
NULL,
NULL)) == NULL)
{
UTIL_Format(error, maxlength, SOURCEMOD_INTERFACE_EXTENSIONS " interface not found");
return false;
}

char path[256];
g_SMAPI->PathFormat(path, sizeof(path),
#if defined __linux__
"addons/myplugin/bin/myplugin_mm_i486.so"
#else
"addons\\myplugin\\bin\\myplugin_mm.dll"
#endif
);

if ((myself = smexts->LoadExternal(&g_SMExt,
path,
"myplugin_mm.ext",
error,
maxlength)) == NULL)
{
/* Error was supplied by call */
return false;
}

return true;
}</cpp>

==Detecting SourceMod Loads==
This is also fairly easy:
<ol>
<li>If not already done: Inherit <tt>IMetamodListener</tt>, implement <tt>OnMetamodQuery()</tt>.</li>
<li>If not already done: Call <tt>ISmmAPI::AddListener</tt> for your <tt>IMetamodListener</tt> interface.</li>
<li>Watch for occurrences of <tt>SOURCEMOD_NOTICE_EXTENSIONS</tt>.</li>
</ol>

Example of such an implementation:
<cpp>
bool StubPlugin::Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlen, bool late)
{
PLUGIN_SAVEVARS();

/* Blah blah blah */

ismm->AddListener(this, this);

return true;
}

void *StubPlugin::OnMetamodQuery(const char *iface, int *ret)
{
if (strcmp(iface, SOURCEMOD_NOTICE_EXTENSIONS) == 0)
{
/* BIND TO SOURCEMOD */
}

if (ret != NULL)
{
*ret = IFACE_OK;
}

return NULL;
}</cpp>

It is very important to return <tt>NULL</tt> even when this interface is detected. Otherwise, you may block other extensions from receiving the callback.

==Detaching from SourceMod==
Detaching is essential; if your plugin unloads without detaching, SourceMod will very quickly crash trying to deference your memory. Luckily, doing so is trivial. For example, in your <tt>ISmmPlugin::Unload()</tt> callback:

<cpp>
bool StubPlugin::Unload(char *error, size_t maxlen)
{
smexts->UnloadExtension(myself);
}</cpp>

Where <tt>smexts</tt> is the <tt>IExtensionManager</tt> pointer, and <tt>myself</tt> is the <tt>IExtension</tt> pointer.

=SDK and Sample Implementation=
The SourceMod SDK contains a sample implementation in <tt>public/mms_sample_ext</tt>. It is the Metamod:Source "stub plugin," modified to load as a SourceMod extension.

The following files have been added:
*<tt>sm_sdk_config.h</tt> - Contains two function for mapping and unmapping SourceMod Core interfaces. Interfaces can be enabled or disabled by toggling comments next to preprocessor macros here.
*<tt>sm_sdk_config.cpp</tt> - Implementation of <tt>sm_sdk_config.h</tt>. There is no need to edit this.
*<tt>stub_util.h/cpp</tt> - Contains a platform-safe wrapper for text formatting.
*<tt>sm_ext.cpp/sm_ext.h</tt> - Sample implementation <tt>IExtensionInterface.h</tt> and the binding/detaching code.

Additionally, <tt>stub_mm.cpp</tt>/<tt>stub_mm.h</tt> have been modified. <tt>IMetamodListener</tt> is inherited, and <tt>OnMetamodQuery</tt> is implemented as described earlier. Also, <tt>ISmmAPI::AllPluginsLoaded</tt> attempts a SourceMod binding.

'''Note:''' <tt>sm_sdk_config.h</tt> provides <tt>SM_AcquireInterfaces</tt>. It must be called to acquire the interfaces that are uncommented in the same file, unless you intend to query them manually.

'''Note:''' It is highly recommend that developers read the added files, and at the very least, include the <tt>sm_sdk_config</tt> files, which greatly simplify the acquisition of interfaces.

=Renamed Variables/Macros=
The extension SDK has a few renamed macros/variables from the default SDK. This is to prevent potential name clashes for Metamod:Source plugins, which have pre-existing code.

'''Changed global variables:'''
*g_pForwards, forwards -> sm_forwards
*g_pHandleSys, handlesys -> sm_handlesys
*g_pSM -> sm_main
*playerhelpers -> sm_players
*dbi -> sm_dbi
*gameconfs -> sm_gameconfs
*memutils -> sm_memutils
*gamehelpers -> sm_gamehelpers
*timersys -> sm_timersys
*threader -> sm_threader
*libsys -> sm_libsys
*plsys -> sm_plsys
*textparsers -> sm_text
*adminsys -> sm_adminsys
*menus -> sm_menus

'''Changed macros:'''
*<tt>SM_GET_IFACE</tt> -> <tt>SM_FIND_IFACE_OR_FAIL</tt>
*<tt>SM_GET_LATE_IFACE</tt> -> <tt>SM_FIND_IFACE</tt>

=Doing Something Useful=
SourceMod has over a dozen interfaces for interacting with plugins and greatly simplifying the Half-Life 2 development process. It contains memory abstraction, fast data structures, an abstracted menu and voting system, the ability to create and invoke plugin callbacks ("forwards"), the ability to provide new native functions to plugins, text processing, game data abstraction, threading abstraction, signature scanning, timers, and an object-oriented SQL layer.

For more information, see the [[Writing Extension]] article. Note that the article uses different global names. See the earlier section for finding which names changed.

=Further Reading=
*[[Writing Extension]]
*[[:Category:SourceMod Development|SourceMod Development Category]]
*[http://www.sourcemod.net/sdk/dox/ C++ API auto-generated documentation]

[[Category:SourceMod Development]].

← Older revision		Revision as of 19:37, 13 November 2007
Line 137:		Line 137:

	return true;		return true;
		+	}
		+
		+	void StubPlugin::AllPluginsLoaded()
		+	{
		+	/* BIND TO SOURCMEOD IF POSSIBLE */
	}		}

@@ Line 6: / Line 6: @@
 =Overview=
-Attaching to SourceMod will be fairly easy for any developer who has authored a Metamod:Source plugin.  However, unlike Metamod:Source, SourceMod has fairly stricter design standards and a much richer API set.  It is unacceptable to not account for details such as unloading, and special attention must be taken care to free and manage SourceMod resources properly.  Remember crashes or Handle leaks will affect all of SourceMod, instead of just your plugin.
+Attaching to SourceMod will be fairly easy for any developer who has authored a Metamod:Source plugin.  However, unlike Metamod:Source, SourceMod has fairly stricter design standards and a much richer API set.  It is unacceptable to not account for details such as unloading, and special attention must be taken care to free and manage SourceMod resources properly.  Remember crashes or Handle leaks will affect all of SourceMod's loaded plugins/extensions, instead of just your plugin.
 The general steps are:

← Older revision		Revision as of 07:31, 10 November 2007
Line 183:		Line 183:

	'''Note:''' It is highly recommend that developers read the added files, and at the very least, include the <tt>sm_sdk_config</tt> files, which greatly simplify the acquisition of interfaces.		'''Note:''' It is highly recommend that developers read the added files, and at the very least, include the <tt>sm_sdk_config</tt> files, which greatly simplify the acquisition of interfaces.
		+
		+	'''Note:''' The Makefiles are provided as a convenience/example, and for our own testing. As our build process requires special vcproj/sln changes (which are not yet documented), no Visual Studio project files are provided for <tt>mms_sample_ext</tt>. As most developers will already have an MM:S plugin implemented, this should largely be irrelevant. Otherwise, the project files from <tt>stub_mm</tt> can be used instead.

← Older revision		Revision as of 07:28, 10 November 2007
Line 185:		Line 185:


−	=Renamed Variables/Macros=	+	==Renamed Variables/Macros==
	The extension SDK has a few renamed macros/variables from the default SDK. This is to prevent potential name clashes for Metamod:Source plugins, which have pre-existing code.		The extension SDK has a few renamed macros/variables from the default SDK. This is to prevent potential name clashes for Metamod:Source plugins, which have pre-existing code.

← Older revision		Revision as of 07:27, 10 November 2007
Line 208:		Line 208:
	*<tt>SM_GET_IFACE</tt> -> <tt>SM_FIND_IFACE_OR_FAIL</tt>		*<tt>SM_GET_IFACE</tt> -> <tt>SM_FIND_IFACE_OR_FAIL</tt>
	*<tt>SM_GET_LATE_IFACE</tt> -> <tt>SM_FIND_IFACE</tt>		*<tt>SM_GET_LATE_IFACE</tt> -> <tt>SM_FIND_IFACE</tt>
		+
		+
		+	==Example of a Successful Load==
		+	<pre>
		+	meta load addons/stub_mm
		+	Plugin "Stub Plugin" loaded with id 3.
		+	sm exts list
		+	[SM] Displaying 3 extensions:
		+	[01] SDK Tools (1.0.0.1336): Source SDK Tools
		+	[02] BinTools (1.0.0.1336): Low-level C/C++ Calling API
		+	[03] Stub Plugin (1.0.0.0): Sample empty plugin
		+	sm exts info 3
		+	File: myplugin_mm.ext
		+	Loaded: Yes (version 1.0.0.0)
		+	Name: Stub Plugin (Sample empty plugin)
		+	Author: AlliedModders LLC (http://www.sourcemm.net/)
		+	Binary info: API version 2 (compiled Nov 10 2007)
		+	Method: Loaded by Metamod:Source, attached to SourceMod
		+	meta unload 3
		+	Plugin 3 unloaded.
		+	sm exts list
		+	[SM] Displaying 2 extensions:
		+	[01] SDK Tools (1.0.0.1336): Source SDK Tools
		+	[02] BinTools (1.0.0.1336): Low-level C/C++ Calling API
		+	</pre>

@@ Line 3: / Line 3: @@
 *Enable optional, third party extensibility via SourceMod's scripting layer.
 *For whatever reason, do not want to move their "standalone" plugin to a full SourceMod extension.
-*Or any of the above, in the presence of SourceMod, without actually requiring it to be loaded.
+*Or any of the above, such that new features are added in the presence of SourceMod, but the plugin does not require SourceMod to be present.
 =Overview=

@@ Line 245: / Line 245: @@
 SourceMod has over a dozen interfaces for interacting with plugins and greatly simplifying the Half-Life 2 development process.  It contains memory abstraction, fast data structures, an abstracted menu and voting system, the ability to create and invoke plugin callbacks ("forwards"), the ability to provide new native functions to plugins, text processing, game data abstraction, threading abstraction, signature scanning, timers, and an object-oriented SQL layer.
-For more information, see the [[Writing Extension]] article.  Note that the article uses different global names.  See the earlier section for finding which names changed.
+For more information, see the [[Writing Extensions]] article.  Note that the article uses different global names.  See the earlier section for finding which names changed.
 =Further Reading=

@@ Line 242: / Line 242: @@
 =Further Reading=
-*[[Writing Extension]]
+*[[Writing Extensions]]
 *[[:Category:SourceMod Development|SourceMod Development Category]]
 *[http://www.sourcemod.net/sdk/dox/ C++ API auto-generated documentation]
 [[Category:SourceMod Development]].