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.

Want to skip the step-by-step and see what Cesium for Unreal can do? Download the Cesium for Unreal Samples project.

This guide was written for Unreal Engine 5.1. If you are using a later version of Unreal Engine, the steps will still be the same, though your user interface may look different from the screenshots in this guide.


Still using Cesium for Unreal v1? We recommend upgrading as soon as possible, but you can find the tutorial for the old version here.

A Cesium for Unreal level with Cesium World Terrain and Cesium OSM Buildings, set in Chicago.

You’ll learn how to:

  • Install the Cesium for Unreal plugin to Unreal Engine
  • Create a level and import assets from Cesium ion
  • Set your project's default ion asset token
  • Add lighting to your app with CesiumSunSky
  • Navigate your level with Cesium's DynamicPawn


  • An installed version of Unreal Engine (at least 5.1 or later). For instructions on installing 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.

1Install the Cesium for Unreal plugin

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, then click on the Free button to install the plugin on your Unreal Engine account. Then, click the Install to Engine button to add the plugin to your Unreal Engine installation.

2Create a Cesium for Unreal project

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. The Project Defaults section will allow you to further configure your project. For a simple setup, uncheck Starter Content.

A screenshot of creating a new project in Unreal Engine.

Once you have finished configuring your project, click the Create button. Your new project will open.

2Once the project is fully loaded, activate the Cesium for Unreal plugin. Open the Plugins window (Edit -> Plugins) and search for “Cesium” in the search bar at the top of the Plugins window. Make sure that the checkbox next to the plugin is checked. You may need to restart Unreal Engine after enabling the plugin.

A screenshot of the plugin search box and the "enabled" checkbox for the Cesium for Unreal plugin.

3After restarting the Editor with the Cesium for Unreal plugin activated for the first time, you may see an error related to the Water Body Collision profile. Click the Add entry to DefaultEngine.ini link to fix it.

A screenshot of the "Collision Profile settings do not include an entry for the Water Body Collision profile, which is required for water collision to function" error that may appear when the Cesium for Unreal plugin is first activated.

3Prepare the project and level

1Create a new level (File -> New Level). When prompted, select "Empty Level" to make sure there are no objects in the level.

2Disable the World Bounds Checks. This option is found in World Settings (Window -> World Settings), in the World -> Advanced category.

A screenshot showing the "Enable World Bounds Checks" option in the World Settings.

With Enable World Bounds Checks ON, Unreal Engine will attempt to fly a Pawn that is far from the origin back toward the origin. In most Cesium applications, being far from the origin is completely normal, and this automatic behavior prevents the Pawn from going where the user wants it to go.

3Open the Cesium panel by clicking Window -> Cesium.

A screenshot showing the Cesium option on the Window menu.

You'll need to add some lighting so you'll be able to see the tilesets you add in later steps. Cesium for Unreal comes with a premade, globe-aware sun and atmosphere system called CesiumSunSky.

4You can add Cesium for Unreal actors directly to your level from the Cesium panel. In the Quick Add Basic Actors section of the panel, find Cesium SunSky and click the button to add it to the level. You should see a skylike gradient appear in the viewport.

A screenshot of the Cesium panel highlighting the button used to add a Cesium SunSky to the level.
A screenshot of the skylike gradient that appears when the Cesium SunSky has been added and is working correctly.

Did your viewport turn solid white - and stay that way - after adding the Cesium SunSky? CesiumSunSky uses realistic light intensity values, which are much brighter than standard Unreal projects. As a result, with some project settings, the light will wash out scenes and make them appear white. To fix this, enable the Auto Exposure and Extend default luminance range in Auto Exposure settings options. You can find these options by going to Edit -> Project Settings, then navigating to Engine -> Rendering and scrolling down to the Default Settings section.

A screenshot of the "Auto Exposure" and "Extend default luminance range in Auto Exposure settings" options in the Project Settings.

Alternatively, you can reduce the intensity of the sun lighting to a more reasonable but less realistic value. Click on the CesiumSunSky actor. In the Details panel, find the Directional Light component and reduce the light's Intensity to 10.0.

5Now is a good time to save your level. Click the Save the current level to disk button in the top-left corner of the Editor, or press Ctrl+S. Give your level a name. You may also want to set your new level as the project's default map. This will make sure that your level will automatically open when you restart the project or package and run your application. In the Edit -> Project Settings window left sidebar, click on Maps & Modes, then look for the Default Maps section. Change both the Editor Startup Map and the Game Default Map to your new level.

A screenshot of the "Editor Startup Map" and "Game Default Map" project settings.

4Connect to Cesium ion

1Return to the Cesium panel that you opened in the previous step. Click on the Connect to Cesium ion button.

A screenshot showing the "Connect to Cesium ion" button.

2A pop-up browser window will open. If you are not logged in, log in to your Cesium ion account. You can also sign in with your Epic Games, GitHub, or Google account.

3Once you are logged in, you'll see a prompt asking you to allow Cesium for Unreal to access your assets. Select Allow, then return to Unreal Engine to continue.

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

4Now, you'll create a default Access Token for your project. Every asset that you stream from Cesium ion requires an Access Token. In this tutorial, you'll set a project-wide access token that all your assets will use.
Click on the Token button at the top of the Cesium panel.

A screenshot showing the button on the Cesium panel to open the Token panel.

5A new window will appear to configure the token. Select the Create a new token option, and rename the token if you wish. Then, press the Create New Project Default Token button.

A screenshot showing the "Create a new token" section and the "Create New Project Default Token" button on the Token panel.

The new token you created will be added to your Cesium ion account.
If you already have a token in your Cesium ion account that you would like to use, you can select it from the "Use an existing token" dropdown instead of creating a new one.


Tokens created by Cesium for Unreal access only the assets that you allow. This follows security best practices for your Cesium ion account. Whenever you use the Cesium panel or Cesium ion Assets panel to add an asset to your level, Cesium for Unreal will automatically update the appropriate permission for the token.
You may choose to manually configure your token and add or remove assets using the Access Tokens page on Cesium ion.

5Create a globe

You are ready to add an asset from Cesium ion.

1Using the Cesium panel, add "Cesium World Terrain + Bing Maps Aerial imagery" by clicking the button next to that entry.

A screenshot showing the button to add "Cesium World Terrain + Bing Maps Aerial imagery" to the level.

Terrain will appear in the level.

A screenshot showing terrain in the Editor viewport after Cesium World Terrain has been added.

2Take a look at the Outliner on the right. Along with the CesiumSunSky you added earlier, you'll see a variety of Cesium actors. One of them, Cesium World Terrain, is the tileset you just created. The other three—CesiumCameraManager, CesiumCreditSystemBP, and CesiumGeoreference—are created automatically the first time you add a 3D Tileset or georeferenced actor to the level.

3If Cesium World Terrain is not already selected, select it now. In the Details panel, you'll see more information about this actor.

A screenshot showing the settings on a Cesium3DTileset.

This is a Cesium3DTileset actor. It streams 3D Tiles data into Unreal Engine, and provides a way to configure that tileset.
You'll learn about many of the available settings in later tutorials. For now, feel free to explore and test out different settings. Hover over a setting with your mouse to learn more about what it does.
Once you're ready, continue to the next section.

6Add global 3D buildings to your level

It's time to leave these picturesque hills behind and head to the big city.

1Select the CesiumGeoreference actor in the Outliner. This actor determines where in the world your level is set. The level's current latitude, longitude,  and height can be changed with this actor.

2In the Details panel, look for the Origin Latitude, Origin Longitude, and Origin Height variables under the Cesium category.

A screenshot showing the Origin Longitude, Latitude, and Height properties on a CesiumGeoreference.

The current values of these variables are set to the hills outside Denver, Colorado, USA.

3Change these variables to the coordinates of your favorite city—or use these coordinates to travel to Chicago, Illinois, USA.
Origin Latitude = 41.878101
Origin Longitude = -87.59201
Origin Height = 1000.0
After entering these coordinates, you'll find the level has shifted to this new location.

A screenshot of the view in Chicago, Illinois after updating the CesiumGeoreference origin.

4The city looks very flat. Cesium World Terrain doesn't include building detail. Fortunately, Cesium OSM Buildings can come to the rescue.
From the Cesium Quick Add panel, add Cesium OSM Buildings to the level.

A screenshot showing the view after Cesium OSM Buildings is added to the level.

7Explore your level

In this section, you'll learn how to navigate your level in the editor and during play. You'll also learn about the Dynamic Pawn, a controller included in the Cesium for Unreal plugin to help you navigate the Earth's immense size.

1To move the viewport's camera, click and hold the right mouse button in the viewport window. While holding the right mouse button down, you can look around by moving the mouse and fly around by pressing the W, A, S, and D keys on your keyboard. You can modify the camera speed using the mouse scroll wheel.
You can also modify the camera speed in larger increments using the Camera Speed settings in the top-right corner of the viewport.

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

If you're having trouble navigating the viewport, check out the Unreal Engine Viewport Controls documentation.

2If you pressed the Play button, you'd notice that the default camera speed is very slow, and not adjustable. Given the scale that real-world data can be, you'll need a different Pawn to efficiently navigate the level during play.
Using the Cesium panel, add a Dynamic Pawn.

A screenshot showing the button used to add a Dynamic Pawn to the level.

Q: What is the Dynamic Pawn?
Cesium's DynamicPawn actor extends the built-in pawn class by making it globe-aware. The DynamicPawn also adds important movement functionality, such as the ability to adjust movement speed with the mouse wheel and the ability to fly between global locations along a curved path.

3The DynamicPawn is a georeferenced actor. It maintains its position relative to its coordinates on the globe and not the standard Unreal Engine world coordinates. This means that if you change the Georeference Origin to a different location, the DynamicPawn will stay behind. If you'd like to move it to your new location, select it in the Outliner and set its Location X, Y, and Z coordinates to 0, or use the grey arrow to reset its position to the origin.

A screenshot showing the user interface to edit the position of the Dynamic Pawn.

4You're ready to test out your level!
Press the Play button at the top toolbar. Similar to the viewport controls, you can use the W, A, S, and D keyboard keys and the mouse to fly around. Use the mouse scroll wheel to change your speed.
You've created your first project with Cesium for Unreal. Feel free to explore and check out the world!

Next steps

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

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