Fixed makefile error when issuing 'make clean' or 'make distclean'.
1 <!-- vi: set ts=4 sw=4 : -->
2 <!-- vim: set tw=75 : -->
6 <title>HLSDK DLLAPI Notes</title>
10 <h1>HLSDK DLLAPI Notes
15 <li><a href=#GameDLLInit>GameDLLInit</a>
16 <li><a href=#DispatchSpawn>DispatchSpawn</a>
17 <li><a href=#DispatchThink>DispatchThink</a>
18 <li><a href=#DispatchUse>DispatchUse</a>
19 <li><a href=#DispatchTouch>DispatchTouch</a>
20 <li><a href=#DispatchBlocked>DispatchBlocked</a>
21 <li><a href=#DispatchKeyValue>DispatchKeyValue</a>
22 <li><a href=#DispatchSave>DispatchSave</a>
23 <li><a href=#DispatchRestore>DispatchRestore</a>
24 <li><a href=#DispatchObjectCollsionBox>DispatchObjectCollsionBox</a>
25 <li><a href=#SaveWriteFields>SaveWriteFields</a>
26 <li><a href=#SaveReadFields>SaveReadFields</a>
27 <li><a href=#SaveGlobalState>SaveGlobalState</a>
28 <li><a href=#RestoreGlobalState>RestoreGlobalState</a>
29 <li><a href=#ResetGlobalState>ResetGlobalState</a>
30 <li><a href=#ClientConnect>ClientConnect</a>
31 <li><a href=#ClientDisconnect>ClientDisconnect</a>
32 <li><a href=#ClientKill>ClientKill</a>
33 <li><a href=#ClientPutInServer>ClientPutInServer</a>
34 <li><a href=#ClientCommand>ClientCommand</a>
35 <li><a href=#ClientUserInfoChanged>ClientUserInfoChanged</a>
36 <li><a href=#ServerActivate>ServerActivate</a>
37 <li><a href=#ServerDeactivate>ServerDeactivate</a>
38 <li><a href=#PlayerPreThink>PlayerPreThink</a>
39 <li><a href=#PlayerPostThink>PlayerPostThink</a>
40 <li><a href=#StartFrame>StartFrame</a>
41 <li><a href=#ParmsNewLevel>ParmsNewLevel</a>
42 <li><a href=#ParmsChangeLevel>ParmsChangeLevel</a>
43 <li><a href=#GetGameDescription>GetGameDescription</a>
44 <li><a href=#PlayerCustomization>PlayerCustomization</a>
45 <li><a href=#SpectatorConnect>SpectatorConnect</a>
46 <li><a href=#SpectatorDisconnect>SpectatorDisconnect</a>
47 <li><a href=#SpectatorThink>SpectatorThink</a>
48 <li><a href=#Sys_Error>Sys_Error</a>
49 <li><a href=#PM_Move>PM_Move</a>
50 <li><a href=#PM_Init>PM_Init</a>
51 <li><a href=#PM_FindTextureType>PM_FindTextureType</a>
52 <li><a href=#SetupVisibility>SetupVisibility</a>
53 <li><a href=#UpdateClientData>UpdateClientData</a>
54 <li><a href=#AddToFullPack>AddToFullPack</a>
55 <li><a href=#CreateBaseline>CreateBaseline</a>
56 <li><a href=#RegisterEncoders>RegisterEncoders</a>
57 <li><a href=#GetWeaponData>GetWeaponData</a>
58 <li><a href=#CmdStart>CmdStart</a>
59 <li><a href=#CmdEnd>CmdEnd</a>
60 <li><a href=#ConnectionlessPacket>ConnectionlessPacket</a>
61 <li><a href=#GetHullBounds>GetHullBounds</a>
62 <li><a href=#CreateInstancedBaselines>CreateInstancedBaselines</a>
63 <li><a href=#InconsistentFile>InconsistentFile</a>
64 <li><a href=#AllowLagCompensation>AllowLagCompensation</a>
67 <hr><h3><tt><a name="GameDLLInit">GameDLLInit</a></tt></h3>
68 <i>from dlls/game.cpp:</i><br>
69 <dd><tt>void GameDLLInit(void);</tt><p>
71 Register your console variables here.<br>
72 This gets called one time when the game is initialied.<br>
73 Initialize the game (one-time call after loading of game .dll)<br>
75 <p><i>comments:</i><br>
77 Called just after hlds reports "Dll loaded for mod Half-Life".
80 <hr><h3><tt><a name="DispatchSpawn">DispatchSpawn</a></tt></h3>
81 <i>from dlls/cbase.cpp</I>
82 <dd><tt>int DispatchSpawn(edict_t *pent);</tt><p>
83 <p><i>comments:</i><br>
85 0==Success, -1==Failure ?
88 <hr><h3><tt><a name="DispatchThink">DispatchThink</a></tt></h3>
89 <i>from dlls/cbase.cpp</i><br>
90 <dd><tt>void DispatchThink(edict_t *pent);</tt><p>
92 <hr><h3><tt><a name="DispatchUse">DispatchUse</a></tt></h3>
93 <i>from dlls/cbase.cpp</i><br>
94 <dd><tt>void DispatchUse(edict_t *pentUsed, edict_t *pentOther);</tt><p>
96 <hr><h3><tt><a name="DispatchTouch">DispatchTouch</a></tt></h3>
97 <i>from dlls/cbase.cpp</i><br>
98 <dd><tt>void DispatchTouch(edict_t *pentTouched, edict_t *pentOther);</tt><p>
100 <hr><h3><tt><a name="DispatchBlocked">DispatchBlocked</a></tt></h3>
101 <i>from dlls/cbase.cpp</i><br>
102 <dd><tt>void DispatchBlocked(edict_t *pentBlocked, edict_t *pentOther);</tt><p>
104 <hr><h3><tt><a name="DispatchKeyValue">DispatchKeyValue</a></tt></h3>
105 <i>from dlls/cbase.cpp</i><br>
106 <dd><tt>void DispatchKeyValue(edict_t *pentKeyvalue, KeyValueData *pkvd);</tt><p>
108 <hr><h3><tt><a name="DispatchSave">DispatchSave</a></tt></h3>
109 <i>from dlls/cbase.cpp</i><br>
110 <dd><tt>void DispatchSave(edict_t *pent, SAVERESTOREDATA *pSaveData);</tt><p>
112 <hr><h3><tt><a name="DispatchRestore">DispatchRestore</a></tt></h3>
113 <i>from dlls/cbase.cpp</i><br>
114 <dd><tt>int DispatchRestore(edict_t *pent, SAVERESTOREDATA *pSaveData, int globalEntity);</tt><p>
115 <p><i>comments:</i><br>
117 0==Success, -1==Failure ?
120 <hr><h3><tt><a name="DispatchObjectCollsionBox">DispatchObjectCollsionBox</a></tt></h3>
121 <i>from dlls/cbase.cpp</i><br>
122 <dd><tt>void DispatchObjectCollsionBox(edict_t *pent);</tt><p>
124 <hr><h3><tt><a name="SaveWriteFields">SaveWriteFields</a></tt></h3>
125 <i>from dlls/cbase.cpp</i><br>
126 <dd><tt>void SaveWriteFields(SAVERESTOREDATA *pSaveData, const char *pname, void *pBaseData, TYPEDESCRIPTION *pFields, int fieldCount);</tt><p>
128 <hr><h3><tt><a name="SaveReadFields">SaveReadFields</a></tt></h3>
129 <i>from dlls/cbase.cpp</i><br>
130 <dd><tt>void SaveReadFields(SAVERESTOREDATA *pSaveData, const char *pname, void *pBaseData, TYPEDESCRIPTION *pFields, int fieldCount);</tt><p>
132 <hr><h3><tt><a name="SaveGlobalState">SaveGlobalState</a></tt></h3>
133 <i>from dlls/world.cpp</i><br>
134 <dd><tt>void SaveGlobalState(SAVERESTOREDATA *pSaveData);</tt><p>
136 <hr><h3><tt><a name="RestoreGlobalState">RestoreGlobalState</a></tt></h3>
137 <i>from dlls/world.cpp</i><br>
138 <dd><tt>void RestoreGlobalState(SAVERESTOREDATA *pSaveData);</tt><p>
140 <hr><h3><tt><a name="ResetGlobalState">ResetGlobalState</a></tt></h3>
141 <i>from dlls/world.cpp</i><br>
142 <dd><tt>void ResetGlobalState(void);</tt><p>
144 <hr><h3><tt><a name="ClientConnect">ClientConnect</a></tt></h3>
145 <i>from dlls/client.cpp:</i><br>
146 <dd><tt>BOOL ClientConnect(edict_t *pEntity, const char *pszName, const char *pszAddress, char szRejectReason[128]);</tt><p>
148 Called when a player connects to a server.
150 <p><i>comments:</i><br>
152 Called on initial connect, just after hlds reports "connected", ie:
153 <pre> <tt>"John<1><WON:9856723>" connected, address "127.0.0.1:27005"</tt></pre>
154 This is before the user begins downloading, or anything else.
157 <hr><h3><tt><a name="ClientDisconnect">ClientDisconnect</a></tt></h3>
158 <i>from dlls/client.cpp:</i><br>
159 <dd><tt>void ClientDisconnect(edict_t *pEntity);</tt><p>
161 Called when a player disconnects from a server.<br>
162 GLOBALS ASSUMED SET: g_fGameOver
164 <p><i>comments:</i><br>
166 This is not the opposite of <tt><b>ClientConnect</b></tt>, despite the similar name.
167 It appears to only be called if the client was <tt><b>PutInServer</b></tt> first. If
168 the client disconnects before being <tt><b>PutInServer</b></tt>, no API routine is
169 called. This would be more appropriately named <tt><i><b>ClientRemoveFromServer</i></b></tt>.
172 <hr><h3><tt><a name="ClientKill">ClientKill</a></tt></h3>
173 <i>from dlls/client.cpp:</i><br>
174 <dd><tt>void ClientKill(edict_t *pEntity);</tt><p>
176 Player entered the suicide command.<br>
177 GLOBALS ASSUMED SET: g_ulModelIndexPlayer
179 <p><i>comments:</i><br>
181 When the client typed "kill" in the console?
184 <hr><h3><tt><a name="ClientPutInServer">ClientPutInServer</a></tt></h3>
185 <i>from dlls/client.cpp:</i><br>
186 <dd><tt>void ClientPutInServer(edict_t *pEntity);</tt><p>
188 Called each time a player is spawned.
190 <p><i>comments:</i><br>
192 Called after the client has uploaded/download all necessary resources,
193 just after hlds reports "entered the game", ie:
194 <pre> "John<1>" has entered the game</pre>
197 <hr><h3><tt><a name="ClientCommand">ClientCommand</a></tt></h3>
198 <i>from dlls/client.cpp:</i><br>
199 <dd><tt>void ClientCommand(edict_t *pEntity);</tt><p>
201 Called each time a player uses a "cmd" command.
202 Use CMD_ARGS, CMD_ARGV, and CMD_ARGC to get pointers to the character
206 <hr><h3><tt><a name="ClientUserInfoChanged">ClientUserInfoChanged</a></tt></h3>
207 <i>from dlls/client.cpp:</i><br>
208 <dd><tt>void ClientUserInfoChanged(edict_t *pEntity, char *infobuffer);</tt><p>
210 Called after the player changes userinfo - gives dll a chance to modify
211 it before it gets sent into the rest of the engine.
213 <p><i>comments:</i><br>
215 Called when user issues <tt>"<b>setinfo</b>"</tt> from the console. Also appears to be
216 called whenever the user returns to the game from the ESC menu.
219 <hr><h3><tt><a name="ServerActivate">ServerActivate</a></tt></h3>
220 <i>from dlls/client.cpp:</i><br>
221 <dd><tt>void ServerActivate(edict_t *pEdictList, int edictCount, int clientMax);</tt><p>
223 Every call to ServerActivate should be matched by a call to
226 <p><i>comments:</i><br>
229 Apparently called when the server has loaded the map, but before it
230 precaches from the <tt><b>.res</b></tt> file.
233 <hr><h3><tt><a name="ServerDeactivate">ServerDeactivate</a></tt></h3>
234 <i>from dlls/client.cpp:</i><br>
235 <dd><tt>void ServerDeactivate(void);</tt><p>
237 Peform any shutdown operations here.<br>
238 It's possible that the engine will call this function more times than
239 is necessary. Therefore, only run it one time for each call to
242 <p><i>comments:</i><br>
244 Called upon <tt>"<b>quit</b>"</tt> or <tt>"<b>changelevel</b>"</tt> .
247 <hr><h3><tt><a name="PlayerPreThink">PlayerPreThink</a></tt></h3>
248 <i>from dlls/client.cpp:</i><br>
249 <dd><tt>void PlayerPreThink(edict_t *pEntity);</tt><p>
251 Called every frame before physics are run.
254 <hr><h3><tt><a name="PlayerPostThink">PlayerPostThink</a></tt></h3>
255 <i>from dlls/client.cpp:</i><br>
256 <dd><tt>void PlayerPostThink(edict_t *pEntity);</tt><p>
258 Called every frame after physics are run.
261 <hr><h3><tt><a name="StartFrame">StartFrame</a></tt></h3>
262 <i>from dlls/client.cpp:</i><br>
263 <dd><tt>void StartFrame(void);</tt><p>
265 GLOBALS ASSUMED SET: g_ulFrameCount
268 <hr><h3><tt><a name="ParmsNewLevel">ParmsNewLevel</a></tt></h3>
269 <i>from dlls/client.cpp</i><br>
270 <dd><tt>void ParmsNewLevel(void);</tt><p>
272 <hr><h3><tt><a name="ParmsChangeLevel">ParmsChangeLevel</a></tt></h3>
273 <i>from dlls/client.cpp</i><br>
274 <dd><tt>void ParmsChangeLevel(void);</tt><p>
276 <hr><h3><tt><a name="GetGameDescription">GetGameDescription</a></tt></h3>
277 <i>from dlls/client.cpp:</i><br>
278 <dd><tt>const char *GetGameDescription(void);</tt><p>
280 Returns string describing current .dll game.<br>
281 Returns the descriptive name of this .dll. E.g., Half-Life, or Team
283 This function might be called before the world has spawned, and the game
284 rules initialized.<br>
287 <hr><h3><tt><a name="PlayerCustomization">PlayerCustomization</a></tt></h3>
288 <i>from dlls/client.cpp:</i><br>
289 <dd><tt>void PlayerCustomization(edict_t *pEntity, customization_t *pCust);</tt><p>
291 Notifies .dll of new customization for player.<br>
292 A new player customization has been registered on the server.
293 UNDONE: This only sets the # of frames of the spray can logo animation
297 <hr><h3><tt><a name="SpectatorConnect">SpectatorConnect</a></tt></h3>
298 <i>from dlls/client.cpp:</i><br>
299 <dd><tt>void SpectatorConnect(edict_t *pEntity);</tt><p>
301 Called when spectator joins server.<br>
302 A spectator has joined the game.<br>
305 <hr><h3><tt><a name="SpectatorDisconnect">SpectatorDisconnect</a></tt></h3>
306 <i>from dlls/client.cpp:</i><br>
307 <dd><tt>void SpectatorDisconnect(edict_t *pEntity);</tt><p>
309 Called when spectator leaves the server.<br>
310 A spectator has left the game.<br>
313 <hr><h3><tt><a name="SpectatorThink">SpectatorThink</a></tt></h3>
314 <i>from dlls/client.cpp:</i><br>
315 <dd><tt>void SpectatorThink(edict_t *pEntity);</tt><p>
317 Called when spectator sends a command packet (usercmd_t).<br>
318 A spectator has sent a usercmd.<br>
321 <hr><h3><tt><a name="Sys_Error">Sys_Error</a></tt></h3>
322 <i>from dlls/client.cpp:</i><br>
323 <dd><tt>void Sys_Error(const char *error_string);</tt><p>
325 Called when engine has encountered an error.<br>
326 Notify game .dll that engine is going to shut down.<br>
327 Engine is going to shut down, allows setting a breakpoint in game dll
328 to catch that occasion.<br>
329 Add code ( e.g., _asm { int 3 }; here to cause a breakpoint for
330 debugging your game .dlls.<br>
332 <p><i>comments:</i><br>
337 <hr><h3><tt><a name="PM_Move">PM_Move</a></tt></h3>
338 <i>from pm_shared/pm_shared.c:</i><br>
339 <dd><tt>void PM_Move(struct playermove_s *ppmove, int server);</tt><p>
341 This modume implements the shared player physics code between
342 any particular game and the engine. The same PM_Move routine is built
343 into the game .dll and the client .dll and is invoked by each side as
344 appropriate. There should be no distinction, internally, between server
345 and client. This will ensure that prediction behaves appropriately.
347 <p><i>comments:</i><br>
352 <hr><h3><tt><a name="PM_Init">PM_Init</a></tt></h3>
353 <i>from pm_shared/pm_shared.c:</i>
354 <dd><tt>void PM_Init(struct playermove_s *ppmove);</tt><p>
356 Server version of player movement initialization.
358 <p><i>comments:</i><br>
363 <hr><h3><tt><a name="PM_FindTextureType">PM_FindTextureType</a></tt></h3>
364 <i>from pm_shared/pm_shared.c</i><br>
365 <dd><tt>char PM_FindTextureType(char *name);</tt><p>
366 <p><i>comments:</i><br>
371 <hr><h3><tt><a name="SetupVisibility">SetupVisibility</a></tt></h3>
372 <i>from dlls/client.cpp:</i><br>
373 <dd><tt>void SetupVisibility(edict_t *pViewEntity, edict_t *pClient, unsigned char **pvs, unsigned char **pas);</tt><p>
374 <i>from dlls/client.cpp:</i>
376 Set up PVS and PAS for networking for this client.
378 A client can have a separate "view entity" indicating
379 that his/her view should depend on the origin of that view entity. If
380 that's the case, then pViewEntity will be non-NULL and will be used.
381 Otherwise, the current entity's origin is used. Either is offset by the
382 view_ofs to get the eye position.
384 From the eye position, we set up the PAS and PVS to use for filtering
385 network messages to the client. At this point, we could override the
386 actual PAS or PVS values, or use a different origin.
388 NOTE: Do not cache the values of pas and pvs, as they depend on
389 reusable memory in the engine, they are only good for this one frame
391 <p><i>comments:</i><br>
396 <hr><h3><tt><a name="UpdateClientData">UpdateClientData</a></tt></h3>
397 <i>from dlls/client.cpp:</i><br>
398 <dd><tt>void UpdateClientData (const struct edict_s *ent, int sendweapons, struct clientdata_s *cd);</tt><p>
400 Set up data sent only to specific client.<br>
401 Data sent to current client only.<br>
402 Engine sets argument 'cd' to 0 before calling.<br>
404 <p><i>comments:</i><br>
409 <hr><h3><tt><a name="AddToFullPack">AddToFullPack</a></tt></h3>
410 <i>from dlls/client.cpp:</i><br>
411 <dd><tt>int AddToFullPack(struct entity_state_s *state, int e, edict_t *ent, edict_t *host, int hostflags, int player, unsigned char *pSet);</tt><p>
413 Return 1 if the entity state has been filled in for the ent and the
414 entity will be propagated to the client, 0 otherwise.
416 State is the server maintained copy of the state info that is
417 transmitted to the client. A MOD could alter values copied into state
418 to send the "host" a different look for a particular entity update,
421 Arguments 'e' and 'ent' are the entity that is being added to the
422 update, if 1 is returneds. Host is the player's edict of the player
423 whom we are sending the update to. Player is 1 if the ent/e is a
424 player and 0 otherwise. Argument 'pSet' is either the PAS or PVS that
425 we previous set up. We can use it to ask the engine to filter the
426 entity against the PAS or PVS.
428 We could also use the pas/ pvs that we set in SetupVisibility, if we
429 wanted to. Caching the value is valid in that case, but still only for
432 <p><i>comments:</i><br>
437 <hr><h3><tt><a name="CreateBaseline">CreateBaseline</a></tt></h3>
438 <i>from dlls/client.cpp:</i><br>
439 <dd><tt>void CreateBaseline(int player, int eindex, struct entity_state_s *baseline, struct edict_s *entity, int playermodelindex, vec3_t player_mins, vec3_t player_maxs);</tt><p>
441 Tweak entity baseline for network encoding, allows setup of player
443 Creates baselines used for network encoding, especially for player data
444 since players are not spawned until connect time.<br>
446 <p><i>comments:</i><br>
451 <hr><h3><tt><a name="RegisterEncoders">RegisterEncoders</a></tt></h3>
452 <i>from dlls/client.cpp:</i><br>
453 <dd><tt>void RegisterEncoders(void);</tt><p>
455 Callbacks for network encoding.<br>
456 Allows game .dll to override network encoding of certain types of
457 entities and tweak values, etc.<br>
459 <p><i>comments:</i><br>
464 <hr><h3><tt><a name="GetWeaponData">GetWeaponData</a></tt></h3>
465 <i>from dlls/client.cpp</i><br>
466 <dd><tt>int GetWeaponData(struct edict_s *player, struct weapon_data_s *info);</tt><p>
467 <p><i>comments:</i><br>
472 <hr><h3><tt><a name="CmdStart">CmdStart</a></tt></h3>
473 <i>from dlls/client.cpp:</i><br>
474 <dd><tt>void CmdStart(const edict_t *player, const struct usercmd_s *cmd, unsigned int random_seed);</tt><p>
476 We're about to run this usercmd for the specified player. We can set
477 up groupinfo and masking here, etc. This is the time to examine the
478 usercmd for anything extra. This call happens even if think does not.
480 <p><i>comments:</i><br>
485 <hr><h3><tt><a name="CmdEnd">CmdEnd</a></tt></h3>
486 <i>from dlls/client.cpp:</i><br>
487 <dd><tt>void CmdEnd (const edict_t *player);</tt><p>
489 Each cmdstart is exactly matched with a cmd end, clean up any
490 group trace flags, etc. here.
492 <p><i>comments:</i><br>
497 <hr><h3><tt><a name="ConnectionlessPacket">ConnectionlessPacket</a></tt></h3>
498 <i>from dlls/client.cpp:</i><br>
499 <dd><tt>int ConnectionlessPacket(const struct netadr_s *net_from, const char *args, char *response_buffer, int *response_buffer_size);</tt>
501 Return 1 if the packet is valid. Set response_buffer_size if you want
502 to send a response packet. Incoming, it holds the max size of the
503 response_buffer, so you must zero it out if you choose not to respond.
505 <p><i>comments:</i><br>
510 <hr><h3><tt><a name="GetHullBounds">GetHullBounds</a></tt></h3>
511 <i>from dlls/client.cpp:</i><br>
512 <dd><tt>int GetHullBounds(int hullnumber, float *mins, float *maxs);</tt><p>
514 Engine calls this to enumerate player collision hulls,
515 for prediction. Return 0 if the hullnumber doesn't exist.
517 <p><i>comments:</i><br>
522 <hr><h3><tt><a name="CreateInstancedBaselines">CreateInstancedBaselines</a></tt></h3>
523 <i>from dlls/client.cpp:</i><br>
524 <dd><tt>void CreateInstancedBaselines (void);</tt><p>
526 Tweak entity baseline for network encoding, allows setup of player baselines, too.<br>
527 Create pseudo-baselines for items that aren't placed in the map at
528 spawn time, but which are likely to be created during play (e.g.,
529 grenades, ammo packs, projectiles, corpses, etc.).<br>
531 <p><i>comments:</i><br>
536 <hr><h3><tt><a name="InconsistentFile">InconsistentFile</a></tt></h3>
537 <i>from dlls/client.cpp:</i><br>
538 <dd><tt>int InconsistentFile(const edict_t *player, const char *filename, char *disconnect_message);</tt>
540 One of the ENGINE_FORCE_UNMODIFIED files failed the consistency check
541 for the specified player Return 0 to allow the client to continue, 1 to
542 force immediate disconnection (with an optional disconnect message of
543 up to 256 characters).
545 <p><i>comments:</i><br>
550 <hr><h3><tt><a name="AllowLagCompensation">AllowLagCompensation</a></tt></h3>
551 <i>from dlls/client.cpp:</i><br>
552 <dd><tt>int AllowLagCompensation(void);</tt><p>
554 The game .dll should return 1 if lag compensation should be allowed
555 (could also just set the sv_unlag cvar. Most games right now should
556 return 0, until client-side weapon prediction code is written and
557 tested for them (note you can predict weapons, but not do lag
558 compensation, too, if you want.
560 <p><i>comments:</i><br>