CityEngine VR Experience for Unreal Studio

Document created by BNeukom-esristaff Employee on Apr 11, 2018Last modified by SArisona-esristaff on Mar 21, 2019
Version 7Show 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 describes how to get all necessary data from CityEngine into the template project and also how a user can navigate the scene in VR.


For more information on how to use the City Engine Unreal exporter please refer to the CityEngine Exporter for Unreal Engine Quick Start Guide and for more information about VR with Unreal Engine to Steam VR Quick Start.


Note: the whole setup of the scene can be completed without using the HTC Vive headset.


Note: this guide refers to the CityEngine VR Experience version 2018.1. Release notes are provided at the end of this document.





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 with Mesh Merging set to Globally and Instancing to Disabled and center the global offset by using the Center button. For more information on how to export a model from CityEngine into Unreal Engine please refer to CityEngine Exporter for Unreal Engine Quick Start Guide.

    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 also Importing Scenarios).

  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:

  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 Terrain

The CityEngine Datasmith exporter currently does not support exporting terrain data. To export terrain data we therefore use the FBX export as follows:


  1. Select the terrain and export using the FBX exporter with default settings, except the global offset which should match the global offset used for the export of the city model.
  2. Import the FBX file using the Import button in Unreal and select the Convert Scene Unit checkbox before clicking Import.

  3. After importing the mesh into Unreal Engine, the material needs to be replaced. First a Material Instance of the M_CE_Opaque material needs to be created:

  4. Open this newly created Material Instance and set the ColorMap to the texture which was imported from the fbx import.

  5. After that, drag the imported FBX model from the Content Browser in Unreal into the level and set its Location to 0 for all axes:

  6. Finally, replace the material on the Actor with our newly created material.


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: you can also change the time zone, latitude and longitude which will affect the shadows in your scene by selecting the SunPositionCalculator from the World Outliner as shown in the screenshot below.


Enabling trueSKY

To enable trueSKY follow these steps:

  1. Create an account on the trueSKY website.
  2. Download the trueSKY UE binary distribution version 4.20.3 4.2 from the downloads page.
  3. Execute the installer and follow the installation steps.
  4. Open the CEVRExperience project.
  5. Open the File menu and Execute a Python Script.
  6. Select the from the Python folder inside the Content folder of the CEVRExperience project.
  7. 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


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 2018.0 (feature release, 2018-07-12)

  • Initial release of the CityEngine VR Experience


CityEngine VR Experience 2018.0.1 (bug fix release, 2018-07-20)

  • Update: Support for UE4 4.20

  • Bugfixes

CityEngine VR Experience 2018.0.2 (bug fix release, 2018-10-03)

  • Bugfix: Disabled static lighting by default

  • Bugfix: Fixed packaging issues


CityEngine VR Experience 2018.1 (feature release, 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
2 people found this helpful