CityEngine VR Experience for Unreal Engine
The CityEngine VR Experience Unreal Engine 4 project template is a complete solution for creating virtual reality experiences to explore ArcGIS CityEngine architecture and urban planning scenarios. It consists of a virtual office with a planning table at the center, upon which CityEngine models can be placed 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 VR Experience Advanced Features documentation.
Update (November 05 2021): The CityEngine VR Experience 2021.1 for Unreal Engine 4.27 is available in the Unreal Marketplace. Follow this link to get the project template for free.
Note: The whole setup of the scene can be completed without using a VR headset. However, to fine tune the experience, you will need a headset.
Note: This document refers to CityEngine VR Experience 2021.1, CityEngine 2021.1, and Unreal Engine 4.27.
Requirements
To use the CityEngine VR Experience the following software / hardware is required:
- ArcGIS CityEngine (see also ArcGIS CityEngine Requirements)
- Epic Games Unreal Engine 4 (see also the Unreal Requirements)
- CityEngine VR Experience Project template, available from the UE4 Marketplace
- Visual Studio 2017 or 2019 (see also Unreal Visual Studio Setup) configured for Unreal Engine
- VR headset:
- Oculus: Rift, Rift S, Quest 1 + Link, Quest 2 + Link
- HTC: Vive, Vive Pro
- HP: Reverb
- Basic knowledge of CityEngine and Unreal Engine 4
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
- 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). - 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.
- 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: 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. - 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 command in the Play menu.
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 VRExperienceTutorial.
Note: After importing the model from CityEngine you can hide either the room or the city model using the Unreal editor's world outliner.
Exporting Scenarios and Importing them into Unreal Engine
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.
- First you need to export the scenarios from CityEngine. To simplify this process download the zipped Python script , extract the zip file and copy the Python script into your projects script folder. Open the Python script and run it by pressing F9 or by selecting Python/Run Script in the menu. This script will export all scenarios of the current scene as well as the default objects. After launching the python script the Unreal Engine export dialog will appear where you can configure your export. Make sure to click the Center button and to set Mesh Merging to Globally.
- Click Finish to start the export. The export will create multiple datasmith exports which can be imported to Unreal Engine as shown in the next step.
- Switch to Unreal Engine and open the Scenario Import dialog via the CityEngine Toolbox.
- Select the exported Datasmith file in the file dialog and click Open. Next, choose which scenarios you want to import and press the Import button.
The import process will now import the datasmith files, add the imported data to the level and setup the Actors correctly in the World Outliner. For each imported Plan an UrbanEvent Actor is created and for each Scenario a BranchActor.
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 pointer (using the Trigger Button, see also the VR Navigation section) from the controller.
- Open the Blueprints folder in the Content Browser
- Search for the BP_TeleportationTarget Blueprint
- 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 - The teleportation targets can belong either to the whole scene, to a plan or to a specific scenario.
- If a teleportation target belongs to a certain plan it will only show up if this plan is currently active.
- If the teleportation target is attached to a scenario, it will only be visible if this scenario is active.
- Otherwise the teleportation target will always be visible
Note: A plan is represented with the Blueprint BP_UrbanEvent and a scenario with the Blueprint BP_Branch.
Note: These Blueprints will automatically be created if the workflow described in the section Import Scenarios is used.
- To attach a teleportation target to either a plan or a scenario you can drag it one the desired Actor in the World Outliner as shown in the following screenshot:
This will attach the teleportation target to the Branch (Scenario) "Current Conditions" and it will therefore only be visible if this UrbanEvent (Plan) is active.
Changing the City Name
To change the name of the city (which is shown above the planning table), select "BP_LevelController" in the World Outliner. In the Details panel, scroll down to "CE Level Controller" and edit the field "City Name". Note that the name will only show up after you launch the VR experience.
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.
- Menu
Opens the menu which allows for changing Urban Events and Branches, adjust the time of day and rotate the table. See also the Changing Scenarios, Rotate the table and the Adjusting Time of Day sections. - Trackpad
Swiping left or right will change the active scenario of your city model. See also the Changing Scenarios section. - Home Button
- Power Indicator
- Power Plugin
- Controller Sensors
- Trigger Button
The trigger button is used for teleportation, for panning and scaling the city and for interacting with UI elements such as handles and menu sliders. - Grip Button
Locomotion
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 cannot 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:
Changing Plans and Scenarios
You can select a plan by aiming your laser pointer at an object indicated by a yellow outline and then pressing the Trigger Button. Alternatively you can select the plan in the Plans part of the menu. To change the scenario, select the slider in the menu and move the indicator to the desired scenario. If you want to get an overview of all plans again, you can use the Zoom Out button, this will bring you back to the initial overview.
Points of Interest
To navigate to a dedicated point of interest, aim the laser at a teleportation target and press the Trigger Button.
If you are inside the city model you can display all teleportation targets by opening the menu using the Menu button and then pressing the Viewports button. A portal for each available point of interest will appear. Point at one of the portals and press the Trigger Button to teleport there.
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.
Known Issues
Blurry Textures in Packaged Build
In some cases the textures are not streamed in correctly and appear blurry in the packaged build. This can be fixed by dragging the Blueprints/BP_TextureStreamingFix Actor into the scene (as show in screenshot below). This should fix the issue but will increase the initial startup phase by roughly 10 seconds.
CityEngine VR Experience for Unreal Engine Release Notes
CityEngine VR Experience 2021.1 (2021-11-05)
- Update: Support for Unreal Engine 4.27 (and dropped support for earlier versions)
- Update: Support for Oculus Quest 2 + Link
- Bugfixes
CityEngine VR Experience 2020.0 (2020-08-13)
- Update: Support for Unreal Engine 4.25 (and dropped support for earlier versions)
- Update: Support for Oculus Quest + Link
- New feature: Table navigation (zoom, rotate) with controller thumbstick
- New feature: Free movement (in view direction, also vertically and in-air) with controller thumbstick
- New feature: Support for bird's eye viewpoints
- Bugfixes
CityEngine VR Experience 2019.1.1 (2020-02-26)
- Update: Support for Unreal Engine 4.24 (and dropped support for earlier versions)
- Update: Use UE4 4.24's sky atmosphere model
- Bugfixes
CityEngine VR Experience 2019.1 (2019-11-19)
- Update: Support for Unreal Studio 4.23 (and dropped support for earlier versions)
- New feature: HP Reverb support (Windows Mixed Reality)
- New feature: Oculus Rift S support
- New feature: Completely redesigned and enhanced UI/UX
- New feature: Support for multiple plans and scenarios
- New feature: CityEngine export and UE4 import of multiple plans and scenarios at once
- New feature: Display of outline for scenarios and plans
- New feature: Onboarding experience with step by step explanation
- New feature: Automatically create VR materials after import
- New fearure: Non-VR level with metadata support
- Update: Improved sun position and day light simulation
- Update: Improved teleporting
- Update: Unified controllers for Steam VR, Oculus Rift / Rift S, HP Reverb
- Update: Expose UI settings to the level controller
- Update: Instanced mesh support
- Update: Consolidated documentation on GeoNet
- Bugfixes
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
