Controls console-related parameters.
Adding Console Command with Several Arguments#
The Console class can be used to create custom user console commands with a different number of arguments. This section provides an example of how to create a custom console command with several arguments.
Prior Knowledge
It is supposed that you have already created an empty C# project by using UNIGINE SDK Browser.
In the example below, we perform the following actions:
- Define and implement AppWorldLogic instance methods for console commands.
- Get the console instance (which has a singleton implementation) and add a new command.
1. Adding Instance Methods
In this example, we define three methods in the AppWorldLogic.cs file: one as a callback for a console command and another two methods for actions depending on the number of arguments:
- choose_command() selects the appropriate method.
- action_no_args() is called if there are no console arguments.
- action_one_arg() is called if an argument was passed.
Source code (C#)
// AppWorldLogic.cs
public static void choose_command(int argc, string[] argv)
{
for (int i = 0; i < argc; i++) {
Log.Message("arg[{0}]: {1}\n", i, argv[i]);
}
// note: the first element of argv is the name of console command
if (argc == 1) {
action_no_args();
}
else if (argc == 2) {
action_one_arg(argv[1]);
}
// for more arguments:
//else if (...) {
// // etc
//}
}
// write the message into console, if there are no arguments
public static void action_no_args()
{
Log.Message("first action! no arguments!\n");
}
// write the message into console, if an argument was passed
public static void action_one_arg(string s)
{
Log.Message("second action! the argument is:{0} \n", s);
}Arguments argc and argv are used to get the arguments count and arguments vector.
Notice
The first element of argv always keeps the name of a console command. Thus, argc is always >= 1. To get the first passed argument, you should use argv[1].
2. Adding Custom Console Command
Add a custom command to the AppWorldLogic.cs file by using addCommand() function. By adding this code into init() function of the AppWorldLogic class, the engine adds a new console command on AppWorldLogic class instance initialization.
Source code (C#)
// AppWorldLogic.cs
using Unigine;
/* ... */
public override bool Init()
{
// add a command
Console.AddCommand("console_action","Performs custom console action",choose_command);
return 1;
}
/* ... */3. Running Sample
After building the project, run it and open the console. Write recently created command to check the result:
Output
#if you write "console_action"
arg[0]: console_action
first action! no arguments!
#if you write "console_action arg"
arg[0]: console action
arg[1]: arg
second action! the argument is:argTo remove the added console command, use removeCommand() method.
See Also#
- C++ API sample located in the folder <UnigineSDK>/source/samples/Api/Systems/Console
- C# API sample located in the folder <UnigineSDK>/source/csharp/samples/Api/Systems/Console
Console Class
Properties
int Lock#
Checks if the console is disabled.
set
Disables or enables the console. By default the console is enabled.
set value -
Positive integer to disable the console; otherwise, 0.
int NumCommands#
The number of all available console commands, including the custom ones.
int NumVariables#
The number of all available console variables.
int IsActive#
A value indicating if the console is opened or closed.
set
Opens or closes the console. By default the console is closed.
set value -
Positive integer to make the console active (opened); otherwise, 0.
Members
void SetBackgroundColor ( vec4 color ) #
Sets a background color for the console.Arguments
- vec4 color - Four-component vector specifying the color in the RGBA format.
bool IsCommand ( string name ) #
Returns a value indicating if a command with a given name exists.Arguments
- string name - The command name.
Return value
Returns 1 if the command with a given name exists; otherwise, 0.string GetCommandDescription ( string name ) #
Returns the description of the console command by its name. If the name isn't specified, an empty string will be returned.Arguments
- string name - The command name.
Return value
The command description if it exists; otherwise, an empty string.string GetCommandName ( int num ) #
Returns the name of the console command by its number in the array of the existing commands.Arguments
- int num - The command number.
Return value
The command name if it is found in the array of the existing commands; otherwise, an empty string.void SetErrorColor ( vec4 color ) #
Sets a color for error messages in the console.Arguments
- vec4 color - Four-component vector specifying the color in the RGBA format.
void SetFloat ( string name, float value ) #
Sets a float value for a given variable.Arguments
- string name - The variable name.
- float value - Float value of the variable.
float GetFloat ( string name ) #
Returns a float value of a given variable.Arguments
- string name - The variable name.
Return value
Float value of the variable.float GetFloatMax ( string name ) #
Returns a maximum float value for a given variable.Arguments
- string name - Variable name.
Return value
Maximum float value of the variable.float GetFloatMin ( string name ) #
Returns a minimum float value for a given variable.Arguments
- string name - Variable name.
Return value
Minimum float value of the variable.bool IsFloat ( string name ) #
Checks if the value set for the given console variable is of the float type.Arguments
- string name - The variable name.
Return value
1 if the variable value is float; otherwise, 0.void SetInt ( string name, int value ) #
Sets an integer value for a given variable.Arguments
- string name - Variable name.
- int value - Value of the variable.
int GetInt ( string name ) #
Returns an integer value of a given variable.Arguments
- string name - Variable name.
Return value
Integer value of the variable.int GetIntMax ( string name ) #
Returns a maximum integer value for a given variable.Arguments
- string name - Variable name.
Return value
Maximum integer value of the variable.int GetIntMin ( string name ) #
Returns a minimum integer value for a given variable.Arguments
- string name - Variable name.
Return value
Minimum integer value of the variable.bool IsInt ( string name ) #
Checks if the value of the given console variable is of the integer type.Arguments
- string name - The variable name.
Return value
1 if the variable value is int; otherwise, 0.void SetMessageColor ( vec4 color ) #
Sets a color for ordinary messages in the console.Arguments
- vec4 color - Four-component vector specifying the color in the RGBA format.
IntPtr addOutputCallback ( OutputDelegate func ) #
Adds a callback function that will be executed when a text is output to the console.The function is useful when you implement a custom console, for example. The callback function must receive 2 arguments:- string text - a text that is output to the console,
- int level - one of the LEVEL_* variables that indicate the type of the output text. The value can be important for setting a color for console messages, for example.
Source code (C#)
// the callback function
private static void output_callback(string text, int level)
{
switch (level)
{
case Unigine.Console.LEVEL_NORMAL:
// logic for ordinary messages
break;
case Unigine.Console.LEVEL_WARNING:
// logic for warnings
break;
case Unigine.Console.LEVEL_ERROR:
// logic for error messages
break;
}
}
public override bool Init()
{
// set the callback
Console.AddOutputCallback(output_callback);
return 1;
}Arguments
- OutputDelegate func - Callback function. The callback arguments must be: (string text, int level).
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool removeOutputCallback ( IntPtr id ) #
Removes the specified callback from the list of output callbacks.Arguments
- IntPtr id - Callback ID obtained when adding it.
Return value
True if the callback with the given ID was removed successfully; otherwise false.void clearOutputCallbacks ( ) #
Clears all added output callbacks.void SetPrompt ( string str ) #
Updates the console prompt. The default prompt is Unigine~#.Arguments
- string str - New console prompt.
void SetString ( string name, string value ) #
Sets a string value for a given variable.Arguments
- string name - The variable name.
- string value - String value of the variable.
string GetString ( string name ) #
Returns the string value of a given variable.Arguments
- string name - The variable name.
Return value
String value of the variable.bool IsString ( string name ) #
Checks if the value of the given console variable is of the string type.Arguments
- string name - The variable name.
Return value
1 if the variable value is string; otherwise, 0.void SetTextColor ( vec4 color ) #
Sets a common font color for the console.Arguments
- vec4 color - Four-component vector specifying the color in the RGBA format.
bool IsVariable ( string name ) #
Returns a value indicating if a variable with a given name exists.Arguments
- string name - The variable name.
Return value
1 if the variable exists; otherwise, 0.string GetVariableDescription ( string name ) #
Returns the description of the console variable by its name. If the name isn't specified, an empty string will be returned.Arguments
- string name - The variable name.
Return value
The variable description if it exists; otherwise, an empty string.string GetVariableName ( int num ) #
Returns the name of the console variable by its number in the array of the existing variables.Arguments
- int num - The variable number.
Return value
The variable name if it is found in the array of the existing variables; otherwise, an empty string.void SetVec2 ( string name, vec2 value ) #
Sets a two component vector for the console variable.Arguments
- string name - Name of the variable.
- vec2 value - Value of the variable.
vec2 GetVec2 ( string name ) #
Returns the two component vector console variable.Arguments
- string name - Name of the variable.
Return value
Value of the variable.bool IsVec2 ( string name ) #
Returns a value indicating if the console variable is a two component vector.Arguments
- string name - Name of the variable.
Return value
1 if the variable is a two component vector; otherwise, 0.void SetVec3 ( string name, vec3 value ) #
Sets a three component vector for the console variable.Arguments
- string name - Name of the variable.
- vec3 value - Value of the variable.
vec3 GetVec3 ( string name ) #
Returns the three component vector console variable.Arguments
- string name - Name of the variable.
Return value
Value of the variable.bool IsVec3 ( string name ) #
Returns a value indicating if the console variable is a three component vector.Arguments
- string name - Name of the variable.
Return value
1 if the variable is a three component vector; otherwise, 0.void SetVec4 ( string name, vec4 value ) #
Sets a four component vector for the console variable.Arguments
- string name - Name of the variable.
- vec4 value - Value of the variable.
vec4 GetVec4 ( string name ) #
Returns the four component vector console variable.Arguments
- string name - Name of the variable.
Return value
Value of the variable.bool IsVec4 ( string name ) #
Returns a value indicating if the console variable is a four component vector.Arguments
- string name
Return value
1 if the variable is a three component vector; otherwise, 0.void SetWarningColor ( vec4 color ) #
Sets a color for warning messages in the console.Arguments
- vec4 color - Four-component vector specifying the color in the RGBA format.
void addCommand ( string name, string desc, CommandCallback callback ) #
Adds a custom console command bound to a given callback function.Arguments
- string name - Name of the new console command.
- string desc - Short description to be displayed in the console.
- CommandCallback callback - The callback function to be run on command execution. The callback arguments must be (int argc, string[] argv,...).
Return value
1 if the custom command is added successfully; otherwise, 0.void Flush ( ) #
Forces to execute all queued console commands.bool RemoveCommand ( string name ) #
Removes a custom console command.Arguments
- string name - Name of the custom console command.
Return value
1 if the custom command has been removed successfully; otherwise, 0.void Run ( string command ) #
Runs the specified console command.Arguments
- string command - A console command with arguments.
Last update:
2020-07-31
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)