Old Editor Workflow Projects

Run the upgrade script that:
- Updates files to new formats (if any).
- Generates GUIDs for all files stored in the data folder and saves them to the data/guids.db file. This is required as the asset system operates with GUIDs, not paths.
- Replaces paths by which files are referenced in the .world, .node, .settings, .track, .mat, .prop, etc. with the generated GUIDs in the GUID path format (e.g. guid://e231e15beff2309b8f87c30b2c105cc4d2399973). An exception is the base and manual materials and properties: paths in these files won't be replaced with GUIDs.
  Notice
  To avoid errors and collisions caused by such replacing, upgrade your code so that it correctly processes GUIDs.
- Generates .meta and runtime files for the uncompressed textures.
  Notice
  For other files in the original data folder, no .meta and runtime files are generated by the upgrade script.
Run the upgraded project with the Editor: .meta and runtime files for assets (meshes, nodes, textures, materials, properties, tracks, settings, worlds, source code files, etc.) will be generated automatically, if required.
Notice
It might be necessary to perform additional actions in the Editor:
- Run the console command to upgrade FBX files (optional).
- Run migration of ObjectTerrain to ObjectTerrainGlobal (required if any).

Details on migrating project's content are described below.

Textures

Textures are migrated as follows:

The uncompressed folder becomes a usual folder. If there are .meta files generated for the uncompressed textures, they will be replaced with the newly generated .meta files. The .dds files that correspond to the uncompressed ones are moved to the .runtimes folder and the .meta files are generated for them as well.
Notice
The new .meta files generated for the uncompressed textures store references to the corresponding runtime .dds files.

For example, if you store the textures in the data/my_project/textures/uncompressed folder, the assets will be stored in the data/my_project/textures/uncompressed folder and the corresponding .dds files will be moved to the .runtimes folder.

Migration of Uncompressed Textures
The .meta and runtime files won't be generated for textures if there is no corresponding uncompressed textures. To create assets for such textures, run the Editor: the .meta and runtime files will be generated automatically.
Notice
If there are the .dds files with no uncompressed textures, they will be treated as native assets: no runtime files will be generated for them by default. However, you can re-import them with custom settings, if necessary.

FBX Files

For .fbx files, the .meta and runtime files (.mesh, .node, .anim) are generated when the project is run with the Editor. If an .fbx file has the corresponding .mesh files stored in the meshes folder, you can link this .fbx to these meshes instead of the generated ones: in the console, run the link_meshes_to_fbx command:

Source code

Unigine~# link_meshes_to_fbx

In the result, the .fbx asset will link to the runtime file generated for the meshes/.mesh. At that, the meshes/.mesh file will be deleted as well as the mesh generated for the .fbx on the Editor start.

For example, you have data/my_project/meshes/ashtray.mesh in the project and there is data/my_project/ashtray.fbx that contains the mesh. After upgrading the project and running the Editor, the files will be linked as follows:

After running the console command, links will change as follows:

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

Settings

The .settings files will be migrated as follows:

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

The assets for the settings will be created after the Editor start.

Other File Types

The .meta and runtime files for all other file types (meshes, nodes, materials, properties, tracks, worlds, source code files) will be created after the Editor start, if necessary.

Migrating Materials

NoticeSkip this chapter, if your project is created with/migrated to UNIGINE SDK 2.6+ by using the Editor 1 workflow.

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 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.

Notice

The 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.

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, it can occur, if 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.7, 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.

Last update: 2018-04-26

Help improve this article

Was this article helpful?

Report a problem related to this article

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