The Maps SDK for Unity is a collection of tools for building Unity applications from real map data. It enables Unity developers to interact with Mapbox web services APIs (including the Maps, Geocoding and Directions APIs) and create game objects via a C#-based API and graphical user interface.
To install the Maps SDK for Unity, follow the instructions in the installation guide. Once installed, you can start exploring some of our existing examples in the SDK or read our step-by-step tutorials.
The Maps SDK for Unity comes with several example scenes to showcase various features and possibilities of the SDK. You can find these scenes by navigating to
Mapbox > Setup, or by looking at the Examples folder in the Project window and double-clicking on a Scene file to open it. Look at the installation guide for more information.
Introduction to the Maps SDK
The Mapbox Maps SDK for Unity contains several scripts and
ScriptableObjects that work together to enable various features:
- MapVisualizer: Visualizes a map. A MapVisualizer creates the requested tiles and relays them to the necessary factories. Every map rendered with our SDK must have a MapVisualizer.
- Factory: Processes terrain, image, and vector data of maps for rendering.
- LayerVisualizer: Receives vector data to create and style features (such as buildings) as a layer on the map.
- Stacks and Modifiers: Stacks are collections of modifiers. Modifiers are scripts that create, modify, and style features.
The Map Editor is a modular, tree-like node editor designed to help developers create their custom map visualizations. It can be found under the
Mapbox > Map Editor in the Unity top bar. While it is not necessary to use, it is a valuable tool for navigating and understanding the underlying structure of a map.
When you open the Map Editor window, it finds the Map Visualizer used in the scene and draws it automatically. Each node is a ScriptableObject in the mesh generation structure, and corresponds directly to a file in the project. Click on a node to see its settings in the Inspector panel.
The Map Editor also includes checkboxes next to the vector factory's layer visualizers, which allows you to toggle them on and off. This allows for quick customizations of which layers to show.
Custom map styles
Image factories have a field called
Map Type that can be set to "basic" or "custom". You can select “basic” to use one of the generic Mapbox map styles, or select “custom” to use a custom style from Mapbox Studio.
There are two ways to specify a custom style:
- Copy a style URL from your Mapbox Studio account and paste it into the
Idfield of your image factory.
- Search for a style linked to your account. Note: to search for a style, you may have to generate a new access token with
styles:listscope enabled. If you had to create a new access token, remember to swap it out with the old token in your Mapbox Setup panel.
After specifying which custom style you want to use, you’ll see the map with the new style when you play the scene. You can further customize your map style in Mapbox Studio. Note that there may be some differences in color quality and resolution between Mapbox Studio and Unity: this is expected.
Using this documentation
The Overview section contains guides introducing concepts related to the Maps SDK for Unity. Some of these guides walk through core concepts as illustrated in the example scenes that are provided with the Maps SDK. Read more about each of these examples:
- Explorer: Showcases Mapbox's vector data.
- Location provider: Shows how to position and orient a
PlayerGameObject on a map.
- Vector tile maps: Shows how to utilize vector tiles to generate 3D features as well as utilizing such metadata in your app or game.
- Zoomable maps: Allows you to create a runtime zoomable and pannable map.
You can also learn how to add attribution to Unity applications that use the Mapbox Maps SDK for Unity in the Attribution guide.
The Tutorials section contains a list of step-by-step tutorials for using the Maps SDK for Unity.
In the API reference, you can view the complete reference documentation for the Maps SDK for Unity.