Instant Placement developer guide for AR Foundation

Learn how to use the Instant Placement API, or persistent raycasts, in your own apps.

Prerequisites

Make sure that you understand fundamental AR concepts and how to configure an ARCore session before proceeding.

Concept names

Names of certain concepts and methods may differ between AR Foundation and the ARCore SDK for Unity. These are listed in the table below for easy reference.

AR Foundation ARCore SDK for Unity
Persistent raycasts Instant Placement
ARRaycastManager.AddRaycast(Vector2, float) Frame.RaycastInstantPlacement(float, float, float, out TrackableHit)
ARRaycast TrackableHit
(No equivalence) InstantPlacementPoint
ARRaycast.trackingState InstantPlacementPointTrackingMethod

Prerequisites

This guide assumes you have already installed and configured Unity. If not, see the Getting started with ARCore Extensions for AR Foundation for installation and setup steps.

Configure a new session with ARRaycastManager

Instant Placement (persistent raycasts) is available out of the box with the AR Foundation package. Follow these steps to set up your scene.

AR Foundation 4.x

  1. Add the predefined game objects AR Session Origin and AR Session.

  2. Add the AR Raycast Manager component into the AR Session Origin game object.

When Raycast Prefab is not null, ARRaycastManager will instantiate the prefab and automatically sync its pose with the pose of ARRaycast.

AR Foundation 5.x

  1. Add the predefined game objects XR Origin and AR Session.

  2. Add the AR Raycast Manager component into the XR Origin game object.

When Raycast Prefab is not null, ARRaycastManager will instantiate the prefab and automatically sync its pose with the pose of ARRaycast.

AR Foundation 6.x

  1. Add the predefined game objects XR Origin and AR Session.

  2. Add the AR Raycast Manager component into the XR Origin game object.

When Raycast Prefab is not null, ARRaycastManager will instantiate the prefab and automatically sync its pose with the pose of ARRaycast.

Place an object

In a new ARCore session, perform a hit test using ARRaycastManager.AddRaycast(Vector2, float).

public ARRaycastManager RaycastManager; // set from the Editor Inspector.

void Update()
{
    Touch touch;
    if (Input.touchCount < 1 || (touch = Input.GetTouch(0)).phase != TouchPhase.Began)
    {
        return;
    }

    if (EventSystem.current.IsPointerOverGameObject(touch.fingerId))
    {
        return;
    }

    ARRaycast raycast = RaycastManager.AddRaycast(touch.position, _estimateDistance);
    if (raycast != null)
    {
        // You can instantiate a 3D object here if you haven’t set Raycast Prefab in the scene.
        …
    }
}

Monitor the ARRaycast tracking state

If ARCore has an accurate 3D pose, the ARRaycast.trackingState will be Tracking. Otherwise, it will start with Limited and transition to Tracking once ARCore has an accurate 3D pose. Once the tracking state becomes Tracking, it will not revert to Limited.