We’ve seen some amazing demos recently where people combine the Mapbox Unity SDK and Apple’s recently announced ARKit APIs to make stunning maps with 3D terrain and buildings that magically hover over objects in the real world. I wanted to break down the steps required to do this and turn this magic into reality.

Note: This project requires an iPhone 6S (or later) running a pre-release of iOS 11, a pre-release version of Xcode 9, and a patched version of Unity (Unity 5.6.1.p1 or later). Some experience with both Unity and iOS development using Xcode is helpful, but not required.

Step 1: Make a scene!

To get started, check out this guide to learn how to make a Unity scene with mesh terrain and Mapbox map imagery. In this post, I am using the Mapbox Satellite style in Honopu Arch on the Island of Kauai in Hawaii, but you can use any map style or location you want.

Once I’ve got a Mapbox map running in a scene in Unity, I connect it to ARKit on my device.

Step 2: Install the Unity ARKit Plugin

The team at Unity have made available a plugin that does all of the heavy lifting to get a scene up and running quickly on an iDevice with ARKit. I downloaded that plugin and followed the instructions in the repo to import the package into my development environment. It’s also worth noting this Unity forum for discussion about the plugin and using ARKit with Unity in general.

Once I’ve got the plugin installed (remember to make sure you are on the Unity 5.6.1.p1 or greater), there are just a few final steps to build and run the demo on device.

Step 3: Finishing touches

Now that I have a scene and all the other prerequisites completed, I’m ready to customize my map game object for display — in the real world!

Coming from the terrain mesh guide noted above, if I change the location string to a latitude of 22.1670308 and a longitude of -159.6720046 (for Honopu Arch in Kauai), I see a scene that looks like this:

Now I want to make a few adjustments to the Scene camera and map game object so that it’ll render at about the size of a small table.

Remove the skybox

Since I’m making a map for use in augmented reality, I want to strip out the virtual sky and horizon provided by default by Unity. That skybox would otherwise cover up the camera images in the background behind my map object. I use a green solid color instead of the default skybox value for my scene’s camera background:

Adjust the map game object

To make a map that is a good scale and positioned well for display above a real world object about the size of a small table, I position the map down about 300 units on the y axis, set a Unity Tile Size of 0.1 and set the Range Tile Provider script’s values all to 3.

Note: these values tend to look good for a small map on top of a table in the real world. However, a larger Unity Tile Size (and perhaps smaller range values) projects a much larger map that you can walk around in! But be careful out there!

Hook up the Unity ARKit Plugin scripts

The Unity ARKit Plugin that I installed before interfaces with the native ARKit APIs and is very customizable. However, to get my map up and running on the coffee table, there are just a few pre-built scripts I need to attach to my camera and a new, camera manager game object:

First, I add the UnityARVideo script as a new component to my camera and set the Clear Material to the YUVMaterial provided in the Unity ARKit Plugin package:

Second, I create a new camera manager game object (ARCameraManager is a fine name) and add UnityARCameraManager script. I associate the camera manager with my scene’s camera:

Final Step: Test your scene

I am now able to build my Unity project for an iOS device and install and run the application on my phone via Xcode. Again, this requires a pre-release version of Xcode 9 and an iPhone 6s (or later) device running a beta version of iOS 11.

If you just want to quickly try out this example, here’s my Unity-generated Xcode project. You can download that, sign up for a Mapbox account and set your access token in MapboxUnityARKitExample/Data/Raw/MapboxAccess.txt, and give it a spin!

Show us what you built. Share your demo and mention @Mapbox on Twitter or Instagram and use the hashtag #BuiltWithMapbox, we’ll send some prizes and swag to the best contributors.