This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Landscape Tool
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Objects
Sound Objects
Pathfinding Objects
Players
Programming
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Content Creation
Content Optimization
Materials
Art Samples
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Application Logic System

In UNIGINE, you can implement application logic in the following ways:

  • in C++ or C#
  • combining C++ or C# with UnigineScript — in this case, the execution sequence for each implemented method, corresponding to a certain stage of the application's life cycle (i.e., init(), update(), postUpdate(), etc.), is the following:
    1. UnigineScript function
    2. C++/C# method

The application logic has three basic components that have different lifetimes:

  • World logic. It takes effect only when the world is loaded. For projects that use UnigineScript only, the logic is written to the world script (each particular world can have its own script). A default script is created as a *.usc file named after your project at the project creation. Such files are stored in the data/ folder.
    For applications that use C++ AppWorldLogic.cpp is created, and for C# applications — AppWorldLogic.cs. These files are stored in the <your_project_folder>/source/ folder and stay loaded during the whole engine runtime. They have implemented methods to put your logic code inside. WorldLogic in C++/C# (unlike UnigineScript) works with every loaded world, so you can't assign a specific WorldLogic to a certain world.
  • System logic. It exists during the application life cycle. The logic is implemented in the default system script named unigine.usc and stored in the data/ folder of your project as the core.ung archive. You can put your logic in this file if you use UnigineScript only. You can also inherit SystemLogic class and implement your logic in C++ or C#.
  • Editor logic. This component is to be used in case you need to implement your own Editor. It has more implemented methods providing you with clear understanding of the current Engine events (a node has been created, a property has been deleted, a material has been changed, etc.). You can inherit EditorLogic class and implement your logic in C++ or C#. Or you can create a UnigineScript file and add it using the -editor_script path_to_file.usc command-line argument.
    Notice
    When you create a new C++ / C# project, it has already inherited World Logic class (AppWorldLogic), System Logic class (AppSystemLogic), and Editor Logic class (AppEditorLogic) with implemented methods to put your logic code inside.

If a project uses UnigineScript only, its execution sequence is strictly defined in scripts and cannot be modified.
If a project is created using C++ or C#, a programmer can control the execution sequence by manually calling Engine's init(), update(), postUpdate(), swap(), and shutdown() methods when required and add logic anywhere between these blocks, as shown in the C++ sample <UnigineSDK>/source/samples/Api/Render/Screenshot/Screenshot.cpp.

World Logic#

If the World Logic is implemented in UnigineScript, it is loaded or unloaded at the same time as the world itself is loaded or unloaded. The World Logic implemented in C++/C# stays loaded during the whole UNIGINE engine runtime. The World Logic may use the following methods, which are available for both UnigineScript and C++/C#:

Source code (C++)
#include "AppWorldLogic.h"

AppWorldLogic::AppWorldLogic() {

}

AppWorldLogic::~AppWorldLogic() {

}

int AppWorldLogic::init() {

	return 1;
}

int AppWorldLogic::update() {

	return 1;
}

int AppWorldLogic::postUpdate() {

	return 1;
}

int AppWorldLogic::updatePhysics() {

	return 1;
}

int AppWorldLogic::shutdown() {

	return 1;
}

int AppWorldLogic::save(const Unigine::StreamPtr &stream) {
	UNIGINE_UNUSED(stream);
	return 1;
}

int AppWorldLogic::restore(const Unigine::StreamPtr &stream) {
	UNIGINE_UNUSED(stream);
	return 1;
}

init() function#

Engine calls this function on the world initialization. The code inside should initialize resources for your world scene during the world start.

updateAsyncThread() function#

In the updateAsyncThread() function, you can specify all logic functions you want to be called every frame independently of the rendering thread. This function does not block the Main Thread.

Notice
This function does not have protection locks, so it is not recommended to modify other components inside this function, unless you are absolutely sure, that these components won't be modified or removed elsewhere.

updateSyncThread() function#

In the updateSyncThread() function, you can specify any parallel logic functions to be executed before the Update(). This function blocks the Main Thread until all calls are completed.

Notice
This function should be used to call only the API methods related to the current node: the node itself, its materials and properties.

update() function#

In the update() function, you can specify all logic-related functions you want to be called every frame while your application is executed. Engine calls this function before updating each render frame.

postUpdate() function#

This is an additional function used to correct behavior after the state of the node has been updated. Engine calls this function before rendering each render frame.

updatePhysics() function#

This function is used to control physics in your application. Engine calls this function before updating each physics frame.

swap() function#

This function is designed to operate with the results of the updateAsyncThread() function — all other methods (threads) have already been performed and are idle. After this function, only two actions occur:

  • All objects that are queued for deletion are deleted.
  • Profiler is updated.

shutdown() function#

The function is called when the world is unloaded, and is used to delete resources that were created during world script execution to avoid memory leaks. Engine calls this function on the world shutdown. Inside this function, you should delete all pointers to created objects.

save() and restore() functions#

The save() function saves custom user data to a file. Engine calls this function when the world is saving its state. To restore data from a file, you need to use the restore() function. Engine calls this function when the world is restoring its state.

Notice
The basic recommended workflow is to have a single AppWorldLogic class to process all worlds in your project. However, you can split world-specific code between separate classes inherited from WorldLogic.

System Logic#

The System Logic stays loaded during the whole UNIGINE Engine runtime. It may use the following methods, which are available for both UnigineScript and C++/C#:

Source code (C++)
#include "AppSystemLogic.h"

AppSystemLogic::AppSystemLogic() {

}

AppSystemLogic::~AppSystemLogic() {

}

int AppSystemLogic::init() {
	return 1;
}

int AppSystemLogic::update() {
	return 1;
}

int AppSystemLogic::postUpdate() {
	return 1;
}

int AppSystemLogic::shutdown() {
	return 1;
}

int AppSystemLogic::destroyRenderResources() {
	return 1;
}

init() function#

Engine calls this function on initialization. Here you should put the code that you want to be executed during the system script initialization.

update() function#

Engine calls this function before updating each render frame. Here you should put the code that you want to be updated each frame. The logic should be related to the engine job. These are the examples of operations that are performed by a default system script:

  • The system script handles the mouse. It controls whether the mouse is grabbed when clicked (by default), the mouse cursor disappears when not moved for some time, or not handled by the system.
  • Main menu logic is updated.
  • Other system-related user input is handled.

postUpdate() function#

Engine calls this function before rendering each render frame. It can access the updated data on node states and correct the behavior accordingly in the same frame.

shutdown() function#

Engine calls this function on application shutdown. You should release all the resources that you created for system script.

destroyRenderResources() function#

Engine calls this function when the video mode is changed or application is restarted (i.e. video_restart is called). It is used to reinitialize the graphics context if application directly uses any OpenGL or DirectX commands).

Editor Logic#

This component is to be used in case you need to implement your own Editor. It has more implemented methods providing you with clear understanding of the current Engine events (a node has been created, a property has been deleted, a material has been changed, etc.).

The Editor Logic may use the following methods, which are available for both UnigineScript and C++/C#:

Source code (C++)
#include "AppEditorLogic.h"

AppEditorLogic::AppEditorLogic() {
	
}

AppEditorLogic::~AppEditorLogic() {
	
}

int AppEditorLogic::init() {
	return 1;
}

int AppEditorLogic::update() {
	return 1;
}

int AppEditorLogic::postUpdate() {
	return 1;
}

int AppEditorLogic::shutdown() {
	return 1;
}

int AppEditorLogic::destroyRenderResources() {
	return 1;
}

int AppEditorLogic::worldInit() {
	return 1;
}

int AppEditorLogic::worldShutdown() {
	return 1;
}

int AppEditorLogic::worldSave() {
	return 1;
}

init() function#

The engine calls this function on the world initialization. It initializes all belongings of UnigineEditor.

update() function#

If the editor is loaded, the engine calls this function before updating each render frame. Here you can put some editor-related logic that should be updated each frame.

postUpdate() function#

If the editor is loaded, the engine calls this function before rendering each render frame.

shutdown() function#

The engine calls this function on editor shutdown. Engine applications may continue running.

destroyRenderResources() function#

The engine calls this function when the video mode is changed or the application is restarted (i.e. video_restart is called). The function is used to reinitialize the graphics context (if the application directly uses any OpenGL or DirectX commands)

worldInit() function#

If the editor is loaded, the Engine calls this function on the world initialization. Use this function, if you want to initialize something before the World Logic starts its init() function.

worldShutdown() function#

If the editor is loaded, the engine calls this function on the world shutdown.

worldSave() function#

If the editor is loaded, the Engine calls this function on saving the world.

Last update: 2021-07-16
Build: ()