3 * =============================================================================
4 * SourceMod (C)2004-2007 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
40 NetFlow_Outgoing = 0, /**< Outgoing traffic */
41 NetFlow_Incoming, /**< Incoming traffic */
42 NetFlow_Both /**< Incoming and outgoing traffic */
45 #define MAXPLAYERS 64 /**< Maximum number of players that can be in server */
46 #define MAX_NAME_LENGTH 32 /**< Maximum buffer required to store a client name */
49 * Called on client connection.
51 * @param client Client index.
52 * @param rejectmsg Buffer to store the rejection message when the connection is refused.
53 * @param maxlen Maximum number of characters for rejection buffer.
54 * @return True to validate client's connection, false to refuse it.
56 forward bool:OnClientConnect(client, String:rejectmsg[], maxlen);
59 * Called when a client is entering the game.
61 * Whether a client has a steamid is undefined until OnClientAuthorized
62 * is called, which may occur either before or after OnClientPutInServer.
63 * Similarly, use OnClientPostAdminCheck() if you need to verify whether
64 * connecting players are admins.
66 * GetClientCount() will include clients as they are passed through this
67 * function, as clients are already in game at this point.
69 * @param client Client index.
72 forward OnClientPutInServer(client);
75 * Called when a client is disconnecting from the server.
77 * @param client Client index.
80 forward OnClientDisconnect(client);
83 * Called when a client is disconnected from the server.
85 * @param client Client index.
88 forward OnClientDisconnect_Post(client);
91 * Called when a client is sending a command.
93 * @param client Client index.
94 * @param args Number of arguments.
97 forward Action:OnClientCommand(client, args);
100 * Called whenever the client's settings are changed.
102 * @param client Client index.
105 forward OnClientSettingsChanged(client);
108 * Called when a client receives a Steam ID. The state of a client's
109 * authorization via Steam or as an admin is not guaranteed here.
110 * Use OnClientAuthorized() or OnClientPostAdminCheck() for those,
113 * This is called by bots, but the ID will be "BOT".
115 * @param client Client index.
116 * @param auth Client auth string.
119 forward OnClientAuthorized(client, const String:auth[]);
122 * Called once a client is authorized and fully in-game, but
123 * before admin checks are done. This can be used to override
124 * the default admin checks for a client. You should only use
125 * this for overriding; use OnClientPostAdminCheck() instead
126 * if you want notification.
128 * Note: If handled/blocked, PostAdminCheck must be signalled
129 * manually via NotifyPostAdminCheck().
131 * This callback is gauranteed to occur on all clients, and always
132 * after each OnClientPutInServer() call.
134 * @param client Client index.
135 * @return Plugin_Handled to block admin checks.
137 forward Action:OnClientPreAdminCheck(client);
140 * Called directly before OnClientPostAdminCheck() as a method to
141 * alter administrative permissions before plugins perform final
142 * post-connect operations.
144 * In general, do not use this function unless you are specifically
145 * attempting to change access permissions. Use OnClientPostAdminCheck()
146 * instead if you simply want to perform post-connect authorization
149 * See OnClientPostAdminCheck() for more information.
151 * @param client Client index.
154 forward OnClientPostAdminFilter(client);
157 * Called once a client is authorized and fully in-game, and
158 * after all post-connection authorizations have been performed.
160 * This callback is gauranteed to occur on all clients, and always
161 * after each OnClientPutInServer() call.
163 * @param client Client index.
166 forward OnClientPostAdminCheck(client);
169 * Returns the maximum number of clients allowed on the server. This may
170 * return 0 if called before OnMapStart(), and thus should not be called
171 * in OnPluginStart().
173 * @return Maximum number of clients allowed.
175 native GetMaxClients();
178 * Returns the client count put in the server.
180 * @param inGameOnly If false connecting players are also counted.
181 * @return Client count in the server.
183 native GetClientCount(bool:inGameOnly=true);
186 * Returns the client's name.
188 * @param client Player index.
189 * @param name Buffer to store the client's name.
190 * @param maxlen Maximum length of string buffer (includes NULL terminator).
191 * @return True on success, false otherwise.
192 * @error If the client is not connected an error will be thrown.
194 native bool:GetClientName(client, String:name[], maxlen);
197 * Retrieves a client's IP address.
199 * @param client Player index.
200 * @param name Buffer to store the client's ip address.
201 * @param maxlen Maximum length of string buffer (includes NULL terminator).
202 * @param remport Remove client's port from the ip string (true by default).
203 * @return True on success, false otherwise.
204 * @error If the client is not connected or the index is invalid.
206 native bool:GetClientIP(client, String:ip[], maxlen, bool:remport=true);
209 * Retrieves a client's authentication string (SteamID).
211 * @param client Player index.
212 * @param auth Buffer to store the client's auth string.
213 * @param maxlen Maximum length of string buffer (includes NULL terminator).
214 * @return True on success, false otherwise.
215 * @error If the client is not connected or the index is invalid.
217 native bool:GetClientAuthString(client, String:auth[], maxlen);
220 * Retrieves a client's user id, which is an index incremented for every client
221 * that joins the server.
223 * @param client Player index.
224 * @return User id of the client.
225 * @error If the client is not connected or the index is invalid.
227 native GetClientUserId(client);
230 * Returns if a certain player is connected.
232 * @param client Player index.
233 * @return True if player is connected to the server, false otherwise.
235 native bool:IsClientConnected(client);
238 * Returns if a certain player has entered the game.
240 * @param client Player index (index does not have to be connected).
241 * @return True if player has entered the game, false otherwise.
242 * @error Invalid client index.
244 native bool:IsClientInGame(client);
247 * Returns if a client is in the "kick queue" (i.e. the client will be kicked
248 * shortly and thus they should not appear as valid).
250 * @param client Player index (must be connected).
251 * @return True if in the kick queue, false otherwise.
252 * @error Invalid client index.
254 native bool:IsClientInKickQueue(client);
257 * Backwards compatibility stock - use IsClientInGame
258 * @deprecated Renamed to IsClientInGame
260 #pragma deprecated Use IsClientInGame() instead
261 stock bool:IsPlayerInGame(client)
263 return IsClientInGame(client);
267 * Returns if a certain player has been authenticated.
269 * @param client Player index.
270 * @return True if player has been authenticated, false otherwise.
272 native bool:IsClientAuthorized(client);
275 * Returns if a certain player is a fake client.
277 * @param client Player index.
278 * @return True if player is a fake client, false otherwise.
280 native bool:IsFakeClient(client);
283 * Returns if a certain player is an observer/spectator.
285 * @param client Player index.
286 * @return True if player is an obverser, false otherwise.
288 native bool:IsClientObserver(client);
291 * Returns if the client is alive or dead.
293 * Note: This function was originally in SDKTools and was moved to core.
295 * @param client Player's index.
296 * @return True if the client is alive, false otherwise.
297 * @error Invalid client index, client not in game, or no mod support.
299 native bool:IsPlayerAlive(client);
302 * Retrieves values from client replicated keys.
304 * @param client Player's index.
305 * @param key Key string.
306 * @param value Buffer to store value.
307 * @param maxlen Maximum length of valve (UTF-8 safe).
308 * @return True on success, false otherwise.
309 * @error Invalid client index, or client not connected.
311 native bool:GetClientInfo(client, const String:key[], String:value[], maxlen);
314 * Retrieves a client's team index.
316 * @param client Player's index.
317 * @return Team index the client is on (mod specific).
318 * @error Invalid client index, client not in game, or no mod support.
320 native GetClientTeam(client);
323 * Sets a client's AdminId.
325 * @param client Player's index.
326 * @param id AdminId to set. INVALID_ADMIN_ID removes admin permissions.
327 * @param temp True if the id should be freed on disconnect.
329 * @error Invalid client index, client not connected, or bogus AdminId.
331 native SetUserAdmin(client, AdminId:id, bool:temp=false);
334 * Retrieves a client's AdminId.
336 * @param client Player's index.
337 * @return AdminId of the client, or INVALID_ADMIN_ID if none.
338 * @error Invalid client index, or client not connected.
340 native AdminId:GetUserAdmin(client);
343 * Sets access flags on a client. If the client is not an admin,
344 * a temporary, anonymous AdminId is given.
346 * @param client Player's index.
347 * @param ... Flags to set on the client.
349 * @error Invalid client index, or client not connected.
351 native AddUserFlags(client, AdminFlag:...);
354 * Removes flags from a client. If the client is not an admin,
355 * this has no effect.
357 * @param client Player's index.
358 * @param ... Flags to remove from the client.
360 * @error Invalid client index, or client not connected.
362 native RemoveUserFlags(client, AdminFlag:...);
365 * Sets access flags on a client using bits instead of flags. If the
366 * client is not an admin, and flags not 0, a temporary, anonymous AdminId is given.
368 * @param client Player's index.
369 * @param flags Bitstring of flags to set on client.
372 native SetUserFlagBits(client, flags);
375 * Returns client access flags. If the client is not an admin,
376 * the result is always 0.
378 * @param client Player's index.
380 * @error Invalid client index, or client not connected.
382 native GetUserFlagBits(client);
385 * Returns whether a user can target another user.
386 * This is a helper function for CanAdminTarget.
388 * @param client Player's index.
389 * @param target Target player's index.
390 * @return True if target is targettable by the player, false otherwise.
391 * @error Invalid or unconnected player indexers.
393 native bool:CanUserTarget(client, target);
396 * Runs through the Core-defined admin authorization checks on a player.
397 * Has no effect if the player is already an admin.
399 * Note: This function is based on the internal cache only.
401 * @param client Client index.
402 * @return True if access was changed, false if it did not.
403 * @error Invalid client index or client not in-game AND authorized.
405 native bool:RunAdminCacheChecks(client);
408 * Signals that a player has completed post-connection admin checks.
409 * Has no effect if the player has already had this event signalled.
411 * Note: This must be sent even if no admin id was assigned.
413 * @param client Client index.
415 * @error Invalid client index or client not in-game AND authorized.
417 native NotifyPostAdminCheck(client);
420 * Creates a fake client.
422 * @param name Name to use.
423 * @return Client index on success, 0 otherwise.
425 native CreateFakeClient(const String:name[]);
428 * Sets a convar value on a fake client.
430 * @param client Client index.
431 * @param cvar ConVar name.
432 * @param value ConVar value.
434 * @error Invalid client index, client not connected,
435 * or client not a fake client.
437 native SetFakeClientConVar(client, const String:cvar[], const String:value[]);
440 * Returns the client's health.
442 * @param client Player's index.
443 * @return Health value.
444 * @error Invalid client index, client not in game, or no mod support.
446 native GetClientHealth(client);
449 * Returns the client's model name.
451 * @param client Player's index.
452 * @param model Buffer to store the client's model name.
453 * @param maxlen Maximum length of string buffer (includes NULL terminator).
455 * @error Invalid client index, client not in game, or no mod support.
457 native GetClientModel(client, String:model[], maxlen);
460 * Returns the client's weapon name.
462 * @param client Player's index.
463 * @param weapon Buffer to store the client's weapon name.
464 * @param maxlen Maximum length of string buffer (includes NULL terminator).
466 * @error Invalid client index, client not in game, or no mod support.
468 native GetClientWeapon(client, String:weapon[], maxlen);
471 * Returns the client's max size vector.
473 * @param client Player's index.
474 * @param vec Destination vector to store the client's max size.
476 * @error Invalid client index, client not in game, or no mod support.
478 native GetClientMaxs(client, Float:vec[3]);
481 * Returns the client's min size vector.
483 * @param client Player's index.
484 * @param vec Destination vector to store the client's min size.
486 * @error Invalid client index, client not in game, or no mod support.
488 native GetClientMins(client, Float:vec[3]);
491 * Returns the client's position angle.
493 * @param client Player's index.
494 * @param ang Destination vector to store the client's position angle.
496 * @error Invalid client index, client not in game, or no mod support.
498 native GetClientAbsAngles(client, Float:ang[3]);
501 * Returns the client's origin vector.
503 * @param client Player's index.
504 * @param vec Destination vector to store the client's origin vector.
506 * @error Invalid client index, client not in game, or no mod support.
508 native GetClientAbsOrigin(client, Float:vec[3]);
511 * Returns the client's armor.
513 * @param client Player's index.
514 * @return Armor value.
515 * @error Invalid client index, client not in game, or no mod support.
517 native GetClientArmor(client);
520 * Returns the client's death count.
522 * @param client Player's index.
523 * @return Death count.
524 * @error Invalid client index, client not in game, or no mod support.
526 native GetClientDeaths(client);
529 * Returns the client's frag count.
531 * @param client Player's index.
532 * @return Frag count.
533 * @error Invalid client index, client not in game, or no mod support.
535 native GetClientFrags(client);
538 * Returns the client's send data rate in bytes/sec.
540 * @param client Player's index.
542 * @error Invalid client index, client not in game, or fake client.
544 native GetClientDataRate(client);
547 * Returns if a client is timing out
549 * @param client Player's index.
550 * @return True if client is timing out, false otherwise.
551 * @error Invalid client index, client not in game, or fake client.
553 native bool:IsClientTimingOut(client);
556 * Returns the client's connection time in seconds.
558 * @param client Player's index.
559 * @return Connection time.
560 * @error Invalid client index, client not in game, or fake client.
562 native Float:GetClientTime(client);
565 * Returns the client's current latency (RTT), more accurate than GetAvgLatency but jittering.
567 * @param client Player's index.
568 * @param flow Traffic flowing direction.
570 * @error Invalid client index, client not in game, or fake client.
572 native Float:GetClientLatency(client, NetFlow:flow);
575 * Returns the client's average packet latency in seconds.
577 * @param client Player's index.
578 * @param flow Traffic flowing direction.
579 * @return Average latency.
580 * @error Invalid client index, client not in game, or fake client.
582 native Float:GetClientAvgLatency(client, NetFlow:flow);
585 * Returns the client's average packet loss, values go from 0 to 1 (for percentages).
587 * @param client Player's index.
588 * @param flow Traffic flowing direction.
589 * @return Average packet loss.
590 * @error Invalid client index, client not in game, or fake client.
592 native Float:GetClientAvgLoss(client, NetFlow:flow);
595 * Returns the client's average packet choke, values go from 0 to 1 (for percentages).
597 * @param client Player's index.
598 * @param flow Traffic flowing direction.
599 * @return Average packet choke.
600 * @error Invalid client index, client not in game, or fake client.
602 native Float:GetClientAvgChoke(client, NetFlow:flow);
605 * Returns the client's data flow in bytes/sec.
607 * @param client Player's index.
608 * @param flow Traffic flowing direction.
610 * @error Invalid client index, client not in game, or fake client.
612 native Float:GetClientAvgData(client, NetFlow:flow);
615 * Returns the client's average packet frequency in packets/sec.
617 * @param client Player's index.
618 * @param flow Traffic flowing direction.
619 * @return Packet frequency.
620 * @error Invalid client index, client not in game, or fake client.
622 native Float:GetClientAvgPackets(client, NetFlow:flow);
625 * Translates an userid index to the real player index.
627 * @param userid Userid value.
628 * @return Client value.
629 * @error Returns 0 if invalid userid.
631 native GetClientOfUserId(userid);
634 * Disconnects a client from the server.
636 * Kicking clients from certain events or callbacks may cause crashes. If in
637 * doubt, create a short (0.1 second) timer to kick the client in the next
640 * @param client Client index.
641 * @param format Optional formatting rules for disconnect reason.
642 * Note that a period is automatically appended to the string by the engine.
643 * @param ... Variable number of format parameters.
645 * @error Invalid client index, or client not connected.
647 native KickClient(client, const String:format[]="", any:...);
650 * Changes a client's team through the mod's generic team changing function.
651 * On CS:S, this will kill the player.
653 * @param client Client index.
654 * @param team Mod-specific team index.
656 * @error Invalid client index, client not connected, or lack of
659 native ChangeClientTeam(client, team);
