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 */
49 * MAXPLAYERS is not the same as MaxClients.
50 * MAXPLAYERS is a hardcoded value as an upper limit. MaxClients changes based on the server.
52 * Both GetMaxClients() and MaxClients are only available once the map is loaded, and should
53 * not be used in OnPluginStart().
56 #define MAXPLAYERS 65 /**< Maximum number of players SourceMod supports */
57 #define MAX_NAME_LENGTH 32 /**< Maximum buffer required to store a client name */
59 public const MaxClients; /**< Maximum number of players the server supports (dynamic) */
62 * Called on client connection. If you return true, the client will be allowed in the server.
63 * If you return false (or return nothing), the client will be rejected. If the client is
64 * rejected by this forward or any other, OnClientDisconnect will not be called.
66 * Note: Do not write to rejectmsg if you plan on returning true. If multiple plugins write
67 * to the string buffer, it is not defined which plugin's string will be shown to the client,
68 * but it is guaranteed one of them will.
70 * @param client Client index.
71 * @param rejectmsg Buffer to store the rejection message when the connection is refused.
72 * @param maxlen Maximum number of characters for rejection buffer.
73 * @return True to validate client's connection, false to refuse it.
75 forward bool:OnClientConnect(client, String:rejectmsg[], maxlen);
78 * Called once a client successfully connects. This callback is paired with OnClientDisconnect.
80 * @param client Client index.
83 forward OnClientConnected(client);
86 * Called when a client is entering the game.
88 * Whether a client has a steamid is undefined until OnClientAuthorized
89 * is called, which may occur either before or after OnClientPutInServer.
90 * Similarly, use OnClientPostAdminCheck() if you need to verify whether
91 * connecting players are admins.
93 * GetClientCount() will include clients as they are passed through this
94 * function, as clients are already in game at this point.
96 * @param client Client index.
99 forward OnClientPutInServer(client);
102 * Called when a client is disconnecting from the server.
104 * @param client Client index.
107 forward OnClientDisconnect(client);
110 * Called when a client is disconnected from the server.
112 * @param client Client index.
115 forward OnClientDisconnect_Post(client);
118 * Called when a client is sending a command.
120 * As of SourceMod 1.3, the client is guaranteed to be in-game.
121 * Use command listeners (console.inc) for more advanced hooks.
123 * @param client Client index.
124 * @param args Number of arguments.
127 forward Action:OnClientCommand(client, args);
130 * Called whenever the client's settings are changed.
132 * @param client Client index.
135 forward OnClientSettingsChanged(client);
138 * Called when a client receives a Steam ID. The state of a client's
139 * authorization as an admin is not guaranteed here. Use
140 * OnClientPostAdminCheck() if you need a client's admin status.
142 * This is called by bots, but the ID will be "BOT".
144 * @param client Client index.
145 * @param auth Client auth string.
148 forward OnClientAuthorized(client, const String:auth[]);
151 * Called once a client is authorized and fully in-game, but
152 * before admin checks are done. This can be used to override
153 * the default admin checks for a client. You should only use
154 * this for overriding; use OnClientPostAdminCheck() instead
155 * if you want notification.
157 * Note: If handled/blocked, PostAdminCheck must be signalled
158 * manually via NotifyPostAdminCheck().
160 * This callback is gauranteed to occur on all clients, and always
161 * after each OnClientPutInServer() call.
163 * @param client Client index.
164 * @return Plugin_Handled to block admin checks.
166 forward Action:OnClientPreAdminCheck(client);
169 * Called directly before OnClientPostAdminCheck() as a method to
170 * alter administrative permissions before plugins perform final
171 * post-connect operations.
173 * In general, do not use this function unless you are specifically
174 * attempting to change access permissions. Use OnClientPostAdminCheck()
175 * instead if you simply want to perform post-connect authorization
178 * See OnClientPostAdminCheck() for more information.
180 * @param client Client index.
183 forward OnClientPostAdminFilter(client);
186 * Called once a client is authorized and fully in-game, and
187 * after all post-connection authorizations have been performed.
189 * This callback is gauranteed to occur on all clients, and always
190 * after each OnClientPutInServer() call.
192 * @param client Client index.
195 forward OnClientPostAdminCheck(client);
198 * This function will be deprecated in a future release. Use the MaxClients variable instead.
200 * Returns the maximum number of clients allowed on the server. This may
201 * return 0 if called before OnMapStart(), and thus should not be called
202 * in OnPluginStart().
204 * You should not globally cache the value to GetMaxClients() because it can change from
205 * SourceTV or TF2's arena mode. Use the "MaxClients" dynamic variable documented at the
208 * @return Maximum number of clients allowed.
210 native GetMaxClients();
213 * Returns the maximum number of human players allowed on the server. This is
214 * a game-specific function used on newer games to limit the number of humans
215 * that can join a game and can be lower than MaxClients. It is the number often
216 * reflected in the server browser or when viewing the output of the status command.
217 * On unsupported games or modes without overrides, it will return the same value
220 * You should not globally cache the value to GetMaxHumanPlayers() because it can change across
221 * game modes. You may still cache it locally.
223 * @return Maximum number of humans allowed.
225 native GetMaxHumanPlayers();
228 * Returns the client count put in the server.
230 * @param inGameOnly If false connecting players are also counted.
231 * @return Client count in the server.
233 native GetClientCount(bool:inGameOnly=true);
236 * Returns the client's name.
238 * @param client Player index.
239 * @param name Buffer to store the client's name.
240 * @param maxlen Maximum length of string buffer (includes NULL terminator).
241 * @return True on success, false otherwise.
242 * @error If the client is not connected an error will be thrown.
244 native bool:GetClientName(client, String:name[], maxlen);
247 * Retrieves a client's IP address.
249 * @param client Player index.
250 * @param name Buffer to store the client's ip address.
251 * @param maxlen Maximum length of string buffer (includes NULL terminator).
252 * @param remport Remove client's port from the ip string (true by default).
253 * @return True on success, false otherwise.
254 * @error If the client is not connected or the index is invalid.
256 native bool:GetClientIP(client, String:ip[], maxlen, bool:remport=true);
259 * Retrieves a client's authentication string (SteamID).
261 * @param client Player index.
262 * @param auth Buffer to store the client's auth string.
263 * @param maxlen Maximum length of string buffer (includes NULL terminator).
264 * @param validate Check backend validation status.
265 * DO NOT PASS FALSE UNLESS YOU UNDERSTAND THE CONSEQUENCES,
266 * You WILL KNOW if you need to use this, MOST WILL NOT.
267 * @return True on success, false otherwise.
268 * @error If the client is not connected or the index is invalid.
270 native bool:GetClientAuthString(client, String:auth[], maxlen, bool:validate=true);
273 * Returns the client's Steam account ID.
275 * @param client Client Index.
276 * @param validate Check backend validation status.
277 * DO NOT PASS FALSE UNLESS YOU UNDERSTAND THE CONSEQUENCES,
278 * You WILL KNOW if you need to use this, MOST WILL NOT.
279 * @return Steam account ID or 0 if not available.
280 * @error If the client is not connected or the index is invalid.
282 native GetSteamAccountID(client, bool:validate=true);
285 * Retrieves a client's user id, which is an index incremented for every client
286 * that joins the server.
288 * @param client Player index.
289 * @return User id of the client.
290 * @error If the client is not connected or the index is invalid.
292 native GetClientUserId(client);
295 * Returns if a certain player is connected.
297 * @param client Player index.
298 * @return True if player is connected to the server, false otherwise.
300 native bool:IsClientConnected(client);
303 * Returns if a certain player has entered the game.
305 * @param client Player index (index does not have to be connected).
306 * @return True if player has entered the game, false otherwise.
307 * @error Invalid client index.
309 native bool:IsClientInGame(client);
312 * Returns if a client is in the "kick queue" (i.e. the client will be kicked
313 * shortly and thus they should not appear as valid).
315 * @param client Player index (must be connected).
316 * @return True if in the kick queue, false otherwise.
317 * @error Invalid client index.
319 native bool:IsClientInKickQueue(client);
322 * Backwards compatibility stock - use IsClientInGame
323 * @deprecated Renamed to IsClientInGame
325 #pragma deprecated Use IsClientInGame() instead
326 stock bool:IsPlayerInGame(client)
328 return IsClientInGame(client);
332 * Returns if a certain player has been authenticated.
334 * @param client Player index.
335 * @return True if player has been authenticated, false otherwise.
337 native bool:IsClientAuthorized(client);
340 * Returns if a certain player is a fake client.
342 * @param client Player index.
343 * @return True if player is a fake client, false otherwise.
345 native bool:IsFakeClient(client);
348 * Returns if a certain player is the SourceTV bot.
350 * @param client Player index.
351 * @return True if player is the SourceTV bot, false otherwise.
353 native bool:IsClientSourceTV(client);
356 * Returns if a certain player is the Replay bot.
358 * @param client Player index.
359 * @return True if player is the Replay bot, false otherwise.
361 native bool:IsClientReplay(client);
364 * Returns if a certain player is an observer/spectator.
366 * @param client Player index.
367 * @return True if player is an obverser, false otherwise.
369 native bool:IsClientObserver(client);
372 * Returns if the client is alive or dead.
374 * Note: This function was originally in SDKTools and was moved to core.
376 * @param client Player's index.
377 * @return True if the client is alive, false otherwise.
378 * @error Invalid client index, client not in game, or no mod support.
380 native bool:IsPlayerAlive(client);
383 * Retrieves values from client replicated keys.
385 * @param client Player's index.
386 * @param key Key string.
387 * @param value Buffer to store value.
388 * @param maxlen Maximum length of valve (UTF-8 safe).
389 * @return True on success, false otherwise.
390 * @error Invalid client index, or client not connected.
392 native bool:GetClientInfo(client, const String:key[], String:value[], maxlen);
395 * Retrieves a client's team index.
397 * @param client Player's index.
398 * @return Team index the client is on (mod specific).
399 * @error Invalid client index, client not in game, or no mod support.
401 native GetClientTeam(client);
404 * Sets a client's AdminId.
406 * @param client Player's index.
407 * @param id AdminId to set. INVALID_ADMIN_ID removes admin permissions.
408 * @param temp True if the id should be freed on disconnect.
410 * @error Invalid client index, client not connected, or bogus AdminId.
412 native SetUserAdmin(client, AdminId:id, bool:temp=false);
415 * Retrieves a client's AdminId.
417 * @param client Player's index.
418 * @return AdminId of the client, or INVALID_ADMIN_ID if none.
419 * @error Invalid client index, or client not connected.
421 native AdminId:GetUserAdmin(client);
424 * Sets access flags on a client. If the client is not an admin,
425 * a temporary, anonymous AdminId is given.
427 * @param client Player's index.
428 * @param ... Flags to set on the client.
430 * @error Invalid client index, or client not connected.
432 native AddUserFlags(client, AdminFlag:...);
435 * Removes flags from a client. If the client is not an admin,
436 * this has no effect.
438 * @param client Player's index.
439 * @param ... Flags to remove from the client.
441 * @error Invalid client index, or client not connected.
443 native RemoveUserFlags(client, AdminFlag:...);
446 * Sets access flags on a client using bits instead of flags. If the
447 * client is not an admin, and flags not 0, a temporary, anonymous AdminId is given.
449 * @param client Player's index.
450 * @param flags Bitstring of flags to set on client.
453 native SetUserFlagBits(client, flags);
456 * Returns client access flags. If the client is not an admin,
457 * the result is always 0.
459 * @param client Player's index.
461 * @error Invalid client index, or client not connected.
463 native GetUserFlagBits(client);
466 * Returns whether a user can target another user.
467 * This is a helper function for CanAdminTarget.
469 * @param client Player's index.
470 * @param target Target player's index.
471 * @return True if target is targettable by the player, false otherwise.
472 * @error Invalid or unconnected player indexers.
474 native bool:CanUserTarget(client, target);
477 * Runs through the Core-defined admin authorization checks on a player.
478 * Has no effect if the player is already an admin.
480 * Note: This function is based on the internal cache only.
482 * @param client Client index.
483 * @return True if access was changed, false if it did not.
484 * @error Invalid client index or client not in-game AND authorized.
486 native bool:RunAdminCacheChecks(client);
489 * Signals that a player has completed post-connection admin checks.
490 * Has no effect if the player has already had this event signalled.
492 * Note: This must be sent even if no admin id was assigned.
494 * @param client Client index.
496 * @error Invalid client index or client not in-game AND authorized.
498 native NotifyPostAdminCheck(client);
501 * Creates a fake client.
503 * @param name Name to use.
504 * @return Client index on success, 0 otherwise.
506 native CreateFakeClient(const String:name[]);
509 * Sets a convar value on a fake client.
511 * @param client Client index.
512 * @param cvar ConVar name.
513 * @param value ConVar value.
515 * @error Invalid client index, client not connected,
516 * or client not a fake client.
518 native SetFakeClientConVar(client, const String:cvar[], const String:value[]);
521 * Returns the client's health.
523 * @param client Player's index.
524 * @return Health value.
525 * @error Invalid client index, client not in game, or no mod support.
527 native GetClientHealth(client);
530 * Returns the client's model name.
532 * @param client Player's index.
533 * @param model Buffer to store the client's model name.
534 * @param maxlen Maximum length of string buffer (includes NULL terminator).
536 * @error Invalid client index, client not in game, or no mod support.
538 native GetClientModel(client, String:model[], maxlen);
541 * Returns the client's weapon name.
543 * @param client Player's index.
544 * @param weapon Buffer to store the client's weapon name.
545 * @param maxlen Maximum length of string buffer (includes NULL terminator).
547 * @error Invalid client index, client not in game, or no mod support.
549 native GetClientWeapon(client, String:weapon[], maxlen);
552 * Returns the client's max size vector.
554 * @param client Player's index.
555 * @param vec Destination vector to store the client's max size.
557 * @error Invalid client index, client not in game, or no mod support.
559 native GetClientMaxs(client, Float:vec[3]);
562 * Returns the client's min size vector.
564 * @param client Player's index.
565 * @param vec Destination vector to store the client's min size.
567 * @error Invalid client index, client not in game, or no mod support.
569 native GetClientMins(client, Float:vec[3]);
572 * Returns the client's position angle.
574 * @param client Player's index.
575 * @param ang Destination vector to store the client's position angle.
577 * @error Invalid client index, client not in game, or no mod support.
579 native GetClientAbsAngles(client, Float:ang[3]);
582 * Returns the client's origin vector.
584 * @param client Player's index.
585 * @param vec Destination vector to store the client's origin vector.
587 * @error Invalid client index, client not in game, or no mod support.
589 native GetClientAbsOrigin(client, Float:vec[3]);
592 * Returns the client's armor.
594 * @param client Player's index.
595 * @return Armor value.
596 * @error Invalid client index, client not in game, or no mod support.
598 native GetClientArmor(client);
601 * Returns the client's death count.
603 * @param client Player's index.
604 * @return Death count.
605 * @error Invalid client index, client not in game, or no mod support.
607 native GetClientDeaths(client);
610 * Returns the client's frag count.
612 * @param client Player's index.
613 * @return Frag count.
614 * @error Invalid client index, client not in game, or no mod support.
616 native GetClientFrags(client);
619 * Returns the client's send data rate in bytes/sec.
621 * @param client Player's index.
623 * @error Invalid client index, client not in game, or fake client.
625 native GetClientDataRate(client);
628 * Returns if a client is timing out
630 * @param client Player's index.
631 * @return True if client is timing out, false otherwise.
632 * @error Invalid client index, client not in game, or fake client.
634 native bool:IsClientTimingOut(client);
637 * Returns the client's connection time in seconds.
639 * @param client Player's index.
640 * @return Connection time.
641 * @error Invalid client index, client not in game, or fake client.
643 native Float:GetClientTime(client);
646 * Returns the client's current latency (RTT), more accurate than GetAvgLatency but jittering.
648 * @param client Player's index.
649 * @param flow Traffic flowing direction.
650 * @return Latency, or -1 if network info is not available.
651 * @error Invalid client index, client not in game, or fake client.
653 native Float:GetClientLatency(client, NetFlow:flow);
656 * Returns the client's average packet latency in seconds.
658 * @param client Player's index.
659 * @param flow Traffic flowing direction.
660 * @return Latency, or -1 if network info is not available.
661 * @error Invalid client index, client not in game, or fake client.
663 native Float:GetClientAvgLatency(client, NetFlow:flow);
666 * Returns the client's average packet loss, values go from 0 to 1 (for percentages).
668 * @param client Player's index.
669 * @param flow Traffic flowing direction.
670 * @return Average packet loss, or -1 if network info is not available.
671 * @error Invalid client index, client not in game, or fake client.
673 native Float:GetClientAvgLoss(client, NetFlow:flow);
676 * Returns the client's average packet choke, values go from 0 to 1 (for percentages).
678 * @param client Player's index.
679 * @param flow Traffic flowing direction.
680 * @return Average packet loss, or -1 if network info is not available.
681 * @error Invalid client index, client not in game, or fake client.
683 native Float:GetClientAvgChoke(client, NetFlow:flow);
686 * Returns the client's data flow in bytes/sec.
688 * @param client Player's index.
689 * @param flow Traffic flowing direction.
691 * @error Invalid client index, client not in game, or fake client.
693 native Float:GetClientAvgData(client, NetFlow:flow);
696 * Returns the client's average packet frequency in packets/sec.
698 * @param client Player's index.
699 * @param flow Traffic flowing direction.
700 * @return Packet frequency.
701 * @error Invalid client index, client not in game, or fake client.
703 native Float:GetClientAvgPackets(client, NetFlow:flow);
706 * Translates an userid index to the real player index.
708 * @param userid Userid value.
709 * @return Client value.
710 * @error Returns 0 if invalid userid.
712 native GetClientOfUserId(userid);
715 * Disconnects a client from the server as soon as the next frame starts.
717 * Note: Originally, KickClient() was immediate. The delay was introduced
718 * because despite warnings, plugins were using it in ways that would crash.
719 * The new safe version can break cases that rely on immediate disconnects,
720 * but ensures that plugins do not accidentally cause crashes.
722 * If you need immediate disconnects, use KickClientEx().
724 * Note: IsClientInKickQueue() will return true before the kick occurs.
726 * @param client Client index.
727 * @param format Optional formatting rules for disconnect reason.
728 * Note that a period is automatically appended to the string by the engine.
729 * @param ... Variable number of format parameters.
731 * @error Invalid client index, or client not connected.
733 native KickClient(client, const String:format[]="", any:...);
736 * Immediately disconnects a client from the server.
738 * Kicking clients from certain events or callbacks may cause crashes. If in
739 * doubt, create a short (0.1 second) timer to kick the client in the next
742 * @param client Client index.
743 * @param format Optional formatting rules for disconnect reason.
744 * Note that a period is automatically appended to the string by the engine.
745 * @param ... Variable number of format parameters.
747 * @error Invalid client index, or client not connected.
749 native KickClientEx(client, const String:format[]="", any:...);
752 * Changes a client's team through the mod's generic team changing function.
753 * On CS:S, this will kill the player.
755 * @param client Client index.
756 * @param team Mod-specific team index.
758 * @error Invalid client index, client not connected, or lack of
761 native ChangeClientTeam(client, team);
764 * Returns the clients unique serial identifier.
766 * @return Serial number.
768 native GetClientSerial(client);
771 * Returns the client index by its serial number.
773 * @return Client index, or 0 for invalid serial.
775 native GetClientFromSerial(serial);
