Skip to main content

Building Global Scenes with Georeferenced Sublevels

This tutorial shows you how to start building georeferenced sublevels across the Cesium globe that you can seamlessly stream in and out. You will visit Denver, Boston, the Grand Canyon, and any other places of your choice. Within each sublevel, you are free to build game mechanics and scenery just as you typically would in Unreal.

Build sublevels across the world and seamlessly explore them.

Prerequisites

  • Know how to set up a basic Cesium for Unreal application. If you are new to Cesium for Unreal, check out the Cesium for Unreal Quickstart to learn how to install Cesium for Unreal, connect it with Cesium ion, and create a simple world.
  • A Cesium ion account to stream real-world data into Unreal Engine.
  • Have completed the previous Cesium for Unreal Getting Started Tutorials in order. Especially make sure that you have a good sense of georeferencing and object placement in Cesium for Unreal.

Introduction

So far the tutorials have covered several ways to build projects and explore 3D Tiles tilesets in Cesium for Unreal. However, up until now you have been limited to building Unreal scenes centered around only one location on the globe at a time. This central location so far has been determined by the CesiumGeoreference actor that you may have seen in the World Outliner. To be more precise, the job of the CesiumGeoreference is to put this “central location” at the Unreal origin. As you get further away from this origin, things will get weird fast. The down-direction used to determine gravity will become incorrect, physics will become jittery, and exact placement of Unreal objects will start to become imprecise.

While these limitations do not exist for georeferenced objects such as 3D tilesets, the DynamicPawn, and actors with a CesiumGeoreferenceComponent (learn more about georeferenced objects here), many Unreal tools you may want to use including the built in physics-engine, the SunSky system, and object placement will fall apart once you are sufficiently far from the origin.

The purpose of this tutorial is to introduce a way to overcome these issues. Creating georeferenced sublevels allows us to specify a unique “central location” per sublevel. Each sublevel can then support all the physics, foliage, and game-logic you are used to in Unreal Engine. After this tutorial you will be able to:

  • Create a persistent global level
  • Put several local sublevels within the persistent level
  • Fill each sublevel with assets and game-logic using your typical Unreal workflow
  • Seamlessly fly between sublevels as well as explore the persistent level
  • Stay aware of pitfalls along the way

1Create a world composition project

Setting up georeferenced sublevels requires some extra preparation steps that are not covered in the Quickstart tutorial.

1First, create a new project with a completely empty level and delete any default actors that showed up in the World Outliner.

Cesium for Unreal sublevels to remove

2Go to the Content Browser and create a folder within your project’s Content folder called World. Save the empty level inside this folder, name this level Globe. This will be the Persistent Level going forward, it will represent the entire earth.

3Go to the Settings icon in the toolbar and click World Settings.

Cesium for Unreal sublevels world settings

4Search for Enable World Composition and enable it.

Cesium for Unreal sublevels world composition

5Now still in World Settings, search for Enable World Bounds Check and disable it. Objects may move very large distances in the global-scale world of Cesium for Unreal. Disabling World Bounds Check ensures that Unreal does not delete objects that travel very far from the origin.

Cesium for Unreal sublevels world bounds

6Now bring up the levels panel by going to Window and clicking Levels.

Cesium for Unreal sublevels levels menu

7Next, in the Levels panel, click Summon World Composition.

Cesium for Unreal sublevels summon comp

8In the World Composition window that was just opened, create a new layer that has Streaming Distance disabled (the CesiumGeoreference will take care of deciding when to load sublevels). Name the new layer CesiumLayer.

Cesium for Unreal sublevels new layer
Information

If you accidentally leave Streaming Distance enabled, you will have to create a new layer. Currently, there is no way to edit a layer’s settings once it has been created.

9To finish setting up the project, make sure you are logged in to Cesium ion within Unreal. If you are unsure how to do this, read Step 5 of the Quickstart tutorial.

Cesium for Unreal sublevels Cesium ion

2Set up the persistent global level

If you have been going through the Cesium for Unreal Getting Started Tutorials in order so far, everything in Step 2 should be familiar. If anything is unexpected or confusing, follow the links provided for more detailed instructions.

1Now that the project is set up and you are logged in, it’s time to fill the persistent global level with real world data from Cesium ion. First add Cesium World Terrain With Bing Aerial Imagery to the scene, this will be the global base-terrain with satellite imagery. If you are unsure how to do this, read Step 6 of the Quickstart tutorial.

Cesium for Unreal sublevels cwt no light

2Since the level has no lighting yet, add the CesiumSunSky actor to the scene. If you are unable to find the correct actor or your screen appears completely white, please follow the instructions in Step 3 of the Quickstart tutorial. Once the CesiumSunSky is added to the scene and the extended luminance range setting is enabled, you should be able to see the picturesque foothills of Denver under a beautiful blue sky.

Cesium for Unreal sublevels denver foothills

3The CesiumSunSky is not yet correctly georeferenced to the globe, which may eventually cause strange lighting issues. To fix this, find the default CesiumGeoreference actor in the World Outliner and navigate to its Details panel. Under the Cesium Sun Sky section, set the Sun Sky property to the CesiumSunSky actor that was added to the scene in the last step.

Cesium for Unreal sublevels sunsky geo

4In order to set up a few detailed, real-world locations to start building sublevels on, import the Aerometrex Denver Photogrammetry and Nearmap Boston Photogrammetry 3D Tilesets. For a quick refresher on how to search for and add 3D Tilesets from Cesium ion check out the Adding Datasets tutorial. You can always double-click 3D Tilesets in the World Outliner to jump the editor camera to the location of the tileset.

Cesium for Unreal sublevels denver city

The Aerometrex Denver Photogrammetry 3D Tileset.

Cesium for Unreal sublevels boston

The Nearmap Boston Photogrammetry 3D Tileset.

Information

Are either the Aerometrex Denver Photogrammetry or Nearmap Boston Photogrammetry missing from the asset list? Visit the Cesium ion Asset Depot page, find the photogrammetry tilesets, and click Add to my assets on both. 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.

5In order to fly around the entire earth without becoming disoriented, add a DynamicPawn actor to the scene and set Auto Possess Player to Player 0 in the Details panel. This pawn adjusts its orientation as it is flown around the earth to always maintain the appropriate up direction. If you are having trouble finding the DynamicPawn actor, see Step 3 of the Quickstart tutorial.

Cesium for Unreal sublevels dynamic pawn

3Set up a georeferenced sublevel

1You are ready to start creating the first georeferenced sublevel. First, move the editor camera to the location you are interested in building the first sublevel. This can be done by adjusting the editor camera speed and directly flying to the location in the editor or by double-clicking on the photogrammetry tileset you want to visit. If you know the WGS84 coordinates for where you want to set the location, you can directly enter this in the CesiumGeoreference details panel. For this tutorial, we will double-click on the Aerometrex Denver Photogrammetry tileset in the World Outliner to quickly move there. You are free to pick any location for your first sublevel.

Cesium for Unreal sublevels denver double click
Information

Does the globe look sideways or upside down in the editor viewport after flying or teleporting across the earth? Hit the Place Georeference Origin Here button in the Details panel of the CesiumGeoreference actor to set the current editor camera position as the new central location. But be careful about doing this after placing Unreal assets in the world, it’s possible to lose the intended placement of objects if they are not properly georeferenced first. For a more comprehensive overview of georeferencing and object placement, check out the Cesium for Unreal object placement tutorial.

2Now that you are in the general area of interest, fly the editor camera to a particular spot you want to build the sublevel at and once again press the Place Georeference Origin Here button. For this tutorial, we are going to fly to this skyscraper’s rooftop in downtown Denver.

Cesium for Unreal sublevels denver rooftop

3Next, go back to the Levels panel and create a new sublevel. Create a folder within the World folder called Sublevels, and save the new level into this folder.

Cesium for Unreal sublevels create sublevel

Create the new sublevel.

Cesium for Unreal sublevels sublevels folder

Create the Sublevels folder in the World folder.

4In the Levels panel, double-click on the new sublevel to load it. Then, right-click on the sublevel, go to Assign to Layer, and pick CesiumLayer (or whatever you named your custom levels layer in Step 1.8).

Cesium for Unreal sublevels assign layer
Cesium for Unreal sublevels sublevel save

Save the sublevel in the Sublevels folder.

Information

If the sublevel is not added to a levels layer with Streaming Distance disabled, you may notice the sublevel occasionally spawning very far out of place in play-mode. If you notice this at any time, check if all sublevels are properly placed in your custom levels layer and check that it has Streaming Distance disabled.

5At this point, the sublevel is created and the central location wanted for your sublevel is correctly set on the CesiumGeoreference actor. To georeference the sublevel (i.e., to lock the current alignment of the sublevel with the globe), go to the Details panel of the CesiumGeoreference actor and press Check for New Sublevels.

Cesium for Unreal sublevels check for sublevels

Georeference the sublevel by pressing Check for New Sublevels.

Cesium for Unreal sublevels sublevel properties

Once the sublevel is successfully georeferenced, you should be able to see a new entry in the Cesium Sublevels array.

6You should now see a blue wire-frame sphere. The sphere is centered around the sublevel’s “central location” (i.e., georeference) and its radius is determined by the Load Radius property in the sublevel’s entry in the Cesium Sublevels array. This sphere designates the area the player camera has to enter in order for the level to be loaded. You are free to expand or shrink the Load Radius as needed for your use case.

Cesium for Unreal sublevels load radius

4Pitfalls to avoid

Information

Refer to this list of pitfalls anytime you run into problems while using georeferenced sublevels.

Building inside a georeferenced sublevel is just as easy as building in general within Unreal, but there are a few potential pitfalls to be aware of before you can start on the fun part:

Changing the CesiumGeoreference world origin should be avoided while actively building a sublevel.

  • At best, it will cause a slightly annoying sublevel misalignment which can be fixed by typing in the appropriate Current Level Index or pressing Jump To Current Level. At worst, the alignment of recently added objects will be completely lost.

Be careful not to accidentally change or delete any of the sublevel georeferences in the Cesium Sublevels array on the CesiumGeoreference actor.

  • Doing so will cause assets that were previously placed in the sublevel to no longer appear where they were originally placed.

To check if recently placed assets have been added to the sublevel correctly, toggle the visibility icon next to the sublevel in the Levels panel; the assets should disappear when the level is hidden.

  • If you find that you have placed a number of assets into the persistent global level by accident instead of a given sublevel, select all the misplaced assets, right-click on the desired sublevel in the Levels panel, and click Move Selected Actors to Level. Be careful with foliage in particular as it tends to add itself to the same level as the geometry it’s drawn on, which often ends up being the persistent global level.

Be careful not to add already georeferenced objects into a georeferenced sublevel.

  • In particular, do not place Cesium 3D Tileset actors, DynamicPawns, or otherwise any actors with a CesiumGeoreferenceComponent attached into a georeferenced sublevel. These should only ever be placed in the persistent global level. The purpose of georeferenced sublevels is particularly to provide a way to georeference asset types that cannot be georeferenced in the typical way described in the Placing Objects on the Globe tutorial.

5Building within a georeferenced sublevel

1Make sure your sublevel is loaded and set as the current level by double-clicking it in the Levels panel. In this example, we added a few props and a third-person controller on this Denver building’s rooftop. Feel free to add your own characters, vehicles, foliage, physics objects, and game logic. Look to the adding custom controllers tutorial for some inspiration.

Cesium for Unreal sublevels rooftop scene

A simple Unreal scene set up on the rooftop.

Cesium for Unreal sublevels man on street

Explore the real-world data with any of your own characters or vehicles.

2Press Play, and try flying the DynamicPawn all the way into space and then finding your sublevel again. You may need a map!

6Creating multiple sublevels

The real usefulness of georeferenced sublevels becomes apparent once you build multiple sublevels.

1You are ready to save your current sublevel and start building a new one. Check once again that all intended assets are in the correct sublevel. Move assets between levels as needed if you find that any assets are in the wrong level. Press Ctrl + Shift + S to save both the sublevel and persistent global level. Now, right-click on the sublevel in the Levels panel and select Unload.

Cesium for Unreal sublevels unload level
Information

When working in the editor, only one georeferenced sublevel should be loaded at a time. If multiple sublevels with different georeferences are simultaneously loaded and visible, they will confusingly appear on top of each other in the editor. This is not an issue during play.

2Now repeat parts of Step 3 as needed to build your next sublevel. Remember to save all sublevels in the Content/World/Sublevels/ folder. Again, you are free to build this sublevel wherever you would like. We built the next sublevel on a soccer field in Boston.

Cesium for Unreal sublevels boston sublevel

A simple scene with grass, trees, characters, a vehicle, and two cubes for goalposts.

In play-mode you can again see that the whole world is explorable. Any sublevels you create can be visited by simply flying there.

3You are free to create as many more sublevels as you like. Get used to the steps involved and make note of common mistakes to avoid them in the future. Try creating one last sublevel at the Grand Canyon. As usual, make sure to properly save and unload the previous level first. Then, set the origin of the CesiumGeoreference actor to the following coordinates:

Origin Latitude = 36.056595

Origin Longitude = -112.118392

Origin Height = 2200

From there, fly to the particular location you want to build the sublevel, press Place Georeference Origin Here, and set up a new sublevel in the usual way.

Cesium for Unreal sublevels grand canyon

Another simple example of building a sublevel.

Learn how to use the DynamicPawn’s fly-to functionality in the next tutorial.

Next steps

In the global-scale world provided by Cesium for Unreal, it is easy to become lost when aimlessly flying around. Fortunately, using the georeferencing system built into Cesium for Unreal, it is straight forward to not only determine your location on the globe, but also to move towards a target location. This is especially easy when using the fly-to functionality of the DynamicPawn. Check out the next tutorial in the series to learn how to transition between global locations.

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.