This page has been translated automatically.
Видеоуроки
Interface
Essentials
Advanced
Полезные советы
Программирование на C#
Принципы работы
Свойства (properties)
Компонентная Система
Рендер
Физика
Редактор UnigineEditor
Обзор интерфейса
Работа с ассетами
Настройки и предпочтения
Работа с проектами
Настройка параметров узла
Setting Up Materials
Setting Up Properties
Освещение
Landscape Tool
Sandworm (Experimental)
Использование инструментов редактора для конкретных задач
Extending Editor Functionality
Встроенные объекты
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Objects
Sound Objects
Pathfinding Objects
Players
Программирование
Настройка среды разработки
Примеры использования
UnigineScript
C++
C#
Унифицированный язык шейдеров UUSL
File Formats
Rebuilding the Engine Tools
GUI
Двойная точность координат
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
Работа с контентом
Оптимизация контента
Материалы
Art Samples
Tutorials
Внимание! Эта версия документация УСТАРЕЛА, поскольку относится к более ранней версии SDK! Пожалуйста, переключитесь на самую актуальную документацию для последней версии SDK.
Внимание! Эта версия документации описывает устаревшую версию SDK, которая больше не поддерживается! Пожалуйста, обновитесь до последней версии SDK.

Application Logic System

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

  • in pure UnigineScript
  • in C++ or C#
  • combining UnigineScript with C++ or C# — 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. This script is created as a *.usc file named after your project at the project creation. The file is stored in the data/ folder.
    For applications that use C++ AppWorldLogic.cpp is created, and for C# applications — AppWorldLogic.cs. This file is stored in the <your_project_folder>/source/ folder and stays loaded during the whole engine runtime. It has implemented methods to put your logic code inside.
  • 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. It takes effect only when UnigineEditor is loaded. Create a UnigineScript file and add it using the -editor_script path_to_file.usc command-line argument. You can also inherit EditorLogic class and implement your logic in C++ or C#.
    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 (i.e. state_save is called). To restore data from a file, you need to use the restore() function. Engine calls this function when the world is restoring its state (state_restore is called).

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#

The editor logic methods are called only if the editor is loaded. Otherwise, the engine ignores these methods.

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 the world save.

Last update: 24.11.2020
Build: ()