CityEngine VR Experience for Unreal Studio

Document created by BNeukom-esristaff Employee on Apr 11, 2018Last modified by BSteger-esristaff on Nov 13, 2019
Version 13Show Document
  • View in full screen mode

The CityEngine VR Experience Unreal Engine 4 project template is a complete solution for creating virtual reality experiences to explore CityEngine architecture and urban planning scenarios. It consists of a virtual office with a planning table at the center where CityEngine models can be placed on and interacted with. Multi-headset mode is supported, thus scenarios can be collaboratively viewed, explored and discussed. 


This document provides and introduction to get all necessary data from CityEngine into Unreal Engine and how to configure and use the CityEngine VR Experience. For details on CityEngine export refer to the CityEngine Unreal / Datasmith export documentation. For details on configuring and customizing the Unreal Engine VR Experience, refer to the CityEngine to Unreal Studio Workflows documentation.


Note: the whole setup of the scene can be completed without using a VR headset.


Note: this guide refers to the CityEngine VR Experience version 2019.0 and Unreal Studio 4.22.





CityEngine VR Experience Data Import and Setup

The main Level of this template project in Unreal Engine consists of an office room with a round table at the center. The table is the main interaction point within the VR experience and arbitrary city models from CityEngine can be placed on top of it. The following sections explain how to get your city model (optionally with scenarios) into Unreal Engine 4 and how set it up correctly.


Exporting a City from CityEngine and Importing it into Unreal Engine

  1. Export your city model from CityEngine with the Unreal Engine exporter by selecting the models you wish to export. In the export dialog, set Mesh Merging to Globally and Instancing to Disabled and center the global offset by using the Center button. Also select the terrain layer(s) you wish to export to Unreal Engine as landscapes.

    Note: if you plan to also export scenarios you should remember the global offset of your model and reuse the same offset for the scenario model later (see Importing Scenarios below for details).

  2. Create a new project based on the CityEngine VR Experience project in your Vault and choose any name for it and open the newly created project afterwards. Note: when opening the project for the first time, it needs to be rebuilt. This will take some time, since all shaders are recompiled:

    Note: if you get the following error message:

    It most likely means your Visual Studio installation is not correct. Please check the Requirements section.

  3. Import the resulting Datasmith file (with ".udatasmith" file ending) into the tabletop VR project level.

    Leave the default values for the Datasmith import Options dialog.

    Note that after importing the city it might appear to be too big for the room. The scaling and culling happens automatically once the level is run as described in the next step.

  4. Everything should now be set up and you can play your level using the "VR Preview" from the Unreal Editor Play menu as seen in the screenshot below. For more information on Unreal Engine with Steam VR the please refer to Unreal Engine Steam VR Quick Start.

    If you don't have a headset connected you can still test the experience using the Simulate menu from the Play button.
    You can navigate in the scene with the W,A,S and D keys and use your mouse to look around. Interaction with the model is only possible using the VR headset. See also Navigating the Viewport tutorial for further help.


Note: there are several tutorials available within the editor.. They describe how to import terrain and scenarios as well as how to add teleportation targets. You can start the tutorial by pressing the white play button on the TableTopVRTutorial.


Note: after importing the model from CityEngine you can hide either the room or the citymodel from the toolbar as shown in the screenshot below. This only affects the editor view and not the final VR experience. It is intended to help with the navigation inside the editor.


Importing Scenarios

Scenarios make it possible to create different designs for the same scene. For example, scenarios can represent multiple development proposals for a site or different phases of construction. The following steps describe how scenarios can be exported from CityEngine and imported into the Level in Unreal Engine.


  1. Select a scenario in CityEngine and export it (only the model from the scenario as seen in the screenshot below) with the same settings as your initial export mentioned before.

  2. Import the resulting Datasmith file into the Tabletop VR Template level.

  3. Select the newly imported ActorMesh in the World Outliner in Unreal and add a Tag in the Details panel of the Actor as seen below:

  4. Select the BP_LevelController Actor in the World Outliner and add the previously entered Tag into the Scenario Tags as seen below:

    The Active Scenario Tag is the scenario which is active when you start the Level.

  5. You can repeat this step for as many times as you need to if you want to add multiple scenarios.


Adding Teleportation Locations for Specific Points of Interest

Teleportation locations can be used to let the user quickly navigate to points of interest inside the city model by using the laser pointr (using the Trigger Button, see also the VR Navigation section) from the controller.


  1. Open the Blueprints folder in the Content Browser
  2. Search for the BP_TeleportationTarget Blueprint
  3. Drag the Blueprint anywhere inside your scene where you want a teleportation location
    Note: the rotation of the Blueprint Actor determines the orientation which the user will face after teleporting to this teleportation location


VR Navigation and Interaction

This section describes the navigation and interaction tools available in the VR experience.


Controller Overview

Following an overview of all interaction possibilities of the controller and a short description. The controller interactions which are of interest for the VR experience are highlighted in bold type. After that a more detailed description of each interaction follows. 

  1. Menu
    Opens the menu which allows for changing scenarios and adjusting time of day. See also the Changing Scenarios sand the Adjusting Time of Day sections.
  2. Trackpad
    Swiping left or right will change the active scenario of your city model. See also the Changing Scenarios section.
  3. Home Button
  4. Power Indicator
  5. Power Plugin
  6. Controller Sensors
  7. Trigger Button
    The trigger button is used for activating the laser pointer, the teleportation beam, for panning and scaling the city and for interacting with UI elements such as handles and menu sliders.
  8. Grip Button


City Model Interaction

You can interact with the city model using one controller and its Trigger Button.



In this VR experience, locomotion is primarily handled by teleportation. To teleport to a new location, press the Trigger Button and move the controller until the teleportation beam appears. If the beam appears red, you can not move to that position. You can also change the direction you are facing when teleporting by tilting the controller. The resulting orientation is indicated by the arrow on the ground as seen in the screenshot below.


You can also teleport into the city using this technique if you do not wish to teleport to dedicated points of interest (see below). To jump out of the city or to another dedicated location, simply point the controller upwards to the sky and press the Trigger Button. Then a number of portals will appear. Point at one of the portals and press the Trigger Button to teleport.



Panning and Zooming the City Model

To pan or zoom the city model, hover with your controller closely over the city model until the pan/zoom icon appears over your controller. Then press the Trigger Button and move to controller horizontally to pan the city model and vertically to zoom the city model in or out.


Rotating the City Model and Adjusting the Virtual Table

To rotate the city model grab the blue torus at the edge of the table until the icon appears. Then press the Trigger Button and move your controller to the left or the right, as shown in the image below. To raise or lower the table, press the Trigger Button  and move your controller up or down. To increase or decrease the table, press the Trigger Button and move the controller towards or away from the table's center.



Teleporting to Points of Interests

To navigate to a dedicated point of interest, aim the laser at a teleportation target and press the Trigger Button



Changing Scenarios

There are two different ways of changing the active scenario:

  • Using the Menu: By pressing the Menu Button, the menu that shows the scenarios and the time of day is activated. You can adjust the sliders in the menu by moving the controller close to the slider indicator (the blue sphere) and then pressing the Trigger Button to move the indicator to the desired scenario or time of day. 
  • Using the Trackpad: You can change the active scenario by swiping left (previous scenario) or right (next scenario) on your trackpad.


Adjusting the Time of Day

Activate the menu by pressing the Menu Button and then use the slider to adjust the time. 


Note: to change your time zone, latitude and longitude, to configure your daylight settings or to use trueSKY, please refer to the corresponding section in the CityEngine to Unreal Studio Workflows documentation.


Changing the Virtual Planning Office Skybox

The skybox (i.e. the surroundings outside the planning office) can be replaced with a different 360° panorama as follows:


  1. Import the new image containing the 360° panorama for the skybox either by dragging it from the Explorer into the Content Browser or through the Import button in the Content Browser. Note that the image must use equirectangular projection such as the image below.

  2. Open the imported image and set the value for "Level of Detail -> Mip Gen Settings" to "NoMipmaps".

  3. Save the changes and close the tab.
  4. Navigate to "Content -> Maps -> Room -> Skybox" in the Content Browser and open the "MI_EquirectangularRoomSkyBox" material instance.

  5. Change the value for "Parameter Groups -> SkyBoxTexture" to the newly imported image.

  6. Save the changes and press play to test if the Skybox is displayed correctly.


Multiplayer Support (Experimental)

With the experimental Multiplayer feature, multiple people can join the same VR experience and interact with each other in a local network. First one user has to host a server and then other users can join this server. The following sections explain how to host and join a server in more detail.


Hosting a Server

Press "H" on the computer keyboard to host a server.


Joining a Server

Press "J" on the computer keyboard to join an existing server in the local network.


CityEngine VR Experience for Unreal Studio Release Notes


CityEngine VR Experience 2019.0 (2019-05-20)

  • Update: Support for Unreal Studio 4.22 (and dropped support for earlier versions)
  • New feature: Oculus rift support
  • New feature: Support for native datasmith terrains
  • New feature: Support for CityEngine PBR materials
  • New feature: Support for non-photo-realistic sketch-style rendering
  • New feature: Helper tools and scripts for batch replacement of actors and foliage
  • Update: Improved sun position and day light simulation
  • Update: Improved teleporting and scenario change UX
  • Update: Improved real-time vertical alignment of base map
  • Documentation: Comprehensive workflow documentation from CityEngine to Unreal Studio for advanced scenarios
  • Bugfixes


CityEngine VR Experience 2018.1 (2018-11-21)

  • New feature: Simplified UX (one controller, one button interaction)
  • New feature: TrueSky support
  • New feature: HTC Vive Pro support
  • New feature: Workflow for custom office panoramas
  • Bugfixes


CityEngine VR Experience 2018.0.2 (2018-10-03)

  • Bugfix: Disabled static lighting by default

  • Bugfix: Fixed packaging issues


CityEngine VR Experience 2018.0.1 (2018-07-20)

  • Update: Support for Unreal Studio 4.20

  • Bugfixes


CityEngine VR Experience 2018.0 (2018-07-12)

  • Initial release of the CityEngine VR Experience

2 people found this helpful