Skip to content

The "Hello ARC" App

Jump to bottom
Giorgio edited this page Jul 7, 2021 · 14 revisions

This "Hello World" guide walks you through creating a project, installing the ARC library, and creating the basic components for your first networked game.

Requirements

This tutorial requires a Unity version that supports the Multiplayer HLAPI, the AR Foundation package, and the ARCore or ARKit XR plugins, as well as an AR-capable mobile device.

Create a new project in Unity

  1. Open the Unity Hub.
  2. Click New.
  3. Select type "3D".
  4. Rename the project "Hello World".
  5. Select the location to save the project.

Import the required libraries

See the documentation linked above to install HLAPI, AR Foundation and its XR plugins, as well as configuring your project for a mobile AR app.

Import the ARC library

See the Importing the Library guide to install the ARC library.

Setting up a Sample Scene

First, we must create a basic AR scene for the project. According to the Scene Setup manual:

  1. Right-click in the scene hierarchy.
  2. Select XR > AR Session and XR > AR Session Origin from the context menu.
  3. Select the AR Camera game object in the scene hierarchy, and set its tag to MainCamera.

Your project hierarchy should now look like this:

Sample scene hierarchy

Create the Basic Components

In this section, we will create the basic building blocks of a multiuser shared session.

Creating the ARC Manager

In this section, we will add an ARC Manager.

  1. Right-click in the Hierarchy tab of the Main Unity Window.
  2. Select Create Empty.
  3. Rename the GameObject ARC Manager.

There should only be one ARC Manager in your scene. It is the object that contains the ARCSetupManager component. You may get unexpected results if you create more than one ARC Manager.

  1. Select ARC Manager.
  2. Click Add Component in the Inspector Tab.
  3. Select ARC from the list shown.
  4. Select the ARCSetupManager component from the list displayed.
  5. Save your scene.

Setting up CaptainsMess

You may have noticed that when adding the ARCSetupManager component, a CaptainsMess component is added as well. This is because the ARC library requires it to manage networking. We will now set it up with a user Prefab and a network event listener.

Creating an object to spawn for each connected user

  1. Right-click in the Hierarchy tab of the Main Unity Window.
  2. Select Create Empty.
  3. Rename it ARC User.
  4. Add an ARCUser component.
  5. Click the Assets folder.
  6. Create a new folder and call it Prefabs.
  7. Make ARC User a prefab by dragging it to the Prefabs folder you just created.
  8. Delete ARC User from the scene.

We remove User because we will be using CaptainsMess to spawn the user. The library cannot track objects that start in the scene.

  1. Select ARC Manager.
  2. Inside the CaptainsMess component tab, locate the Player Prefabs field.
  3. Drag the user prefab from above into the empty slot.

Creating an object to invoke networking events

  1. Right-click in the Hierarchy tab of the Main Unity Window.
  2. Select Create Empty.
  3. Rename it ARC Listener.
  4. Add an ARCSessionListener component.
  5. Select ARC Manager.
  6. Inside the CaptainsMess component tab, locate the Listener field.
  7. Drag the ARC Listener game object from the Hierarchy into the empty slot.

Creating an object to spawn for the current session

  1. Right-click in the Hierarchy tab of the Main Unity Window.
  2. Select Create Empty.
  3. Rename it ARC Session.
  4. Add an ARCSession component.
  5. Click the Assets folder.
  6. Make ARC Session a prefab by dragging it to the Prefabs folder.
  7. Delete ARC Session from the scene.
  8. Select ARC Listener.
  9. Inside the ARCSessionListener component tab, locate the Shared Session Prefab field.
  10. Drag the ARC Session prefab from above into the empty slot.

Creating a static scenery

  1. Right-click in the Hierarchy tab of the Main Unity Window.
  2. Select Create Empty.
  3. Rename it Scenery and centre it at (0, 0, 0).
  4. Create some 3D objects and place them around the scene.
  5. Select all 3D objects above and parent them to the Scenery object.
  6. Click the Assets folder.
  7. Make Scenery a prefab by dragging it to the Prefabs folder.
  8. Delete Scenery from the scene.
  9. Select ARC Manager.
  10. Inside the ARCSetupManager component tab, locate the Static Scene Prefab field.
  11. Drag the Scenery prefab from above into the empty slot.

Create a User Interface

The current object setup is enough for a simple scene. Since the ARC library needs user input to work, we will create a user interface to interact with it. While this mainly consists of GUI elements, the ARCSetupManager component exposes some meaningful fields too.

Creating the setup UI

  1. Right-click in the Hierarchy tab of the Main Unity Window.
  2. Select UI > Button. A Canvas object with a Canvas component will be created automatically.
  3. Rename the button GameObject ButtonStart.
  4. Expand the ButtonStart hierarchy, and select the nested Text GameObject.
  5. Inside the Text component tab, locate the Text field and change its content to "Start".
  6. Create three more buttons, rename them ButtonCancel, ButtonCapture, and ButtonContinue respectively, and change their description text accordingly.
  7. Set all buttons inactive except for ButtonStart.

Making the UI buttons interactive

  1. Select ButtonStart in the Hierarchy tab of the Main Unity Window.
  2. Inside the Button component tab, locate the On Click() Event field.
  3. Click + to create a slot.
  4. Select ARC Manager and drag it in the empty Object field.
  5. Click "No Function".
  6. Select CaptainsMess > AutoConnect ().

We are adding a listener to the button's OnClick event. When the button is clicked (or tapped), the CaptainsMess.AutoConnect() function will be triggered.

  1. Repeat steps 1-6 for the other three buttons:
    • ButtonCancel: add the CaptainsMess.Cancel() function.
    • ButtonCapture: add the ARCSetupManager.CaptureImage() function.
    • ButtonContinue: add the ARCSetupManager.SubmitCapturedImages() function.

Showing/hiding the UI

In this section, we will use the ARCSessionListener events to control the UI visibility. This way, the user will see only buttons related to the current app state.

  1. Select ARC Listener in the Hierarchy tab of the Main Unity Window.
  2. Inside the ARCSessionListener component tab, locate the Start Connecting () field.
  3. Add a slot for ButtonStart and assign the GameObject.SetActive function with argument false.
  4. Add a slot for ButtonCancel and assign the GameObject.SetActive function with argument true.

Start Connecting preview

We are adding more listeners to the events. This time, they are invoked by another script rather than being triggered by clicking a button.

  1. Inside the ARCSessionListener component tab, locate the Stop Connecting () field.
  2. Add a slot for ButtonStart and assign the GameObject.SetActive function with argument true.
  3. Add a slot for ButtonCancel and assign the GameObject.SetActive function with argument false.

Stop Connecting preview

  1. Inside the ARCSessionListener component tab, locate the Joined Lobby () field.
  2. Add a slot for ButtonStart and assign the GameObject.SetActive function with argument false.
  3. Add a slot for ButtonCancel and assign the GameObject.SetActive function with argument false.

Joined Lobby preview

  1. Inside the ARCSessionListener component tab, locate the Server Created () field.
  2. Add a slot for ButtonCapture and assign the GameObject.SetActive function with argument true.
  3. Add a slot for ButtonContinue and assign the GameObject.SetActive function with argument true.

Server Created preview

We want to show some buttons only to the current session host since they're the only ones who should capture the marker images for the current session.

  1. Inside the ARCSessionListener component tab, locate the Left Lobby () field.
  2. Add a slot for ButtonStart and assign the GameObject.SetActive function with argument true.
  3. Add a slot for ButtonCancel and assign the GameObject.SetActive function with argument false.
  4. Add a slot for ButtonCapture and assign the GameObject.SetActive function with argument false.
  5. Add a slot for ButtonContinue and assign the GameObject.SetActive function with argument false.

Left Lobby preview

  1. Select ARC Manager in the Hierarchy tab of the Main Unity Window.
  2. Inside the ARCSessionManager component tab, locate the Capture Completed () field inside the Capture Events dropdown.
  3. Add a slot for ButtonCapture and assign the GameObject.SetActive function with argument false.
  4. Add a slot for ButtonContinue and assign the GameObject.SetActive function with argument false.

Capture Completed preview

Add gizmos when tracking the markers

  1. Right-click in the Hierarchy tab of the Main Unity Window.
  2. Select 3D Object > Sphere.
  3. Rename the new GameObject GizmoScanning.
  4. Set its scale to (0.1, 0.1, 0.1).
  5. Select 3D Object > Cube.
  6. Rename the new GameObject GizmoScanned.
  7. Set its scale to (0.1, 0.1, 0.1).
  8. Click the Assets folder.
  9. Make GizmoScanning and GizmoScanned prefabs by dragging them to the Prefabs folder.
  10. Delete GizmoScanning and GizmoScanned from the scene.
  11. Select ARC Manager.
  12. Inside the ARCSetupManager component tab, locate the Scanning Prefab field.
  13. Drag the GizmoScanning prefab from above into the empty slot.
  14. Inside the ARCSetupManager component tab, locate the Marker Scanned Prefab field.
  15. Drag the GizmoScanned prefab from above into the empty slot.

Testing Hello ARC

Now we will test to see if everything works as expected. Build the app and deploy it to your mobile device.

  1. When the app starts, look around you to let AR Foundation detect your surroundings.
  2. When you're done, tap Start.

If you now tap Cancel, the session startup process will stop, and the button Start should show up again.

  1. Take a picture of (at least) two flat objects on a horizontal surface by tapping on Capture.
  2. When you're done, move away. Then, tap Continue.
  3. Now, the scanning phase begins. Hover your phone over the objects you just photographed. Let AR Foundation detect the surface.

When an image is being tracked, a small 3D sphere will appear on top of it. Once an image has been scanned, a cube will replace the sphere. When all images are detected, the cubes will disappear, and the static scenery will appear instead.

  1. If you follow the previous steps using a different device, the capture button will not show up. Instead, the app will skip to the scanning phase once the host confirms the marker images to be used.

All connected devices must scan the markers, then everyone will see the same static scenery at the same spot in the environment.

Congratulations! You have created your first multiuser AR app! For the next steps, see Building on Hello ARC.

© 2021 Giorgio Liggio
Clone this wiki locally