Engine Initialization

The engine initialization starts when the main executable application (64-bit version of the .exe file, debug or release one) loads the corresponding UNIGINE library (.dll or .so). From this point on, the following steps are performed:

1. The UNIGINE memory allocator is initialized for faster and more optimal allocations compared to the default system allocator. In the engine code, it is set via the USE_MEMORY directive.

2. Command-line options are parsed, namely: options that set paths to the data folder, plugin directories, log and configuration files, and also the project name.

   Notice

   Command-line values override the default values and values specified in the configuration files.
3. Four (4) threads are created: a sound, a world, a render, and a file system thread.

4. A path to the folder where all application data will be saved by default:

   • If you pass a project name via the command line or on engine initialization, all data (such as log files, cache, and configuration files) are stored in the user's home directory as follows:

     • On Windows, in the C:/Users/<username>/<project_name>/ folder
     • On Linux, in the /home/<username>/.<project_name>/ folder
   • Otherwise, data is stored in the application folder (<PROJECT_DIRECTORY>/bin/ with the binary executable file).
5. A log file is created. If not specified in the command-line options, the default log file is placed in the application directory under the name log.txt.

6. Remaining command-line options are parsed (the ones that haven't been parsed previously). These options specify basic video settings, such as a graphics API to be used for rendering (DirectX or Vulkan; also you can disable the graphics API), size of the application window, and so on.

   You can also pass any external #define directives and console variables via the command line.

   Notice

   Command-line values override the default values and values specified in the configuration files.
7. A path to the project *.cache files is set. Usually cache files include compiled shaders, system and Editor Logic.

8. External plugin libraries specified in the -extern_plugin command line option and plugin libraries stored in the plugin directories specified in the -plugin_path option are loaded.

   Notice

   A custom plugin library can be loaded at any moment of UNIGINE run time.
9. The File System is initialized. If project files are packed into UNG or ZIP archives protected by a password, the engine checks if the password coincides with the password set for the binary file (if any) and loads these archives.
10. The dedicated asset management subsystem of the Engine's file system is initialized and performs scanning for all run-time files.
11. Render and sound managers that will automatically organize and handle rendering and sounds are initialized.
12. The Boot screen is shown based on the default.boot configuration file.
13. If the shaders_preload console variable is enabled, shaders for all loaded materials in the application are compiled and cached.
14. The application window is created based on the specified settings.
15. All engine subsystems (such as visualizer, physics, sound, render, pathfinding subsystems, and so on) are created.
16. Sound and file system threads are run.
17. External definitions passed in the -extern_define command line option are set.
18. The init() functions of all loaded plugins are called.
19. Console commands from the command line are queued for further execution.
20. The Splash screen is shown if it is enabled.

21. The System Logic is loaded and started. Basically, the System Logic performs housekeeping necessary to start and keep the UNIGINE-based application going. It stays loaded during the whole UNIGINE run time.

    The default system script, when initialized, does the following:

    • Loads a localization file.
    • Initializes the main menu.
    • Sets the Loading screen, if necessary. It is better to set the loading screen before loading a world. In this case, displaying a loading screen will give the engine time to load resources and compile shaders. By default, a standard UNIGINE screen is shown.
    Notice

    You can replace the default system script located in the data/core/unigine.usc with a custom one. In this script, you can set your own loading screen for the project, specify custom modules to be loaded, and so on. For large projects, it makes sense to specify the world you want to load right in your system script.

    If you use a custom system script, it performs the logic you implemented.

22. Console commands from the command line that were queued previously are run.

    Notice

    If you want to run console commands from the system script, they are run after the queued console commands.

23. If the preload-related console variables are specified in the Engine start-up configuration file, pso, shaders, and materials are compiled and cached.

    Notice

    However, a shader cache file is large and its loading on engine initialization drops performance.

If the initialization is completed successfully, a non-zero value is returned, and the execution process continues.