3 * ======================================================
5 * Copyright (C) 2004-2007 AlliedModders LLC and authors.
7 * ======================================================
9 * This software is provided 'as-is', without any express or implied warranty.
10 * In no event will the authors be held liable for any damages arising from
11 * the use of this software.
13 * Permission is granted to anyone to use this software for any purpose,
14 * including commercial applications, and to alter it and redistribute it
15 * freely, subject to the following restrictions:
17 * 1. The origin of this software must not be misrepresented; you must not
18 * claim that you wrote the original software. If you use this software in a
19 * product, an acknowledgment in the product documentation would be
20 * appreciated but is not required.
21 * 2. Altered source versions must be plainly marked as such, and must not be
22 * misrepresented as being the original software.
23 * 3. This notice may not be removed or altered from any source distribution.
28 #ifndef _INCLUDE_ISMM_PLUGIN_H
29 #define _INCLUDE_ISMM_PLUGIN_H
32 * @brief Plugin API interface
36 #include <interface.h>
37 #include <sourcehook.h>
40 #define PLAPI_VERSION 13
41 #define PLAPI_NAME "ISmmPlugin"
48 virtual int GetApiVersion() { return PLAPI_VERSION; }
49 virtual ~ISmmPlugin() { }
52 * @brief Called on plugin load.
54 * NOTE - As of API 7, this is called as DLLInit() executes - after the parameters are known, but before
55 * the original GameDLL function is called. Therefore, you cannot hook it, but you don't need to -
56 * Load() is basically your hook.
57 * NOTE - As of API 7, you can override factories before the engine and gamedll exchange them.
58 * However, take care to note that if your plugin is unloaded, and the gamedll/engine have cached
59 * an interface you've passed, something will definitely crash. Be careful.
61 * @param id Internal id of plugin. Saved globally by PLUGIN_SAVEVARS()
62 * @param ismm External API for SourceMM. Saved globally by PLUGIN_SAVEVARS()
63 * @param list Contains a list of factories. Hook a factory call by setting one equal to your own function.
64 * @param late Set to true if your plugin was loaded late (not at server load).
65 * @param error Error message buffer
66 * @param maxlen Size of error message buffer
67 * @return True if successful, return false to reject the load.
69 virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
72 * @brief Called when your plugin is "queried".
74 * This is useful for rejecting a loaded state. For example, if your plugin wants
75 * to stop operating, it can simply return false and copy an error message. This
76 * will notify other plugins or MM:S of something bad that happened. NOTE - MM:S
77 * will not cache the return state, so if you return false, your plugin will not
78 * actually be paused or unloaded. This callback will be called when:
79 * - Another plugin requests it
80 * - Someone types "meta list", it will show up as "REFUSED"
81 * - When Metamod need to re-check the plugin's status
82 * - If the plugin does something like overload a factory, Metamod will make sure the Query() returns true
84 * Also note that this query will only override Metamod when the plugin is running and not paused.
86 * @param error Buffer for error message. This can be NULL!
87 * @param maxlen Maximum length of error buffer.
88 * @return Status code - true for okay, false for badness.
90 virtual bool QueryRunning(char *error, size_t maxlen)
96 * @brief Called on plugin unload. You can return false if you know your plugin
97 * is not capable of restoring critical states it modifies.
99 * @param error Error message buffer
100 * @param maxlen Size of error message buffer
101 * @return True on success, return false to request no unload.
103 virtual bool Unload(char *error, size_t maxlen)
108 /** @brief Called on plugin pause.
110 * @param error Error message buffer
111 * @param maxlen Size of error message buffer
112 * @return True on success, return false to request no pause.
114 virtual bool Pause(char *error, size_t maxlen)
119 /** @brief Called on plugin unpause.
121 * @param error Error message buffer
122 * @param maxlen Size of error message buffer
123 * @return True on success, return false to request no unpause.
125 virtual bool Unpause(char *error, size_t maxlen)
130 /** @brief Return author as string */
131 virtual const char *GetAuthor() =0;
133 /** @brief Return plugin name as string */
134 virtual const char *GetName() =0;
136 /** @brief Return a description as string */
137 virtual const char *GetDescription() =0;
139 /** @brief Return a URL as string */
140 virtual const char *GetURL() =0;
142 /** @brief Return quick license code as string */
143 virtual const char *GetLicense() =0;
145 /** @brief Return version as string */
146 virtual const char *GetVersion() =0;
148 /** @brief Return author as string */
149 virtual const char *GetDate() =0;
151 /** @brief Return author as string */
152 virtual const char *GetLogTag() =0;
155 * @brief Called when all plugins have been loaded.
157 * This is called after DLLInit(), and thus the mod has been mostly initialized.
158 * It is also safe to assume that all other (automatically loaded) plugins are now
159 * ready to start interacting, because they are all loaded.
161 virtual void AllPluginsLoaded()
167 * @brief Added in 1.1 so plugins could listen to specific events
169 class IMetamodListener
172 virtual ~IMetamodListener()
177 * @brief Called when a plugin is loaded.
179 * @param id Id of the plugin.
181 virtual void OnPluginLoad(PluginId id)
186 * @brief Called when a plugin is unloaded.
188 * @param id Id of the plugin.
190 virtual void OnPluginUnload(PluginId id)
195 * @brief Called when a plugin is paused.
197 * @param id Id of the plugin.
199 virtual void OnPluginPause(PluginId id)
204 * @brief Called when a plugin is unpaused.
206 * @param id Id of the plugin.
208 virtual void OnPluginUnpause(PluginId id)
213 * @brief Called when the level is loaded (after GameInit, before ServerActivate).
215 * To override this, hook IServerGameDLL::LevelInit().
217 * @param pMapName Name of the map.
218 * @param pMapEntities Lump string of the map entities, in KeyValue format.
219 * @param pOldLevel Unknown.
220 * @param pLandmarkName Unknown.
221 * @param loadGame Unknown.
222 * @param background Unknown.
224 virtual void OnLevelInit(char const *pMapName, char const *pMapEntities, char const *pOldLevel, char const *pLandmarkName, bool loadGame, bool background) { }
227 * @brief Called when the level is shut down. May be called more than once.
229 virtual void OnLevelShutdown()
234 * @brief Called when engineFactory() is used through Metamod:Source's wrapper.
235 * This can be used to provide interfaces to other plugins or the GameDLL.
237 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
239 * @param iface Interface string.
240 * @param ret Optional pointer to store return code.
241 * @return Generic pointer to the interface, or NULL if not found.
243 virtual void *OnEngineQuery(const char *iface, int *ret)
254 * @brief Called when the physics factory is used through Metamod:Source's wrapper.
255 * This can be used to provide interfaces to other plugins.
257 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
259 * @param iface Interface string.
260 * @param ret Optional pointer to store return code.
261 * @return Generic pointer to the interface, or NULL if not found.
263 virtual void *OnPhysicsQuery(const char *iface, int *ret)
274 * @brief Called when the filesystem factory is used through Metamod:Source's wrapper.
275 * This can be used to provide interfaces to other plugins.
277 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
279 * @param iface Interface string.
280 * @param ret Optional pointer to store return code.
281 * @return Generic pointer to the interface, or NULL if not found.
283 virtual void *OnFileSystemQuery(const char *iface, int *ret)
294 * @brief Called when the server DLL's factory is used through Metamod:Source's wrapper.
295 * This can be used to provide interfaces to other plugins.
297 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
299 * @param iface Interface string.
300 * @param ret Optional pointer to store return code.
301 * @return Generic pointer to the interface, or NULL if not found.
303 virtual void *OnGameDLLQuery(const char *iface, int *ret)
314 * @brief Called when Metamod's own factory is invoked.
315 * This can be used to provide interfaces to other plugins.
317 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
319 * @param iface Interface string.
320 * @param ret Optional pointer to store return code.
321 * @return Generic pointer to the interface, or NULL if not found.
323 virtual void *OnMetamodQuery(const char *iface, int *ret)
334 * @brief Called when Metamod:Source acquires a valid IServerPluginCallbacks
335 * pointer to be used for hooking by plugins.
337 * This will only be called after a call to ISmmAPI::EnableVSPListener().
338 * If called before GameInit, this callback will occur before LevelInit.
339 * Otherwise, it will be called on the first call after that.
341 * This callback is provided to all plugins regardless of which (or how many)
342 * called EnableVSPListener(), but only if at least one did in fact enable it.
344 * This callback is only available for plugins using API v1:5 (Metamod:Source 1.4+).
345 * If a plugin loads lately, it may still call EnableVSPListener().
347 * @param iface Interface pointer. If NULL, then the VSP listening construct
348 * failed to initialize and is not available.
350 virtual void OnVSPListening(IServerPluginCallbacks *iface) { }
353 * @brief Called when Metamod:Source is about to remove a concommand or convar.
354 * This can also be called if ISmmAPI::UnregisterConCmdBase is used by a plugin.
356 * @param id Id of the plugin that created the concommand or convar.
357 * @param pCommand Pointer to concommand or convar that is being removed.
359 virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
364 #define PL_EXPOSURE CreateInterface
365 #define PL_EXPOSURE_C "CreateInterface"
367 #define PLUGIN_EXPOSE(name, var) \
368 ISmmAPI *g_SMAPI = NULL; \
369 ISmmPlugin *g_PLAPI = NULL; \
370 PluginId g_PLID = (PluginId)0; \
371 SourceHook::ISourceHook *g_SHPtr = NULL; \
372 SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
373 if (name && !strcmp(name, PLAPI_NAME)) { \
374 return static_cast<void *>(&var); \
379 #define PLUGIN_GLOBALVARS() \
380 extern SourceHook::ISourceHook *g_SHPtr; \
381 extern ISmmAPI *g_SMAPI; \
382 extern ISmmPlugin *g_PLAPI; \
383 extern PluginId g_PLID;
385 #define PLUGIN_SAVEVARS() \
387 g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
388 g_PLAPI = static_cast<ISmmPlugin *>(this); \
391 #define META_LOG g_SMAPI->LogMsg
392 #define META_REGCMD(name) g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command)
393 #define META_REGCVAR(var) g_SMAPI->RegisterConCommandBase(g_PLAPI, var)
394 #define META_UNREGCMD(name) g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command)
395 #define META_UNREGCVAR(var) g_SMAPI->UnregisterConCommandBase(g_PLAPI, var)
396 #define META_CONPRINT g_SMAPI->ConPrint
397 #define META_CONPRINTF g_SMAPI->ConPrintf
399 /* Probably should use this up above someday */
400 #define CONCMD_VARNAME(name) name##_command
403 #if defined __WIN32__ || defined _WIN32 || defined WIN32
404 #define SMM_API extern "C" __declspec(dllexport)
405 #elif defined __GNUC__
406 #if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
407 #define SMM_API extern "C" __attribute__ ((visibility("default")))
409 #define SMM_API extern "C"
412 #endif //!defined SMM_API
415 * @brief Macro for automatically getting a current or newer Valve interface.
417 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
418 * @param v_var Variable name to store into.
419 * @param v_type Interface type (do not include the pointer/asterisk).
420 * @param v_name Interface name.
422 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
423 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
426 if (error && maxlen) \
428 ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
434 * @brief Same as GET_V_IFACE, except searches for any.
436 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
437 * @param v_var Variable name to store into.
438 * @param v_type Interface type (do not include the pointer/asterisk).
439 * @param v_name Interface name.
441 #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
442 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
445 if (error && maxlen) \
447 ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
452 #endif //_INCLUDE_ISMM_PLUGIN_H