Skip to main content

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.
Information

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.

1Install the Cesium for Unreal plugin and create your first project

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.

A screenshot of Cesium for Unreal in the Unreal Engine marketplace.

2Sign in if needed and click on the Free button to install the plugin on your Unreal Engine account.

2Create the project and level

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.

A screenshot of Unreal Engine project categories
A screenshot of the Unreal Engine template selector dialog

Choose No Starter Content to avoid cluttering the level with unneeded content.

A screenshot of the Unreal Engine project settings dialog

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.

A screenshot of the "enabled" checkbox for the Cesium for Unreal plugin

3If the level contains any objects, use the World Outliner to remove them so that we start with an empty level.

A screenshot of the World Outliner dialog

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.

A screenshot of the Unreal Engine default maps settings dialog

3Connect to Cesium ion

1Open the Cesium panel by clicking the icon in the toolbar.

A screenshot showing the Cesium for Unreal icon in the Unreal Engine toolbar

The Cesium panel will show up on the left side of the editor window.

A screenshot of the Cesium for Unreal panel in Unreal Engine

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:

A screenshot of the Cesium for Unreal permissions panel in Unreal Engine

Select Allow and head back to Unreal Engine to continue with the next steps.

4Create a globe

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).

Screenshot of the Quick Add dialog in Unreal Engine

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.

5Add lighting with CesiumSunSky

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.

A screenshot of the Unreal Engine default luminance dialog

2Return to the Cesium panel. Add a CesiumSunSky actor to the scene.

Information

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.

Screenshot of the CesiumGeoreference actor configuration dialog in Unreal Engine
Information

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.

Screenshot of the CesiumSunSky actor configuration dialog in Unreal Engine

For more information on how these properties work, visit the Using a Geospatially Accurate Sun tutorial or the Unreal Engine SunSky actor documentation.

6Add a DynamicPawn

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.

A screenshot of configuring the FloatingPawn in Unreal Engine
Information

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.

7Add 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.

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.

Screenshot of the Quick Add dialog in Unreal Engine

2Select Cesium OSM Buildings and click on Add to Level.

Screenshot of the Cesium ion Assets selector dialog in Unreal Engine

Again, you will see that Cesium OSM Buildings is now added to the World Outliner.

Information

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 LongitudeOrigin Latitude, and Origin Height variables under the Cesium category.

Screenshot of the CesiumGeoreference actor configuration dialog in Unreal Engine with location fields highlighted

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.629799Latitude = 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).

Screenshot of the FloatingPawn actor configuration dialog in Unreal Engine

4Press the Play button at the top toolbar and then use the WAS, 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.

Screenshot of the camera speed control in the editor viewport of Unreal Engine

Next steps

Now you are ready to add more assets and customize the scene. Continue on to Adding Datasets.

Content and code examples at cesium.com/learn are available under the Apache 2.0 license. You can use the code examples in your commercial or non-commercial applications.