engine.console Functions

WarningThe scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScript (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.

Controls console-related parameters.

Onscreen Console Overlay#

By default the console overlay is disabled. To make it output console messages to the application screen it should be enabled. You can adjust the overlay’s behavior and appearance as well as specify the messages that will be printed exclusively to the onscreen overlay and will not be written to the console.

Onscreen Overlay with custom parameters and colored text

You can customize the console font by using the setFontSize(), setMessageColor(), setWarningColor(), and setErrorColor() methods. See the following example:

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 UnigineScript project by using UNIGINE SDK Browser.

In the example below, we perform the following actions:

Define and implement methods for console commands.
Add a new command.

1. Implementing Callback Function

In this example, we define 2 functions in the world script (unigine_project.usc file): one as a callback for a console command with no arguments and one for a console command with 1 argument.

Source code (UnigineScript)

// unigine_project.usc

// a script function to be executed for no arguments input
void console_action_callback() {
	log.message("first action! no arguments!\n");
}

// a script function to be executed for 1 argument input
void console_action_callback(string arg) {
	log.message("second action! the argument is: %s\n",arg);
}

2. Adding Custom Console Command

Add a custom command to the unigine_project.usc file by using engine.console.addCommand() function. By adding this code into init() function, the engine adds a new console command on world initialization.

Source code (UnigineScript)

// unigine_project.usc

/* ... */

int init() {
	// add a command
	engine.console.addCommand("console_action","my_command description","console_action_callback");
	
	return 1;
}

/* ... */

3. Running Sample

Run the project and open the console. Write recently created command to check the result:

Output

#if you write "console_action"
console_action
first action! no arguments!

#if you write "console_action arg"
console action arg
second action! the argument is: arg

To remove the added console command, use removeCommand() method.

Methods:

Name	Description View: Sort by:
setActive	Opens or closes the console.
isActive	Returns a value indicating if the console is opened or closed.
setBackgroundColor	Sets a background color for the console.
setFontSize	Sets the size for the console font.
getFontSize	Returns the size for the console font.
setErrorColor	Sets a color for error messages in the console.
setLock	Disables or enables the console.
getLock	Checks if the console is disabled.
setMessageColor	Sets a color for ordinary messages in the console.
getNumCommands	Returns the number of all available console commands, including the custom ones.
getNumVariables	Returns the number of all available console variables.
setPrompt	Updates the console prompt.
setTextColor	Sets a common font color for the console.
setWarningColor	Sets a color for warning messages in the console.
isCommand	Returns a value indicating if a command with a given name exists.
getCommandDescription	Returns the description of the console command by its name.
getCommandName	Returns the name of the console command by its number in the array of the existing commands.
setFloat	Sets a float value for a given variable.
getFloat	Returns a float value of a given variable.
getFloatMax	Returns a maximum float value for a given variable.
getFloatMin	Returns a minimum float value for a given variable.
isFloat	Checks if the value set for the given console variable is of the float type.
setInt	Sets an integer value for a given variable.
getInt	Returns an integer value of a given variable.
getIntMax	Returns a maximum integer value for a given variable.
getIntMin	Returns a minimum integer value for a given variable.
isInt	Checks if the value of the given console variable is of the integer type.
getPrompt	Returns the console prompt.
setString	Sets a string value for a given variable.
getString	Returns the string value of a given variable.
isString	Checks if the value of the given console variable is of the string type.
isVariable	Returns a value indicating if a variable with a given name exists.
getVariableDescription	Returns the description of the console variable by its name.
getVariableName	Returns the name of the console variable by its number in the array of the existing variables.
setVec2	Sets a two component vector for the console variable.
getVec2	Returns the two component vector console variable.
isVec2	Returns a value indicating if the console variable is a two component vector.
setVec3	Sets a three component vector for the console variable.
getVec3	Returns the three component vector console variable.
isVec3	Returns a value indicating if the console variable is a three component vector.
setVec4	Sets a four component vector for the console variable.
getVec4	Returns the four component vector console variable.
isVec4	Returns a value indicating if the console variable is a four component vector.
addCommand	Adds a custom console command bound to a given callback function.
flush	Forces to execute all queued console commands.
removeCommand	Removes a custom console command.
run	Runs the specified console command.
getBackgroundColor	Returns the background color for the console.
getMessageColor	Returns the color for ordinary messages in the console.
getWarningColor	Returns the color for warning messages in the console.
getErrorColor	Returns the color for error messages in the console.
getTextColor	Returns the common font color for the console.
setFontSize	Returns the current font size used for console messages.
getFontSize	Returns the current font size used for console messages.
setHeight	Sets the height of the console.
getHeight	Returns the console height in percentage of the window height.
setLimit	Sets the maximum number of messages the console can output.
getLimit	Returns the maximum number of messages the console can output.
setWrapping	Enables the text wrapping to the next line.
isWrapping	Returns a value indicating if the text wrapping is enabled for the console.
setOnscreen	Shows or hides the onscreen overlay.
isOnscreen	Returns a value indicating if the onscreen overlay is shown or hidden.
setOnscreenFontSize	Sets the size for the onscreen overlay font.
getOnscreenFontSize	Returns the size of the onscreen overlay font.
setOnscreenHeight	Sets the height value for the onscreen overlay.
getOnscreenHeight	Returns the height for the onscreen overlay.
setOnscreenTime	Sets the time during which the text is displayed on the screen.
getOnscreenTime	Returns the time during which the text is displayed on the screen.
getLastMessage	Returns the last message printed to the console.
getLastWarning	Returns the last warning message printed to the console.
getLastError	Returns the last error message printed to the console.

Console Class

Members

void engine.console.setActive ( int active ) #

Opens or closes the console. By default the console is closed.

Arguments

int active - Positive integer to make the console active (opened); otherwise, 0.

int engine.console.isActive ( ) #

Returns a value indicating if the console is opened or closed.

Return value

1 if the console is active (opened); otherwise, 0.

void engine.console.setBackgroundColor ( vec4 color ) #

Sets a background color for the console.

Arguments

vec4 color - Four-component vector specifying the color in the RGBA format.

void engine.console.setFontSize ( int size ) #

Sets the size for the console font.

Arguments

int size - The size of the console font.

int engine.console.getFontSize ( ) #

Returns the size for the console font.

Return value

The size of the console font.

int engine.console.isCommand ( string name ) #

Returns a value indicating if a command with a given name exists.

Arguments

string name - The command name.

Return value

1 if the command with a given name exists; otherwise, 0.

string engine.console.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 engine.console.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 engine.console.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 engine.console.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 engine.console.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 engine.console.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 engine.console.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.

int engine.console.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

True if the variable value is float; otherwise, false.

void engine.console.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 engine.console.getInt ( string name ) #

Returns an integer value of a given variable.

Arguments

string name - Variable name.

Return value

Value of the variable.

int engine.console.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 engine.console.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.

int engine.console.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

True if the variable value is int; otherwise, false.

void engine.console.setLock ( int lock ) #

Disables or enables the console. By default the console is enabled.

Arguments

int lock - Positive integer to disable the console; otherwise, 0.

int engine.console.getLock ( ) #

Checks if the console is disabled.

Return value

1 if the console is disabled; otherwise, 0.

void engine.console.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.

int engine.console.getNumCommands ( ) #

Returns the number of all available console commands, including the custom ones.

Return value

The number of available console commands.

int engine.console.getNumVariables ( ) #

Returns the number of all available console variables.

Return value

The number of available console variables.

void engine.console.setPrompt ( string prompt ) #

Updates the console prompt. The default prompt is Unigine~#.

Arguments

string prompt - New console prompt.

string engine.console.getPrompt ( ) #

Returns the console prompt.

Return value

The prompt text.

void engine.console.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 engine.console.getString ( string name ) #

Returns the string value of a given variable.

Arguments

string name - The variable name.

Return value

String value of the variable.

int engine.console.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

True if the variable value is string; otherwise, false.

void engine.console.setTextColor ( vec4 color ) #

Sets a common font color for the console.

Arguments

vec4 color - Four-component vector specifying the color in the RGBA format.

int engine.console.isVariable ( string name ) #

Returns a value indicating if a variable with a given name exists.

Arguments

string name - The variable name.

Return value

True if the variable exists; otherwise, false.

string engine.console.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 engine.console.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 engine.console.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 engine.console.getVec2 ( string name ) #

Returns the two component vector console variable.

Arguments

string name - Name of the variable.

Return value

Value of the variable.

int engine.console.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

True if the variable is a two component vector; otherwise, false.

void engine.console.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 engine.console.getVec3 ( string name ) #

Returns the three component vector console variable.

Arguments

string name - Name of the variable.

Return value

Value of the variable.

int engine.console.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

True if the variable is a three component vector; otherwise, false.

void engine.console.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 engine.console.getVec4 ( string name ) #

Returns the four component vector console variable.

Arguments

string name - Name of the variable.

Return value

Value of the variable.

int engine.console.isVec4 ( string name ) #

Returns a value indicating if the console variable is a four component vector.

Arguments

string name

Return value

True if the variable is a three component vector; otherwise, false.

void engine.console.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.

int engine.console.addCommand ( string name, string desc, string callback ) #

Adds a custom console command bound to a given callback function. The command can have up to 6 arguments, which will be passed to the script function.

Arguments

string name - Name of the new console command.
string desc - Short description to be displayed in the console.
string callback - Name of the callback function to be run on command execution.

Return value

1 if the custom command is added successfully; otherwise, 0.

void engine.console.flush ( ) #

Forces to execute all queued console commands.

engine.console.removeCommand ( ) #

Removes a custom console command.

Arguments

Return value

1 if the custom command has been removed successfully; otherwise, 0.

void engine.console.run ( ) #

Runs the specified console command.