intermediate
No code
Mesh generation with the Mapbox Maps SDK for Unity, Part 1: add terrain to a scene
Prerequisite
Familiarity with Unity.

This is the first tutorial in a three-part tutorial series that will walk you through how to create a visualization of 3D buildings on top of a 3D terrain map for use in a Unity application. In part 1, you’ll add terrain to a scene and visualize it. In order to build a complete visualization, you’ll:

  • Set up a Mapbox project in Unity.
  • Learn about the Mapbox-specific terminology, tools, and services you’ll use to build your visualization.
  • Build some factories with the Mapbox Unity Mapbox Maps SDK for Unity to request map data and transform it into 3D objects.
  • Build some visualizers to describe how your map data should be rendered in a scene.
  • Build a complete scene and take it for a spin!

Getting started

Before getting started, you’ll need to:

  1. Install the Mapbox Maps SDK for Unity. For full installation instructions, visit https://www.mapbox.com/unity-sdk.
  2. Create an empty Unity project.
  3. Configure your Mapbox access token in your Unity project. For token configuration instructions, visit http://www.mapbox.com/unity-sdk/#token.

Set up your project

Your map project needs a place to call home. All of the Mapbox Unity SDK tools you’ll be using can be found in the Mapbox context menu which can be accessed by Right-clicking on a folder.

Use the Unity interface to create a root directory and add a MapVisualization scriptable object by following these steps:

  1. Create a new folder called CityMap.
  2. Right-click on the CityMap folder then select Create, then Mapbox.
  3. Select MapVisualizer.
  4. Click on BasicMapVisualizer.
  5. Rename the BasicMapVisualizer object to CityMap.

Right-click the CityMap Folder and Navigate to the BasicMapVizualizer

Create a TerrainFactory

Now that you have a MapVisualization set up, it needs a TerrainFactory. The TerrainFactory uses Mapbox Terrain to create terrain meshes within your Unity project. This will ultimately serve as the height model upon which you’ll drape map imagery to create a 3D map model.

To create a TerrainFactory:

  1. Create a folder inside the CityMap folder and name it CityTerrain.
  2. Right-click on your CityTerrain folder, navigate to Factories and select TerrainFactory to create a new script.
  3. Rename the file to CityTerrain.

menu options in the Unity UI for creating a new TerrainFactory

Configure TerrainFactory

Next, you’ll need to connect your new TerrainFactory, CityTerrain, to your MapVisualization, CityMap. You can do this in the Inspector window.

In Unity, the Inspector window displays detailed information about the currently selected GameObject. Within the Inspector window you can connect components and modify properties.

To connect CityTerrain to CityMap:

Open the Inspector window for your CityMap MapVisualization.

inspector window in Unity

  1. Under Factories, select Add New Empty.
  2. Add CityTerrain as a Factory by clicking the magnifying glass icon then selecting CityTerrain from the pop up window.

window to select a module in Unity

The visualizer CityMap will now have the CityTerrain factory attached.

Optional configurations

  • Setting a Loading Texture can give visual cues to your users for tiles that are loading as well as hide re-used raster tiles.
    • Explore the Slippy Map example for more information.
  • You can configure the Height Multiplier value to change the vertical exaggeration of your heights.
    • Setting the Height Multiplier to 0 will create flat terrain.
      • This can however lead to extra bandwidth consumption and map build times.
      • To generate a flat map instead use a FlatTerrainFactory.
  • To prevent the terrain from glowing, you can create a new material, then reduce the Smoothness to 0. Assign your new material to to your CityTerrain script’s Material parameter.

CityTerrain Options

Add your newly created CityTerrainMaterial to the CityTerrain TerrainFactory.

Create a Map ImageFactory

Your MapVisualization also needs an ImageFactory in order to request and assemble the visual map data you’ll drape on the 3D model you created in the previous step.

To create an ImageFactory:

  1. Create a folder inside CityMap and name it CityImagery.
  2. Right-click on the CityImagery folder then select Create, then Mapbox.
  3. Select Factories.
  4. Click on ImageFactory.
  5. Rename the ImageFactory object to CityImagery.

menu options in the Unity UI for creating a new ImageFactory

Configure ImageFactory

Next, you’ll modfiy the properties of your new ImageFactory, CityImagery, and connect it to your MapVisualization, CityMap.

In the ImageFactory Inspector window, there are several properties that can be modified including the map style that you would like to use in your scene. You can use a Mapbox template style by specifying Basic Mapbox style as the Map Type or use a custom style using the Custom option.

You can create custom map styles in Mapbox Studio. See the Mapbox Studio Manual and our Create a custom style tutorial for more information on how to create custom styles.

Here, you’ll use the Mapbox Dark template style:

  1. Open your CityImagery script’s Inspector menu.
  2. Make sure Map Type is set to Basic Mapbox style.
  3. Change the Style parameter to Dark.

screenshot of CityImagery script’s Inspector menu

Next, connect your ImageFactory to the CityMap MapVisualization:

  1. Open the CityMap inspector.
  2. Select Add New Empty.
  3. Add CityImagery as the second Factory.

add a component from the inspector window

Generate a map

Use what you’ve configured so far to generate a map.

Right-click in the hierarchy panel and select Create Empty to create a new empty GameObject in the scene and name it Map.

Configure your scene

Add some components to your Map GameObject to display the map:

  1. Click Add Component.
  2. Add a Basic Map component to your Map object.

inspector window after adding a basic map component

  1. Set the Map Visualizer to CityMap.
  2. Set Latitude Longitude String property to 37.792159, -122.401723 to center your map on San Francisco.
  3. Set the Zoom to 16.
  4. Add a RangeTileProvider component to your Map object by clicking on the Add Component button, then set Range to 1,1,1,1.
  5. Add this RangeTileProvider to the component’s TileProvider field.

Finished product

Click the play button to build the scene. Make sure you are in the Scene tab after building the scene. Adjust your view (you won’t be able to see much in game view since you haven’t set up the camera yet), but you should see the Mapbox Dark style!

finished scene

Next steps

Now that you’ve added terrain to a scene and visualized it, head to Part 2 of the tutorial series to learn how to add 3D buildings to your scene.