Content Migration

Automatic Upgrade

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

NoticeBy 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 and tracks 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.

Manual Upgrade

This mode should be used to upgrade content stored outside the project's data folder.

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

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.
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 content stored in the project's data folder to the list of arguments passed to the upgrade script. 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, tracks and configuration files upgraded.

Creating Assets for Editor 2

In order to use the new Editor 2 for project development, you should migrate project's content to make it compatible with the new asset system. To perform this, use the create_assets_for_data_path console command. It creates assets for content stored in the data folder, saves them to the <your_project_folder>/assets folder and builds the project. The command is available for Editor 2 only.

NoticeThe command is used for migrating projects created with Unigine SDK prior to version 2.6. It is an experimental feature, so we cannot guarantee correct migration of your project's content.

The command should be run in the Editor 2 console after upgrading the project to the Unigine SDK version 2.6.

Details on creating assets for project's content are described below.

Textures

Assets for textures are created as follows:

The uncompressed folder won't be created in the assets folder: only the assets for the textures stored in this folder will be. For example, if you store the textures in the data/<your_project_name>/textures/uncompressed folder the assets will be stored in the assets/textures folder.
The assets for .dds textures will be created if there is no corresponding uncompressed texture. In this case, some issues may arise, as the type of the texture (albedo, metalness, etc.) is unknown (no .meta file) and the type of compression that should be used for such texture is also unknown.

FBX Files

The assets will be created for the .fbx files instead of the corresponding .mesh files stored in the meshes folder if these .fbx files are stored in the same folder as the meshes one.

For example, if you have <your_project_folder>/meshes/name_1.mesh and <your_project_folder>/meshes/name_2.mesh in the project and there is <your_project_folder>/name.fbx that contains both meshes, the asset will be created for the latter one (assets/name.fbx.asset).

However, issues with objects scale, merging static meshes and combining meshes by LODs may arise.

NoticeIf an .fbx file hasn't been assigned automatically during migration, it should be done manually.

Meshes

The assets for the .mesh files will be created if there are no .fbx files for them.

Materials

The assets will be created for all material files stored in the data folder.

Properties

Editor 2 doesn't allow changing node's properties, so, after migration, the number of .prop files will increase:

If the same property is assigned for several nodes, the following file will be created for each node: <property_name>_<node_name>_merged_postfix.prop.
If the property is assigned to a single node, the following file will be created: <property_name>_<node_name>_postfix.prop.

NoticeKnown issue: file names specified in the property's parameters may be missed during migration, so you will have to specify them manually.

Settings

The .settings files will be migrated as follows:

If the file stores render settings, it will have the .render_settings extension.
If the file stores physics settings, it will have the .physics_settings extension.
If the file stores sound settings, it will have the .sound_settings extension.

And then the assets will be created for the upgraded settings files.

Tracks

The assets will be created for all .track files stored in the data folder.

Worlds

The assets will be created for all .world files stored in the data folder.

Source Code Files

The assets will be created for all source code .h and .cpp files stored in the data folder.

Migrating Materials

The main changes:

Removed material libraries. Now each material is stored in a separate file.
There are 2 main types of materials: base and user. The user material can also be manual.
The base materials are stored in the .basemat files.
The user materials are stored in the .mat files.
Materials hierarchy is based on GUIDs. However, manual materials can store name-based references to parent manual materials.
The base materials cannot be organized in a hierarchy: they can be on its top only.

XML Changes

The .basemat or .mat XML files are now used instead the old .mat material library file.

.basemat

The base material .basemat contains almost the same elements as the old .mat file, except:

The materials and material elements replaced with the base_material.
The object and decal attributes of the shader element replaced with node.
The object and decal attributes of the bind element replaced with node.
Added the new group element. So, the group attribute of the states, textures and parameters became optional.
Added the guid attribute for the base_material element.
Removed the log10 value of the flags attribute of the parameter element.
States, parameters, textures and shaders may be arranged in any order.

.mat

The user material .mat file stores overridden values of the parent material properties. Besides, it has the following differences from the old material file:

The materials and material elements replaced with the material.
Added the parent_name attribute for the material element.
Added the guid attribute for the material element.
Added the manual attribute for the material element.
Added the base_material attribute for the material element.
Removed the hidden attribute for overridden states, textures and parameters.
The parent attribute now contains a material's GUID.
The user material cannot have custom properties or shaders.
States, parameters, textures and shaders may be arranged in any order, as for the base material.

NoticeThe set of elements of the .basemat and .mat files differs. For more details, check the corresponding articles on these files formats.

Materials Migration Process

The upgrade script performs the following on materials of the project:

Replaces all material libraries (*.mat) with the homonym folders that store materials files. Each material from the library will be stored in a separate *.basemat or *.mat file depending on its type.
For example, the default project unigine_project.mat library will be replaced with the unigine_project folder that stores the ground_grid.mat and material_ball.mat materials.
Moves materials that have been assigned to node surfaces and overridden via Nodes Editor (Surfaces tab -> Material -> Edit) to the folder that stores the node and assigns the following names to these materials:
- Materials assigned to objects: <node_name>_materials/<node_name>_<surface_name>_<index>.mat. An index is added if such material name already exists in the folder.
- Materials assigned to decals: <node_name>_materials/<node_name>_<index>.mat. An index is added if such material name already exists in the folder.
Indexes materials with the same names (as UnigineEditor requires a unique name for each material). For example, if you have 2 material libraries with materials named my_material in each of them, they will be renamed as follows: my_material_0, my_material_1.

After migration, some objects' surfaces can become red. It can have the following reasons:

Materials have been upgraded incorrectly.
These surfaces don't have materials assigned.
Notice
If the material is assigned to the surface but doesn't exist in materials hierarchy, the surface will be rendered red and the console will report an error.

Peculiarities

A base material with a custom shader inherited from another base material requires advanced preparation: copy the parent material to the child material and save it as a unique base material. In this case, such material will be migrated correctly.

Exceptions

There are cases when the material won't be migrated:

If the material's parent isn't found.
If there is a material in a library used in several worlds and its parent has the same name as materials in other libraries also used by these worlds, but these materials have different base materials. So, in one world the material has one base material, and in the other world it has the other base material. Such material won't be migrated.
For example, there are 3 material libraries: L0, L1 and L2. The L0 library contains the m0 material that is inherited from the m material. The L1 and L2 libraries also have the m materials: in L1 it is inherited from mesh_base, in L2 - from decal_base. These material libraries are used by the W0 and W1 worlds: L0 and L1 are used by W0, L0 and L2 - by W1. Thus, W0 will load m0 that can be applied to a mesh only, and W1 will load m0 that can be applied to a decal only. In this case, the m0 material won't be migrated.

The materials can be migrated incorrectly in the following cases:

If a NodeReference node is created from the code and refers to a nonexistent material library. In this case, the first material with the same name as the missed library's material will be found and assigned. If such material doesn't exist, the NodeReference won't be rendered at all.
If the path to the material library specified in the *.world file isn't relative to the data folder. During migration, the materials can be saved into the wrong directory.
For example, the library is stored in data/demos/lightmap/lightmap.mat and the lightmap.world references the library as follows:
Source code (XML)
```
...
<materials>
	<library>lightmap/lightmap.mat</library>
</materials>

...
```

grass_impostor_base Migration

Unfortunately, after migrating to UNIGINE 2.6, textures specified for the grass_impostor_base material will be applied incorrectly. So, you will have to manually flip diffuse and normal textures by X axis.

Migrating Properties

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.

Last update: 2017-10-21

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)