Content Migration
In order to use the updated asset system for project development, you should migrate project's content.
You can upgrade content of your project to UNIGINE 2.7 in the automatic or manual mode.
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.
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.
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:
- 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 the project's data folder to the list of arguments passed to the upgrade script.
usc_x64.exe upgrade.usc path/to/the/additional_content_1 path/to/the/additional_content_2 ...
For example:When migrating from UNIGINE 2.6, the path to the data folder must be specified as well.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.
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.
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".
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:
- Run your project with UnigineEditor.
- Select the ObjectTerrain object(s) that you want to migrate.
It is recommended to select all ObjectTerrain objects in the scene: they will be migrated into a single ObjectTerrainGlobal.
- Open the Terrain tab in the Parameters window and click Migrate. Enabling the Automatic option will launch migration process in fully-automatic mode.
- 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.
- 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.
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. - 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.
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 MigrationRefined Textures MigrationAs 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".
- The coarse textures and the per-surface refined albedo and mask textures are migrated as follows:
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.