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:
- UnigineScript function
- 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.
NoticeWhen 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#:
#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.
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.
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.
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#:
#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#:
#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.