Mapbox in Unity 2018

Mapbox in Unity 2018

Learn how to set up Mapbox and how to script projects in this tutorial by Jesse Glover, the author of Unity 2018 Augmented Reality Projects.

Setting up Mapbox

1: The very first thing you need to do is sign up for Mapbox. This requires a username, email address, and password:

2. After you have signed up and verified your email address, it will take you to a page to find out which version of Mapbox you need. You have the option of iOSAndroidWeb, and Unity:

3. Choose the Maps SDK for Unity, and ensure that you’ve downloaded the Unity package before proceeding:

4. You’ll be given an access token, which will be required to utilize the Mapbox software. Make sure you copy this key and paste it into Notepad for later use:

5. Create a new Unity project and call it Fitness for Fun:

6. Import the Mapbox Unity asset file into the project:

7. This will probably take some time to install:


8. Right away, after the installation, you should notice a new menu item called Mapbox. This opens up quite a few new features that are exposed for us to play with:

9. Mapbox gives us Atlas Template GeneratorClear File CacheSetup, and Map Editor options:

10. The Mapbox Atlas Template Generator is a tool that allows you to create and test custom map atlases:

11. The Map Editor allows you to visualize the underlying data structure of the maps you create and use:

12. In addition to that, the Map Editor’s data is tied directly to the Map object’s Abstract Map Script. Any changes you make to the Abstract Map Script data is reflected in the Map Editor, and any changes you make in the Map Editor are reflected in the Abstract Map Script’s data:

13. The Mapbox Setup option allows you to select Example scenes or Map Prefabs; however, this can only be accessed after you copy and paste your Access Token and submit the information. This will require you to be connected to the internet for verification:

Important items to note

With different project types, you will have prefabs that will automatically be added to the active scene. In this section, you will go over the main object that is added to any template type, which is the Map object.

The Map is the most important object that is added to any template and has many extremely important items within the script that you should go over:


The first item within the Map object is the Abstract Map script. The most important items within are MAP LAYERSGENERALLocation, and Others:

Within the GENERAL tab, you have:

  • LatitudeLongitude: If you click on Search, you can set this by typing in an address, or country and city, or even city and state, depending on the location you want to utilize. It will automatically convert it to be latitude and longitude values.
  • Zoom: This is specifically set for how close and far away the map can be drawn; be advised that the zoom function will only work appropriately if you have the proper tilesets generated for it.
  • ExtentOptions: These are how far you want the map to be drawn. By default, it is set to the bounds of the camera.
  • Camera: This is the camera you want to use, whether it is an AR camera with Vuforia, ARCore, ARKit, or even the regular Unity camera.
  • UpdateInterval: This is how long the program should wait before updating positions and drawing.
  • InitializeOnStart: This is a Boolean value for whether or not you want the map to immediately be drawn upon the start of the scene:

The Others tab has a few options as well:

  • PlacementOptions allows you to choose between At Location Center and At Tile Center. This controls the center or root placement of the tiles. Location center can be defined by you whereas the tile center is the center of the tile.
  • Snap Map To Zero is a Boolean value that specifies whether or not the map’s root should be snapped to 0,0,0.
  • Scaling Options allows you to choose whether you want a custom or world scale. Custom is defined by Unity using a Mercator conversion factor. World scale means that the actual scale is rendered and the Mercator conversion is ignored.
  • Unity Tile Size is the size of the tiles used in Unity units.
  • Loading Texture is the texture used when the textures are loading.

The next tab is the IMAGE tab:

  • DataSource: This is the source of maps. You can use Mapbox StreetsMapbox OutdoorsMapbox DarkMapbox LightMapbox SatelliteMapbox Satellite StreetCustom, or None. These are essentially theme options for the map you want to use.
  • UseRetina: This is a Boolean that allows you to choose whether you want to enable the usage of larger texture maps and better visual quality for retina displays.
  • UseCompression: This is a Boolean that allows you to use Unity compression for the tile texture.
  • UseMipMap: This is a Boolean that lets you choose whether to use Unity-generated mip mapping.

The next tab is TERRAIN, which gives you the ability to modify the terrain of your Mapbox maps:

  • Data Source: This is the first option available, and it lets you choose between using Mapbox TerrainCustom, or NoneMapbox Terrain provides you with digital elevation with worldwide coverage. Custom allows you to use a custom elevation model. None is a flat terrain.
  • Map Id: This is the ID of the corresponding tileset that you want to use.
  • Elevation Layer Type: This gives you the choice between Flat TerrainTerrain with ElevationLow Polygon Terrain, and Globe Terrain. This allows you to render your terrain with the specified elevation type. Flat Terrain renders a flat terrain with no elevation. Terrain with Elevation renders a terrain with elevation from the source specified. Low Polygon Terrain renders a low polygon terrain with elevation from the source specified. Globe Terrain renders a terrain with no elevation for a globe.
  • Base Material: This is the material used to render the terrain tiles.
  • Exaggeration Factor: This multiplies the factor to vertically exaggerate elevation on the terrain; however, it doesn’t work with the Flat Terrain Elevation Layer Type.
  • Add Collider: This is a Boolean that lets you add Unity physics colliders to terrain tiles for detecting collisions.

The Others tab within the TERRAIN tab has a few options available as well:

  • Sample Count: This gives you the resolution for your terrain, with the result being an n x n grid.
  • Use Relative Height: This is a Boolean that lets you use a world-relative scale for scaling the terrain height.
  • Earth Radius: This is the radius of the Earth you want to use in meters.
  • Show Sidewalls: This is a Boolean that adds side walls to terrain meshes, which reduces visual artifacts.
  • Add to Unity layer: This adds the terrain tiles to the Unity layer. Upon checking the checkbox, you will get the choice of which layer you want to add them to—DefaultTransparentFXIgnore RaycastWaterUIPostprocessing, and Add Layer.

Next is the MAP LAYERS tab:

  • DataSource: This is the source dataset for the vector data.
  • MapId: This is the ID of the map you’re using.
  • UseOptimizedStyle: This is a Boolean that allows you to use Mapbox-style optimized tilesets that remove any layers or features in the tile that’s not represented by a Mapbox style. Style-optimized vector tiles are smaller, serve over the wire, and are a great way to reduce the size of offline caches.
  • EnableCoroutines: This is a Boolean that allows you to use coroutines.
  • EntityPerCoroutine: This specifies how many entities can be grouped together in a single coroutine call.

POINTS OF INTEREST is the next tab. Here, you can create special markers for important locations in your application or game:

  • RequiredMapId: This is the map ID of the tileset you are using and cannot be empty.
  • AddLayer: This allows you to add points of interest layers.
  • RemoveSelected: This allows you to delete a layer.

The last tab is FEATURES, which gives you Vector Layer Visualizers with the options to add or remove visualizers. FEATURES allow you to modify how certain features look in relation to the point of interest you create:

  • AddVisualizer: This allows you to change how you visualize a points of interest layer
  • RemoveSelected: This allows you to delete the selected visualizer

Finally, you have another script called Initialize Map With Location Provider, which only has the option to add an Abstract Map object to it. This script does what the name states—it registers if you are on an iOS, Windows, or Android device, and selects the Location Provider that is most relevant to it.

Setting up the project

It's now time to set up the project:

1. Create a new scene and call it FitnessFun:

2. Click on Mapbox and then Setup. This will open a setup menu where you need to paste your Access Token in order to gain access to the Map Prefabs template:

3. The Map Prefabs template to use is Location Based Game:

4. It will add a prefab onto your scene, which will have what looks like a pawn in the scene edit tab:

5. If you look over in the Hierarchy pane, you’ll notice a LocationBasedGame prefab added there, and if you drill down to look at the objects inside, you’ll see a MapPlayer, and LocationProvider inside. You’ll also notice Canvas and EventSystem automatically added to the Hierarchy:

6. Inside the Scenes folder, create a Scripts folder:

7. Inside this Scripts folder, create a C# script called TargetLocationController:

8. Create another script called DestroyTargetLocation:

9. Go back to the Hierarchy pane and make a copy of the Player component:

10 Remove the Immediate Position and Rotation with Location scripts along with renaming it to targetLocation:

11. Inside the Scenes folder, create a folder called Prefabs:

12. Drag and drop the TargetLocation object into the Prefabs folder:

13. Navigate to the Scripts folder and open the TargetLocationController script.

You need to write a script to create a new instance of the TargetLocation object and to destroy the object when something happens.

Scripting the project

1. First emsure you utilize Unity Engine, as you need access to MonoBehaviour:


using UnityEngine;

2. The public class will be called TargetLocationController, which is of the same name as the script file you named in the Unity Editor. You will also inherit from MonoBehaviour:


public class TargetLocationController : MonoBehaviour

3. Create a public GameObject called targetObject so that you can drag and drop your prefab onto this object to set a reference to it:


private GameObject targetObject;

4. Now create a Start() method at this point. You want to find the object in the project with the tag of targetLocation, as you’ll be creating it upon a touch event instantiating it:


private void Start()
    targetObject = GameObject.FindGameObjectWithTag("targetLocation");

5. You’ll need to create a SetLocation method and instantiate a new raycast to utilize the touch event the way you want for reading finger presses on the screen:


private void SetLocation()
RaycastHit hit = new RaycastHit();

6. Now loop through to check on your input via touch events:


for (int i = 0; i < Input.touchCount; ++i)

7. Check to see if the touch count is greater than 0, and if your touch phase is moved:


if (Input.touchCount > 0 && Input.GetTouch(0).phase == TouchPhase.Moved)

8. Now, construct a ray from the current touch coordinates on the screen:


Ray ray = Camera.main.ScreenPointToRay(Input.GetTouch(i).position);

9. You need to do a check to see if the raycast hits anything:


if (Physics.Raycast(ray, out hit))

10. If the raycast hits something, then create a new instance of your prefab with the position based on your touch event:


Instantiate(targetObject, new Vector3(Input.GetTouch(i).position.x, 4.23f, Input.GetTouch(i).position.y), Quaternion.identity);

11. In the Update() method, call the SetLocation script:


private void Update()

12. Now, you just need a simple collision check script to check if the player object collides with the targetlocation object. You want to destroy the targetLocation object if the player object collides with it.

13. Open the Destroy Target Location script.

14. You’ll need the UnityEngine namespace as usual, since you want to inherit from MonoBehaviour:


using UnityEngine;
using System.Collections;

15. The name of the class is the same as the name you gave the C# script file and inherits from MonoBehaviour, so you can attach it to a game object in the Unity Editor:


public class DestroyTargetLocation: MonoBehaviour

16. Create an OnCollisionEnter method with the parameters of Collision col:


void OnCollisionEnter (Collision col)

17. Do a simple if check to see if what you are colliding with is the targetLocation object via the object's tag name:


if(col.gameObject.tag == "targetLocation")

18. If the simple if check returns true, then you must destroy the targetLocation object:



You now have everything you need to finalize the project.

Finalizing the project

1. Navigate back to the Unity Editor, attach the targetLocation script to the player object, and set the object to be the targetLocation object:

2. Attach the DestroyTargetLocation script to the object called LocationBasedGame:

3. Now you can click on File | Build:

4. Set the project type for Android:

5. Make sure the only scene added for building is the Chapter6 scene. If the scenes list is empty, click on Add Current Scene:

6. Now, build the project and install it on your Android device to run the program.

That’s it. If you enjoyed this article and want to master AR game development in Unity 2018, check out Unity 2018 Augmented Reality Projects. The book takes a practical, project-based approach to teach the specifics of augmented reality development in Unity and helps you build four immersive and fun applications using ARKit, ARCore, and Vuforia.

Leave A Comment

Please login to post your valuable comments.

Join the newsletter

Get the latest vLemonn news first