|
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@249
|
20 |
and a modified version of SDK 2.3 at <a href="http://metamod.org/files/sdk/">metamod.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><one or more Get function></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 <name>" 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@249
|
373 |
*player</i>)</b></tt> <b>OBSOLETE</b> |
|
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@249
|
377 |
<br>This function is considered <b>obsolete</b> as the new method of |
|
darope@249
|
378 |
querying a client's cvar (added in hlsdk-2.3-p3/MM 1.18.1) is much more |
|
darope@249
|
379 |
reliable than the old one and doesn't need this function anymore. It is |
|
darope@249
|
380 |
strongly recommended to not use this function and the old |
|
darope@249
|
381 |
QueryClientCvar() and CvarValue() functions anymore, but only use the |
|
darope@249
|
382 |
new QueryClientCvar2() and CvarValue2() functions. |
|
darope@249
|
383 |
<br><i>Note:</i> This function can only be used in conjunction with the |
|
darope@249
|
384 |
old QueryClientCvar() function. Use with the new QueryClientCvar2() |
|
darope@249
|
385 |
function is not needed and therefor undefined, i.e. it doesn't return |
|
darope@249
|
386 |
anything meaningful when used in conjunction with it. |
|
darope@0
|
387 |
</ul> |
|
darope@0
|
388 |
|
|
darope@0
|
389 |
<p><br> |
|
darope@0
|
390 |
<a name=loading> |
|
darope@0
|
391 |
<h2>Plugin Loading |
|
darope@0
|
392 |
</h2></a> |
|
darope@0
|
393 |
|
|
darope@0
|
394 |
<i>(this is some rough notes I intend to fill in in the future)</i><p> |
|
darope@0
|
395 |
|
|
darope@0
|
396 |
Plugins are loaded when the engine calls <tt><b>GiveFnptrsToDll()</b></tt>. |
|
darope@0
|
397 |
The config file is parsed, and for each valid plugin (uncommented, platform |
|
darope@0
|
398 |
relevant), the operation is: |
|
darope@0
|
399 |
|
|
darope@0
|
400 |
<ul> |
|
darope@0
|
401 |
<li> dlopen() the file, store the handle |
|
darope@0
|
402 |
<li> dlsym() and call: |
|
darope@0
|
403 |
<pre> |
|
darope@0
|
404 |
Meta_Init (if present) |
|
darope@0
|
405 |
GiveFnptrsToDll |
|
darope@0
|
406 |
Meta_Query |
|
darope@0
|
407 |
Meta_Attach |
|
darope@0
|
408 |
</pre> |
|
darope@0
|
409 |
<li> if present, call function pointers, and store resulting function table: |
|
darope@0
|
410 |
<pre> |
|
darope@0
|
411 |
GetEntityAPI |
|
darope@0
|
412 |
GetEntityAPI2 |
|
darope@0
|
413 |
GetNewDLLFunctions |
|
darope@0
|
414 |
|
|
darope@0
|
415 |
GetEntityAPI_Post |
|
darope@0
|
416 |
GetEntityAPI2_Post |
|
darope@0
|
417 |
GetNewDLLFunctions_Post |
|
darope@0
|
418 |
|
|
darope@0
|
419 |
GetEngineFunctions |
|
darope@0
|
420 |
GetEngineFunctions_Post |
|
darope@0
|
421 |
</pre> |
|
darope@0
|
422 |
</ul> |
|
darope@0
|
423 |
|
|
darope@0
|
424 |
<p> |
|
darope@0
|
425 |
<hr> |
|
darope@0
|
426 |
|
|
darope@0
|
427 |
</body> |
|
darope@0
|
428 |
</HTML> |