# Mapbox Unity SDK: maps, location and routing inside a Unity project

> The Mapbox Unity SDK is a Unity Package Manager package that provides map rendering, device location, directions and geocoding to Unity apps targeting iOS and Android. The install is a package from disk, the access token is a text file in Resources, and the Android build needs a plugin folder copied by hand from the folder matching your editor version.

**mapbox/mapbox-unity-sdk** — Mapbox Unity SDK - https://www.mapbox.com/unity/

- Repository: https://github.com/mapbox/mapbox-unity-sdk
- Stars: 785 · Forks: 231
- Language: C#
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/mapbox-mapbox-unity-sdk

## A package from disk, not a folder you drop in

The Mapbox Unity SDK provides map rendering, location services, directions, and geocoding for Unity, and it is distributed as a Unity Package Manager package under the name com.mapbox.sdk. The primary language is C#, and the repository layout follows the UPM convention, with Runtime, Editor, Tests, Samples~, and Documentation~ directories alongside the package.json and the usual Unity .meta files.

The installation is four steps and none of them involve a package registry. You clone or download the SDK, open the Unity Package Manager with the Window menu, click the plus sign in the top left of the Package Manager window, choose Add package from disk, and select the SDK's package.json. The package then appears in the list of installed packages, and that is the verification step.

There is an explicit stopping point in the documentation. For an editor-only evaluation you can stop there, because iOS and Android each need one extra step at build time.

The manifest pins the compatibility requirements, and they are not negotiable. The minimum Unity version is 2022.3 LTS, the build targets are iOS and Android, and the render pipeline is the Universal Render Pipeline, which is required. The package depends on the URP package at version 10.10.1, the newtonsoft-json package at 3.2.1, Burst at 1.8.12, and the input system at 1.7.0.

Two of those dependencies come with a caveat worth reading. The terrain and building shaders ship as URP Shader Graphs, so URP is a hard requirement rather than a preference. And Burst is used for the Burst-compiled terrain decode and collider job, which means the first domain reload after you open the project pays a one-shot AOT compile, a one time cost that is easy to mistake for a slow editor.

## The editor version matrix, and the Android folder you copy yourself

The support matrix is a table of editor versions and their status, and it is unusually honest for a vendor SDK.

2022.3 LTS is the primary target, and its Android build settings folder ships at Runtime/AndroidBuildSettings/2022.3.38f1/. 2021.3 LTS is best effort, with its folder at 2021.3.41f1/. Unity 6, the 6000.x line, is also best effort with a folder at 6000/. 2023.x non-LTS is untested, and anything below 2021.3 is unsupported.

The practical consequence of that table is a manual step at build time. When building for Android, you copy the Plugins folder from the matching, or closest lower, editor version's subfolder under Runtime/AndroidBuildSettings into your project's Assets folder. This is not a package manager operation, and it is the step most likely to be forgotten.

The reason it exists is visible in the platform table. On iOS the native code ships as XCFrameworks under Runtime/Mapbox/BaseModule/Plugins/iOS/, which Unity's plugin importer picks up automatically, multi-slice. On Android the native libraries live under Runtime/Mapbox/BaseModule/Plugins/sqlite/Android/libs/ and are provided for arm64-v8a, armeabi-v7a, and x86, and the project-side configuration is required, which is what the copy step is for. The path includes sqlite because the on-device database is a native component, and that is exactly the kind of file the Package Manager cannot place for you in a per-editor folder.

The platform table is also where the boundaries are. Only iOS and Android are supported build targets, and the Unity Editor in Play mode on Windows or macOS is supported for development but is not a shipping target. Standalone, WebGL, console, and VisionOS are not supported.

So the answer to which Unity versions are safe to target is narrow and precise: 2022.3 LTS if you want the documented path, and the other two only if you are prepared to test your own build.

## The access token is a text file in Resources

Every Mapbox API call, whether for tiles, geocoding, or directions, requires a Mapbox access token, and the way the SDK takes it is simple.

You set the token through the editor menu, with Mapbox then Setup, and it is stored at Assets/Resources/Mapbox/MapboxConfiguration.txt, loaded at runtime through Resources.Load. You get a token from the account page at account.mapbox.com/access-tokens.

Two details are worth noting. The token lives in a text file inside the project, under Assets, which means it is committed to your repository unless you exclude it, and it is shipped inside your build, which means it is extractable from the build. Neither of those is unusual for a mobile SDK, but it is a decision you should make knowingly rather than inherit.

The second detail is the SKU token, which is appended to signed requests automatically. That is Mapbox's mechanism for attributing usage to a specific SKU, and it means the requests the SDK makes are attributable out of the box, which is convenient for billing and for quotas.

The package manifest also shows the shape of the whole feature set, which is worth reading as a summary of what the SDK is.

```json
{
    "name": "com.mapbox.sdk",
    "version": "3.1.1",
    "unity": "2022.3",
    "dependencies": {
        "com.unity.render-pipelines.universal": "10.10.1",
	"com.unity.nuget.newtonsoft-json": "3.2.1",
	"com.unity.burst": "1.8.12",
	"com.unity.inputsystem": "1.7.0"
    }
}
```

The README records the current version as 3.1.0 while the manifest says 3.1.1, which is the kind of small drift you get between a release and the commit that follows it, and it is another reason to read the CHANGELOG rather than the README table when you are pinning a version.

## Five samples, and the one that is a game starting point

Five sample scenes ship with the SDK, and you import them from the Package Manager, by selecting the Mapbox Unity SDK, going to the Samples tab, and clicking Import next to the one you want. After import each sample lives under Assets/Samples/Mapbox Unity SDK, with the version and the sample name in the path, and the documentation tells you to copy the relevant pieces into your own layout and delete the Samples folder.

The samples are chosen to cover the feature list rather than to look impressive. WorldMapViewer is the minimal setup, a pan and zoom interactive world map, and the README recommends it as the best first-time evaluation target. DirectionsApiDemo calls the Directions API and renders a route on the map. GeocodingApiDemo does forward and reverse geocoding. MapboxComponents demonstrates high performance component-system-based layer rendering, with buildings, areas, and roads.

The fifth is the one worth knowing about. LocationBasedGame takes the device GPS and turns it into in-scene avatar movement, and the README calls it the starting point in the style of a location based mobile game. It includes a LocationBasedMap prefab that is described as a useful starting point for any GPS-driven game, since dropping it into a scene gives you a working location-aware map with a follow camera and a character that follows the device location.

That prefab is the fastest evaluation path for a team whose actual product is a location game, because the map, the camera, and the avatar are already wired together.

The samples are also the only documentation of the API you get inside the repository itself, since the rest of the documentation lives in the Documentation~ directory with a Getting Started guide and a camera system guide among the files referenced.

## Fixed coordinates in the Inspector, or the device GPS at build time

The SDK gives you two ways to decide where the map is looking, and the choice between them is the main design decision in an app built on it.

The first is the MapboxMapBehaviour component, which has a MapInformation field with editable latitude, longitude, zoom, pitch, bearing, and scale. With Initialize On Start checked, the map opens at those coordinates at startup. The README positions this as good for development and for apps where the map location is fixed or driven by your own UI, with a city tour and a real-estate app filtered by area as the examples.

The second is the LocationModule, which swaps in device GPS at build time and predefined test coordinates in the editor. That swap is the useful part for a developer, because your editor play mode shows one place and the built app shows the real device position, without a second code path.

Wiring it up takes three steps, and the first one is a step you have to take rather than a step you can skip. You disable Initialize On Start on the MapboxMapBehaviour, because the location provider will initialize the map asynchronously when the first GPS fix comes in. You add Snap Map To Location Provider to your map GameObject, which moves the map centre to follow the device location. And you attach Snap Transform To Location Provider to the character or avatar transform, so the avatar follows the device position in world space.

The asynchronous first fix is the part that changes how you write the rest of the app, because the map does not exist at a fixed moment in the first frame. Anything that assumes a camera position or a map centre in Start has to wait for the provider instead.

For a marker at a chosen coordinate rather than a GPS-driven one, the README points into the Getting Started guide for placing a GameObject at a latitude and longitude.

## iOS build settings, and the licence you have to read

The iOS build requirements are a short table, and every line of it is mandatory rather than advisory.

The scripting backend must be IL2CPP, the minimum iOS version recommended is 11.0 or newer, the architecture is ARM64, and if you request location you have to set NSLocationWhenInUseUsageDescription, or NSLocationAlwaysUsageDescription, in Info.plist before asking for it. The XCFrameworks, MapboxCommon and Turf, ship multi-slice and are picked up automatically by the Unity plugin importer, so there is no manual work on that side beyond the settings.

The IL2CPP requirement and the location permission string are the two that catch people out. IL2CPP matters because the alternative scripting backends are not covered by the supported configuration, and the permission string matters because the app crashes or silently fails to get a fix without it, which is the platform's enforcement rather than the SDK's.

On the licence, the repository is classified by GitHub as having a custom licence that it cannot be classified automatically, and there is a LICENSE file at the root. The SDK is a commercial product from a vendor, so the terms are the ones in that file, and the practical point for an engineer is that a mapping SDK with a token, a SKU, and usage terms attached is not something you treat like a permissive open source dependency. Read the file before you ship, and check what the token in the Resources file permits for the distribution model you are using.

On maintenance, the repository is not archived and the last push was on 2026-10-19, so the package is being worked on, but there are no GitHub releases, which is normal for a UPM package that is consumed from disk. The version history lives in CHANGELOG.md, and the upgrade path from 3.0 to 3.1 has its own document in Documentation~, named Migration-3.0-to-3.1.md, which is where to look if you are moving up a version.

## Conclusion

The Mapbox Unity SDK fits a mobile Unity team that wants a map, device location, routing and geocoding without building a tile pipeline, and that is already committed to the Universal Render Pipeline, since the package requires it. It does not fit a studio shipping a standalone, WebGL or console build, since only iOS and Android are supported targets, and it does not fit a team unwilling to maintain a per-editor-version plugin copy step for Android. Verify first that your editor version is on the support matrix, with 2022.3 LTS as the primary target and 2021.3 and Unity 6 marked best effort, that your Mapbox access token is set through the Mapbox Setup menu before the first API call, and that you read the migration notes in Documentation~ if you are moving up from version 3.0.

## FAQ

### How do I install the Mapbox Unity SDK?

Clone or download the SDK, open the Unity Package Manager with the Window menu, click the plus sign, choose Add package from disk, and select the SDK's package.json. The package then appears in the installed list, and iOS and Android builds each need one extra step afterwards.

### Which Unity versions does the Mapbox Unity SDK support?

2022.3 LTS is the primary target, 2021.3 LTS and Unity 6, the 6000.x line, are best effort, 2023.x non-LTS is untested, and anything below 2021.3 is unsupported. The Universal Render Pipeline is required, and the package depends on the URP package at 10.10.1.

### Where is the Mapbox access token stored?

You set it through the Mapbox then Setup editor menu, and it is stored at Assets/Resources/Mapbox/MapboxConfiguration.txt, loaded at runtime through Resources.Load. An SKU token is appended to signed requests automatically, and tokens are created at account.mapbox.com/access-tokens.

### What extra step does an Android build need?

You copy the Plugins folder from the matching, or closest lower, editor version's subfolder under Runtime/AndroidBuildSettings into your project's Assets folder. The native libraries for arm64-v8a, armeabi-v7a, and x86 live under the sqlite Android plugins folder, and this project-side step is what places them.

### How do I make the map follow the device GPS in Unity?

Disable Initialize On Start on the MapboxMapBehaviour, add Snap Map To Location Provider to the map GameObject so the centre follows the device, and attach Snap Transform To Location Provider to the character transform so the avatar follows in world space. The LocationBasedGame sample does exactly this.

## Sources

- [Issues](https://github.com/mapbox/mapbox-unity-sdk/issues)
- [mapbox/mapbox-unity-sdk on GitHub](https://github.com/mapbox/mapbox-unity-sdk)
- [README](https://github.com/mapbox/mapbox-unity-sdk/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mapbox-mapbox-unity-sdk