Skip to main content

Cesium for Unity Quickstart

This is a quickstart guide to building a Cesium for Unity app with Cesium World Terrain and Cesium OSM Buildings.

A Cesium for Unity scene with Cesium World Terrain and Cesium OSM Buildings, set in Chicago.

A Cesium for Unity scene with Cesium World Terrain and Cesium OSM Buildings, set in Chicago.

You’ll learn how to:

  • Import the Cesium for Unity package into Unity
  • Create a level and import assets from Cesium ion
  • Set your project's default ion asset token
  • Navigate your scene with Cesium's DynamicCamera

Prerequisites

  • An installed version of Unity 2021.3.2f1 or later., The latest version of Unity 2021.3+ LTS is recommended. For instructions on installing Unity, visit the Unity download page and refer to the Installing Unity guide.
  • A Cesium ion account to stream terrain and building assets into Unity. 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.

1Create a new project and import the Cesium For Unity package

1. Create a new Unity project. Unity recommends creating projects with the Unity Hub, which you can download here. This tutorial was written with Unity Hub 3.3.0.

Create a new project from the Projects tab by clicking the New project button.

A new window should open, allowing you to configure your project. This tutorial uses the 3D (URP) template, but the 3D (HDRP) template will also work. Give your project a name and choose its file location. Then, press Create project. Your new project will open momentarily.

Configure Unity project with 3D (URP) template.

Information

Cesium for Unity works with both the Universal Render Pipeline (URP) and High Definition Render Pipeline (HDRP). However, it does not support Unity’s built-in renderer. If you choose the empty 3D project as your template, the datasets loaded by Cesium will not render properly.

2. Once the project has fully loaded, open the Project Settings by going to Editor > Project Settings... in the menu.

3. Click the Package Manager section on the left.

4. Add a new Scoped Registry with the following settings and click Save:

Name: Cesium

URL: https://unity.pkg.cesium.com

Scope(s): com.cesium.unity

5. Close the project settings and then open the Package Manager by going to Window > Package Manager in the menu.

Open Window then Package Manger in the menu.

6. In the Package Manager, click on the Packages drop-down and select My Registries.

7. Cesium for Unity will appear in the package list. Click on it, and then click Install. Cesium for Unity and its dependencies will be downloaded and installed.

8. After the previous step, you may see this pop-up.

Missing TextMeshPro Essential Resources pop-up

This window will appear because Cesium for Unity depends on resources in the TextMeshPro package, which is not included by default in Unity projects. To import these resources, click Import TextMeshPro Essential Resources. If you close this window by accident, you can also import the resources using Window > TextMeshPro > Import TMP Essential Resources.

Import TMP Essential Resources

9. The previous step will open a window with a list of the included TextMeshPro assets. Make sure all of the assets in the Fonts, Resources, Shaders, and Sprites folders are selected. You can choose not to import the Documentation folder if you do not need it.

Make sure all of the assets in the Fonts, Resources, Shaders, and Sprites folders are selected.

Press the Import button to import the resources to your Assets folder. You can verify that the import was successful by checking the folder in the Project window. There should be a new folder named “TextMesh Pro” containing all of the imported assets.

There should be a new folder named “TextMesh Pro” containing all of the imported assets.

2Connect to Cesium ion

1. Open the Cesium window by selecting Cesium > Cesium from the menu.

Open the Cesium window by selecting Cesium > Cesium from the menu.

2. Click the Connect to Cesium ion button.

Connect to ion button in Cesium panel

3. A 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.

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

Allow ion access.

5. Now 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 window.

Click on the Token button at the top of the Cesium window.

6. A 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 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.

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.

Information

Tokens created by Cesium for Unity 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 scene, Cesium for Unity 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.

3Add a globe to your scene

Unity creates a new SampleScene whenever you create a new project. Feel free to rename your scene. Verify that it contains a Main Camera and a Directional Light in the Hierarchy window.

Verify that your scene contains a Main Camera and a Directional Light in the Hierarchy window.

If either of these objects is missing, you can add it from the menu by clicking GameObject > Camera or GameObject > Light > Directional Light, respectively. You may have additional objects in your scene depending on which render pipeline you chose, which is fine.

With these basic objects in your scene, you are ready to add an asset from Cesium ion.

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

Add "Cesium World Terrain + Bing Maps Aerial imagery."

Terrain will start to appear in the scene.

Terrain will start to appear in the scene. This scene shows brown and green foothills with a blue sky at the top and a road in the middle.

2. Take a look at the Hierarchy window. You should see two new game objects. One of them, Cesium World Terrain, is the tileset you just created. The parent of the tileset, CesiumGeoreference, is created automatically the first time you add a 3D Tileset to the scene.

Game objects CesiumGeoreference and Cesium World Terrain

3. If Cesium World Terrain is not already selected, select it now. In the Inspector window, you'll see more information about this game object.

More info about Cesium World Terrain in the Inspector window

This is a Cesium3DTileset component. When attached to a game object, it streams 3D Tiles data into Unity and provides ways to configure that tileset.

You'll learn about many of the available settings in future tutorials. For now, feel free to explore and try out the different settings yourself. Hover over any setting with your mouse to learn more about what it does.

Once you're ready, continue to the next section.

4Configure the Main Camera

In your scene, you should have a game object named Main Camera with a Camera component attached. If you added a camera to the level yourself, it may be called Camera instead. This camera will capture your scene during Play Mode. You can preview this by clicking the Game tab.

The Game tab in Unity

You may notice that the terrain on the horizon is strangely cut off. This clipping can also happen in the Scene view while moving the Editor camera around, though it is usually less obvious.

In the Editor, you may notice that the terrain on the horizon gets cut off while moving the camera around.

This happens because cameras in Unity can only see a limited range in front of them. If you view your camera from the Scene view, you can see its range visualized as a frustum, like below.

The camera cannot see very far in the distance.

The start and end of the camera’s frustum are defined by the clipping planes. These represent the distances from the camera at which objects will show up. It is clear that the camera cannot see very far in the distance.

Cesium World Terrain is a full-scale globe, so Unity is rendering terrain that spans hundreds of thousands of miles, just from this camera view! However, Unity’s cameras are not configured to see objects this far by default. Fortunately, you can manually adjust the clipping planes so the camera can properly view the scene in Play Mode.

1. Select your camera from the Hierarchy window, and go to the Camera settings in the Inspector. Find the values of the Clipping Planes.

Select the Main Camera from the Hierarchy window, and find the Camera settings in the Inspector.

The Near clipping plane is the minimum distance from the camera where objects start to appear. If this is a large value, objects close to the camera will not show up. On the other hand, the Far clipping plane is the maximum distance from the camera that objects will appear. Anything farther than the Far plane will not appear.

It is clear that the camera cannot see very far in the distance. However, this can be easily changed in the Camera component.

2. Set the Near value to 1 and the Far value to a large value, at least 100,000. This will significantly extend the sight of the camera and prevent the terrain from being clipped in-game.

Set the Near value to 1 and the Far value to a large value, at least 100,000.

In your own applications, these values can change depending on your use cases. For example, you can set the Near plane to a larger value if you plan to show data only from far away. Try not to let the Far plane get too far away from the Near plane, or you may run into rendering issues. See the Unity documentation for the Camera component for more details.

Now that your camera can see more of the scene, feel free to position the camera to get the best view of the terrain. You can use the Move and Rotate tools in the Scene view to move the camera to the perfect spot. You can also switch to these tools by pressing the W and E keys on your keyboard respectively.

Move and rotate the camera with the tools in the Scene View.

The Unity Editor’s camera works a bit differently than the in-game cameras. You can view its settings by clicking the camera icon from the Scene view.

The Unity Editor’s camera works a bit differently than the in-game camera. You can view its settings by clicking the camera icon from the Scene view.

The editor camera has an option for Dynamic Clipping, which automatically adjusts the Near and Far values of the camera depending on what is visible in your scene. When this option is checked, the Near and Far planes cannot be manually adjusted.

Dynamic clipping in camera settings

This setting is useful when working with Cesium for Unity, especially when zooming in and out on the globe. However, the automatic adjustments are not always precise, and clipping may still occur. If necessary, you can disable this option and set the Near and Far values yourself. You can also change the Camera Speed if you want to travel around the globe faster in the Editor.

5Add global 3D buildings to your scene

Now that you’ve adjusted your camera to render more of the Unity scene, let’s return to adding content to the world. Cesium for Unity can visualize more than just terrain, which we can demonstrate with a global dataset of city buildings.

  1. Select the CesiumGeoreference game object in the Hierarchy window. This object determines where in the world your Unity scene is set. The scene's current latitude, longitude, and height can be changed with this game object.
  2. In the Inspector window, look for the Latitude, Longitude, and Height variables under the Origin (Longitude Latitude Height) header.

These coordinates currently point to the hills outside Denver, Colorado, USA.

3. Change these variables to the coordinates of your favorite city. This tutorial uses the following coordinates for Chicago, Illinois, USA.

Latitude: 41.878101
Longitude: -87.59201
Height: 1000.0

After entering these coordinates, the scene will have shifted to the new location.

Chicago in Cesium World Terrain in Unity


4. The city looks very flat because Cesium World Terrain doesn't include building details. Fortunately, the Cesium OSM Buildings dataset can be added to fill the empty space.

In the Cesium window, locate the Cesium OSM Buildings option underneath Quick Add Cesium ion Assets. Click to add the data to the scene.

In the Cesium window, locate the Cesium OSM Buildings option underneath Quick Add Cesium ion Assets. Click to add the data to the scene.

The buildings should now appear on top of the terrain. You may be able to recognize some of the buildings that make up the Chicago skyline!

Chicago with Cesium World Terrain and Cesium OSM Buildings in Unity

6Explore your scene

Now that you have added global real-world content to your scene, let’s learn how to navigate it. You’ll learn multiple ways to move the Editor camera through your scene. You’ll also learn about the Dynamic Camera, a controller included in the Cesium for Unity package that will help you navigate the Earth's immense size during play mode.

The Editor camera can be controlled by using your keyboard and mouse. With the Scene View selected, use the arrow keys to move the camera forward, backward, left, or right. You can pan the camera by either selecting the hand icon in the Tools menu or holding the middle mouse button, then dragging across the Scene View window.

Use the hand tool to move around the Scene View.

To look around with the camera, hold the right mouse button and drag the mouse across the Scene View. You can also rotate the camera by holding Alt and dragging with the left mouse button. Lastly, you can use the mouse’s scroll wheel, or hold Alt while dragging with the right mouse button, to zoom in and out of the scene.

If the Editor camera is moving too slowly, you can adjust the Camera Speed as described in the previous step.

For play mode, Unity provides a Character Controller component that you can attach to your camera to move it through the scene. However, you may need a controller that accounts for the scale of real-world data and can efficiently navigate the globe at any altitude. This is where Cesium for Unity’s Dynamic Camera comes in.

Information

Q: What is the Dynamic Camera?

Cesium's DynamicCamera is a globe-aware camera controller that can adjust its orientation based on where it is on the globe. The DynamicCamera is able to dynamically adjust its clipping planes so the globe is not clipped as it zooms out. It also offers easier navigation of the globe by allowing users to adjust its movement speed with the mouse wheel, and providing the ability to fly between global locations along a curved path.

1. Using the Cesium panel, add a Dynamic Camera to your scene.

Add a Dynamic Camera from the Cesium panel

The DynamicCamera should appear under the existing CesiumGeoreference in the Hierarchy window.

The DynamicCamera under the CesiumGeoreference in the scene hierarchy.

2. Disable the Main Camera by selecting it in the Hierarchy window and unchecking the box next to its name in the Inspector. The DynamicCamera will become the new main camera of the scene. You can also remove the Main Camera object from the scene entirely.

Click the checkbox next to the main camera's name to disable it.

3. Since the DynamicCamera is a georeferenced object, it will maintain its position relative to its coordinates on the globe, and not the standard Unity world coordinates. This means that if the CesiumGeoreference’s Origin is changed to a different location, the DynamicCamera will stay behind.

If you'd like to move it to your new location, select it in the Hierarchy window and find its Transform in the Inspector. Change its Position’s X, Y, and Z coordinates to 0 to move it to the Unity origin. You can also right-click the three dots on the Transform component and select Reset from the dropdown menu.

Click the three dots next to the DynamicCamera's transform, then click Reset to restore the transform's default values.

4. You're ready to test out your scene! Press the Play button at the top toolbar.

Press the Play button to enter play mode.

You can use the W, A, S, and D keys and the mouse to fly around. You can also use the Q and E keys to move the camera vertically with respect to the globe. Use the mouse scroll wheel if you need to change your speed.

You've created your first scene with Cesium for Unity. Feel free to explore and check out the world!

Next steps

Now you are ready to add your own assets to 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.