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 _console_included
36 #define _console_included
39 * Console variable bound values used with Get/SetConVarBounds()
43 ConVarBound_Upper = 0,
48 * Console variable query helper values.
52 QUERYCOOKIE_FAILED = 0,
56 * Reply sources for commands.
60 SM_REPLY_TO_CONSOLE = 0,
65 * Console variable query result values.
67 enum ConVarQueryResult
69 ConVarQuery_Okay = 0, /**< Retrieval of client convar value was successful. */
70 ConVarQuery_NotFound, /**< Client convar was not found. */
71 ConVarQuery_NotValid, /**< A console command with the same name was found, but there is no convar. */
72 ConVarQuery_Protected /**< Client convar was found, but it is protected. The server cannot retrieve its value. */
76 * @section Flags for console commands and console variables. The descriptions
77 * for each constant come directly from the Source SDK.
79 #define FCVAR_NONE 0 /**< The default, no flags at all */
80 #define FCVAR_UNREGISTERED (1<<0) /**< If this is set, don't add to linked list, etc. */
81 #define FCVAR_LAUNCHER (1<<1) /**< Defined by launcher. */
82 #define FCVAR_GAMEDLL (1<<2) /**< Defined by the game DLL. */
83 #define FCVAR_CLIENTDLL (1<<3) /**< Defined by the client DLL. */
84 #define FCVAR_MATERIAL_SYSTEM (1<<4) /**< Defined by the material system. */
85 #define FCVAR_PROTECTED (1<<5) /**< It's a server cvar, but we don't send the data since it's a password, etc. Sends 1 if it's not bland/zero, 0 otherwise as value. */
86 #define FCVAR_SPONLY (1<<6) /**< This cvar cannot be changed by clients connected to a multiplayer server. */
87 #define FCVAR_ARCHIVE (1<<7) /**< Set to cause it to be saved to vars.rc */
88 #define FCVAR_NOTIFY (1<<8) /**< Notifies players when changed. */
89 #define FCVAR_USERINFO (1<<9) /**< Changes the client's info string. */
90 #define FCVAR_PRINTABLEONLY (1<<10) /**< This cvar's string cannot contain unprintable characters (e.g., used for player name, etc.) */
91 #define FCVAR_UNLOGGED (1<<11) /**< If this is a FCVAR_SERVER, don't log changes to the log file / console if we are creating a log */
92 #define FCVAR_NEVER_AS_STRING (1<<12) /**< Never try to print that cvar. */
93 #define FCVAR_REPLICATED (1<<13) /**< Server setting enforced on clients. */
94 #define FCVAR_CHEAT (1<<14) /**< Only useable in singleplayer / debug / multiplayer & sv_cheats */
95 #define FCVAR_STUDIORENDER (1<<15) /**< Defined by the studiorender system. */
96 #define FCVAR_DEMO (1<<16) /**< Record this cvar when starting a demo file. */
97 #define FCVAR_DONTRECORD (1<<17) /**< Don't record these command in demo files. */
98 #define FCVAR_PLUGIN (1<<18) /**< Defined by a 3rd party plugin. */
99 #define FCVAR_DATACACHE (1<<19) /**< Defined by the datacache system. */
100 #define FCVAR_TOOLSYSTEM (1<<20) /**< Defined by an IToolSystem library */
101 #define FCVAR_FILESYSTEM (1<<21) /**< Defined by the file system. */
102 #define FCVAR_NOT_CONNECTED (1<<22) /**< Cvar cannot be changed by a client that is connected to a server. */
103 #define FCVAR_SOUNDSYSTEM (1<<23) /**< Defined by the soundsystem library. */
104 #define FCVAR_ARCHIVE_XBOX (1<<24) /**< Cvar written to config.cfg on the Xbox. */
105 #define FCVAR_INPUTSYSTEM (1<<25) /**< Defined by the inputsystem DLL. */
106 #define FCVAR_NETWORKSYSTEM (1<<26) /**< Defined by the network system. */
107 #define FCVAR_VPHYSICS (1<<27) /**< Defined by vphysics. */
114 * Executes a server command as if it were on the server console (or RCON)
116 * @param format Formatting rules.
117 * @param ... Variable number of format parameters.
120 native ServerCommand(const String:format[], any:...);
123 * Inserts a server command at the beginning of the server command buffer.
125 * @param format Formatting rules.
126 * @param ... Variable number of format parameters.
129 native InsertServerCommand(const String:format[], any:...);
132 * Executes every command in the server's command buffer, rather than once per frame.
136 native ServerExecute();
139 * Executes a client command. Note that this will not work on clients unless
140 * they have cl_restrict_server_commands set to 0.
142 * @param client Index of the client.
143 * @param fmt Format of the client command.
144 * @param ... Format parameters/
146 * @error Invalid client index, or client not connected.
148 native ClientCommand(client, const String:fmt[], any:...);
151 * Executes a client command on the server without being networked.
153 * FakeClientCommand() overwrites the command tokenization buffer. This can
154 * cause undesired effects because future calls to GetCmdArg* will return
155 * data from the FakeClientCommand(), not the parent command. If you are in
156 * a hook where this matters (for example, a "say" hook), you should use
157 * FakeClientCommandEx() instead.
159 * @param client Index of the client.
160 * @param fmt Format of the client command.
161 * @param ... Format parameters
163 * @error Invalid client index, or client not connected.
165 native FakeClientCommand(client, const String:fmt[], any:...);
168 * Executes a client command on the server without being networked. The
169 * execution of the client command is delayed by one frame to prevent any
170 * re-entrancy issues that might surface with FakeClientCommand().
172 * @param client Index of the client.
173 * @param fmt Format of the client command.
174 * @param ... Format parameters
176 * @error Invalid client index, or client not connected.
178 native FakeClientCommandEx(client, const String:fmt[], any:...);
181 * Sends a message to the server console.
183 * @param format Formatting rules.
184 * @param ... Variable number of format parameters.
187 native PrintToServer(const String:format[], any:...);
190 * Sends a message to a client's console.
192 * @param client Client index.
193 * @param format Formatting rules.
194 * @param ... Variable number of format parameters.
196 * @error If the client is not connected an error will be thrown.
198 native PrintToConsole(client, const String:format[], any:...);
201 * Reples to a message in a command.
203 * A client index of 0 will use PrintToServer().
204 * If the command was from the console, PrintToConsole() is used.
205 * If the command was from chat, PrintToChat() is used.
207 * @param client Client index, or 0 for server.
208 * @param format Formatting rules.
209 * @param ... Variable number of format parameters.
211 * @error If the client is not connected or invalid.
213 native ReplyToCommand(client, const String:format[], any:...);
216 * Returns the current reply source of a command.
218 * @return ReplySource value.
220 native ReplySource:GetCmdReplySource();
223 * Sets the current reply source of a command.
225 * Only use this if you know what you are doing. You should save the old value
226 * and restore it once you are done.
228 * @param source New ReplySource value.
229 * @return Old ReplySource value.
231 native ReplySource:SetCmdReplySource(ReplySource:source);
234 * Returns whether the current say hook is a chat trigger.
236 * This function is only meaningful inside say or say_team hooks.
238 * @return True if a chat trigger, false otherwise.
240 native bool:IsChatTrigger();
243 * Displays usage of an admin command to users depending on the
244 * setting of the sm_show_activity cvar. Additionally, the client
245 * who typed the command will receive the same text without any
246 * client name prefix (as a confirmation).
248 * @param client Client index doing the action, or 0 for server.
249 * @param format Formatting rules.
250 * @param ... Variable number of format parameters.
254 native ShowActivity(client, const String:format[], any:...);
257 * Same as ShowActivity(), except the tag parameter is used instead of
258 * "[SM] " (note that you must supply any spacing).
260 * @param client Client index doing the action, or 0 for server.
261 * @param tag Tag to display with.
262 * @param format Formatting rules.
263 * @param ... Variable number of format parameters.
267 native ShowActivityEx(client, const String:tag[], const String:format[], any:...);
270 * Called when a server-only command is invoked.
272 * @params args Number of arguments that were in the argument string.
273 * @return An Action value. Not handling the command
274 * means that Source will report it as "not found."
276 functag SrvCmd Action:public(args);
279 * Creates a server-only console command, or hooks an already existing one.
281 * @param cmd Name of the command to hook or create.
282 * @param callback A function to use as a callback for when the command is invoked.
283 * @param description Optional description to use for command creation.
284 * @param flags Optional flags to use for command creation.
286 * @error Command name is the same as an existing convar.
288 native RegServerCmd(const String:cmd[], SrvCmd:callback, const String:description[]="", flags=0);
291 * Called when a generic console command is invoked.
293 * @param client Index of the client, or 0 from the server.
294 * @param args Number of arguments that were in the argument string.
295 * @return An Action value. Not handling the command
296 * means that Source will report it as "not found."
298 functag ConCmd Action:public(client, args);
301 * Creates a console command, or hooks an already existing one.
303 * @param cmd Name of the command to hook or create.
304 * @param callback A function to use as a callback for when the command is invoked.
305 * @param description Optional description to use for command creation.
306 * @param flags Optional flags to use for command creation.
308 * @error Command name is the same as an existing convar.
310 native RegConsoleCmd(const String:cmd[], ConCmd:callback, const String:description[]="", flags=0);
313 * Creates a console command as an administrative command. If the command does not exist,
314 * it is created. When this command is invoked, the access rights of the player are
315 * automatically checked before allowing it to continue.
317 * @param cmd String containing command to register.
318 * @param callback A function to use as a callback for when the command is invoked.
319 * @param adminflags Administrative flags (bitstring) to use for permissions.
320 * @param group String containing the command group to use. If empty,
321 * the plugin's filename will be used instead.
322 * @param description Optional description to use for help.
323 * @param flags Optional console flags.
325 * @error Command name is the same as an existing convar.
327 native RegAdminCmd(const String:cmd[],
330 const String:description[]="",
331 const String:group[]="",
335 * Returns the number of arguments from the current console or server command.
336 * @note Unlike the HL2 engine call, this does not include the command itself.
338 * @return Number of arguments to the current command.
343 * Retrieves a command argument given its index, from the current console or
345 * @note Argument indexes start at 1; 0 retrieves the command name.
347 * @param argnum Argument number to retrieve.
348 * @param buffer Buffer to use for storing the string.
349 * @param maxlength Maximum length of the buffer.
350 * @return Length of string written to buffer.
352 native GetCmdArg(argnum, String:buffer[], maxlength);
355 * Retrieves the entire command argument string in one lump from the current
356 * console or server command.
358 * @param buffer Buffer to use for storing the string.
359 * @param maxlength Maximum length of the buffer.
360 * @return Length of string written to buffer.
362 native GetCmdArgString(String:buffer[], maxlength);
365 * Creates a new console variable.
367 * @param name Name of new convar.
368 * @param defaultValue String containing the default value of new convar.
369 * @param description Optional description of the convar.
370 * @param flags Optional bitstring of flags determining how the convar should be handled. See FCVAR_* constants for more details.
371 * @param hasMin Optional boolean that determines if the convar has a minimum value.
372 * @param min Minimum floating point value that the convar can have if hasMin is true.
373 * @param hasMax Optional boolean that determines if the convar has a maximum value.
374 * @param max Maximum floating point value that the convar can have if hasMax is true.
375 * @return A handle to the newly created convar. If the convar already exists, INVALID_HANDLE is returned.
376 * @error Convar name is blank or is the same as an existing console command.
378 native Handle:CreateConVar(const String:name[], const String:defaultValue[], const String:description[]="", flags=0, bool:hasMin=false, Float:min=0.0, bool:hasMax=false, Float:max=0.0);
381 * Searches for a console variable.
383 * @param name Name of convar to find.
384 * @return A handle to the convar if it is found. INVALID_HANDLE otherwise.
386 native Handle:FindConVar(const String:name[]);
389 * Called when a console variable's value is changed.
391 * @param convar Handle to the convar that was changed.
392 * @param oldValue String containing the value of the convar before it was changed.
393 * @param newValue String containing the new value of the convar.
396 functag ConVarChanged public(Handle:convar, const String:oldValue[], const String:newValue[]);
399 * Creates a hook for when a console variable's value is changed.
401 * @param convar Handle to the convar.
402 * @param callback An OnConVarChanged function pointer.
404 * @error Invalid or corrupt Handle or invalid callback function.
406 native HookConVarChange(Handle:convar, ConVarChanged:callback);
409 * Removes a hook for when a console variable's value is changed.
411 * @param convar Handle to the convar.
412 * @param callback An OnConVarChanged function pointer.
414 * @error Invalid or corrupt Handle, invalid callback function, or no active hook on convar.
416 native UnhookConVarChange(Handle:convar, ConVarChanged:callback);
419 * Returns the boolean value of a console variable.
421 * @param convar Handle to the convar.
422 * @return The boolean value of the convar.
423 * @error Invalid or corrupt Handle.
425 native bool:GetConVarBool(Handle:convar);
428 * Sets the boolean value of a console variable.
430 * @param convar Handle to the convar.
431 * @param value New boolean value.
432 * @param replicate If set to true, the new convar value will be set on all clients.
433 * This will only work if the convar has the FCVAR_REPLICATED flag
434 * and actually exists on clients.
435 * @param notify If set to true, clients will be notified that the convar has changed.
436 * This will only work if the convar has the FCVAR_NOTIFY flag.
438 * @error Invalid or corrupt Handle.
440 native SetConVarBool(Handle:convar, bool:value, bool:replicate=false, bool:notify=false);
443 * Returns the integer value of a console variable.
445 * @param convar Handle to the convar.
446 * @return The integer value of the convar.
447 * @error Invalid or corrupt Handle.
449 native GetConVarInt(Handle:convar);
452 * Sets the integer value of a console variable.
454 * @param convar Handle to the convar.
455 * @param value New integer value.
456 * @param replicate If set to true, the new convar value will be set on all clients.
457 * This will only work if the convar has the FCVAR_REPLICATED flag
458 * and actually exists on clients.
459 * @param notify If set to true, clients will be notified that the convar has changed.
460 * This will only work if the convar has the FCVAR_NOTIFY flag.
462 * @error Invalid or corrupt Handle.
464 native SetConVarInt(Handle:convar, value, bool:replicate=false, bool:notify=false);
467 * Returns the floating point value of a console variable.
469 * @param convar Handle to the convar.
470 * @return The floating point value of the convar.
471 * @error Invalid or corrupt Handle.
473 native Float:GetConVarFloat(Handle:convar);
476 * Sets the floating point value of a console variable.
478 * @param convar Handle to the convar.
479 * @param value New floating point value.
480 * @param replicate If set to true, the new convar value will be set on all clients.
481 * This will only work if the convar has the FCVAR_REPLICATED flag
482 * and actually exists on clients.
483 * @param notify If set to true, clients will be notified that the convar has changed.
484 * This will only work if the convar has the FCVAR_NOTIFY flag.
486 * @error Invalid or corrupt Handle.
488 native SetConVarFloat(Handle:convar, Float:value, bool:replicate=false, bool:notify=false);
491 * Retrieves the string value of a console variable.
493 * @param convar Handle to the convar.
494 * @param value Buffer to store the value of the convar.
495 * @param maxlength Maximum length of string buffer.
497 * @error Invalid or corrupt Handle.
499 native GetConVarString(Handle:convar, String:value[], maxlength);
502 * Sets the string value of a console variable.
504 * @param convar Handle to the convar.
505 * @param value New string value.
506 * @param replicate If set to true, the new convar value will be set on all clients.
507 * This will only work if the convar has the FCVAR_REPLICATED flag
508 * and actually exists on clients.
509 * @param notify If set to true, clients will be notified that the convar has changed.
510 * This will only work if the convar has the FCVAR_NOTIFY flag.
512 * @error Invalid or corrupt Handle.
514 native SetConVarString(Handle:convar, const String:value[], bool:replicate=false, bool:notify=false);
517 * Resets the console variable to its default value.
519 * @param convar Handle to the convar.
520 * @param replicate If set to true, the new convar value will be set on all clients.
521 * This will only work if the convar has the FCVAR_REPLICATED flag
522 * and actually exists on clients.
523 * @param notify If set to true, clients will be notified that the convar has changed.
524 * This will only work if the convar has the FCVAR_NOTIFY flag.
526 * @error Invalid or corrupt Handle.
528 native ResetConVar(Handle:convar, bool:replicate=false, bool:notify=false);
531 * Returns the bitstring of flags on a console variable.
533 * @param convar Handle to the convar.
534 * @return A bitstring containing the FCVAR_* flags that are enabled.
535 * @error Invalid or corrupt Handle.
537 native GetConVarFlags(Handle:convar);
540 * Sets the bitstring of flags on a console variable.
542 * @param convar Handle to the convar.
543 * @param flags A bitstring containing the FCVAR_* flags to enable.
545 * @error Invalid or corrupt Handle.
547 native SetConVarFlags(Handle:convar, flags);
550 * Retrieves the specified bound of a console variable.
552 * @param convar Handle to the convar.
553 * @param type Type of bound to retrieve, ConVarBound_Lower or ConVarBound_Upper.
554 * @param value By-reference cell to store the specified floating point bound value.
555 * @return True if the convar has the specified bound set, false otherwise.
556 * @error Invalid or corrupt Handle.
558 native bool:GetConVarBounds(Handle:convar, ConVarBounds:type, &Float:value);
561 * Sets the specified bound of a console variable.
563 * @param convar Handle to the convar.
564 * @param type Type of bound to set, ConVarBound_Lower or ConVarBound_Upper
565 * @param set If set to true, convar will use specified bound. If false, bound will be removed.
566 * @param value Floating point value to use as the specified bound.
568 * @error Invalid or corrupt Handle.
570 native SetConVarBounds(Handle:convar, ConVarBounds:type, bool:set, Float:value=0.0);
573 * Retrieves the name of a console variable.
575 * @param convar Handle to the convar.
576 * @param value Buffer to store the name of the convar.
577 * @param maxlength Maximum length of string buffer.
579 * @error Invalid or corrupt Handle.
581 native GetConVarName(Handle:convar, const String:name[], maxlength);
583 funcenum ConVarQueryFinished
586 * Called when a query to retrieve a client's console variable has finished.
588 * @param cookie Unique identifier of query.
589 * @param client Player index.
590 * @param result Result of query that tells one whether or not query was successful.
591 * See ConVarQueryResult enum for more details.
592 * @param convarName Name of client convar that was queried.
593 * @param convarValue Value of client convar that was queried if successful. This will be "" if it was not.
594 * @param value Value that was passed when query was started.
597 public(QueryCookie:cookie, client, ConVarQueryResult:result, const String:cvarName[], const String:cvarValue[], any:value),
600 * Called when a query to retrieve a client's console variable has finished.
602 * @param cookie Unique identifier of query.
603 * @param client Player index.
604 * @param result Result of query that tells one whether or not query was successful.
605 * See ConVarQueryResult enum for more details.
606 * @param convarName Name of client convar that was queried.
607 * @param convarValue Value of client convar that was queried if successful. This will be "" if it was not.
610 public(QueryCookie:cookie, client, ConVarQueryResult:result, const String:cvarName[], const String:cvarValue[])
614 * Starts a query to retrieve the value of a client's console variable.
616 * @param client Player index.
617 * @param name Name of client convar to query.
618 * @param callback A function to use as a callback when the query has finished.
619 * @param value Optional value to pass to the callback function.
620 * @return A cookie that uniquely identifies the query.
621 * Returns QUERYCOOKIE_FAILED on failure, such as when used on a bot.
623 native QueryCookie:QueryClientConVar(client, const String:cvarName[], ConVarQueryFinished:callback, any:value=0);
626 * Gets a command iterator. Must be freed with CloseHandle().
628 * @return A new command iterator.
630 native Handle:GetCommandIterator();
633 * Reads a command iterator, then advances to the next command if any.
634 * Only SourceMod specific commands are returned.
636 * @param iter Command iterator Handle.
637 * @param name Name buffer.
638 * @param nameLen Name buffer size.
639 * @param eflags Effective default flags of a command.
640 * @param desc Command description buffer.
641 * @param descLen Command description buffer size.
642 * @return True on success, false if there are no more commands.
644 native bool:ReadCommandIterator(Handle:iter,
652 * Returns whether a client has access to a given command string. The string
653 * can also be any override string, as overrides can be independent of
654 * commands. This important feature essentially allows you to create custom
655 * flags using the override system.
657 * @param client Client index.
658 * @param command Command name. If the command is not found, the default
660 * @param flags Flag string to use as a default, if the command or override
662 * @param override_only If true, SourceMod will not attempt to find a matching
663 * command, and it will only use the default flags specified.
664 * Otherwise, SourceMod will ignore the default flags if
665 * there is a matching admin command.
666 * @return True if the client has access, false otherwise.
668 native bool:CheckCommandAccess(client,
669 const String:command[],
671 bool:override_only=false);
674 * Returns true if the supplied character is valid in a ConVar name.
676 * @param c Character to validate.
677 * @return True is valid for ConVars, false otherwise
679 stock bool:IsValidConVarChar(c)
681 return (c == '_' || IsCharAlpha(c) || IsCharNumeric(c));
