UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and 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
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes

Content Migration

In order to use the updated asset system for project development, you should migrate project's content.

Warning
It is mandatory to migrate the project to UNIGINE 2.7 to avoid issues with migration to future versions.

You can upgrade content of your project to UNIGINE 2.7 in the automatic or manual mode.

Notice
In case of migrating the cross-platform project, perform upgrading on Windows to avoid collisions of file names.

Depending on the version of UNIGINE SDK used to create the project, the migration process differs. Choose your variant to get more details:

  • Projects that use the old Editor workflow, namely:
    • Projects created with UNIGINE SDK prior to version 2.6
    • Projects created with/migrated to UNIGINE SDK 2.6/2.6.1 by using Editor 1 workflow.
  • Projects created with (or migrated to) UNIGINE SDK 2.6/2.6.1 that use the assets workflow.

Automatic Upgrade

Automatic upgrade of the project's content can be performed via UNIGINE SDK Browser.

Notice
By default, the automatic mode is used to upgrade only binary executable files and content stored in the project's data folder. If you have content stored outside the data folder you will have to upgrade it manually.

In the result, the binary executable and configuration files, meshes, terrains, worlds, nodes, splines, materials, properties, tracks, settings files will be upgraded to new formats (if any). The <unigine_project>/migration.log.html log file will be opened in the web browser. However, you can uncheck Migrate Content during automatic upgrading and perform content upgrading manually. In this case, only binary executable files will be upgraded.

Notice
In the automatic mode, contents of each data folder used in the project will be migrated independently.

Manual Upgrade

This mode should be used to upgrade content stored outside the project's data folder. Also you can use it instead of automatic content upgrading.

To upgrade the project's content in the manual mode, do the following:

  1. Put the binary executable <UnigineSDK>/bin/usc_x64.exe (or <UnigineSDK>/bin/usc_x86.exe) to the <UnigineSDK>/utils/upgrade folder that contains the upgrade script.
  2. In the command prompt, run the upgrade.usc with the required options:
    Shell commands
    usc_x64.exe upgrade.usc path/to/the/additional_content_1 path/to/the/additional_content_2 ...
    If you have unchecked Migrate Content during automatic upgrading, add the path to the project's data folder to the list of arguments passed to the upgrade script.
    Notice
    When migrating from UNIGINE 2.6, the path to the data folder must be specified as well.
    For example:
    Shell commands
    usc_x64.exe upgrade.usc <unigine_project>/data path/to/the/additional_content_1 path/to/the/additional_content_2 ...
    Here:
    • path/to/the/additional_content_* - paths to folders with content stored outside the data folder.
As a result, you will get your meshes, terrains, worlds, nodes, splines, materials, properties, tracks, configuration and settings files upgraded (if necessary).

Properties Migration

The main changes:

  • Removed property libraries. Now each property is stored in a separate .prop file. Loading order of properties doesn't matter.
  • There are 2 main types of properties: manual (including base ones) and user. The user property can also be manual.
  • Properties hierarchy is based on GUIDs. However, manual properties store name-based references to parent manual properties.
  • All properties used in the project are loaded on the engine start-up.
Notice
For more details on properties, read the articles in the Properties section.

The upgrade script replaces all property libraries with the homonym folders that store .prop files: each file stores a single property. For example, the my_project.prop library will be replaced with the my_project folder that stores the .prop file for each property from the library.

In case when a missing property was detected, the corresponding warning message will be displayed in the console and the default surface_base property will be assigned. Please note that this may cause a significant performance drop in case of high-poly meshes when physics is enabled. To disable physics(collision/intersection) for objects it is recommended to use the corresponding checkboxes.

XML Changes

The .prop file now stores a single property instead of the library with several properties. So, it has the following differences:

  • The properties element is removed.
  • The states element is removed. All states became parameters. Now to display or hide the parameter, use conditions.
  • The options element is removed. All options became parameters.
  • Added the new group element. So, the group attribute of the parameters became optional.
  • Added the guid, parent_name, manual and version attributes for the property element.
  • The parent attribute now contains a property's GUID.
  • Added the filter attribute for the parameter element.
  • Added file, node, property and material values for the type attribute of the parameter element.
  • Added conditions for parameters of the property.
  • Attributes type="string" and flags="file" of the parameters are replaced with the single attribute type="file".
Notice
For more details, read the Property File Format article.

ObjectTerrain To ObjectTerrainGlobal Migration

As the Global Terrain object evolves and can now be generated using non-georeferenced data, the old Terrain object is considered deprecated and will be removed in future releases. You will not be able to create or edit a Terrain object via the Editor, as it will only be supported as a run-time object.

UNIGINE 2.7 provides Terrain Migration Tool that enables you to migrate your Terrain object or multiple objects into a Global Terrain keeping all its details and visual appearance.

To perform migration, do the following:

  1. Run your project with UnigineEditor.
  2. Select the ObjectTerrain object(s) that you want to migrate.
    Notice
    It is recommended to select all ObjectTerrain objects in the scene: they will be migrated into a single ObjectTerrainGlobal.
  3. Open the Terrain tab in the Parameters window and click Migrate. Enabling the Automatic option will launch migration process in fully-automatic mode.

  4. Selected ObjectTerrain(s) with all details will be converted into a single ObjectTerrainGlobal named migrated_terrain and the landscape project created for it will be opened in the Landscape tool. The old ObjectTerrain(s) will be disabled, but not deleted from the World hierarchy.
  5. Generate the Global Terrain by pressing OK in the Steps window of the Landscape tool that opens. If the Automatic option has been disabled, you will need to click the Generate button in the Landscape tool window first.

    In the result, the migrated_terrain node will be updated. Values of the albedo, roughness, microfiber parameters of the ObjectTerrain material will be copied to the ObjectTerrainGlobal material. If several ObjectTerrains are migrated, the material parameters of the first selected one will be copied.

    Notice
    If the material mask of the ObjectTerrain material has a non-default value, you should specify it manually after migration as it isn't copied to the ObjectTerrainGlobal material.
  6. After making sure everything looks as it should, you can click Remove files to remove old ObjectTerrain(s) from the scene and clean up all associated runtimes. Skip this step, if you are going to repeat migration.

Notice
If you want to repeat migration of the ObjectTerrain(s), remove the ObjectTerrainGlobal generated during previous migration to avoid issues.

The Terrain Migration Tool produces the following files and folders:

  • In the <terrain_name>_migration_project folder, the generated terrain data is stored.
  • In the root of the data folder, texture arrays are stored: they are copied "as is".
  • In the <terrain_name>_terrain_migration_files folder, the data source files (height, albedo, masks sources), height and albedo textures are stored.
    • The coarse textures and the per-surface refined albedo and mask textures are migrated as follows:

      Coarse Textures Migration

      Refined Textures Migration
      As the mask texture is a 2D array texture, each texture of the array is saved in a separate .dds file during migration, namely:
      • The first texture of each texture array is saved to the details_refined_ObjectTerrain_0_0 folder with the corresponding name.
      • The second texture of each texture array is saved to the details_refined_ObjectTerrain_0_1 folder with the corresponding name.
      • Etc.

      For example: the first textures of the 00x00_m.dds and 00x01_m.dds texture arrays will be saved as tile_0_0.dds and tile_0_1.dds textures to the details_refined_ObjectTerrain_0_0 folder; the second textures will be saved to the details_refined_ObjectTerrain_0_1 folder with the same names, an so on.

      In the generated Global Terrain, the produced textures are used as data sources.

    • Height and albedo textures are copied to the <terrain_name>_terrain_migration_files folder "as is".

There are some things you should be aware of:

  • Shading of the ObjectTerrain and ObjectTerrainGlobal objects differs, so, their visual representation may also differ.
  • LOD settings of ObjectTerrainGlobal can be adjusted after migration to increase performance.
  • Some detail materials may require additional adjustment after migration: tiling of detail textures and detail masks blending should be readjusted.
  • To display holes of the migrated ObjectTerrain, disable the Use Insets option on the States tab of the ObjectTerrainGlobal material.

Global Terrain Migration

In UNIGINE 2.7, the format of the files that store the tileset of the ObjectTerrainGlobal has been changed. To upgrade your terrain, run the project with the loaded UnigineEditor: the tileset files will be updated automatically.

Last update: 2018-05-07