3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _clients_included
36 #define _clients_included
39 * Network flow directions.
43 NetFlow_Outgoing = 0, /**< Outgoing traffic */
44 NetFlow_Incoming, /**< Incoming traffic */
45 NetFlow_Both, /**< Both values added together */
48 #define MAXPLAYERS 64 /**< Maximum number of players that can be in server */
49 #define MAX_NAME_LENGTH 32 /**< Maximum buffer required to store a client name */
52 * Called on client connection.
54 * @param client Client index.
55 * @param rejectmsg Buffer to store the rejection message when the connection is refused.
56 * @param maxlen Maximum number of characters for rejection buffer.
57 * @return True to validate client's connection, false to refuse it.
59 forward bool:OnClientConnect(client, String:rejectmsg[], maxlen);
62 * Called when a client is entering the game.
64 * Whether a client has a steamid is undefined until OnClientAuthorized
65 * is called, which may occur either before or after OnClientPutInServer.
66 * Similarly, use OnClientPostAdminCheck() if you need to verify whether
67 * connecting players are admins.
69 * GetClientCount() will include clients as they are passed through this
70 * function, as clients are already in game at this point.
72 * @param client Client index.
75 forward OnClientPutInServer(client);
78 * Called when a client is disconnecting from the server.
80 * @param client Client index.
83 forward OnClientDisconnect(client);
86 * Called when a client is disconnected from the server.
88 * @param client Client index.
91 forward OnClientDisconnect_Post(client);
94 * Called when a client is sending a command.
96 * @param client Client index.
97 * @param args Number of arguments.
100 forward Action:OnClientCommand(client, args);
103 * Called whenever the client's settings are changed.
105 * @param client Client index.
108 forward OnClientSettingsChanged(client);
111 * Called when a client receives a Steam ID. The state of a client's
112 * authorization via Steam or as an admin is not guaranteed here.
113 * Use OnClientAuthorized() or OnClientPostAdminCheck() for those,
116 * This is called by bots, but the ID will be "BOT".
118 * @param client Client index.
119 * @param auth Client auth string.
122 forward OnClientAuthorized(client, const String:auth[]);
125 * Called once a client is authorized and fully in-game, but
126 * before admin checks are done. This can be used to override
127 * the default admin checks for a client. You should only use
128 * this for overriding; use OnClientPostAdminCheck() instead
129 * if you want notification.
131 * Note: If handled/blocked, PostAdminCheck must be signalled
132 * manually via NotifyPostAdminCheck().
134 * This callback is gauranteed to occur on all clients, and always
135 * after each OnClientPutInServer() call.
137 * @param client Client index.
138 * @return Plugin_Handled to block admin checks.
140 forward Action:OnClientPreAdminCheck(client);
143 * Called directly before OnClientPostAdminCheck() as a method to
144 * alter administrative permissions before plugins perform final
145 * post-connect operations.
147 * In general, do not use this function unless you are specifically
148 * attempting to change access permissions. Use OnClientPostAdminCheck()
149 * instead if you simply want to perform post-connect authorization
152 * See OnClientPostAdminCheck() for more information.
154 * @param client Client index.
157 forward OnClientPostAdminFilter(client);
160 * Called once a client is authorized and fully in-game, and
161 * after all post-connection authorizations have been performed.
163 * This callback is gauranteed to occur on all clients, and always
164 * after each OnClientPutInServer() call.
166 * @param client Client index.
169 forward OnClientPostAdminCheck(client);
172 * Returns the maximum number of clients allowed on the server. This may
173 * return 0 if called before OnMapStart(), and thus should not be called
174 * in OnPluginStart().
176 * @return Maximum number of clients allowed.
178 native GetMaxClients();
181 * Returns the client count put in the server.
183 * @param inGameOnly If false connecting players are also counted.
184 * @return Client count in the server.
186 native GetClientCount(bool:inGameOnly=true);
189 * Returns the client's name.
191 * @param client Player index.
192 * @param name Buffer to store the client's name.
193 * @param maxlen Maximum length of string buffer (includes NULL terminator).
194 * @return True on success, false otherwise.
195 * @error If the client is not connected an error will be thrown.
197 native bool:GetClientName(client, String:name[], maxlen);
200 * Retrieves a client's IP address.
202 * @param client Player index.
203 * @param name Buffer to store the client's ip address.
204 * @param maxlen Maximum length of string buffer (includes NULL terminator).
205 * @param remport Remove client's port from the ip string (true by default).
206 * @return True on success, false otherwise.
207 * @error If the client is not connected or the index is invalid.
209 native bool:GetClientIP(client, String:ip[], maxlen, bool:remport=true);
212 * Retrieves a client's authentication string (SteamID).
214 * @param client Player index.
215 * @param auth Buffer to store the client's auth string.
216 * @param maxlen Maximum length of string buffer (includes NULL terminator).
217 * @return True on success, false otherwise.
218 * @error If the client is not connected or the index is invalid.
220 native bool:GetClientAuthString(client, String:auth[], maxlen);
223 * Retrieves a client's user id, which is an index incremented for every client
224 * that joins the server.
226 * @param client Player index.
227 * @return User id of the client.
228 * @error If the client is not connected or the index is invalid.
230 native GetClientUserId(client);
233 * Returns if a certain player is connected.
235 * @param client Player index.
236 * @return True if player is connected to the server, false otherwise.
238 native bool:IsClientConnected(client);
241 * Returns if a certain player has entered the game.
243 * @param client Player index (index does not have to be connected).
244 * @return True if player has entered the game, false otherwise.
245 * @error Invalid client index.
247 native bool:IsClientInGame(client);
250 * Returns if a client is in the "kick queue" (i.e. the client will be kicked
251 * shortly and thus they should not appear as valid).
253 * @param client Player index (must be connected).
254 * @return True if in the kick queue, false otherwise.
255 * @error Invalid client index.
257 native bool:IsClientInKickQueue(client);
260 * Backwards compatibility stock - use IsClientInGame
261 * @deprecated Renamed to IsClientInGame
263 #pragma deprecated Use IsClientInGame() instead
264 stock bool:IsPlayerInGame(client)
266 return IsClientInGame(client);
270 * Returns if a certain player has been authenticated.
272 * @param client Player index.
273 * @return True if player has been authenticated, false otherwise.
275 native bool:IsClientAuthorized(client);
278 * Returns if a certain player is a fake client.
280 * @param client Player index.
281 * @return True if player is a fake client, false otherwise.
283 native bool:IsFakeClient(client);
286 * Returns if a certain player is an observer/spectator.
288 * @param client Player index.
289 * @return True if player is an obverser, false otherwise.
291 native bool:IsClientObserver(client);
294 * Returns if the client is alive or dead.
296 * Note: This function was originally in SDKTools and was moved to core.
298 * @param client Player's index.
299 * @return True if the client is alive, false otherwise.
300 * @error Invalid client index, client not in game, or no mod support.
302 native bool:IsPlayerAlive(client);
305 * Retrieves values from client replicated keys.
307 * @param client Player's index.
308 * @param key Key string.
309 * @param value Buffer to store value.
310 * @param maxlen Maximum length of valve (UTF-8 safe).
311 * @return True on success, false otherwise.
312 * @error Invalid client index, or client not connected.
314 native bool:GetClientInfo(client, const String:key[], String:value[], maxlen);
317 * Retrieves a client's team index.
319 * @param client Player's index.
320 * @return Team index the client is on (mod specific).
321 * @error Invalid client index, client not in game, or no mod support.
323 native GetClientTeam(client);
326 * Sets a client's AdminId.
328 * @param client Player's index.
329 * @param id AdminId to set. INVALID_ADMIN_ID removes admin permissions.
330 * @param temp True if the id should be freed on disconnect.
332 * @error Invalid client index, client not connected, or bogus AdminId.
334 native SetUserAdmin(client, AdminId:id, bool:temp=false);
337 * Retrieves a client's AdminId.
339 * @param client Player's index.
340 * @return AdminId of the client, or INVALID_ADMIN_ID if none.
341 * @error Invalid client index, or client not connected.
343 native AdminId:GetUserAdmin(client);
346 * Sets access flags on a client. If the client is not an admin,
347 * a temporary, anonymous AdminId is given.
349 * @param client Player's index.
350 * @param ... Flags to set on the client.
352 * @error Invalid client index, or client not connected.
354 native AddUserFlags(client, AdminFlag:...);
357 * Removes flags from a client. If the client is not an admin,
358 * this has no effect.
360 * @param client Player's index.
361 * @param ... Flags to remove from the client.
363 * @error Invalid client index, or client not connected.
365 native RemoveUserFlags(client, AdminFlag:...);
368 * Sets access flags on a client using bits instead of flags. If the
369 * client is not an admin, and flags not 0, a temporary, anonymous AdminId is given.
371 * @param client Player's index.
372 * @param flags Bitstring of flags to set on client.
375 native SetUserFlagBits(client, flags);
378 * Returns client access flags. If the client is not an admin,
379 * the result is always 0.
381 * @param client Player's index.
383 * @error Invalid client index, or client not connected.
385 native GetUserFlagBits(client);
388 * Returns whether a user can target another user.
389 * This is a helper function for CanAdminTarget.
391 * @param client Player's index.
392 * @param target Target player's index.
393 * @return True if target is targettable by the player, false otherwise.
394 * @error Invalid or unconnected player indexers.
396 native bool:CanUserTarget(client, target);
399 * Runs through the Core-defined admin authorization checks on a player.
400 * Has no effect if the player is already an admin.
402 * Note: This function is based on the internal cache only.
404 * @param client Client index.
405 * @return True if access was changed, false if it did not.
406 * @error Invalid client index or client not in-game AND authorized.
408 native bool:RunAdminCacheChecks(client);
411 * Signals that a player has completed post-connection admin checks.
412 * Has no effect if the player has already had this event signalled.
414 * Note: This must be sent even if no admin id was assigned.
416 * @param client Client index.
418 * @error Invalid client index or client not in-game AND authorized.
420 native NotifyPostAdminCheck(client);
423 * Creates a fake client.
425 * @param name Name to use.
426 * @return Client index on success, 0 otherwise.
428 native CreateFakeClient(const String:name[]);
431 * Sets a convar value on a fake client.
433 * @param client Client index.
434 * @param cvar ConVar name.
435 * @param value ConVar value.
437 * @error Invalid client index, client not connected,
438 * or client not a fake client.
440 native SetFakeClientConVar(client, const String:cvar[], const String:value[]);
443 * Returns the client's health.
445 * @param client Player's index.
446 * @return Health value.
447 * @error Invalid client index, client not in game, or no mod support.
449 native GetClientHealth(client);
452 * Returns the client's model name.
454 * @param client Player's index.
455 * @param model Buffer to store the client's model name.
456 * @param maxlen Maximum length of string buffer (includes NULL terminator).
458 * @error Invalid client index, client not in game, or no mod support.
460 native GetClientModel(client, String:model[], maxlen);
463 * Returns the client's weapon name.
465 * @param client Player's index.
466 * @param weapon Buffer to store the client's weapon name.
467 * @param maxlen Maximum length of string buffer (includes NULL terminator).
469 * @error Invalid client index, client not in game, or no mod support.
471 native GetClientWeapon(client, String:weapon[], maxlen);
474 * Returns the client's max size vector.
476 * @param client Player's index.
477 * @param vec Destination vector to store the client's max size.
479 * @error Invalid client index, client not in game, or no mod support.
481 native GetClientMaxs(client, Float:vec[3]);
484 * Returns the client's min size vector.
486 * @param client Player's index.
487 * @param vec Destination vector to store the client's min size.
489 * @error Invalid client index, client not in game, or no mod support.
491 native GetClientMins(client, Float:vec[3]);
494 * Returns the client's position angle.
496 * @param client Player's index.
497 * @param ang Destination vector to store the client's position angle.
499 * @error Invalid client index, client not in game, or no mod support.
501 native GetClientAbsAngles(client, Float:ang[3]);
504 * Returns the client's origin vector.
506 * @param client Player's index.
507 * @param vec Destination vector to store the client's origin vector.
509 * @error Invalid client index, client not in game, or no mod support.
511 native GetClientAbsOrigin(client, Float:vec[3]);
514 * Returns the client's armor.
516 * @param client Player's index.
517 * @return Armor value.
518 * @error Invalid client index, client not in game, or no mod support.
520 native GetClientArmor(client);
523 * Returns the client's death count.
525 * @param client Player's index.
526 * @return Death count.
527 * @error Invalid client index, client not in game, or no mod support.
529 native GetClientDeaths(client);
532 * Returns the client's frag count.
534 * @param client Player's index.
535 * @return Frag count.
536 * @error Invalid client index, client not in game, or no mod support.
538 native GetClientFrags(client);
541 * Returns the client's send data rate in bytes/sec.
543 * @param client Player's index.
545 * @error Invalid client index, client not in game, or fake client.
547 native GetClientDataRate(client);
550 * Returns if a client is timing out
552 * @param client Player's index.
553 * @return True if client is timing out, false otherwise.
554 * @error Invalid client index, client not in game, or fake client.
556 native bool:IsClientTimingOut(client);
559 * Returns the client's connection time in seconds.
561 * @param client Player's index.
562 * @return Connection time.
563 * @error Invalid client index, client not in game, or fake client.
565 native Float:GetClientTime(client);
568 * Returns the client's current latency (RTT), more accurate than GetAvgLatency but jittering.
570 * @param client Player's index.
571 * @param flow Traffic flowing direction.
573 * @error Invalid client index, client not in game, or fake client.
575 native Float:GetClientLatency(client, NetFlow:flow);
578 * Returns the client's average packet latency in seconds.
580 * @param client Player's index.
581 * @param flow Traffic flowing direction.
582 * @return Average latency.
583 * @error Invalid client index, client not in game, or fake client.
585 native Float:GetClientAvgLatency(client, NetFlow:flow);
588 * Returns the client's average packet loss, values go from 0 to 1 (for percentages).
590 * @param client Player's index.
591 * @param flow Traffic flowing direction.
592 * @return Average packet loss.
593 * @error Invalid client index, client not in game, or fake client.
595 native Float:GetClientAvgLoss(client, NetFlow:flow);
598 * Returns the client's average packet choke, values go from 0 to 1 (for percentages).
600 * @param client Player's index.
601 * @param flow Traffic flowing direction.
602 * @return Average packet choke.
603 * @error Invalid client index, client not in game, or fake client.
605 native Float:GetClientAvgChoke(client, NetFlow:flow);
608 * Returns the client's data flow in bytes/sec.
610 * @param client Player's index.
611 * @param flow Traffic flowing direction.
613 * @error Invalid client index, client not in game, or fake client.
615 native Float:GetClientAvgData(client, NetFlow:flow);
618 * Returns the client's average packet frequency in packets/sec.
620 * @param client Player's index.
621 * @param flow Traffic flowing direction.
622 * @return Packet frequency.
623 * @error Invalid client index, client not in game, or fake client.
625 native Float:GetClientAvgPackets(client, NetFlow:flow);
628 * Translates an userid index to the real player index.
630 * @param userid Userid value.
631 * @return Client value.
632 * @error Returns 0 if invalid userid.
634 native GetClientOfUserId(userid);
637 * Disconnects a client from the server as soon as the next frame starts.
639 * Note: Originally, KickClient() was immediate. The delay was introduced
640 * because despite warnings, plugins were using it in ways that would crash.
641 * The new safe version can break cases that rely on immediate disconnects,
642 * but ensures that plugins do not accidentally cause crashes.
644 * If you need immediate disconnects, use KickClientEx().
646 * Note: IsClientInKickQueue() will return true before the kick occurs.
648 * @param client Client index.
649 * @param format Optional formatting rules for disconnect reason.
650 * Note that a period is automatically appended to the string by the engine.
651 * @param ... Variable number of format parameters.
653 * @error Invalid client index, or client not connected.
655 native KickClient(client, const String:format[]="", any:...);
658 * Immediately disconnects a client from the server.
660 * Kicking clients from certain events or callbacks may cause crashes. If in
661 * doubt, create a short (0.1 second) timer to kick the client in the next
664 * @param client Client index.
665 * @param format Optional formatting rules for disconnect reason.
666 * Note that a period is automatically appended to the string by the engine.
667 * @param ... Variable number of format parameters.
669 * @error Invalid client index, or client not connected.
671 native KickClientEx(client, const String:format[]="", any:...);
674 * Changes a client's team through the mod's generic team changing function.
675 * On CS:S, this will kill the player.
677 * @param client Client index.
678 * @param team Mod-specific team index.
680 * @error Invalid client index, client not connected, or lack of
683 native ChangeClientTeam(client, team);
