Building Global Scenes with Georeferenced Sublevels
The release of Cesium for Unreal 1.7.0 has changed and streamlined the way that sublevels work. This tutorial is still helpful, but is currently outdated. It will be updated soon. In the meantime, please check out this forum post to learn about the new workflow.
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.
- 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 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
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.
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.
4Search for Enable World Composition and enable it.
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.
6Now bring up the levels panel by going to Window and clicking Levels.
7Next, in the Levels panel, click Summon World Composition.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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:
- 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.
- 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.
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.
2Press Play, and try flying the DynamicPawn all the way into space and then finding your sublevel again. You may need a map!
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.
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.
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.
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.