If you’ve ever wanted to add real world maps to your Unity game or application, you’re in luck. This week, I tried out the Mapbox Unity plugin and have to report that it’s extremely easy to use and pretty powerful. If you want to get real world maps like PokemonGO, or even generate a voxel world from real terrain, mapbox makes it quick and painless to accomplish. These Unity3D maps can be generated dynamically at runtime or if you have a specific location you can pre-build them and include them with your app or game.
Getting the Unity3d maps SDK (MapBox)
You can download the mapbox Unity SDK here: https://www.mapbox.com/unity/
It comes as an .assetpackage file that you import into your project.
Account Setup
Before you can use mapbox in your application, you need an account and an API key.
Create an account on the mapbox site.
Visit your API Tokens page and copy your api token: https://www.mapbox.com/studio/account/tokens/
Open the Mapbox window.
Enter your Access Token
If it’s valid, you should see the “TokenValid” notification in the window.
Examples
The first thing I’d recommend you try is load up the various example scenes that come with the package.
These examples show a good sampling of the things you can do with the mapbox plugin.
Start with the Slippy demo, it’s likely the most applicable for your projects.
It shows how to select an area and start scrolling along, loading in new tiles as they’re needed (much like you’d do if you were tracking a persons real world position).
The mesh here is 3d, you can also run on it, fly over it, or anything else you’d do with a 3d terrain
You can adjust the starting location and zoom range with the MapController gameobject in the scene.
What kind of maps can I have?
If you take another look at the MapController, you’ll see there’s a Map Visualization field.
The Map visualization controls exactly what it says, the visuals of your map. You can customize it or build your own from scratch (I’d recommend customizing a few first).
They’ve also bundled a variety of visualizations into the plugin, if you search and replace (or try out other demo scenes), you can see how some of these look.
For example, here I’ve swapped in the PoiDemoVisualization and moved our starting point to London
Voxel Maps
Or.. maybe you want a minecraft style voxel representation of your area..
The VoxelWorld scene shows exactly how to set this up.
Pre-building a map
One thing I needed to do and you may as well is pre-generate a map for a specific area.
If your application or game only needs a certain geographic area, maybe a map of some specific city, or a big landmark like the pyramids.. you can build it and bundle it in with very little work.
The MapController class that ships with the plugin is meant to be a demo/starting point, but with a little extension you can change it to be an editor time generator instead of runtime.
The quick and dirty way to do this is just edit the MapController class and move the map generation / initialization to a context menu.
Change this..
To this..
And you’ll have a context menu like this that you can use before pressing play.
It’s important to note that if you do this, you WILL break the demos. So if you’re even a little comfortable with c#, you’re probably better off copying the MapController class and making your own modified version of it. Or if you’re very comfortable with c#, dig in and build something awesome.
Range
The last thing I want to cover is the Range field. This tells Mapbox how many tiles away from the Lat/Lng you want to generate in each direction (N, E, S, W). It defaults to 0, but you can adjust it to the values that feel right for your specific application.
Performance Notes
While I was trying out this plugin, I wanted to know how it would fare for performance. With some of the demos I quickly realized there was a big variance on the vertex count depending on some options.
The biggest performance hit I came across was with generating roads. With roads on, in a smaller metropolitan area, my vertex count went from around 500,000 to 20,000,000.
This could be a bug, or it could be me using the SDK wrong, I’m not sure (though I’m going to ask the developers). But if you need to keep your counts down, I’d recommend disabling road generation in your visualiaztion settings (or using one of the predefined ones that doesn’t generate road meshes).
Pricing
I haven’t had a need to pay for Mapbox yet because my usage is pretty small. The free plan covers up to 50,000 users a month on mobile, and after that the price jumps up quick to $499/mo.
But if you have more than 50k users a month in your app or game and collect any revenue at all, the cost should be nominal.
The big limit on the free version seems more than generous and is probably the tier most people are in.
if you pre-generate the maps, you’re never calling the sdk and wouldn’t hit this either, but again that’s only valid for uses where you don’t need the whole world, just a tiny area.
Conclusions
I really love this Mapbox SDK and the fact that it’s free to use for most projects. It’s easy to get setup with and customize to your hearts desire. I plan to keep using it going forward and dig in deeper to discover all the power inside.