Get Started with the Maps SDK for Unity

This guide will walk you through adding the most recent version of the Mapbox Maps SDK for Unity package to your project and initializing a Mapbox map in scene.

V2 is not in active development

The V2 of the Maps SDK for Unity SDK is not in active development and may not work properly without modification.

This guide includes workarounds such as file deletion and package code changes to work with modern Unity installations. v3 is in development and will be released soon.

Visit the #unity channel in the Mapbox Developer Discord to connect with the user community and get updates on version 3.

You'll learn how to:

• Set up a Mapbox project in Unity.
• Learn about the Mapbox-specific terminology, tools, and services you’ll use to build your visualization.
• Add a map to your scene.
• Customize your map for your specific needs.
• Learn how to add buildings and other vector data.

Prerequisites

• A Mapbox account: Sign up or log into a free account on Mapbox.
• Unity Editor: Install the Unity Editor. Mapbox Maps SDK for Unity is compatible with Unity 2017.1.0 or greater.

Part 1: Add the package and configure your project

1. Download the Mapbox unity package by clicking the button below:

arrow-downDownload v2.1.1 Unity Package

2. Create or open a unity project.

   • The Mapbox Maps SDK for Unity is compatible with 2017.1.0 or greater.

3. Import the custom package into Unity.

   • First, click Assets > Import Package > Custom Package
   • Then select the package you downloaded.
   • Next a menu will appear named Import Unity Package, and click the Import button at the bottom of the panel.
   • Errors will appear but these will be fixed in the next step.

4. Once the package has imported, you will need to remove specific folders.

   • In Unity V2, there are certain folders in the package that cause issues. These errors will be fixed in Unity V3, but for now to remedy these errors, delete the following 4 folders in the Assets folder:
     • GoogleARCore
     • Mapbox AR
     • UnityARInterface
     • UnityARKitPlugin
   • Once removed a pop-up will appear, click the blue Yes, for these and other files that might be found later button.
     • This will make sure these folders are safely removed from the project.
   • Because you need to remove these folders, AR is not functional.

5. In the new menu, add a public access token.
   • Once the folders are deleted, the Mapbox Setup menu will appear.
   • In this menu, you will need to add a public access token, for example your default access token.
   • To grab a token go to your Developer Console and copy your default token from the page.
   • Then paste the token in the input field and hit submit.

Once the menu states your token is valid, you can close the menu and move to Part 2: Add a map.

Part 2: Add a map

1. Add a map to your scene
   • Go to your project folders and under Assets/Mapbox/Prefabs, drag the Map prefab into your scene.
   • This prefab will spawn a map in scene on load and give you options in the details panel to customize the map.
2. If using Unity 6, change Texture parameters in script.
   • Due to changes in Unity 6, you will need to adjust code in the Map prefab script.
   • Open the UnityTile.cs file in Assets/Mapbox/MeshGeneration/Data/UnityTile.cs
   • On line 294, change the two parameters marked as 0 to 1.
3. If using URP, make sure to convert the Mapbox package file to match your Render Pipeline.
   • First, make sure you've saved your scene.
   • Next, go to Window > Rendering > Render Pipeline Converter.
   • Select Material Upgrade and click Initialize Converters.
   • Click on the Material Upgrade box to see all the selected objects. Make sure only Mapbox objects are selected unless you want to also make changes to your own files, because Render Pipeline conversions make permanent changes to your files.
     • There should be 81 files in total.
   • Now hit Convert Assets.
4. Save and hit play!
   • Once you hit play, a map should spawn in your game window.
   • The texture may be cyan at first but the map should load in after a moment.

You have a map! Note that you may need to change the camera’s position to see the map properly in the Game panel, but you can see it in the Scene panel.

Now that you have a map running, you can customize it as seen in the next section.

Part 3: Customize your map

You can customize your map in various ways, but for this tutorial, you'll walk through creating a mountain scene and a city scene.

Create a map with terrain and satellite data

First with your map, recreate Mt. Hood in Oregon, USA. You can elevation and a realistic style to the map to better view the mountain.

1. Select your Map object and go to the Inspector window.
2. Under the Abstract Map general settings, either change the location to 45.374218, -121.688341 or search “Mt Hood” and select the first option.
3. Set the zoom level to 13.
4. Under Extent Options, set each direction to 2.
   • Note that if you set these values to high, you may experience performance issues.
5. Open the Others settings in the GENERAL section and toggle Snap Map to Zero.
6. Next add the satellite style to the map.
   • Under the IMAGE section, change the Data Source to Custom.
   • Here you can enter different style URLs to choose a style for your map.
   • You will see styles in the dropdown list, but these styles are out of date and we recommend using the style URLs directly.
   • To see a full list, see the Classic Mapbox Styles table, but for this demo, you can enter the URL from below:

mapbox://styles/mapbox/satellite-v9

7. Finally, open the TERRAIN section and change the Elevation Layer Type to Terrain with Elevation.
8. Save your scene and hit play.

Now if you switch to the Scene window and you’ll see something like this:

Adding collisions to your map

If you want to add collision to your terrain, under the TERRAIN section and toggle on Add Collider.

Create a map with 3D buildings

Next you will recreate downtown Manhattan, with a stylized look and rendering 3D buildings.

1. First set the location to 40.706843, -74.011370 or search “New York Stock Exchange” and select the first option.
2. Set the zoom level to 17.
   • Make sure that if you adjust this zoom level it is 15 or higher otherwise all the buildings may not render.
3. Next add a dark style to the map.
   • Under the IMAGE section, change the Data Source to custom and enter the following URL into the input field: mapbox://styles/mapbox/dark-v11
4. In the TERRAIN section, change the Elevation Layer Type to Flat Terrain.
5. Under MAP LAYERS, change the Data Source to Mapbox Streets V8 with Building Ids.
6. Now, under FEATURES, click Add Feature and select buildings.
   • These options will not appear unless you complete step 5.
7. Now hit play and you'll see Manhattan with 3d buildings!

Sometime textures will take a minute to load so if you see everything is a cyan color, wait a moment and the proper textures should appear.

Troubleshooting

ARBackground errors

If you see any errors referencing AR, make sure all the AR packages listed below are deleted from the Assets folder:

• GoogleARCore
• Mapbox AR
• UnityARInterface
• UnityARKitPlugin

Only some buildings are showing

Make sure on the Map object in the GENERAL section, zoom is 15 or higher. If the zoom level is too low not all buildings will be rendered.

Editor or Build crash

Make sure to optimize usage, for example, if you are spawning buildings make a smaller radius for example 1 unit long. Also setting Extent Options to Camera Bounds may cause a crash.

Texture must have width greater than 0 error

If using Unity 6, change texture code.

• Due to changes in Unity 6, you will need to adjust code in the Map prefab script.
• Go to line 294 in UnityTile.cs and change the two parameters marked as 0 and switch them to 1.

Why are my textures pink or cyan?

Pink

If using URP, make sure to convert the Mapbox package file to match your Render Pipeline.

• Go to Window > Rendering > Render Pipeline Converter
• Select Material Upgrade and click Initialize Converters
• Click on the Material Upgrade box to see all the selected objects. Make sure only Mapbox objects are selected unless you want to also make changes to your own files, because Render Pipeline conversions make permanent changes to your files.

Cyan

If your textures are cyan this means they are working, but loading. Wait for a few moments and the proper textures should render.

Next steps

Congratulations! You've created 2 different maps in Unity with the Mapbox Maps SDK for Unity. Now you can continue to customize your map or add game play functionality to the scene.

Was this page helpful?