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