Export DATASMITH (Unreal and Twinmotion)

You can export Unreal Engine and Twinmotion (DATASMITH) data from CityEngine to the Unreal Engine Editor and Twinmotion. This is typically used for architectural and design visualization workflows, but you can also use it for games and other tasks.

Note:
  • Exporting Unreal data is only available on Windows.
  • To export Unreal data in CityEngine, the Unreal Engine Launcher must be installed first.
  • The CityEngine Model Loader Project is no longer needed and will be removed from the Unreal Engine Launcher.

Export options

In addition to the general export options, the following options are available for DATASMITH export:

OptionDescription

Export Twinmotion Compatible

Makes the DATASMITH export compatible with Twinmotion. The export uses Unreal Base Materials, which are compatible with both Twinmotion and Unreal (the Use Unreal Base Materials export option must be set to true). It also disables features that are not compatible with Twinmotion:

  • Texture atlasing
  • Instancing options
  • Exporting terrains
  • Exporting metadata
  • Exporting LODs
  • Exporting scenarios

Global Offset

Applies global offset for generated geometry for x, y, and z axes (Cartesian coordinate values).

Mesh Merging

Sets how the resulting meshes are merged:

  • Per Initial Shape—Meshes are merged by initial shapes.
  • Per Initial Shape by Material—Meshes are merged by initial shapes by material. This results in one mesh per material for each initial shape.
  • Globally—Meshes are merged globally.
  • Globally by Material—Meshes are merged globally by material.

Instancing

Sets how instancing is handled:

  • Disabled—Instancing is disabled.
  • Use Instanced Meshes—Instancing is enabled, which results in meshes being shared between actors, if possible.
  • Use Instanced Mesh Actors—Instancing is enabled, and instances are added using hierarchical instanced static mesh (HISMC) actors.

Metadata

Exports metadata when Mesh Merging is set to either Per Initial Shape or Per Initial Shape by Material. The following are the metadata export options:

  • All—Writes object attributes and reports to object metadata.
  • Attributes—Writes object attributes to object metadata.
  • Reports—Writes generated report data to object metadata.
  • None—Object attributes and report data are not written to object metadata.

The exported metadata is attached to the root object of each initial shape in Unreal.

Terrain Layers

Exports terrain layers to Unreal Engine Landscapes. The following options are supported:

  • Do not export any terrain layers
  • Export all visible terrain layers
  • Export all selected terrain layers
  • Export all terrain layers

Use Unreal Base Materials

Uses Unreal Base Materials as the primary material for all exported materials. These predefined materials are compatible with both Twinmotion and Unreal. They support the following CityEngine material attributes:

  • material.colormap and material.color
  • material.normalmap
  • material.opacitymap and material.opacity
  • material.emissivemap and material.emissive.{r|g|b}
  • material.roughnessmap and material.roughness
  • material.metallicmap and material.metallic

Use Texture Atlases

Enables texture atlases that combine exported textures and reduce the number of materials. Texture atlases typically have the greatest impact when used on slower hardware, for example, on mobile VR devices such as the Oculus Quest.

Export LOD

Enables export of level of detail (LOD). Exporting LOD is only enabled when exporting per initial shape.

LOD Attribute

The name of the CGA attribute that specifies the LOD. The attribute must have an Enum annotation. For each element of the Enum annotation, a derivation is triggered when the LOD attribute is set to this element value.

The following example generates three LODs per initial shape:

@Enum(“low”, “medium”, “high”)
attr Lod = “low”

Note:
If the attribute is defined in multiple CGA files, it must have the same elements (LODs).

LOD Order

The semantic order of the LOD Attribute values.

  • Ascending—The lowest level of detail is defined first.
  • Descending—The highest level of detail is defined first.

For example, if the LOD Attribute option is defined as follows, the order is ascending, as the lowest level of detail is defined first.

@Enum(“low”, “medium”, “high”)
attr Lod = “low”

Export Scenarios

Enables export of CityEngine scenarios to Unreal Enginevariants. For each scenario, you can individually specify whether to export it as a variant.

Default Objects

Defines how default objects are exported.

  • From Selection—Only the selected default objects are exported.
  • Visible—All default objects that are visible in the scene are exported and the selection is ignored.

Mapping between CityEngine and Unreal entities

Geometry

Each exported mesh is represented as an actor in Unreal. Each unique mesh is exported as a static mesh and reused if instancing is enabled.

Materials

Materials are mapped to Unreal by passing CGA material attributes to an Unreal material instance, which is based on a certain primary (or parent) material.

By default, appropriate primary materials are generated that handle the mapping from CGA material attributes to Unreal material attributes (see also Default primary materials).

Custom primary materials

A custom primary material can be assigned by setting the material.shader CGA attribute to the corresponding Unreal material path, for example, /Game/Materials/CityEngineMaterials/M_CE_MyMaterial.

Each CGA material attribute is exported and can be accessed in Unreal using a material parameter with a specific name and data type. The following table lists the CGA material attributes and their respective Unreal parameter name and type:

CGA attributeUnreal parameter nameUnreal typeNotes

material.color

Color

Vector3

material.opacity

Opacity

float

material.reflectivity

Reflectivity

float

material.shininess

Shininess

float

material.bumpValue

BumpValue

float

material.ambient

Ambient

Vector3

material.specular

Specular

Vector3

material.colormap

ColorMap

Texture2D

material.dirtmap

DirtMap

Texture2D

material.specularmap

SpecularMap

Texture2D

material.opacitymap

OpacityMap

Texture2D

<none>

OpacitySource

float

For the OpacitySource value, select from the following:

  • 0—Use color channels (gray level) from OpacityMap.
  • 1—Use alpha channel from OpacityMap.

material.bumpmap

BumpMap

Texture2D

material.normalmap

NormalMap

Texture2D

<none>

IsPBR

float

  • 1—If material.shader is set to CityEnginePBRShader
  • 0—Otherwise

material.metallic

Metallic

float

material.roughness

Roughness

float

material.emissivecolor

EmissiveColor

Vector3

material.metallicmap

MetallicMap

Texture2D

material.roughnessmap

RoughnessMap

Texture2D

material.occlusionmap

OcclusionMap

Texture2D

material.emissivemap

EmissiveMap

Texture2D

Default primary materials

By default, an appropriate primary material (opaque, transparent, or masked) is generated during export, based on the following rules:

  • If material.opacity is smaller than 1 or material.opacitymap is set
    • and the opacitymap.mode is blend, a Transparent primary material is used.
    • and the opacitymap.mode is masked, a Masked primary material is used.
  • Otherwise the Opaque primary material is used.
Note:

Unreal Engine sorts transparency per actor. Exporting overlapping transparent actors leads to rendering artifacts. Masked binary opacity is not affected by this limitation.

Default material attribute mapping

The default primary materials map the CGA material attributes roughly to a physically based Unreal Material. If material.shader is set to CityEnginePBRShader (this happens automatically if, for example, an inserted glTF model is exported), the default primary materials in Unreal use the PBR material attributes (roughness, metallic, and emissive).

Note:

The specular color is not used in Unreal. The specular color in Unreal depends on the base color and how metallic the material is.