Unigine::Engine Class

Header:

#include <UnigineEngine.h>

List of functions:

The Engine class is required for the engine initialization and executing the main loop of the program. Also, you can get the engine startup options through this class.

Engine Class

Members

static Engine * get()

Returns a pointer to the existing engine instance.

Return value

Pointer to the existing engine.

const char * getAppPath()

Returns a path to the binary executable file.

Return value

Path to the executable file.

const char * getAppPath()

const char * getArg(int num)

Returns a command line argument by its index.

Arguments

int num - Command line argument index.

Return value

Command line argument, string.

const char * getArg(int num)

Arguments

int num

virtual float getArgf(int num) const =0

Returns a command line argument by its index converted to a floating point value.

Arguments

int num - Command line argument index.

Return value

Command line argument.

virtual int getArgi(int num) const =0

Returns a command line argument by its index converted to an integer value.

Arguments

int num - Command line argument index.

Return value

Command line argument.

virtual const char * getCachePath() const =0

Returns a path where cache files will be stored.

Return value

Path to a directory for cache files.

const char * getCachePath()

const char * getDataPath(int num = 0)

Returns a path to the -data_pathdirectory specified at the engine startup.

Arguments

int num - Number of the specified -data_pathdirectory. For example, if the are three directories, their numbers will be 1, 2 and 3.

Return value

Data directory.

const char * getDataPath(int num)

Arguments

int num

virtual int isDone() const =0

Returns the "done" flag on engine quit.

Return value

1 if engine is quitting; otherwise, 0.

const char * getEditorCache()

Returns a path to the editor script cache (provided by the editor_cache command line argument).

Return value

Path to the editor script cache.

virtual int getEditorFunction(const char * name, int num_args) const =0

Returns the editor function identifier.

Arguments

const char * name - Name of the editor script function.
int num_args - Number of editor script function arguments.

Return value

The editor script function identifier.

virtual int isEditorFunction(const char * name, int num_args) const =0

Returns a value indicating if the editor script function exists.

Arguments

const char * name - Name of the editor script function.
int num_args - Number of editor script function arguments.

Return value

1 if the editor script function exists; otherwise, 0.

virtual void * getEditorInterpreter() const =0

Returns pointer to the editor interpreter.

Return value

Pointer to the editor interpreter.

virtual int isEditorInterpreter() const =0

Returns a value indicating if the function is called from the editor script.

Return value

1 if the function is called from the editor script; otherwise, 0.

virtual int isEditorLoaded() const =0

Returns a value indicating if the editor script is loaded.

Return value

1 if the editor script is loaded; otherwise, 0.

EditorLogic * getEditorLogic(int num)

Returns the registered EditorLogic instance.

Arguments

int num

Return value

EditorLogic instance.

const char * getEditorScript()

Returns a path to the editor script (provided by the -editor_scriptcommand line argument).

Return value

Path to the editor script.

const char * getEditorScript()

virtual void setEditorVariable(const char * name, const Variable & v) const =0

Sets the editor script variable by its name.

Arguments

const char * name - Name of the editor script variable.
const Variable & v - Value of the editor script variable.

virtual const Variable & getEditorVariable(const char * name) const =0

Returns the editor script variable by its name.

Arguments

const char * name - Name of the world script variable.

Return value

Value of the editor script variable.

virtual int isEditorVariable(const char * name) const =0

Returns a value indicating if the editor script variable exists.

Arguments

const char * name - Name of the editor script variable.

Return value

Returns 1 if the editor script variable exists; otherwise, 0.

String getError()

Returns the system error message.

Return value

The system error message of the current frame, if there is one; otherwise an empty string.

const char * getExternDefines()

Returns the UnigineScript definitions specified at launch.

Return value

The list of UnigineScript definitions.

const char * getExternDefines()

const char * getHomePath()

Returns a path to the user's home directory.

Return value

Path to the user's home directory.

const char * getHomePath()

static int isInitialized()

Returns the initialization status of the engine.

Return value

1 if the engine is initialized; otherwise, 0.

float getInterfaceTime()

Returns a total accumulative time spent on rendering the GUI widgets.

Return value

Time value, in milliseconds.

int isMainThread()

Checks if the current thread is main.

Return value

1 if the current thread is main; otherwise, 0.

String getMessage()

Returns the last system message of the current frame, or empty string if there are no messages.

Return value

The last system message.

virtual int getNumArgs() const =0

Returns the number of command line arguments.

Return value

Number of command line arguments.

int getNumDataPaths()

Returns the number of the specified -data_pathdirectories.

Return value

Number of data directories.

int getNumEditorLogics()

Returns the number of registered EditorLogic instances.

Return value

Number of EditorLogic instances.

int getNumPluginPaths()

Returns the number of plugins paths specified via -plugin_path.

Return value

Number of paths to plugins.

int getNumPluginPaths()

int getNumPlugins()

int getNumSystemLogics()

Returns the number of registered SystemLogic instances.

Return value

Number of SystemLogic instances.

int getNumWorldLogics()

Returns the number of registered WorldLogic instances.

Return value

Number of WorldLogic instances.

virtual void * getPluginData(int num) const =0

Returns the loaded plugin data.

Arguments

int num - Index of the loaded plugin.

Return value

Data of the loaded plugin, if it exists; otherwise, 0.

virtual Plugin * getPluginInterface(int num) const =0

Returns the loaded plugin interface.

Arguments

int num - Index of the loaded plugin.

Return value

Interface of the loaded plugin, if it exists; otherwise, 0.

virtual const char * getPluginName(int num) const =0

Returns the name of the loaded plugin by its index.

Arguments

int num - Index of the loaded plugin.

Return value

Loaded plugin name.

const char * getPluginPath(int num)

Returns a path to plugin directory specified via -plugin_path by its number.

Arguments

int num - Plugin path number in the row of the specified plugin paths.

Return value

Path to a plugin directory.

const char * getPluginPath(int num)

Arguments

int num

float getRenderTime()

Returns the time value, required to prepare all data to be rendered in the current frame and feed rendering commands from the CPU to the GPU. See the Profiler article for details.

Return value

Rendering time value, milliseconds.

virtual const char * getSavePath() const =0

Returns a path where a default configuration file, save files and screenshots will be stored.

Return value

Path to a directory for default configuration file, save files, etc.

const char * getSavePath()

const char * getSoundApp()

Returns a sound API used for rendering.

Return value

A sound API instance.

const char * getSoundApp()

const char * getSystemCache()

Returns a path to the system script cache.

Return value

Path to the system script cache.

virtual int getSystemFunction(const char * name, int num_args) const =0

Returns the system function identifier.

Arguments

const char * name - Name of the system script function.
int num_args - Number of system script function arguments.

Return value

System script function identifier.

virtual int isSystemFunction(const char * name, int num_args) const =0

Checks whether the system script function exists.

Arguments

const char * name - Name of the system script function.
int num_args - Number of system script function arguments.

Return value

1 if the system script function exists; otherwise, 0.

virtual void * getSystemInterpreter() const =0

Returns a pointer to the system interpreter.

Return value

Pointer to the system interpreter.

virtual int isSystemInterpreter() const =0

Checks if the function is called from the system script.

Return value

1 when the function is called from the system script; otherwise, 0.

SystemLogic * getSystemLogic(int num)

Returns the registered SystemLogic instance.

Arguments

int num

Return value

SystemLogic instance.

const char * getSystemScript()

Returns a path to the system script.

Return value

Path to the system script.

const char * getSystemScript()

virtual void setSystemVariable(const char * name, const Variable & v) const =0

Sets a system script variable by a name.

Arguments

const char * name - Name of the system script variable.
const Variable & v - Value of the system script variable.

virtual const Variable & getSystemVariable(const char * name) const =0

Returns the system script variable by its name.

Arguments

const char * name - Name of the system script variable.

Return value

System script variable.

virtual int isSystemVariable(const char * name) const =0

Checks whether a system script variable exists.

Arguments

const char * name - Name of the system script variable.

Return value

Returns 1 if the system script variable exists; otherwise, 0.

float getTotalTime()

Returns the total time that both rendering and calculating of the frame took (the duration of the main loop in the application execution sequence).

Return value

Total time value, milliseconds.

float getUpdateTime()

Returns the duration of the update phase, during which the objects are prepared for their collision response to be calculated.

Return value

The update phase duration value, milliseconds.

const char * getVideoApp()

Returns a graphics API used for rendering.

Return value

Graphics API used for rendering.

const char * getVideoApp()

virtual int getWorldFunction(const char * name, int num_args) const =0

Returns the world function identifier.

Arguments

const char * name - Name of the world script function.
int num_args - Number of world script function arguments.

Return value

World script function identifier.

virtual int isWorldFunction(const char * name, int num_args) const =0

Returns value indicating if the world script function exists.

Arguments

const char * name - Name of the world script function.
int num_args - Number of world script function arguments.

Return value

1 if the world script function exists; otherwise, 0.

virtual void * getWorldInterpreter() const =0

Returns a pointer to the world interpreter.

Return value

Pointer to the world interpreter.

virtual int isWorldInterpreter() const =0

Returns a value indicating if the function is called from the world script.

Return value

Returns 1 if the function is called from the world script; otherwise, 0.

virtual int isWorldLoaded() const =0

Returns a value indicating if the world script is loaded.

Return value

Returns 1 if the world script is loaded; otherwise, 0.

WorldLogic * getWorldLogic(int num)

Returns the registered WorldLogic instance.

Arguments

int num -

Return value

WorldLogic instance.

virtual void setWorldVariable(const char * name, const Variable & v) const =0

Sets a world script variable by its name.

Arguments

const char * name - Name of the world script variable.
const Variable & v - Value of the world script variable.

virtual const Variable & getWorldVariable(const char * name) const =0

Returns a world script variable by its name.

Arguments

const char * name - Name of the world script variable.

Return value

World script variable.

virtual int isWorldVariable(const char * name) const =0

Returns a value indicating if the world script variable exists.

Arguments

const char * name - Name of the world script variable.

Return value

1 if the world script variable exists; otherwise, 0.

int addEditorLogic(EditorLogic * logic)

Adds an EditorLogic instance to the engine runtime.

Arguments

EditorLogic * logic - EditorLogic instance.

Return value

1 if the operation was successful; otherwise - 0.

virtual int addPlugin(const char * name) const =0

Adds a plugin in engine runtime by its name.

Arguments

const char * name - Plugin name.

Return value

1 if the plugin was added successfully; otherwise - 0.

virtual int addPlugin(Plugin * plugin) const =0

Adds a plugin in engine runtime by using a pointer to this plugin.

Arguments

Plugin * plugin - Plugin pointer.

Return value

1 if the plugin was added successfully; otherwise - 0.

int addSystemLogic(SystemLogic * logic)

Adds an SystemLogic instance to the engine runtime.

Arguments

SystemLogic * logic - SystemLogic instance.

Return value

1 if the operation was successful; otherwise - 0.

int addWorldLogic(WorldLogic * logic)

Adds an WorldLogic instance to the engine runtime.

Arguments

WorldLogic * logic - WorldLogic instance.

Return value

1 if the operation was successful; otherwise - 0.

void dialogError(const char * title)

Displays a dialog window with errors set using the error() function.

Arguments

const char * title - Title to be displayed in the error window.

void dialogError(const char * title)

Arguments

const char * title

void dialogMessage(const char * title)

Displays a dialog window with the last message set using the message() function.

Arguments

const char * title - Title to be displayed in the message window.

void dialogMessage(const char * title)

Arguments

const char * title

virtual int findPlugin(const char * name) const =0

Searches the index of the loaded plugin by its name.

Arguments

const char * name - Name of the plugin.

Return value

Index of the plugin.

static Engine * init(int version, int argc, char ** argv, const char * project = 0, const char * password = 0)

Initializes a new engine instance.

Arguments

int version - Engine version number (UNIGINE_VERSION).
int argc - Number of command line arguments.
char ** argv - Array of command line arguments values.
const char * project - Project name. If this parameter is set, it forces the engine to store rewritable data (such as log file, cache files, config files) in user profile rather than in a directory with binaries. Notice that only the project name is required to pass in for this parameter, not the full path to the project. If there is no need to change location of such files, pass the 0 value.
const char * password - Password for the filesystem archives. Notice that the specified password must be the same as for the project archive (if it exists). Pass the 0 value if you do not need to set a password.

Return value

Pointer to the new engine instance.

static Engine * init(int version, int argc, wchar_t ** argv, const char * project = 0, const char * password = 0)

Initializes a new engine instance.

Arguments

int version - Engine version number (UNIGINE_VERSION).
int argc - Number of command line arguments.
wchar_t ** argv - Array of values of command line arguments (a wide-character string).
const char * project - Project name. If this parameter is set, it forces the engine to store rewritable data (such as log file, cache files, config files) in user profile rather than in a directory with binaries. Notice that only the project name is required to pass in for this parameter, not the full path to the project. If there is no need to change location of such files, pass the 0 value.
const char * password - Password for the filesystem archives. Notice that the specified password must be the same as for the project archive (if it exists). Pass the 0 value if you do not need to set a password.

Return value

Pointer to the new engine instance.

static Engine * init(int version, App * app, int argc, char ** argv, const char * project = 0, const char * password = 0)

Initializes a new engine instance to be used with an external graphics application.

Arguments

int version - Version number (UNIGINE_VERSION).
App * app - Pointer to the graphics App class. Pass the 0 value to ignore this parameter.
int argc - Number of command line arguments.
char ** argv - Array of values of command line arguments.
const char * project - Project name. If this parameter is set, it forces the engine to store rewritable data (such as log file, cache files, config files) in user profile rather than in a directory with binaries. Notice that only the project name is required to pass in for this parameter, not the full path to the project. If there is no need to change location of such files, pass the 0 value.
const char * password - Password for the filesystem archives. Notice that the specified password must be the same as for the project archive (if it exists). Pass the 0 value if you do not need to set a password.

Return value

Pointer to the new engine instance.

static Engine * init(int version, App * app, int argc, wchar_t ** argv, const char * project = 0, const char * password = 0)

Initializes a new engine instance to be used with an external graphics application.

Arguments

int version - Version number (UNIGINE_VERSION).
App * app - Pointer to the graphics App class. Pass the 0 value to ignore this parameter.
int argc - Number of command line arguments.
wchar_t ** argv - Array of values of command line arguments (a wide-character string).
const char * project - Project name. If this parameter is set, it forces the engine to store rewritable data (such as log file, cache files, config files) in user profile rather than in a directory with binaries. Notice that only the project name is required to pass in for this parameter, not the full path to the project. If there is no need to change location of such files, pass the 0 value.
const char * password - Password for the filesystem archives. Notice that the specified password must be the same as for the project archive (if it exists). Pass the 0 value if you do not need to set a password.

Return value

Pointer to the new engine instance.

static Engine * init(int version, App * app, const char * app_path, const char * home_path, int argc, char ** argv, const char * project = 0, const char * password = 0)

Initializes a new engine instance to be used with an external graphics application, which is stored at the specified path.

Arguments

int version - Version number (UNIGINE_VERSION).
App * app - Pointer to the graphics App class. Pass the 0 value to ignore this parameter.
const char * app_path - Path to a directory where binary executable file is stored. Pass the 0 value to ignore this parameter.
const char * home_path - Path to the user's home directory.
int argc - Number of command line arguments.
char ** argv - Array of values of command line arguments.
const char * project - Project name. If this parameter is set, it forces the engine to store rewritable data (such as log file, cache files, config files) in user profile rather than in a directory with binaries. Notice that only the project name is required to pass in for this parameter, not the full path to the project. If there is no need to change location of such files, pass the 0 value.
const char * password - Password for the filesystem archives. Notice that the specified password must be the same as for the project archive (if it exists). Pass the 0 value if you do not need to set a password. Notice that the specified password must be the same as for the project archive (if it exists). Pass the 0 value if you do not need to set a password.

Return value

Pointer to the new engine instance.

static Engine * init(int version, App * app, const char * app_path, const char * home_path, int argc, wchar_t ** argv, const char * project = 0, const char * password = 0)

Initializes a new engine instance to be used with an external graphics application, which is stored at the specified path.

Arguments

int version - Version number (UNIGINE_VERSION).
App * app - Pointer to the graphics App class. Pass the 0 value to ignore this parameter.
const char * app_path - Path to a directory where binary executable file is stored. Pass the 0 value to ignore this parameter.
const char * home_path - Path to the user's home directory.
int argc - Number of command line arguments.
wchar_t ** argv - Array of values of command line arguments (a wide-character string).
const char * project - Project name. If this parameter is set, it forces the engine to store rewritable data (such as log file, cache files, config files) in user profile rather than in a directory with binaries. Notice that only the project name is required to pass in for this parameter, not the full path to the project. If there is no need to change location of such files, pass the 0 value.
const char * password - Password for the filesystem archives. Notice that the specified password must be the same as for the project archive (if it exists). Pass the 0 value if you do not need to set a password. Notice that the specified password must be the same as for the project archive (if it exists). Pass the 0 value if you do not need to set a password.

Return value

Pointer to the new engine instance.

void main(SystemLogic * system, WorldLogic * world, EditorLogic * editor)

Engine main loop. Replaces the following commands:

Source code (C++)

while (isDone() == 0) { 
	update();  
	render(); 
	swap(); 
	}

Arguments

SystemLogic * system - A SystemLogic instance.
WorldLogic * world - A WorldLogic instance.
EditorLogic * editor - An EditorLogic instance.

int removeEditorLogic(EditorLogic * logic)

Removes an EditorLogic instance from engine runtime.

Arguments

EditorLogic * logic - An EditorLogic instance.

Return value

1 if the operation was successful; otherwise - 0.

virtual int removePlugin(Plugin * plugin) const =0

Removes a plugin by using a pointer to this plugin.

Arguments

Plugin * plugin - Plugin pointer to remove.

Return value

1 if the operation was successful; otherwise - 0.

int removeSystemLogic(SystemLogic * logic)

Removes a SystemLogic instance from engine runtime.

Arguments

SystemLogic * logic - A SystemLogic instance.

Return value

1 if the operation was successful; otherwise - 0.

int removeWorldLogic(WorldLogic * logic)

Removes a WorldLogic instance from engine runtime.

Arguments

WorldLogic * logic - A WorldLogic instance.

Return value

1 if the operation was successful; otherwise - 0.

virtual void render() const =0

Engine rendering function. This function must be called every frame.

virtual const Variable & runEditorFunction(const Variable & name) const =0

Runs the editor script function by its name. The target function can receive up to 8 arguments.

Arguments

const Variable & name - Name of the editor script function.

Return value

Editor script function return value.

virtual const Variable & runEditorFunction(const Variable & name, const Variable * args, int num_args) const =0

Runs the editor script function by its name.

Arguments

const Variable & name - Name of the editor script function.
const Variable * args - Pointer to editor script function arguments.
int num_args - Number of editor script function arguments.

Return value

Editor script function return value.

const Variable & runEditorFunction(const Variable & name, const Variable & a0, const Variable & a1, const Variable & a2, const Variable & a3, const Variable & a4, const Variable & a5)

Runs the editor script function by its name. The target function must receive 6 arguments.

Arguments

const Variable & name - Name of the editor script function.
const Variable & a0 - First argument.
const Variable & a1 - Second argument.
const Variable & a2 - Third argument.
const Variable & a3 - Fourth argument.
const Variable & a4 - Fifth argument.
const Variable & a5 - Sixth argument.

Return value

Editor script function return value.

const Variable & runEditorFunction(const Variable & name, const Variable & a0, const Variable & a1, const Variable & a2, const Variable & a3, const Variable & a4, const Variable & a5, const Variable & a6, const Variable & a7)

Runs the editor script function by its name. The target function must receive 8 arguments.

Arguments

const Variable & name - Name of the editor script function.
const Variable & a0 - First argument.
const Variable & a1 - Second argument.
const Variable & a2 - Third argument.
const Variable & a3 - Fourth argument.
const Variable & a4 - Fifth argument.
const Variable & a5 - Sixth argument.
const Variable & a6 - Seventh argument.
const Variable & a7 - Eighth argument.

Return value

Editor script function return value.

const Variable & runEditorFunction(const Variable & name, const Variable & a0, const Variable & a1, const Variable & a2, const Variable & a3, const Variable & a4, const Variable & a5, const Variable & a6)

Runs the editor script function by its name. The target function must receive 7 arguments.

Arguments

const Variable & name - Name of the editor script function.
const Variable & a0 - First argument.
const Variable & a1 - Second argument.
const Variable & a2 - Third argument.
const Variable & a3 - Fourth argument.
const Variable & a4 - Fifth argument.
const Variable & a5 - Sixth argument.
const Variable & a6 - Seventh argument.

Return value

Editor script function return value.

const Variable & runEditorFunction(const Variable & name, const Variable & a0, const Variable & a1, const Variable & a2)

Runs the editor script function by its name. The target function must receive 3 arguments.

Arguments

const Variable & name - Name of the editor script function.
const Variable & a0 - First argument.
const Variable & a1 - Second argument.
const Variable & a2 - Third argument.

Return value

Editor script function return value.

const Variable & runEditorFunction(const Variable & name, const Variable & a0, const Variable & a1, const Variable & a2, const Variable & a3, const Variable & a4)

Runs the editor script function by its name. The target function must receive 5 arguments.

Arguments

const Variable & name - Name of the editor script function.
const Variable & a0 - First argument.
const Variable & a1 - Second argument.
const Variable & a2 - Third argument.
const Variable & a3 - Fourth argument.
const Variable & a4 - Fifth argument.

Return value

Editor script function return value.

const Variable & runEditorFunction(const Variable & name, const Variable & a0)

Runs the editor script function by its name. The target function must receive 1 argument.

Arguments

const Variable & name - Name of the editor script function.
const Variable & a0 - First argument.

Return value

Editor script function return value.

const Variable & runEditorFunction(const Variable & name, const Variable & a0, const Variable & a1, const Variable & a2, const Variable & a3)

Runs the editor script function by its name. The target function must receive 4 arguments.

Arguments

const Variable & name - Name of the editor script function.
const Variable & a0 - First argument.
const Variable & a1 - Second argument.
const Variable & a2 - Third argument.
const Variable & a3 - Fourth argument.

Return value

Editor script function return value.

const Variable & runEditorFunction(const Variable & name, const Variable & a0, const Variable & a1)

Runs the editor script function by its name. The target function must receive 2 arguments.

Arguments

const Variable & name - Name of the editor script function.
const Variable & a0 - First argument.
const Variable & a1 - Second argument.

Return value

Editor script function return value.

virtual const Variable & runSystemFunction(const Variable & name) const =0

Runs the system script function by its name. The target function can receive up to 8 arguments.