Unity with MapTiler real-world 3D content

This step-by-step tutorial will teach you how to use MapTiler maps in your Unity application. To do this, we will use the Cesium plugin for Unity, allowing us to create digital worlds from real-world content in 3D. Now, MapTiler basemaps can be easily used in the plugin, via MapTiler Cloud or MapTiler Server/Data for on-premise and offline use-cases.

Unity Engine is a real-time 3D development engine, that provides tools to create and operate amazing games and other real-time interactive experiences and publish them to a wide range of devices. Unity’s real-time 3D development engine allows artists, designers, and developers to collaborate to create incredible immersive and interactive experiences.

Installation and setting up

  1. Install Unity 2021.3.2f1 or later. Download Unity

Create a new Unity project

  1. 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 Universal 3D (URP) template, but the High Definition 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.

    Unity new URP project

    Cesium for Unity works with both the Universal 3D (URP) and High Definition 3D (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 Edit ➡ Project Settings… in the menu. Click the Package Manager section on the left. 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

    Unity project settings

  3. Close the project settings and then open the Package Manager by going to Window ➡ Package Manager in the menu. In the Package Manager, click on the Packages drop-down and select My Registries.

    Unity package manager

  4. 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.

    Install Cesium for Unity

Add global real-world 3D terrain to your level

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

  2. From the Cesium window, add a blank 3D Tiles tileset.

    Unity add a blank 3D Tiles tileset

  3. Change the Tileset Source from Cesium Ion to ‘From URL’.

    Change Cesium tileset source to From URL

  4. Insert the MapTiler 3D terrain tileset URL in the URL field. The tiles contain real-world elevation data encoded into vector TIN polygons in format for the Cesium JavaScript library. The URL should be https://api.maptiler.com/tiles/terrain-quantized-mesh-v2/tiles.json?key=YOUR_MAPTILER_API_KEY_HERE. Replace YOUR_MAPTILER_API_KEY_HERE with your actual MapTiler API key or just copy the URL from your 3D terrain in the Maptiler Cloud.

    Copy the MapTiler terrain URL

  5. Take a look at the Hierarchy window. The CesiumGeoreference, is created automatically the first time you add a 3D Tileset to the scene.

  6. Add a new component inside the CesiumGeoreference. In the Inspector window click the Add component button. Add a new Web Map Tile Service Raster

    Unity add new Cesium WMTS raster tile service

  7. Get the URL of the (WMTS) Web map tile service of your MapTiler maps. Go to the MapTiler Cloud maps, and select one of the standard maps (high-quality basemaps like Planet, Ocean, High-Res Imagery) or your custom maps (Try the MapTiler Customize). The URL should be https://api.maptiler.com/maps/YOUR_MAP_ID_HERE/{TileMatrix}/{TileCol}/{TileRow}.jpg?key=YOUR_MAPTILER_API_KEY_HERE or open the WMTS Capabilities.

    Open WMTS capabilities

    In the Capabilities XML look for the ResourceURL within Content ➡ Layer. And copy the URL value of the template attribute.

    WMTS capabilities ResourceURL

  8. Configure the Cesium Web Map Tile Service Raster Overlay. Add the WMTS URL obtained in the previous step into the Base URL field and check the projection is Web Mercator.

    Unity configure CesiumWebMapTileServiceRasterOverlay url and mercator

    The process is replicable with MapTiler Server with Download Terrain 3D - Cesium quantized mesh of the entire planet and then for the overlay, any map that is on your MapTiler Server.

Set the initial view localization coordinates

  1. Select the CesiumGeoreference in the Hierarchy.

  2. In the Inspector panel, look for the Latitude, Longitude, and Height variables under the Origin (Longitude Latitude Height) category. Change these variables to the coordinates of your favorite city or use these coordinates to travel to Lake Louise, Canada.

     Origin Latitude = 51.395879
 Origin Longitude = -116.261587
 Origin Height = 3000.0

    Unity CesiumGeoreference change origin latitude and longitude

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

  3. Now that you have added global real-world content to your scene, let’s learn how to navigate it.

  4. Add a Dynamic Camera using the Cesium panel.

    Unity add a Cesium dynamic camera

    The Dynamic Camera can 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 their movement speed with the mouse wheel and providing the ability to fly between global locations along a curved path.

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

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

  6. 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 drop-down menu.

Explore your level

  1. You’re ready to test out your level! Press the Play button at the top toolbar. You can use the W, A, S, and D keyboard keys and the mouse to fly around. Use the Q and E keys to move the camera vertically to the globe. Use the mouse scroll wheel to change your speed. You’ve created your first project with Cesium for Unity. Feel free to explore the world!

Examples

Real-world 3D MapTiler maps in Unity MapTiler High resolution Imagery map

Real-world 3D globe MapTiler maps in Unity MapTiler Global Satellite map

Custom MapTiler old maps in Unity UK Great Britain, 1900s

Real-world 3D MapTiler winter maps in Unity MapTiler Outdoor Winter map

Summary

  • MapTiler basemaps can be easily used in Unity adding a WMTS map, via MapTiler Cloud or MapTiler Server/Data for on-premise and offline use-cases.

  • Create high-fidelity 3D geospatial visualization and simulation capabilities within the Unity Engine using the MapTiler 3D terrain service.

  • Add your custom maps to Unity. Whether they are: maps created with the MapTiler Customize, self-hosted maps & images for use in on-prem/local Cesium-based applications for Unity or create your tiled service with MapTiler Engine.

Learn more

Check out the Cesium for Unity tutorials