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 number of other places of your choice. Within each sublevel, the freedom will be all yours to build game mechanics and scenery just as you typically would in Unreal.
Build sublevels across the world and seamlessly explore them.
- 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.
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 FloatingPawn, 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
Step 1. Create a world composition project
Setting up georeferenced sublevels requires some extra preparation steps that are not covered in the Quickstart tutorial.
First, create a new project with a completely empty level and delete any default actors that showed up in the World Outliner.
Go to the Content Browser and create a folder within your project’s
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.
Go to the Settings icon in the toolbar and click World Settings.
Search for Enable World Composition and enable it.
Now 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.
Now bring up the levels panel by going to Window and clicking Levels.
Next, in the Levels panel, click Summon World Composition.
In 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.
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.
To 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 here.
Step 2. Set 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.
Now 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 on how to do this, quickly read about how to import real world terrain here.
Since 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 here. 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.
The 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.
In 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 importing photogrammetry tutorial. You can always double-click 3D Tilesets in the World Outliner to jump the editor camera to the location of the tileset.
The Aerometrex Denver Photogrammetry 3D Tileset.
The Nearmap Boston Photogrammetry 3D Tileset.
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.
In order to fly around the entire earth without becoming disoriented, add a FloatingPawn 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 FloatingPawn actor, read here.
Step 3. Set up a georeferenced sublevel
You 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.
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.
Now 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.
Next, go back to the Levels panel and create a new sublevel. Create a folder within the
Sublevels, and save the new level into this folder.
Create the new sublevel.
Create the Sublevels folder in the World folder.
Save the sublevel in the Sublevels folder.
In 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).
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.
At 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.
Georeference the sublevel by pressing Check for New Sublevels.
Once the sublevel is successfully georeferenced, you should be able to see a new entry in the Cesium Sublevels array.
You 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.
Step 4. Pitfalls to watch out for
Refer back to these 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, FloatingPawns, 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 last tutorial.
Step 5. Building within a georeferenced sublevel
Make 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.
A simple Unreal scene set up on the rooftop.
Explore the real-world data with any of your own characters or vehicles.
Press Play, and try flying the FloatingPawn all the way into space and then try finding your sublevel again, you may need a map!
Step 6. Creating multiple sublevels
The real usefulness of georeferenced sublevels only becomes apparent once you build multiple sublevels.
You 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.
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.
Now 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.
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.
You are free to create as many more sublevels as you would like. Get used to the steps involved and make note of common mistakes you make to avoid them in the future. If you would like, create 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: (Longitude: -112.118392, Latitude: 36.056595, and 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.
Another simple example of building a sublevel.
Learn how to use the FloatingPawn’s fly-to functionality in the next tutorial.
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 particular target location. This is especially easy when using the fly-to functionality of the FloatingPawn. Check out the next tutorial in the series, to learn how to transition between global locations.