Mesh generation with the Mapbox Maps SDK for Unity, Part 1: add terrain to a scene
Note: This tutorial applies to versions 1.3.0 or earlier of the Mapbox SDK for Unity. To get started with version 1.4.0 or later, please visit this new tutorial.
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!
Before getting started, you’ll need to:
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:
- Create a new folder called CityMap.
- Right-click on the CityMap folder then select Create, then Mapbox.
- Select MapVisualizer.
- Click on BasicMapVisualizer.
- Rename the BasicMapVisualizer object to
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:
- Create a folder inside the CityMap folder and name it CityTerrain.
- Right-click on your CityTerrain folder, navigate to Factories and select TerrainFactory to create a new script.
- Rename the file to
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.
Open the Inspector window for your
- Under Factories, select Add New Empty.
CityTerrainas a Factory by clicking the magnifying glass icon then selecting
CityTerrainfrom the pop up window.
CityMap will now have the
CityTerrain factory attached.
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
- 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.
Add your newly created
CityTerrainMaterial to the
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:
- Create a folder inside CityMap and name it CityImagery.
- Right-click on the CityImagery folder then select Create, then Mapbox.
- Select Factories.
- Click on ImageFactory.
- Rename the ImageFactory object to
Next, you’ll modfiy the properties of your new ImageFactory,
CityImagery, and connect it to your MapVisualization,
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.
Here, you’ll use the Mapbox Dark template style:
- Open your
CityImageryscript’s Inspector menu.
- Make sure Map Type is set to
Basic Mapbox style.
- Change the Style parameter to
Next, connect your ImageFactory to the
- Open the
- Select Add New Empty.
CityImageryas the second Factory.
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
Add some components to your
Map GameObject to display the map:
- Click Add Component.
- Add a Basic Map component to your Map object.
- Set the Map Visualizer to
- Set Latitude Longitude String property to
37.792159, -122.401723to center your map on San Francisco.
- Set the Zoom to
- Add a RangeTileProvider component to your Map object by clicking on the Add Component button, then set Range to
- Add this RangeTileProvider to the component’s TileProvider field.
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!