3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _console_included
19 #define _console_included
22 * Console variable bound values used with Get/SetConVarBounds()
26 ConVarBound_Upper = 0,
31 * Console variable query helper values.
35 QUERYCOOKIE_FAILED = 0,
39 * Reply sources for commands.
43 SM_REPLY_TO_CONSOLE = 0,
48 * Console variable query result values.
50 enum ConVarQueryResult
52 ConVarQuery_Okay = 0, /**< Retrieval of client convar value was successful. */
53 ConVarQuery_NotFound, /**< Client convar was not found. */
54 ConVarQuery_NotValid, /**< A console command with the same name was found, but there is no convar. */
55 ConVarQuery_Protected /**< Client convar was found, but it is protected. The server cannot retrieve its value. */
59 * @section Flags for console commands and console variables. The descriptions
60 * for each constant come directly from the Source SDK.
62 #define FCVAR_NONE 0 /**< The default, no flags at all */
63 #define FCVAR_UNREGISTERED (1<<0) /**< If this is set, don't add to linked list, etc. */
64 #define FCVAR_LAUNCHER (1<<1) /**< Defined by launcher. */
65 #define FCVAR_GAMEDLL (1<<2) /**< Defined by the game DLL. */
66 #define FCVAR_CLIENTDLL (1<<3) /**< Defined by the client DLL. */
67 #define FCVAR_MATERIAL_SYSTEM (1<<4) /**< Defined by the material system. */
68 #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. */
69 #define FCVAR_SPONLY (1<<6) /**< This cvar cannot be changed by clients connected to a multiplayer server. */
70 #define FCVAR_ARCHIVE (1<<7) /**< Set to cause it to be saved to vars.rc */
71 #define FCVAR_NOTIFY (1<<8) /**< Notifies players when changed. */
72 #define FCVAR_USERINFO (1<<9) /**< Changes the client's info string. */
73 #define FCVAR_PRINTABLEONLY (1<<10) /**< This cvar's string cannot contain unprintable characters (e.g., used for player name, etc.) */
74 #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 */
75 #define FCVAR_NEVER_AS_STRING (1<<12) /**< Never try to print that cvar. */
76 #define FCVAR_REPLICATED (1<<13) /**< Server setting enforced on clients. */
77 #define FCVAR_CHEAT (1<<14) /**< Only useable in singleplayer / debug / multiplayer & sv_cheats */
78 #define FCVAR_STUDIORENDER (1<<15) /**< Defined by the studiorender system. */
79 #define FCVAR_DEMO (1<<16) /**< Record this cvar when starting a demo file. */
80 #define FCVAR_DONTRECORD (1<<17) /**< Don't record these command in demo files. */
81 #define FCVAR_PLUGIN (1<<18) /**< Defined by a 3rd party plugin. */
82 #define FCVAR_DATACACHE (1<<19) /**< Defined by the datacache system. */
83 #define FCVAR_TOOLSYSTEM (1<<20) /**< Defined by an IToolSystem library */
84 #define FCVAR_FILESYSTEM (1<<21) /**< Defined by the file system. */
85 #define FCVAR_NOT_CONNECTED (1<<22) /**< Cvar cannot be changed by a client that is connected to a server. */
86 #define FCVAR_SOUNDSYSTEM (1<<23) /**< Defined by the soundsystem library. */
87 #define FCVAR_ARCHIVE_XBOX (1<<24) /**< Cvar written to config.cfg on the Xbox. */
88 #define FCVAR_INPUTSYSTEM (1<<25) /**< Defined by the inputsystem DLL. */
89 #define FCVAR_NETWORKSYSTEM (1<<26) /**< Defined by the network system. */
90 #define FCVAR_VPHYSICS (1<<27) /**< Defined by vphysics. */
97 * Executes a server command as if it were on the server console (or RCON)
99 * @param format Formatting rules.
100 * @param ... Variable number of format parameters.
103 native ServerCommand(const String:format[], any:...);
106 * Inserts a server command at the beginning of the server command buffer.
108 * @param format Formatting rules.
109 * @param ... Variable number of format parameters.
112 native InsertServerCommand(const String:format[], any:...);
115 * Executes every command in the server's command buffer, rather than once per frame.
119 native ServerExecute();
122 * Executes a client command. Note that this will not work on clients unless
123 * they have cl_restrict_server_commands set to 0.
125 * @param client Index of the client.
126 * @param fmt Format of the client command.
127 * @param ... Format parameters/
129 * @error Invalid client index, or client not connected.
131 native ClientCommand(client, const String:fmt[], any:...);
134 * Executes a client command on the server without being networked.
136 * @param client Index of the client.
137 * @param fmt Format of the client command.
138 * @param ... Format parameters
140 * @error Invalid client index, or client not connected.
142 native FakeClientCommand(client, const String:fmt[], any:...);
145 * Sends a message to the server console.
147 * @param format Formatting rules.
148 * @param ... Variable number of format parameters.
151 native PrintToServer(const String:format[], any:...);
154 * Sends a message to a client's console.
156 * @param client Client index.
157 * @param format Formatting rules.
158 * @param ... Variable number of format parameters.
160 * @error If the client is not connected an error will be thrown.
162 native PrintToConsole(client, const String:format[], any:...);
165 * Reples to a message in a command.
167 * A client index of 0 will use PrintToServer().
168 * If the command was from the console, PrintToConsole() is used.
169 * If the command was from chat, PrintToChat() is used.
171 * @param client Client index, or 0 for server.
172 * @param format Formatting rules.
173 * @param ... Variable number of format parameters.
175 * @error If the client is not connected or invalid.
177 native ReplyToCommand(client, const String:format[], any:...);
180 * Returns the current reply source of a command.
182 * @return ReplySource value.
184 native ReplySource:GetCmdReplySource();
187 * Displays usage of an admin command to users depending on the
188 * setting of the sm_show_activity cvar. Additionally, the client
189 * who typed the command will receive the same text without any
190 * client name prefix (as a confirmation).
192 * @param client Client index doing the action, or 0 for server.
193 * @param format Formatting rules.
194 * @param ... Variable number of format parameters.
198 native ShowActivity(client, const String:format[], any:...);
201 * Called when a server-only command is invoked.
203 * @params args Number of arguments that were in the argument string.
204 * @return An Action value. Not handling the command
205 * means that Source will report it as "not found."
207 functag SrvCmd Action:public(args);
210 * Creates a server-only console command, or hooks an already existing one.
212 * @param cmd Name of the command to hook or create.
213 * @param callback A function to use as a callback for when the command is invoked.
214 * @param description Optional description to use for command creation.
215 * @param flags Optional flags to use for command creation.
217 * @error Command name is the same as an existing convar.
219 native RegServerCmd(const String:cmd[], SrvCmd:callback, const String:description[]="", flags=0);
222 * Called when a generic console command is invoked.
224 * @param client Index of the client, or 0 from the server.
225 * @param args Number of arguments that were in the argument string.
226 * @return An Action value. Not handling the command
227 * means that Source will report it as "not found."
229 functag ConCmd Action:public(client, args);
232 * Creates a console command, or hooks an already existing one.
234 * @param cmd Name of the command to hook or create.
235 * @param callback A function to use as a callback for when the command is invoked.
236 * @param description Optional description to use for command creation.
237 * @param flags Optional flags to use for command creation.
239 * @error Command name is the same as an existing convar.
241 native RegConsoleCmd(const String:cmd[], ConCmd:callback, const String:description[]="", flags=0);
244 * Creates a console command as an administrative command. If the command does not exist,
245 * it is created. When this command is invoked, the access rights of the player are
246 * automatically checked before allowing it to continue.
248 * @param cmd String containing command to register.
249 * @param callback A function to use as a callback for when the command is invoked.
250 * @param adminflags Administrative flags (bitstring) to use for permissions.
251 * @param group String containing the command group to use. If empty,
252 * the plugin's filename will be used instead.
253 * @param description Optional description to use for help.
254 * @param flags Optional console flags.
256 * @error Command name is the same as an existing convar.
258 native RegAdminCmd(const String:cmd[],
261 const String:description[]="",
262 const String:group[]="",
266 * Returns the number of arguments from the current console or server command.
267 * @note Unlike the HL2 engine call, this does not include the command itself.
269 * @return Number of arguments to the current command.
274 * Retrieves a command argument given its index, from the current console or
276 * @note Argument indexes start at 1; 0 retrieves the command name.
278 * @param argnum Argument number to retrieve.
279 * @param buffer Buffer to use for storing the string.
280 * @param maxlength Maximum length of the buffer.
283 native GetCmdArg(argnum, String:buffer[], maxlength);
286 * Retrieves the entire command argument string in one lump from the current
287 * console or server command.
289 * @param buffer Buffer to use for storing the string.
290 * @param maxlength Maximum length of the buffer.
293 native GetCmdArgString(String:buffer[], maxlength);
296 * Creates a new console variable.
298 * @param name Name of new convar.
299 * @param defaultValue String containing the default value of new convar.
300 * @param description Optional description of the convar.
301 * @param flags Optional bitstring of flags determining how the convar should be handled. See FCVAR_* constants for more details.
302 * @param hasMin Optional boolean that determines if the convar has a minimum value.
303 * @param min Minimum floating point value that the convar can have if hasMin is true.
304 * @param hasMax Optional boolean that determines if the convar has a maximum value.
305 * @param max Maximum floating point value that the convar can have if hasMax is true.
306 * @return A handle to the newly created convar. If the convar already exists, INVALID_HANDLE is returned.
307 * @error Convar name is blank or is the same as an existing console command.
309 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);
312 * Searches for a console variable.
314 * @param name Name of convar to find.
315 * @return A handle to the convar if it is found. INVALID_HANDLE otherwise.
317 native Handle:FindConVar(const String:name[]);
320 * Called when a console variable's value is changed.
322 * @param convar Handle to the convar that was changed.
323 * @param oldValue String containing the value of the convar before it was changed.
324 * @param newValue String containing the new value of the convar.
327 functag ConVarChanged public(Handle:convar, const String:oldValue[], const String:newValue[]);
330 * Creates a hook for when a console variable's value is changed.
332 * @param convar Handle to the convar.
333 * @param callback An OnConVarChanged function pointer.
335 * @error Invalid or corrupt Handle or invalid callback function.
337 native HookConVarChange(Handle:convar, ConVarChanged:callback);
340 * Removes a hook for when a console variable's value is changed.
342 * @param convar Handle to the convar.
343 * @param callback An OnConVarChanged function pointer.
345 * @error Invalid or corrupt Handle, invalid callback function, or no active hook on convar.
347 native UnhookConVarChange(Handle:convar, ConVarChanged:callback);
350 * Returns the boolean value of a console variable.
352 * @param convar Handle to the convar.
353 * @return The boolean value of the convar.
354 * @error Invalid or corrupt Handle.
356 native bool:GetConVarBool(Handle:convar);
359 * Sets the boolean value of a console variable.
361 * @param convar Handle to the convar.
362 * @param value New boolean value.
363 * @param replicate If set to true, the new convar value will be set on all clients.
364 * This will only work if the convar has the FCVAR_REPLICATED flag
365 * and actually exists on clients.
366 * @param notify If set to true, clients will be notified that the convar has changed.
367 * This will only work if the convar has the FCVAR_NOTIFY flag.
369 * @error Invalid or corrupt Handle.
371 native SetConVarBool(Handle:convar, bool:value, bool:replicate=false, bool:notify=false);
374 * Returns the integer value of a console variable.
376 * @param convar Handle to the convar.
377 * @return The integer value of the convar.
378 * @error Invalid or corrupt Handle.
380 native GetConVarInt(Handle:convar);
383 * Sets the integer value of a console variable.
385 * @param convar Handle to the convar.
386 * @param value New integer value.
387 * @param replicate If set to true, the new convar value will be set on all clients.
388 * This will only work if the convar has the FCVAR_REPLICATED flag
389 * and actually exists on clients.
390 * @param notify If set to true, clients will be notified that the convar has changed.
391 * This will only work if the convar has the FCVAR_NOTIFY flag.
393 * @error Invalid or corrupt Handle.
395 native SetConVarInt(Handle:convar, value, bool:replicate=false, bool:notify=false);
398 * Returns the floating point value of a console variable.
400 * @param convar Handle to the convar.
401 * @return The floating point value of the convar.
402 * @error Invalid or corrupt Handle.
404 native Float:GetConVarFloat(Handle:convar);
407 * Sets the floating point value of a console variable.
409 * @param convar Handle to the convar.
410 * @param value New floating point value.
411 * @param replicate If set to true, the new convar value will be set on all clients.
412 * This will only work if the convar has the FCVAR_REPLICATED flag
413 * and actually exists on clients.
414 * @param notify If set to true, clients will be notified that the convar has changed.
415 * This will only work if the convar has the FCVAR_NOTIFY flag.
417 * @error Invalid or corrupt Handle.
419 native SetConVarFloat(Handle:convar, Float:value, bool:replicate=false, bool:notify=false);
422 * Retrieves the string value of a console variable.
424 * @param convar Handle to the convar.
425 * @param value Buffer to store the value of the convar.
426 * @param maxlength Maximum length of string buffer.
428 * @error Invalid or corrupt Handle.
430 native GetConVarString(Handle:convar, String:value[], maxlength);
433 * Sets the string value of a console variable.
435 * @param convar Handle to the convar.
436 * @param value New string value.
437 * @param replicate If set to true, the new convar value will be set on all clients.
438 * This will only work if the convar has the FCVAR_REPLICATED flag
439 * and actually exists on clients.
440 * @param notify If set to true, clients will be notified that the convar has changed.
441 * This will only work if the convar has the FCVAR_NOTIFY flag.
443 * @error Invalid or corrupt Handle.
445 native SetConVarString(Handle:convar, const String:value[], bool:replicate=false, bool:notify=false);
448 * Returns the bitstring of flags on a console variable.
450 * @param convar Handle to the convar.
451 * @return A bitstring containing the FCVAR_* flags that are enabled.
452 * @error Invalid or corrupt Handle.
454 native GetConVarFlags(Handle:convar);
457 * Sets the bitstring of flags on a console variable.
459 * @param convar Handle to the convar.
460 * @param flags A bitstring containing the FCVAR_* flags to enable.
462 * @error Invalid or corrupt Handle.
464 native SetConVarFlags(Handle:convar, flags);
467 * Retrieves the specified bound of a console variable.
469 * @param convar Handle to the convar.
470 * @param type Type of bound to retrieve, ConVarBound_Lower or ConVarBound_Upper.
471 * @param value By-reference cell to store the specified floating point bound value.
472 * @return True if the convar has the specified bound set, false otherwise.
473 * @error Invalid or corrupt Handle.
475 native bool:GetConVarBounds(Handle:convar, ConVarBounds:type, &Float:value);
478 * Sets the specified bound of a console variable.
480 * @param convar Handle to the convar.
481 * @param type Type of bound to set, ConVarBound_Lower or ConVarBound_Upper
482 * @param set If set to true, convar will use specified bound. If false, bound will be removed.
483 * @param value Floating point value to use as the specified bound.
485 * @error Invalid or corrupt Handle.
487 native SetConVarBounds(Handle:convar, ConVarBounds:type, bool:set, Float:value=0.0);
490 * Retrieves the name of a console variable.
492 * @param convar Handle to the convar.
493 * @param value Buffer to store the name of the convar.
494 * @param maxlength Maximum length of string buffer.
496 * @error Invalid or corrupt Handle.
498 native GetConVarName(Handle:convar, const String:name[], maxlength);
501 * Resets the console variable to its default value.
503 * @param convar Handle to the convar.
505 * @error Invalid or corrupt Handle.
507 native ResetConVar(Handle:convar);
509 funcenum ConVarQueryFinished
512 * Called when a query to retrieve a client's console variable has finished.
514 * @param cookie Unique identifier of query.
515 * @param client Player index.
516 * @param result Result of query that tells one whether or not query was successful.
517 * See ConVarQueryResult enum for more details.
518 * @param convarName Name of client convar that was queried.
519 * @param convarValue Value of client convar that was queried if successful. This will be "" if it was not.
520 * @param value Value that was passed when query was started.
523 public(QueryCookie:cookie, client, ConVarQueryResult:result, const String:cvarName[], const String:cvarValue[], any:value),
526 * Called when a query to retrieve a client's console variable has finished.
528 * @param cookie Unique identifier of query.
529 * @param client Player index.
530 * @param result Result of query that tells one whether or not query was successful.
531 * See ConVarQueryResult enum for more details.
532 * @param convarName Name of client convar that was queried.
533 * @param convarValue Value of client convar that was queried if successful. This will be "" if it was not.
536 public(QueryCookie:cookie, client, ConVarQueryResult:result, const String:cvarName[], const String:cvarValue[])
540 * Starts a query to retrieve the value of a client's console variable.
542 * @param client Player index.
543 * @param name Name of client convar to query.
544 * @param callback A function to use as a callback when the query has finished.
545 * @param value Optional value to pass to the callback function.
546 * @return A cookie that uniquely identifies the query.
547 * Returns QUERYCOOKIE_FAILED on failure, such as when used on a bot.
549 native QueryCookie:QueryClientConVar(client, const String:cvarName[], ConVarQueryFinished:callback, any:value=0);
