Export DATASMITH (Unreal Engine)

The Unreal Engine (DATASMITH) exporter provides efficient data transfer from CityEngine to the Unreal Engine Editor. The main purpose of this exporter is for architectural and design visualization workflows, but will obviously also work for games and other tasks.

Note:

• The Unreal exporter is only available on Windows.
• To use the Unreal exporter in CityEngine, at least the Unreal Engine Launcher needs to be installed as a prerequisite.
• The CityEngine Model Loader Project is not needed anymore and will eventually be removed from the Unreal Engine Launcher.

Export settings

In addition to the general export options, the Unreal Engine DATASMITH has the following options:

Export Twinmotion Compatible	Makes the Datasmith export compatible with Twinmotion. The export will use the “Unreal Base Materials” which are compatible with both Twinmotion and Unreal (the Use Unreal Base Materials export setting will be set to true). It will also disable features which are not compatible with Twinmotion: Texture atlasing Instancing options Exporting Terrains Exporting Metadata Exporting LODs Exporting scenarios
Global Offset	Global offset for generated geometry for x, y and z axes (Cartesian coordinate values).
Mesh Merging	Different options on 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 will result in one mesh per material for each initial shape. Globally: Meshes are merged globally. Globally by Material: Meshes are merged globally by material.
Instancing	Different options on 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	Metadata can be exported when the Mesh Merging mode is set to either Per Initial Shape or Per Initial Shape by Material. Metadata export options: All: Write both object attributes and reports to object metadata. Attributes: Write object attributes to object metadata. Reports: Write generated report data to object metadata. None: Do not include object attributes nor report data. The exported metadata is attached to the root object of each initial shape in Unreal.
Terrain Layers	Terrain layers can be exported 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 the “Unreal Base Materials” as parent 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 biggest impact when used on slower hardware, for example, on mobile VR devices such as the Oculus Quest.
Export LOD	Enables the export of Level of Detail (LOD). Exporting LODs is only enabled when exporting Per Initial Shape.
LOD Attribute	The name of the CGA attribute which specifies the LOD. The attribute needs to have an Enum annotation. For each element of the Enum annotation a derivation will be triggered where the LOD attribute will be set to this element value. The following example @Enum(“low”, “medium”, “high”) attr Lod = “low” generates three LODs per Initial Shape. Note: If the attribute is defined in multiple CGA files it needs to have the same elements (LODs).
LOD Order	The semantic order of the LOD Attribute. Ascending: The lowest level of detail is defined first. Descending: The highest level of detail is defined first. For example, if the LOD Attribute is defined as follows: @Enum(“low”, “medium”, “high”) attr Lod = “low” the order is ascending, as the lowest level of detail is defined first.
Export Scenarios	Enables the export of CityEngine Scenarios to Unreal Engine Variants. Each scenario can be toggled individually whether it should be exported as a Variant or not.
Default Objects	Defines how default objects are exported. From Selection: Only the selected default objects are exported. Visible: All default objects which 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 translated to Unreal by passing CGA material attributes to an Unreal Material Instance which is based on a certain primary (or parent) material.

By default the exporter generates appropriate primary materials which handle the translation 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, e.g. /Game/Materials/CityEngineMaterials/M_CE_MyMaterial.

Each CGA material attribute is exported and can be accessed in Unreal by 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 attribute	Unreal parameter name	Unreal type	Note
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 OpacitySource value: 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:

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

Default material attribute translation

The default primary materials translate the CGA material attributes roughly to a physically based Unreal Material. If the material.shader is set to CityEnginePBRShader (this happens automatically if for example an inserted glTF model is exported), the default primary materials in Unreal will 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.