1 <!-- vi: set ts=4 sw=4 : -->
2 <!-- vim: set tw=75 : -->
6 <title>Coding for Metamod</title>
10 <h1>Coding for Metamod
18 You'll need the Half-Life SDK, of course. In particular you'll need HL SDK
19 version 2.3. You can find the original SDK 2.3 at the <a href="http://www.valve-erc.com/">Valve Editing Resource Center (VERC)</a>,
20 and a modified version of SDK 2.3 at <a href="http://metamod.org/files/sdk/">metamod.org/files/sdk</a>.
27 The basic operation is, for each api call:
30 <li> iterate through list of plugins
31 <li> for each plugin, if it provides this api call, then call the function
33 <li> call the "real" function (in the game dll, or from the engine)
34 <li> for each plugin, check for a "post" version of the function, and call
38 Also, for any api call, each plugin has the opportunity to replace the
39 real routine, in two ways:
42 <li> prevent the real routine from being called (<a
43 href=#MRES_SUPERCEDE><tt><b>SUPERCEDE</b></tt></a>).
44 <li> allow the real routine to be called, but change the value that's
45 returned (<a href=#MRES_OVERRIDE><tt><b>OVERRIDE</b></tt></a>)
48 Thus after each plugin is called, its <tt><b>META_RESULT</b></tt> flag is
49 checked, and action taken appropriately. Note that supercede/override only
50 affects the _real_ routine; other plugins will still be called.
52 In addition to the <tt><b>SUPERCEDE</b></tt> and
53 <tt><b>OVERRIDE</b></tt> flags, there are two additional flags a plugin can
57 <li> <a href=#MRES_HANDLED><tt><b>HANDLED</b></tt></a> ("I did something here")
58 <li> <a href=#MRES_IGNORED><tt><b>IGNORED</b></tt></a> ("I didn't really do anything")
61 These aren't used by Metamod itself, but could be used by plugins to
62 get an idea if a previous plugin did anything.
64 <p> Note that each routine <b><i>needs</i></b> to set its
65 <tt><b>META_RESULT</b></tt> value before returning. Plugin routines that
66 do not set a value will be reported as errors in the logs.
70 <h2>Plugin coding requirements
73 Plugins <i><b>must</b></i> provide the following standard HLSDK exported function:
76 void GiveFnptrsToDll(enginefuncs_t* pengfuncsFromEngine, globalvars_t *pGlobals);
79 <i><b>As well as</b></i> the following new functions:
82 void Meta_Init(void); <i>(optional)</i>
83 int Meta_Query(char *interfaceVersion, plugin_info_t **pinfo, mutil_funcs_t *pMetaUtilFuncs);
84 int Meta_Attach(PLUG_LOADTIME now, META_FUNCTIONS *pFunctionTable, meta_globals_t *pMGlobals, gamedll_funcs_t *pGamedllFuncs);
85 int Meta_Detach(PLUG_LOADTIME now, PL_UNLOAD_REASON reason);
88 Also, it must provide <i><b>at least</b></i> one function returning a standard HL
89 function table, from either the following standard HLSDK functions:
92 int GetEntityAPI( DLL_FUNCTIONS *pFunctionTable, int interfaceVersion );
93 int GetEntityAPI2( DLL_FUNCTIONS *pFunctionTable, int *interfaceVersion );
94 int GetNewDLLFunctions( NEW_DLL_FUNCTIONS *pNewFunctionTable, int *interfaceVersion );
97 or from the following new functions:
100 int GetEntityAPI_Post(DLL_FUNCTIONS *pFunctionTable, int interfaceVersion);
101 int GetEntityAPI2_Post(DLL_FUNCTIONS *pFunctionTable, int *interfaceVersion ;
102 int GetNewDLLFunctions_Post(NEW_DLL_FUNCTIONS *pNewFunctionTable, int *interfaceVersion);
104 int GetEngineFunctions(enginefuncs_t *pengfuncsFromEngine, int *interfaceVersion);
105 int GetEngineFunctions_Post(enginefuncs_t *pengfuncsFromEngine, int *interfaceVersion);
108 Thus, it needs to have (at least):
114 <tt><i><one or more Get function></i></tt>
117 See the <tt>"<b>stub_plugin</b>"</tt> for an example of <b><i>bare
118 minimum</i></b> code. See <tt>"<b>trace_plugin</b>"</tt> for an example of
119 more complete functionality.
121 <p>Also, if the plugin needs to use <tt><b>LINK_ENTITY_TO_CLASS</b></tt>,
122 support for the particular entity(ies) has to be added explicitly to
123 Metamod (<tt>linkfunc.cpp</tt>), just as it does for entities in game DLLs.
127 <h2>Operation Details
130 <p>These are the valid <tt>META_RESULT</tt> values a plugin routine can
134 <a name=MRES_IGNORED><p><li></a>
135 <tt><b>MRES_IGNORED</b></tt>
136 <br> The plugin did nothing. This could be used to tell a subsequent
137 plugin that the some situation hasn't been handled yet. This would be
138 recognized only by other plugins; Metamod itself doesn't do anything
139 special for this situation. Unless otherwise specified by a later
140 plugin, execution of routine in the gameDLL will take place. This is
141 valid in both normal and post routines.
142 <a name=MRES_HANDLED><p><li></a>
143 <tt><b>MRES_HANDLED</b></tt>
144 <br> The plugin handled the situation, or did something with the
145 information. Again, this could be used to tell a subsequent plugin
146 that some situation has already been taken care of, and is not
147 recognized specially by Metamod. Unless otherwise specified by a later
148 plugin, execution of routine in the gameDLL will take place. This is
149 valid in both normal and post routines.
150 <a name=MRES_OVERRIDE><p><li></a>
151 <tt><b>MRES_OVERRIDE</b></tt>
152 <br> The plugin is providing a return value for the routine, which
153 should be used in place of the return value from the gameDLL's routine
154 (the plugin "overrides" the gameDLL's return value).
155 Unless otherwise specified by a later plugin, the gameDLL routine will
156 still be called. Note this only makes sense for non-void routines.
157 This is valid in both normal and post routines.
158 <a name=MRES_SUPERCEDE><p><li></a>
159 <tt><b>MRES_SUPERCEDE</b></tt>
160 <br> The plugin has performed sufficient actions for the routine, and
161 the gameDLL's routine should <i><b>not</b></i> be called (the plugin
162 "supercedes" the gameDLL's routine, more or less replacing it
163 entirely). Any return value for the routine should be specified as
164 well by the plugin. Note this is only valid for normal routines, as
165 post routines cannot prevent calling the gameDLL's routine (as it has
166 already happened!). Also note, this doesn't prevent subsequent plugins
167 from being called for this routine; it supercedes <b><i>only</i></b>
171 As the plugins are called, a running status is kept of the "highest" meta
172 status so far, in the order (lowest to highets) shown above. After calling
173 all the "normal" routines, the status is checked to see if the gameDLL's
174 routine should be called - ie, it will not be called if one (or more) of
175 the plugin's has specified <tt><b>META_SUPERCEDE</b></tt>. The gameDLL's
176 routine is then called, or skipped, as appropriate. Then, all the "post"
177 routines are called in the same manner (except
178 <tt><b>META_SUPERCEDE</b></tt> is no longer a valid meta result).
180 <p>Last, if any plugins specified <tt><b>META_OVERRIDE</b></tt> or
181 <tt><b>META_SUPERCEDE</b></tt>, the return value given by the
182 <b><i>last</i></b> such plugin is returned as the routine's return code to
183 the engine (assuming a non-void routine). Thus, the order of the plugins
184 as specified in the <tt>metamod.ini</tt> <b><i>does</i></b> have a possible
193 The <a href="http://metamod.org/dl/metamod/meta_api.h"><tt>meta_api.h</tt></a>
194 header that describes the Metamod API functions, types, and structures also
195 includes several macros that can be of help when coding a plugin.
198 <a name=SET_META_RESULT><p><li></a>
199 <tt><b>SET_META_RESULT(result)</b></tt>
200 <br> Sets the <tt>META_RESULT</tt> for the plugin.
201 <a name=RETURN_META><p><li></a>
202 <tt><b>RETURN_META(result)</b></tt>
203 <br> Sets the <tt>META_RESULT</tt> for the plugin, and then calls
204 <tt>return</tt>. This assumes a <tt>void</tt> function.
205 <a name=RETURN_META_VALUE><p><li></a>
206 <tt><b>RETURN_META_VALUE(result, value)</b></tt>
207 <br> Sets the <tt>META_RESULT</tt> for the plugin, and then returns the
208 given <tt>value</tt>. This assumes a non-<tt>void</tt> function, and
209 it doesn't matter the particular type of the return value.
210 <a name=META_RESULT_STATUS><p><li></a>
211 <tt><b>META_RESULT_STATUS</b></tt>
212 <br> Gives the current status of <tt>META_RESULT</tt> for this routine
213 from plugins so far. It will return the "highest" result so far, in
214 the order of lesser to greater: <tt>IGNORED</tt>, <tt>HANDLED</tt>,
215 <tt>OVERRIDE</tt>, <tt>SUPERCEDE</tt> (see also above <a
216 href=#operation><i>Operation Details</i></a>)
217 <a name=META_RESULT_PREVIOUS><p><li></a>
218 <tt><b>META_RESULT_PREVIOUS</b></tt>
219 <br> Gives the <tt>META_RESULT</tt> of the previous plugin.
220 <a name=META_RESULT_ORIG_RET><p><li></a>
221 <tt><b>META_RESULT_ORIG_RET(type)</b></tt>
222 <br> Gives the "original" return value for the routine, ie the return
223 value of the routine from gameDLL. The type for the routine's return
224 value must be specified in the macro; this is used as a cast for
225 assignment. Note this is only valid in a "post" routine.
226 <a name=META_RESULT_OVERRIDE_RET><p><li></a>
227 <tt><b>META_RESULT_OVERRIDE_RET(type)</b></tt>
228 <br> Gives the return value from any previous plugin that specified
229 <tt><b>META_OVERRIDE</b></tt> or <tt><b>META_SUPERCEDE</b></tt>. The
230 type for the routine's return value must be specified in the macro;
231 this is used as a cast for assignment. This should only be used after
232 checking the META_RESULT to see if there's actually an override value
234 <a name=MDLL_><p><li></a>
235 <tt><b>MDLL_<i>*</i>(<i>args</i>)</b></tt>
236 <br> Calls a given DLLAPI routine in the gameDLL. For instance,
237 <tt><b>MDLL_GameDLLInit(args)</b></tt>, <tt><b>MDLL_Spawn(args)</b></tt>,
239 <a name=MNEW_><p><li></a>
240 <tt><b>MNEW_<i>*</i>(<i>args</i>)</b></tt>
241 <br> Calls a given NEWAPI routine in the gameDLL. For instance,
242 <tt><b>MNEW_GameShutdown(args)</b></tt>, etc.
248 <h2>Utility Callback Functions
251 In version 1.05, Metamod began providing a set of utility functions to
252 plugins to centralize functionality, reduce code reuse, and to provide some
253 convenience in plugin coding. Presently, only a few functions are
254 provided. More are added as I find the time, and identify some advantage
255 to having them (either for my own plugins, or by others' request for their
258 <p> Note the <tt><b>PLID</b></tt> keyword passed to each function. This is
259 basically a "plugin id" to indicate to Metamod which plugin is calling the
260 function (else it's difficult to tell), and is a macro that should be
261 specified verbatim with each call. (Currently, the macro is merely the
262 plugin_info struct pointer returned by the plugin via <tt>Meta_Query</tt>;
263 in the future this could change to some other identifier.)
266 <a name=LOG_CONSOLE><p><li></a>
267 <tt> void <b>LOG_CONSOLE(PLID, <i>char *fmt, ...</i>)</b></tt>
268 <br> Print a message line on the console. Message is specified as a
269 <tt>printf</tt> style format string and arguments. A trailing newline
270 is provided by the routine and should not be specified in the string
271 (unless you want two newlines).
272 <a name=LOG_MESSAGE><p><li></a>
273 <tt> void <b>LOG_MESSAGE(PLID, <i>char *fmt, ...</i>)</b></tt>
274 <br> Print a message line in the server logs. Message is specified as a
275 <tt>printf</tt> style format string and arguments. A trailing newline
276 is provided by the routine and should not be specified in the string.
277 Log message is prefixed by the <tt>logtag</tt> string in the plugin's
278 "info" struct, surrounded by brackets. For instance:
279 <p><tt>L 04/17/2001 - 18:00:35: [TraceAPI] Tracing Engine routine 'RegUserMsg'</tt>
280 <a name=LOG_ERROR><p><li></a>
281 <tt> void <b>LOG_ERROR(PLID, <i>char *fmt, ...</i>)</b></tt>
282 <br> As in <tt>LOG_MESSAGE</tt> above, only marked as well with the
283 string "ERROR:". For example:
284 <p><tt>L 04/17/2001 - 18:03:13: [TraceAPI] ERROR: malloc failed</tt>
285 <a name=LOG_DEVELOPER><p><li></a>
286 <tt> void <b>LOG_DEVELOPER(PLID, <i>char *fmt, ...</i>)</b></tt>
287 <br> As in <tt>LOG_MESSAGE</tt> above, only message will be logged only
288 if cvar <tt>developer</tt> is set to 1; message is marked as well with
289 the string "dev:". For example:
290 <p><tt>L 04/17/2001 - 18:03:13: [TraceAPI] dev: called: GiveFnptrsToDll</tt>
291 <a name=CENTER_SAY><p><li></a>
292 <tt> void <b>CENTER_SAY(PLID, <i>char *fmt, ...</i>)</b></tt>
293 <br> Prints a message on the center of all players' screens. This is
294 like the "centersay" of AdminMod, with pretty_say enabled, with the
295 same defaults (green, and a 10 second fade-in). A message is logged as
296 well, ie: <i>[added in 1.06]</i>
297 <p><tt>L 04/17/2001 - 15:44:52: [WDMISC] (centersay) random set up us the bomb!</tt>
298 <a name=CENTER_SAY_PARMS><p><li></a>
299 <tt> void <b>CENTER_SAY_PARMS(PLID, <i>hudtextparms_t tparms, char *fmt, ...</i>)</b></tt>
300 <br> As in <tt>CENTER_SAY</tt> above, but allows specifying all the
301 parameters. (see SDK <tt>dlls/util.h</tt> for the struct
302 <tt>hudtextparms_t</tt>). <i>[added in 1.06]</i>
303 <a name=CENTER_SAY_VARARGS><p><li></a>
304 <tt> void <b>CENTER_SAY_VARARGS(PLID, <i>hudtextparms_t tparms, char *fmt, va_list ap</i>)</b></tt>
305 <br> As in <tt>CENTER_SAY_PARMS</tt> above, only the message is passed
306 as a <tt>vsnprintf</tt> style varargs format string and args list.
307 This is included merely because both the previous CENTER_SAY functions
308 actually call this, and it was convenient to include it as well.
309 <i>[added in 1.06]</i>
310 <a name=CALL_GAME_ENTITY><p><li></a>
311 <tt> qboolean <b>CALL_GAME_ENTITY(PLID, <i>char *entStr, entvars_t *pev</i>)</b></tt>
312 <br>Calls an entity function in the gameDLL. For instance, a bot usually
313 needs to call the <tt><b>player</b></tt> entity function.
314 <i>[added in 1.09]</i>
315 <a name=GET_USER_MSG_ID><p><li></a>
316 <tt> int <b>GET_USER_MSG_ID(PLID, <i>const char *name, int *size</i>)</b></tt>
317 <br>Returns the id number corresponding to the given message name, of
318 those messages registered by the gamedll with <a
319 href="engine_notes.html#RegUserMsg">RegUserMsg</a>, optionally
320 returning the registered size of the message as well. This is to
321 allow things like bots to access the name/id mapping without having to
322 catch RegUserMsg themselves, and thus have to be loaded at startup.
323 <i>[added in 1.11]</i>
324 <a name=GET_USER_MSG_NAME><p><li></a>
325 <tt> const char * <b>GET_USER_MSG_NAME(PLID, <i>int msgid, int *size</i>)</b></tt>
326 <br>Returns the name corresponding to the given msgid number, of those
327 messages registered by the gamedll with <a
328 href="engine_notes.html#RegUserMsg">RegUserMsg</a>, optionally
329 returning the registered size of the message as well. It will return
330 guess-names for any builtin Engine messages that it knows about
331 (<tt>SVC_TEMPENTITY</tt>, etc). The returned string is presumed to be
332 a compile-time constant string, stored in the text segment of the
334 <i>[added in 1.11]</i>
335 <a name=GET_PLUGIN_PATH><p><li></a>
336 <tt> const char * <b>GET_PLUGIN_PATH(PLID)</b></tt>
337 <br>Returns the full pathname of the loaded dll/so file for the calling
338 plugin. The returned string is a pointer to a static buffer, and should be
339 copied by the caller to local storage.
340 <i>[added in 1.12]</i>
341 <a name=GET_GAME_INFO><p><li></a>
342 <tt> const char * <b>GET_GAME_INFO(PLID, <i>ginfo_t type</i>)</b></tt>
343 <br>Returns various string-based information about the running
344 game/MOD/gamedll. The given <i>type</i> can be one of:
346 <li><tt><b>GINFO_NAME</b></tt> - short name of game, from "-game" argument to hlds (ie "cstrike")
347 <li><tt><b>GINFO_DESC</b></tt> - long name of game, from autodetection (ie "Counter-Strike")
348 <li><tt><b>GINFO_GAMEDIR</b></tt> - game directory, full pathname (ie "/usr/local/half-life/cstrike")
349 <li><tt><b>GINFO_DLL_FULLPATH</b></tt> - full pathname of the game dll (ie "/usr/local/half-life/cstrike/dlls/cs_i386.so")
350 <li><tt><b>GINFO_DLL_FILENAME</b></tt> - bare filename of the gamedll (ie "cs_i386.so")
352 The returned string is a pointer to a static buffer, and should be
353 copied by the caller to local storage.
354 <i>[added in 1.14]</i>
355 <a name="LOAD_PLUGIN"><p><li></a>
356 <tt> int <b>LOAD_PLUGIN(PLID, <i>const char *name, PLUG_LOADTIME now, void **handle</i>)</b></tt>
357 <br>Attempts to load a plugin as if "meta load <name>" was passed. If
358 handle is passed, it will be NULL on failure or contain the DLL handle on success.
359 Returns 0 for success, non-zero Metamod error value for failure.
360 <i>[added in 1.18]</i>
361 <a name="UNLOAD_PLUGIN"><p><li></a>
362 <tt> int <b>UNLOAD_PLUGIN(PLID, <i>const char *name, PLUG_LOADTIME now, PL_UNLOAD_REASON reason</i>)</b></tt>
363 <br>Attempts to unload a plugin given by name. A plugin cannot unload itself.
364 Returns 0 for success, non-zero Metamod error value for failure.
365 <i>[added in 1.18]</i>
366 <a name="UNLOAD_PLUGIN_BY_HANDLE"><p><li></a>
367 <tt> int <b>UNLOAD_PLUGIN_BY_HANDLE(PLID, <i>void *handle, PLUG_LOADTIME now, PL_UNLOAD_REASON reason</i>)</b></tt>
368 <br>Attempts to unload a plugin given by the DLL handle from LOAD_PLUGIN. A plugin cannot unload itself.
369 Returns 0 for success, non-zero Metamod error value for failure.
370 <i>[added in 1.18]</i>
371 <a name="IS_QUERYING_CLIENT_CVAR"><p><li></a>
372 <tt> const char *<b>IS_QUERYING_CLIENT_CVAR(PLID, <i>const edict_t
373 *player</i>)</b></tt> <b>OBSOLETE</b>
374 <br>Returns the current cvar name that a client is being queried for,
375 NULL if no queries are in session.
376 <i>[added in 1.18]</i>
377 <br>This function is considered <b>obsolete</b> as the new method of
378 querying a client's cvar (added in hlsdk-2.3-p3/MM 1.18.1) is much more
379 reliable than the old one and doesn't need this function anymore. It is
380 strongly recommended to not use this function and the old
381 QueryClientCvar() and CvarValue() functions anymore, but only use the
382 new QueryClientCvar2() and CvarValue2() functions.
383 <br><i>Note:</i> This function can only be used in conjunction with the
384 old QueryClientCvar() function. Use with the new QueryClientCvar2()
385 function is not needed and therefor undefined, i.e. it doesn't return
386 anything meaningful when used in conjunction with it.
394 <i>(this is some rough notes I intend to fill in in the future)</i><p>
396 Plugins are loaded when the engine calls <tt><b>GiveFnptrsToDll()</b></tt>.
397 The config file is parsed, and for each valid plugin (uncommented, platform
398 relevant), the operation is:
401 <li> dlopen() the file, store the handle
402 <li> dlsym() and call:
404 Meta_Init (if present)
409 <li> if present, call function pointers, and store resulting function table:
417 GetNewDLLFunctions_Post
420 GetEngineFunctions_Post