You can upgrade content of your project to UNIGINE 2.6 in the automatic or manual mode.
Automatic upgrade of the project's content can be performed via Unigine SDK Browser.
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.
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:
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:
usc_x64.exe upgrade.usc path/to/the/additional_content_1 path/to/the/additional_content_2 ...Here:
usc_x64.exe upgrade.usc <unigine_project>/data path/to/the/additional_content_1 path/to/the/additional_content_2 ...
- path/to/the/additional_content_* - paths to folders with content stored outside the data folder.
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.
Details on creating assets for project's content are described below.
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.
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).
The assets for the .mesh files will be created if there are no .fbx files for them.
The assets will be created for all material files stored in the data folder.
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.
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.
The assets will be created for all .track files stored in the data folder.
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.
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.
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.
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.
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.
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.
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.
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:
... <materials> <library>lightmap/lightmap.mat</library> </materials> ...
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.
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.