This document describes various workflows for getting data from CityEngine to Unreal Studio and for setting up the Unreal Engine projects, e.g. to correctly handle or modify materials and lighting.
Currently, we provide two UE4 project templates for Unreal Studio to streamline the import process.
- The CityEngine VR Experience is a complete solution for creating virtual reality experiences to explore CityEngine architecture and urban planning scenarios. The getting started and user guide is available here: https://community.esri.com/docs/DOC-11563
- The CityEngine Model Loader is a UE4 template to import CityEngine datasmith imports into Unreal Studio. The getting started guide is available here: https://community.esri.com/docs/DOC-10901
We recommend having a look at these guides first before going into details provided in this document.
Note: The CityEngine Model Loader is a Blueprint only project and thus comes with limited functionality compared to the CityEngine VR Experience (e.g. the CityEngine Toolbox). If you want to use the VR experience features for non-VR, you can either convert the model loader to a C++ project and then copy C++ components from the VR experience as needed, or create an empty level in the VR experience and import the datasmith file there.
Note: This document refers to CityEngine 2019.0 and Unreal Studio 4.22.
- Batch-Replacing Actors and Foliage (VR Experience Only)
- Non-photorealistic Sketch Rendering (VR Experience Only)
- Level of Detail
- Terrains / Landscapes
- Exporting Metadata from CityEngine to Unreal Engine
- Sun Position, Skylight and trueSKY (VR Experience Only)
CityEngine Master Materials
Both the CityEngine Model Loader and the CityEngine VR Experience project come with built-in master materials that are needed for correct setup of materials exported by CityEngine. For details on translation of materials from CityEngine to Unreal Engine, refer to the CityEngine Unreal export documentation at https://doc.arcgis.com/en/cityengine/latest/help/help-export-unreal.htm
Special Considerations for Materials in the VR Experience
The CityEngine VR Experience requires special modifications of materials for the experience to work properly. If you create your own materials or import materials from other projects or third party plugins, it is crucial that you create the VR versions of these materials. This is down using the following two steps:
- Execute the material modification script by pressing the Create VR Materials button in the CityEngine Toolbox
- Click Save All to make the changes persistent.
Using Adobe / Allegorithmic Substance Materials
This section describes how to use Substance materials in combination with CityEngine datasmith exports. The following steps highlight the general workflow, which can be repeatedly applied as your CityEngine scene evolves:
- In the Epic Games Launcher, download the Substance Plugin from the Marketplace.
- Create a new CityEngine VR Experience or CityEngine Model Loader project and enable the plugin.
- In the Material folder of your Unreal project, create a new folder named SubstanceMaterials.
- Open Substance Source and download a material you want to assign from CityEngine.
- Right click on the material (filename ending with _MAT. In our example Royal_Range_Combined_MAT) and press Copy Reference. This will copy the file path for later use in CityEngine.
- Go back to CityEngine, open your scene. Using the model hierarchy view, inspect the facade you want to apply your Substance material to. Double-clicking on the node will move you to the corresponding part of CGA code.
- Insert the command at an appropriate location in your Rule file:
- Replace <material_path> with the path to the material previously copied in Unreal Engine. In our example, the path was "Material'/Game/Materials/SubstanceMaterials.Royal_Range_Combined_MAT.Royal_Range_Combined_MAT".
- Remove the leading Material' and the trailing .Royal_Range_Combined_MAT' and replace <material_path> with this path. The resulting CGA command should look like this:
- Export your scene using the Unreal Engine exporter.
- Go back to Unreal Engine and import the exported datasmith file into the previously created CityEngine Model Loader project with the Substance material.
- If you are using the CityEngine VR Experience you also need to press Create VR Materials button in the editor toolbar and
then click Save All (as explained in the previous section).
Batch-Replacing Actors and Foliage (VR Experience Only)
The Replacement Tool is used to batch-replace placeholder objects exported from CityEngine with high quality assets in Unreal. The following section describes how objects need to be exported in CityEngine and how the Replacement Tool can be used in Unreal.
First a placeholder object needs to be inserted in CityEngine using the CGA insert command as follows (hint: the Scatter Operation can be used to distribute the objects):
The garden_plant.obj can be any object (even a simple cube) as it will be replaced in Unreal. Note that each object you want to replace needs a unique name as the name is used in Unreal to discern between the different Actors. In CityEngine's Unreal Export settings, Instancing needs to be set to Use Instancing so that each placeholder is imported as a separate actor in the scene, named after the asset that created them (in this case the ‘garden_plant.obj’).
Import the Datasmith file as usual. Once the import complete, the result should look something like the scene in the image below.
The Replacement Tool helps batch-replacing the white cubes. It can be found in Unreal Engine in the CityEngine Toolbox:
After selecting the menu item, a dialog with a number of options opens. The image below shows a sample dialog to replace our placeholders with the HillTree_02 model (from Epic Games' Open World Demo Collection):
Following a description for all options of the Replacement Tool:
- Type: Select the type of object you want to replace, and the type of object you want it to be replaced with.
- Filter: Select the criterion for finding the objects that will be replaced, usually we use the name of the actor.
- Scale: Select the scale of the new object. You can either chose to keep the original scale of the placeholder, or to scale randomly the new object within the domain that you specify.
- Replacement: The Replacement Mesh selects the path to the new object, i.e. the object to be used instead of the original one. The replacement percentage defines how many of the existing actors that meet the filter criteria will be replaced. You can add as many replacements as you want for the same criteria. This allows you to distribute different plants using a single placeholder by experimenting with different replacement percentages and executing them one after the other until the desired density has been reached.
- Add to List: You can save your previous replacements in the List so that you can easily repeat them by enabling them and clicking on ‘Execute enabled replacements’.
Note that you can undo the replacement in Unreal Engine with a simple Ctrl+Z, so that you can easily adjust your percentages and parameters until you find the right mix of actors. Here’s what our garden looks like after the execution of multiple replacements:
Note: The Replacement Tool is currently in beta and will be extended in future versions.
Non-photorealistic Sketch Rendering (VR Experience Only)
An experimental non-photorealistic (NPR) shader can be enabled/disabled to highlight edges as shown in the screenshot below:
The shader can be enabled/disabled from the CityEngine Toolbox:
Level of Detail
Unreal Engine can automatically generate Level of Detail (LoD) for meshes. This section briefly describes how these LoDs can be generated and how the settings can be tweaked to get optimal results.
There are two ways to create and edit your LoD settings:
LoD for a Single Mesh
- Open the asset in your content browser and navigate to the details panel.
- Assign a predefined LoD group to the mesh (for buildings, "LargeProb" is a good choice)
- Choose the amount of LoDs you would like to have and save (4 - 6 usually).
LoD for Multiple Meshes
- If you have multiple meshes (buildings) use the Bulk Edit over Property Matrix.
- Experiment with the LoD settings for a single mesh before starting to the edit multiple meshes with the property matrix.
Note: When editing multiple assets over the Property Matrix, Unreal Engine starts to calculate immediately when you hit enter, which potentially leads to very long computation times.
Recommended LoD Settings for VR
In VR the LoD Screen Size needs to be adapted as the resolution is typically higher then no VR. Adjusted Screen Size percentage settings for a VR-Project could look like this:
- LoD Levels: 4
- Switch to Level 1 from 0 at Screen Percentage 60%
- Switch to Level 2 from 1 at Screen Percentage 40%
- Switch to Level 3 from 2 at Screen Percentage 20%
- Switch to Level 4 from 3 at Screen Percentage 10%
For details further details, please refer to Setting Up Automatic LOD Generation documentation.
Terrains / Landscapes
Starting with CityEngine 2019.0, exporting terrains is handled natively by the CityEngine Unreal exporter.
In CityEngine first select the terrain layers you want to export, use the Unreal Engine exporter and set the Terrain Layer options to Export all selected terrain layers. Up on import, the Unreal Studio Datasmith importer automatically creates landscape Actors.
After importing the terrain the Generate Overlap Events property of the terrain must be set to true as shown in the screenshot below:
If performance during runtime is not good enough the Simple Collision Mip Level should be increased.
Exporting Metadata from CityEngine to Unreal Engine
Starting with CityEngine 2019.0, it is possible to export metadata (for example GIS attributes) using the Unreal Engine exporter. To do so, export CityEngine models with the following export options:
- Mesh Merging set to "Per Initial Shape"
- Metadata set to "All"
- Instancing either set to "Disabled" or to "Use Instancing", but not to "Use Instancing with Hierarchical Instanced Static Mesh" since the HISMC mesh component type does not support metadata at this point.
If you are using the CityEngine Model Loader template, you can take advantage of the built-in metadata information display functionality: After starting the level with the Play button, you can look around while pressing your right mouse button and move around using the W, A, S and D keys. Left clicking will highlight the selected actor and show its metadata in a popup.
To see the Metadata in the Unreal Engine Editor first the Shape_Root Actor (there is one Shape_Root Actor for each exported initial Shape from CityEngine) needs to be selected and then its Shape_Root Component. The metadata is then visible in the Asset User Data Section in the Details Panel as seen in the screenshot below:
Sun Position, Skylight and trueSKY (VR Experience Only)
With Unreal Engine 4.21 Epic Games introduced a new plugin for computing the accurate position of the sun in the sky based on your current location, date and time zone. The CityEngine VR Experience comes with improvements to the basic sun position calculator and sky sphere: Instead of exposing singular color values you can change the color and mood of the whole day. This section provides an overview on how to use and configure sun position and our extensions to day light. In addition we show how trueSKY can be enabled in your VR experience project.
Set up your Project
If you are using the CityEngine VR template, the Unreal Engine Sun Position Calculator plugin is already enabled, and the necessary blueprint actors are already added to your scene and you can skip to the next section. If you prefer to work with a custom project / scene, you need to enable the Sun Position Calculator plugin first (Edit -> Plugins) and then add the BP_SunPosition and the BP_SkyController actors to your scene.
Configure your Scene
To configure the scene properly, you need to complete a few steps now. First, click on the BP_SunPosition actor and look at the settings available in the details panel.
- Setup your location and time zone (where the time zone is GMT + the value you enter in the time zone field). The north offset field is for cases where your scene is oriented differently than assumed by the blueprint and you can use this to offset the north by a certain amount of degrees.
- Set the preferred date.
- Set the preferred time.
Once you have set all of these settings the sun position calculator is good to go and you can move on to the sky sphere by clicking on the BP_SkyController actor. The sky controller allows you to not only setup a few basic settings that are independent of the time of day, it also allows you to define curves that control how the sky changes over time.
- Cloud Speed is used to determine the speed at which the cloud layers rotate.
- Sun Height is used as an offset to the computed sun height.
- Cloud Opacity defines how transparent the cloud layer is.
- Sun Brightness defines how bright the sun appears to be.
- Start Brightness defines the brightness of the star layer at night.
- Refresh allows you to refresh the sky material when changes are not immediately visible.
Configuring Light Intensity Curves
Unlike UE4's built-in curves, the curves that come with our sky setup allow you to select between two different modes of operation. If you choose the Height mode, the curves work exactly like they do with the blueprints that come with the Sun Position Calculator plugin. Values are sampled based on the height of the sun, where the value is 1.0 on the equator at noon and -1.0 on the equator at midnight.
If you choose the Time mode however, the curves are expected to cover a value range from 0.0 to 24.0, where these values represent the hours of the day. This allows you to configure values both based on the time as well as the sun height and mix the two approaches where reasonable.
Animating the Time of Day
Tweaking the color and intensity curves to best fit your scene during all times is cumbersome. To facilitate the process, we created an additional blueprint BP_SkyAnimator that allows you to animate the progression of time. It automatically sets the time of day for you, allowing you to easily see how your light intensity curves behave during the day.
To use this blueprint, drag it into the scene and hit play to see the animation run in your selected viewport or directly in VR. Since the curves are stored as separate assets, changes you make to them and save while running the scene are not lost when stopping the scene.
The blueprint allows you to let time flow between a start and an endpoint. Once the time of the endpoint has been reached, the time is reset to the start point, giving you the tools to make fine grained adjustments to your color curves for specific slices of the day.
Handling Screen Space Reflections
If you use a Sky Light with SLS captures enabled, moving the time will invalidate the current capture. If you look at reflections on surfaces that are based on a cube map lookup, you will find that they are not correct anymore after the time has changed. You will see the reflections that were correct when the cube map has last been captured.
By using in the BP_SLSCapturer blueprint, the scene will automatically be recaptured when the time changes. Note that this is an expensive operation and should be coordinated with your application. If you change the time every frame, consider using different approaches like recapturing the scene once you are done changing the time.
Fog is disabled by default in the CityEngine VR Experience template scene. While it can add a lot to the atmosphere of a scene, configuring it correctly is hard and needs a lot of tweaking. Still, if you wish to use an exponential height fog actor and want to change its’ behavior according to the time of day or sun height, you can do so with our blueprints. If you have an exponential height fog actor in your scene, you can add in the fog controller (BP_FogController). The fog controller automatically updates the height fog according to an extended set of curves that provide the same operation modes as the light intensity curves of the sky controller.
Enabling and Using trueSKY
The CityEngine VR Experience supports replacing the builtin day light system with light provided by trueSKY. To enable trueSKY follow these steps:
- Create an account on the trueSKY website.
- Download the latest trueSKY UE binary distribution from the downloads page (at the time of writing: 4.22.1 4.2).
- Execute the installer and follow the installation steps.
- Open the CEVRExperience project.
- From the CityEngine Toolbox, select "Enable trueSKY"
- The editor will enable the plugin, restart and automatically add the necessary trueSKY Actors to the scene.
- For more information on how to use the trueSKY plugin please refer to the official trueSKY documentation.