Cesium for Unreal Quickstart
This is a quickstart guide to building a Cesium for Unreal app with Cesium World Terrain and Cesium OSM Buildings.
Video version of this tutorial. We suggest you follow along in the written tutorial below too—it includes hints not in the video.
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
Prerequisites
- 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.
Start by installing the Cesium for Unreal plugin if you haven’t already.
1Open the Cesium for Unreal plugin page on the Unreal Engine Marketplace.
2Sign in if needed and click on the Free button to install the plugin on your Unreal Engine account.
1Launch 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.
2Activate 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.
3If the level contains any objects, use the World Outliner to remove them so that we start with an empty level.
4Save your level by clicking File -> Save Current and giving it a name.
5Go 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.
1Open the Cesium panel by clicking the icon in the toolbar.
The Cesium panel will show up on the left side of the editor window.
2Connect 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.
In this step, you will begin to populate the scene with assets from Cesium ion.
1Open the Cesium panel by clicking the button in the toolbar. From the Quick Add window, click on “Cesium World Terrain + Bing Maps Aerial imagery” (Or, try adding one of the other Cesium World Terrain + imagery combinations).
This step will generate new Cesium World Terrain and CesiumGeoreference actors in the World Outliner. You should also see terrain appear in the Scene View, though it will appear unlit. Proceed to the next step to add lighting to your scene.
The CesiumSunSky Actor adds beautiful lighting to outdoor scenes. It extends the built-in SunSky Actor by making it globe-aware.
1Go 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.
2Return to the Cesium panel. Add a CesiumSunSky actor to the scene.
Most of the Cesium for Unreal content that you will need can be accessed from the Cesium panel. Looking for the rest of the plugin content? Open the Content Browser. Ensure Show Engine Content and Show Plugin Content are both checked in the View Options in the lower right corner of the Content Browser, then find the Cesium for Unreal Content folder.
The scene may appear white for a moment as the auto exposure adjusts. When it has settled, you should see a sky and atmosphere lighting the terrain.
3There may be a black strip near the horizon. To fix this, select the CesiumGeoreference actor, look for SunSky in the Details panel, and ensure it is set to your 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.
4Adjust 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 Using a Geospatially Accurate Sun tutorial or the Unreal Engine SunSky actor documentation.
Cesium’s DynamicPawn extends the built-in pawn class 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 DynamicPawn can be used to achieve this behavior. (See Transition Between Locations on the Globe to learn how.)
1With the Cesium panel open, add a Dynamic Pawn. The pawn will appear in the World Outliner and the Scene View.
2Select the DynamicPawn in the World Outliner.
3Ensure the DynamicPawn will auto-possess Player 0. In the Details panel, search for “possess.” Select the dropdown next to Auto Possess Player and select Player 0.
Doing this will make sure that in Play mode, the DynamicPawn can be controlled with the mouse and keyboard.
You might see mentions of a FloatingPawn in some documentation or plugin content. The FloatingPawn has been deprecated and replaced with DynamicPawn as of Cesium for Unreal version 1.3.0.
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.
1Navigate 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.
2Select 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.
3If 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 DynamicPawn 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 DynamicPawn in the WorldOutliner and set its Location to (0, 0, 0).
4Press 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 Datasets.