UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
编程
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
应用程序接口
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

Building a Project

Before your project can be distributed to users, it must be properly built. Building a project ensures that all content and code, including all necessary libraries, is up to date, in the proper format, and placed to a proper location to run on the desired target platform.

To build your project via UnigineEditor, perform the following:

  1. In UnigineEditor, select File -> Create Build. The Create Build window will open.

  2. Specify the required settings and click Create Build.

For building C# Component System projects, Component System should be initialized successfully.

Notice
If a project fails to build, check the UnigineEditor console for more details.

Build Content#

By default, the build includes the following:

  • Binaries
  • core.ung and scripts.ung
  • *.cache files
  • Plugins added via SDK browser
    Notice
    If plugins are added via code, they should be added to the build as user files.
  • Assets and/or their runtimes from the data/ folder and from all mount points are added to the build in accordance with the specified Force-Include List
    Notice
    Runtimes are copied together with their *.meta (json) files.
  • Texture cache from the data/.cache_textures folder
  • guids.db file stored in the data/ folder
  • Sound library
  • Launcher file or files
  • Main executable files
  • Files added by user

Build Settings#

Common Settings#

Build Type
(config)
Type of the build that defines which binaries are copied:
  • Release — optimized binary without any additional debug info.
  • For the Development build, two binaries are copied:
    • development binary — optimized binary with Microprofile enabled
    • debug binary — unoptimized binary with debug information enabled
Notice
If the project's SDK is unavailable, this option is unavailable, as well. In this case, Build Type is defined by the build of UNIGINE Engine selected at the project creation.
Project Name
(name)
Name of the output executable or .bat/.sh file. This name shall also be displayed as the Launcher's title and a title of the application window as well.
Build Folder
(path)
Path to the output folder where the build is going to be stored
Warning
  • You shouldn't create this folder inside your project folder, as it may significantly increase its size.
  • Build folder should be empty, otherwise, its contents will be deleted!
Default World
(world)
The world that is loaded when the application is started. If no world is selected, the User shall be responsible for loading worlds via code, otherwise, a black screen will be displayed when running the application.
Precompile Shaders
(precompile)
If enabled, generates shaders for the current Video API.
Shader cache increases performance and reduces spikes and freezes in the release application, which makes it very important for the release build. If the shaders have already been precompiled, selecting this box won't affect the build time.
Notice

Launcher Default Settings#

These settings are used as default (pre-selected) launcher settings. The launcher for the Development build displays more settings than for the Release build.

GUI-based launcher for the Development Build

Below are the settings used by the tool to generate a launcher for your application.

Type
(launcher)
Type of the launcher:
  • GUI-based — executable file with the name <project_name> is created. Running this file opens the GUI with the default launcher settings. These settings are stored in the <project_name>.lconfig JSON file.
  • <project_name>.bat (or .sh for Linux) file is created that contains the default launcher settings.
    In case of the Development build with the project's SDK available, two files are created: <project_name>_development.bat (or .sh for Linux) and <project_name>_debug.bat (or .sh for Linux).
Banner Image
(banner)
The image to be displayed in the launcher. Available for GUI-based launcher only.
To assign an image, drag it from the Asset Browser.
Notice
Only PNG images can be used.
Use OpenVR Check this box, if your project is intended for OpenVR. This will enable OpenVR mode selection in the application launcher.
Use Oculus Check this box, if your project is intended for Oculus. This will enable Oculus mode selection in the application launcher.
Use Varjo Check this box, if your project is intended for Varjo. This will enable Varjo mode selection in the application launcher.
Notice
Necessary VR modes (three options above) for the console mode are specified in the configuration file as follows (list the ones you need):
Source code
"vrmodes": [
    "OpenVR",
    "Oculus",
    "Varjo"
]
Resolution
(selected_res)
The resolution of the application screen. Multiple resolutions can be selected. The resolution that is clicked upon is set as default.
Notice
Multiple resolutions for the console mode are specified in the configuration file via the resolutions parameter (list the ones you need):
Source code
"resolutions": [
    {
        "d": 9,
        "n": 16,
           "w": 960
    },
    {
        "d": 9,
        "n": 16,
        "w": 1024
    }
]
Fullscreen
(fullscreen)
If enabled, the application is run in the Fullscreen mode.
Binary
(binary)
Type of the binary to be selected by default in the launcher, if the selected build type is Development build:
  • Development — optimized binary with Microprofile enabled for performance check
  • Debug — unoptimized binary with debug information
This setting is available for the GUI-based launcher only. The .bat/.sh launcher will create scripts to run the correpsonding executable files.
Video Debug
(vdebug)
Toggling the debug context of the Graphics API. Available for the Development build type only.
Release App / Development App / Debug App
(main_release / main_dev / main_debug)

Path to the corresponding binary to be run. The binary depends on the type of build.

Notice
This option is for the projects that do not use C# Component System.

Note that the binary is defined automatically, if it remains located in the bin/ folder. If it has been moved elsewhere or rearranged in some other way, the path to the file is to be set manually.

Arguments
(args)
Additional start-up command-line options.

UnigineEditor creates the <project_name>.lconfig file that Launcher uses to run the app. If a user changes any parameters and runs the app, the changes are saved in <project_name>.lconfig. Closing Launcher without running it discards any changes.

Delete Unused Assets#

This section enables you to specify assets to be included in your final build. Here is how it looks:

The Build tool scans all assets of the types specified as wildcards (including location) in the Force-Include list (*.world, *.cs, *.fbx, *.prop, etc.), automatically resolving all dependencies (an FBX asset shall be checked for all meshes, meshes shall be checked for materials assigned to their surfaces and so on...). Thus, all assets in your project that are used by the assets of the specified types are collected and included in the final build.

You can add more asset types to the list or remove existing ones by simply right-clicking on the desired line (a new line shall be inserted after the one you clicked on). You can also click Restore Defaults to reset the list to its initial state.

For each type of assets in the list you can specify whether to include runtime or source file. But be careful, as checking only Runtime for .png textures will result in ignoring the ones with the Unchanged option enabled (i.e. having no runtime), they simply won't be included. To check you list against such cases click Check, the following Check List window will open:

In this window all files found in the process of scanning are listed. The ones in white are ok, but the ones in red require your attention, for example, you may mistakenly choose to include source for an asset that has a runtime. So, be sure to check all red ones. The following options are possible:

  • [Source and Runtime] - both boxes are checked (both source and runtime files shall be added).
  • [Source] - when Use Source is checked and the asset has no runtime (only the source shall be added).
  • [Source and it has a Runtime] (shown in red) - when Use Source is checked, but the asset has a runtime (only the source shall be added).
  • [Runtime] - when Use Runtime is checked, and the asset has a runtime(only the runtime shall be added).
  • [No Runtime] (shown in red) - when Use Runtime is checked, but the asset has no runtime (nothing shall be added).
Notice
Force-Include List for the console mode is specified in the configuration file as a set of wildcards follows:
Source code
"delete_unused": [
    {
        "pattern": "",
        "source": "",
        "primary": ""
    }
]

Copy User Files#

User files are added to the build folder by filling in the table with two columns:

  • From (Absolute Path) — an absolute path to a source file or folder. Folders can be specified using wildcards.
  • To (Relative Path) — path to the destination folder that is relative of the Build Folder. It can be a folder name where the file or files are copied to, or a folder and a file name, i.e. the copied file can be renamed as well.

There are some rules for adding user files to the build folder:

From (Absolute Path) To (Relative Path) Comment
C:\test\<folder_name> <another_folder_name>, or
\<another_folder_name>, or
\<another_folder_name>\
All files and folders inside <folder_name> will be recursively copied. Thus, it doesn't matter if you use slashes or not.
C:\Pictures\screenshot_alb.png \folder_with_pictures\, or
folder_with_pictures
One file with the name indicated in the From column will be copied into <output_folder>\folder_with_pictures\
C:\Pictures\screenshot_alb.png \folder_with_pictures\123.png

But: 123.jpg (or 123.png)
The file will be renamed.

However, if the target file extension is written incorrectly (differs from the actual file extension), a new folder with such name will be created instead, i.e. the resulting path of the example destination files will be:
<output_folder>\<folder_with_pictures>\<123.jpg>\screenshot_alb.png
Notice
User files for the console mode are specified in the configuration file as follows:
Source code
"rules": [
    {
        "from": "",
        "to": ""
    }
]

When files with the same name are copied to one folder, their content is checked. If it's the same file, it would be copied once without any warning. However, if names are the same but the files are different, the dialog window will pop up to request which file should be copied.

Warning
If a user file has the same name as a engine-related file, the engine-related file is copied to the Build folder with the corresponding warning in the console. The user file should be renamed manually.

Wildcards can also be used to define the rules for copying user files.

From (Absolute Path) To (Relative Path) Comment
C:\test\<folder_name>\*.tga <tga_pictures> All files with the indicated extension from the selected folder will be copied to the specified folder.
C:\test\<folder_name>\ab*z.png <another_folder_name> All files with the name starting from ab and ending with z.png from the selected folder will be copied to the specified folder.
C:\test\<folder_name>\nn* <another_folder_name> All files with the name starting from nn from the selected folder will be copied to the specified folder.
C:\*.ung ///\\\/one\\\\\\////two\\/// Slashes work differently for Windows and Linux.

Windows:
slashes are transformed to backslashes, all backslashes are merged into one.
<output_folder>\one\two\

Linux:
all slashes are merged into one, but backslashes are not transformed to slashes.
<output_folder>/\\\/one\\\\\\/two\\/
Notice
On Linux, do not use the backslash symbol for defining paths.

Encryption#

Project files can be encrypted using the UNIGINE-native UNG archive format. UNG files are transparent to the engine, and their content is handled as not packed. To save your files in UNG format, use the Archiver tool.

Notice
  • Data streaming doesn't work for UNG/ZIP contents.
  • The maximum size of the archive is 2 GB.

Console Build#

To simplify continuous integration (CI) and batch processing the Build Tool supports console-based management. In the console mode all build options (see descriptions above) can be configured via the dedicated file. By default the file has the following path: <data_path>.editor2/.assemblytool. Default values of configuration parameters are taken from this file (see the example below), but you can change them at your disposal. There are no specific requirements to the name and extension of this file, but it should be in JSON format.

Config File Example (.assemblytool)

Source code
{
    "binary": "Debug",
    "config": "Development",
    "fullscreen": false,
    "launcher": "BinaryFile",
    "precision": "Float",
    "precompile": false,
    "resolutions": [
        {
            "d": 9,
            "n": 16,
            "w": 960
        },
        {
            "d": 9,
            "n": 16,
            "w": 1024
        },
        {
            "d": 9,
            "n": 16,
            "w": 1280
        },
        {
            "d": 9,
            "n": 16,
            "w": 1366
        },
        {
            "d": 9,
            "n": 16,
            "w": 1600
        },
        {
            "d": 9,
            "n": 16,
            "w": 1920
        },
        {
            "d": 9,
            "n": 16,
            "w": 2560
        },
        {
            "d": 9,
            "n": 16,
            "w": 3840
        },
        {
            "d": 10,
            "n": 16,
            "w": 960
        },
        {
            "d": 10,
            "n": 16,
            "w": 1024
        },
        {
            "d": 10,
            "n": 16,
            "w": 1280
        },
        {
            "d": 10,
            "n": 16,
            "w": 1440
        },
        {
            "d": 10,
            "n": 16,
            "w": 1680
        },
        {
            "d": 10,
            "n": 16,
            "w": 1920
        },
        {
            "d": 10,
            "n": 16,
            "w": 2560
        },
        {
            "d": 3,
            "n": 4,
            "w": 800
        },
        {
            "d": 3,
            "n": 4,
            "w": 1024
        },
        {
            "d": 3,
            "n": 4,
            "w": 1280
        },
        {
            "d": 3,
            "n": 4,
            "w": 1600
        },
        {
            "d": 3,
            "n": 4,
            "w": 2048
        },
        {
            "d": 4,
            "n": 5,
            "w": 2560
        }
    ],
    "rules": [
        {
            "from": "",
            "to": ""
        }
    ],
    "selected_res": 0,
    "vapi": "Auto",
    "vdebug": "Disabled",
    "vrmodes": [
        "OpenVR",
        "Oculus",
        "Varjo"
    ]
}

The syntax of running the tool with command-line options is as follows: the full name of the binary executable (64-bit development or release version) followed by necessary CLI-options:

Shell commands
BuildTool_x64* --bt_option1 "argument" --bt_option2 "argument" ...
Notice
Values of CLI-options below override the values stored in the build configuration file.

The list of available options includes the following:

Name Description. Arguments.
-?, -h, --help Displays the help information on all commands available.
--bt_output_directory Path to the output folder where the build is going to be stored.
Warning
  • This folder shouldn't be inside your project's folder, as it may significantly increase its size.
  • Build folder should be empty, otherwise, the Console Build tool shall not start.
The argument can be passed as follows:
  • ../RELATIVE_PATH/
  • ABSOLUTE_PATH
--bt_release_main_file Path to the Release binary to run. The argument can be passed as follows:
  • ../RELATIVE_PATH/
  • ABSOLUTE_PATH
--bt_development_main_file Path to the Development binary to run. The argument can be passed as follows:
  • ../RELATIVE_PATH/
  • ABSOLUTE_PATH
--bt_debug_main_file Path to the Debug binary to run. The argument can be passed as follows:
  • ../RELATIVE_PATH/
  • ABSOLUTE_PATH
--bt_user_options_file Path to the user configuration file (by default: <data_path>/.editor2/.assemblytool). In case the file is missing the Console Build tool will shut down with an error. The argument can be passed as follows:
  • ../RELATIVE_PATH/
  • ABSOLUTE_PATH
--bt_configuration Type of the build that defines which binaries are to be copied (see below):
  • release — optimized binary without any additional debug info.
  • For the development build, two binaries are copied:
    • development — optimized binary with Microprofile enabled
    • debug — unoptimized binary with debug information available
  • release
  • development
--bt_binary Type of the binaries.
  • release
  • development
  • debug
Notice
In case -video_app null is specified, shaders compilation is disabled with the corresponding message printed to the Console (no message shall appear in case shaders compilation was disabled via the settings.
Last update: 2020-10-10