Cesium for Unreal Quickstart
This is a quickstart guide to building a Cesium for Unreal app with Cesium World Terrain and Cesium OSM Buildings.
You’ll learn how to:
- Install the Cesium for Unreal plugin in Unreal Engine
- Add a level and import assets from Cesium ion
- Add photorealistic lighting to your Cesium for Unreal app
- An installed version of Unreal Engine (at least 4.26 or later). For instructions on how to install Unreal Engine, visit the Unreal Engine download page and refer to the Installing Unreal Engine guide for detailed instructions.
- A Cesium ion account to stream terrain and building assets into Unreal Engine. Sign up for a free Cesium ion account if you don’t already have one.
Cesium ion is an open platform for streaming and hosting 3D content, and includes global, curated data that you can use to create your own real-world applications.
Step 1. Install the Cesium for Unreal plugin and create your first project
Start by installing the Cesium for Unreal plugin if you haven’t already.
Open the Cesium for Unreal plugin page on the Unreal Engine Marketplace.
Sign in if needed and click on the Free button to install the plugin on your Unreal Engine account.
Step 2. Create the project and level
Launch Unreal Engine and create a new project. Select Game as the New Project Category and Blank as the Template. Other configurations will also work.
Choose No Starter Content to avoid cluttering the level with unneeded content.
Activate the Cesium for Unreal plugin. Go to Edit -> Plugins and search for “Cesium” in the search bar at the top-right corner of the Plugins window. Make sure that the Enabled checkbox for the plugin is checked. You may need to restart Unreal Engine after enabling the plugin.
If the level contains any objects, use the World Outliner to remove them so that we start with an empty level.
Save your level by clicking File -> Save Current and giving it a name.
Go to Edit -> Project Settings and search for “default”. Set the level you saved above as the Editor Startup Map and the Game Default Map. This ensures your level will be re-opened automatically when Unreal Editor is restarted.
Step 3. Add SunSky lighting and a FloatingPawn
The CesiumSunSky Actor adds beautiful lighting to outdoor scenes. It extends the built-in SunSky Actor by making it globe-aware. Similarly, Cesium’s FloatingPawn extends the built-in FloatingPawn by making it globe-aware and by allowing control of movement speed with the mouse wheel, which is essential when moving across large distances.
When the camera is in flight between locations over the Cesium globe, the camera should follow a curved path parallel to the Earth’s surface, rather than a linear point-to-point trajectory. A Cesium FloatingPawn can be used to achieve this behavior.
Go to Edit -> Project Settings and search for “luminance”. Make sure the option Extend default luminance range in Auto Exposure settings is enabled. Without this option enabled, a level lit with SunSky will be completely washed out when it’s in full sunlight. You may need to restart Unreal Engine after enabling this option.
Open the Content Browser by clicking Window -> Content Browser -> Content Browser 1. Click View Options in the lower-right corner and make sure Show Engine Content and Show Plugin Content are both checked.
Still in the Content Browser click the Choose a path button and then scroll down to find and click CesiumForUnreal Content.
Drag the CesiumSunSky and FloatingPawn into the level viewport to add them to the level.
Step 4. Auto-possess the FloatingPawn at level start
In the step above, you added a FloatingPawn to the level, but there are some additional steps necessary to be able to use it to move around the world.
Select the FloatingPawn in the World Outliner.
Set the Floating Pawn to auto-possess Player 0 actor so that in Game mode, the Floating Pawn can be controlled with the mouse and keyboard. In the Details panel, search for “possess”. Select the dropdown next to Auto Possess Player and select Player 0.
Step 5. Connect to Cesium ion
Open the Cesium panel by clicking the icon in the toolbar.
The Cesium panel will show up on the left side of the editor window.
Connect to Cesium ion with the Connect button. A pop-up browser will show, asking you to allow Cesium for Unreal to access your assets with the currently logged-in account from Cesium ion:
Select Allow and head back to Unreal Engine to continue with the next steps.
Step 6. Create a globe
In this step, you will populate the scene with assets from Cesium ion.
Open the Cesium panel by clicking the button in the toolbar. From the Quick Add window, click on “Cesium World Terrain + Bing Maps Aerial imagery” (feel free to add one of the other Cesium World Terrain + imagery combinations).
This step will generate new Cesium World Terrain and CesiumGeoreference actors in the World Outliner.
There may be a black strip near the horizon. To fix this, select the CesiumGeoreference actor, look for Sun Sky in the Details panel, and initialize it with the new CesiumSunSky actor.
Once the CesiumSunSky actor is connected to the CesiumGeoreference actor, its latitude and longitude variables are modified automatically to keep the globe and the sun in sync.
Adjust the Solar Time property on the CesiumSunSky Actor if the scene is too dark, or to set up a beautiful sunset scene. You may also want to change the Time Zone.
For more information on how these properties work, visit the SunSky actor documentation on the Unreal Engine documentation site.
Step 7. Add global 3D buildings to your scene
In this step, you will add Cesium OSM Buildings on top of the Cesium World Terrain. Similar to step 6, you will use the in-editor Cesium UI to add the new asset.
Navigate back to the Cesium UI in Unreal Engine. Instead of using the Quick Add window like in the previous step, you will use the Cesium ion Assets window to add Cesium OSM Buildings. At the top left corner, click Add to switch to the Cesium ion Assets window. Here you will see all the assets present in your Cesium ion account.
Select Cesium OSM Buildings and click on Add to Level.
Again, you will see that Cesium OSM Buildings is now added to the World Outliner.
Is Cesium OSM Buildings missing from the asset list? Visit the Cesium OSM Buildings Asset Depot page and click Add to my assets. Then return to Unreal Engine, close the Cesium ion Assets panel, and click the Add button again on the Cesium panel to re-open and refresh the asset list.
If you are unable to see the buildings, you might be in a part of the world where there are no buildings. To navigate to a different part of the world, click on the CesiumGeoreference actor in the World Outliner. In the Details panel, look for the Origin Longitude, Origin Latitude, and Origin Height variables under the Cesium category.
Adjust those variables to the values of a location that you would like to be in. For instance, the buildings below are in Chicago, IL, USA at longitude = -87.629799, latitude = 41.878101, and height = 2250.0.
When you set the Georeference origin, the Editor camera will jump there immediately. However, the FloatingPawn will adjust itself so that maintains its previous location on the globe in spite of the change in origin. If you would like to start in Chicago when you press Play, click the FloatingPawn in the WorldOutliner and set its Location to (0, 0, 0).
Press the Play button at the top toolbar and then use the W, A, S, and D keyboard keys and the mouse to fly around and check out the world! Move the mouse wheel up and down to change the camera speed depending on the distance you’re trying to cover. You can also change the speed of the editor camera using the controls at the top right corner of the editor viewport.
Now you are ready to add more assets and customize the scene! Continue on to Adding Photogrammetry.