Headset Calibration Developer Guide (Unity)

How to work with AR 51 Headset Calibration in your Unity app: read its status, show hints to the wearer, and avoid the common integration pitfalls.

It's automatic

Once the Headset Calibrator is in the scene, alignment runs by itself for the whole session — you never call "calibrate". Your only job is to let the wearer know what to do when something is missing, and the calibrator tells you exactly that.

Status you can read

On HeadsetCalibrator:

• State — how well it's lined up right now:
  • NotAligned — not lined up yet.
  • Aligning — roughly lined up; a few more steps make it precise.
  • Aligned — lined up.
  • Lost — was aligned but can't follow right now; the view stays where it is.
• Hint — what the wearer can do now: None, StepIntoView, HeadsetTrackingLost, FindingYou, HoldStill, KeepWalking.
• Events — StateChanged(previous, current) and HintChanged(hint).

Showing hints — three options

1. Use the ready panel

The prefab includes CalibrationHintPanel by default. It shows a short message in front of the wearer only when they can help — after a hint has lasted 2 seconds — and hides once aligned. A brief "You're aligned" confirms the end.

2. Change its texts

In the panel's inspector, edit Texts to match your app's wording or language, and tune the delay, distance and height. See Settings reference.

3. Build your own UI

Turn the panel off (untick Show Hints, or remove the component) and listen to the events:

MyHints.cs

using AR51.HeadsetCalibration;
using UnityEngine;

public class MyHints : MonoBehaviour
{
    public HeadsetCalibrator Calibrator;

    private void OnEnable()
    {
        Calibrator.HintChanged += OnHint;
    }

    private void OnDisable()
    {
        Calibrator.HintChanged -= OnHint;
    }

    private void OnHint(CalibrationHint hint)
    {
        // Show your own message, play a sound, or pause gameplay until hint == None.
        Debug.Log(hint);
    }
}

The sample's CustomHintExample.cs is a complete version of this.

Good to know

The calibrator moves your camera rig's root

If your app also moves the rig (teleport, smooth locomotion), put that movement on a child object of the rig — otherwise the two fight.

• Smoothing (default 20 s) sets how gently later corrections are applied; higher is calmer for the wearer. The first alignment, and the one after a headset recenter, are applied at once.
• New wearer? Call ResetCalibration() when a different person puts the headset on. The view stays where it is until the new alignment is ready.
• SkeletonId tells you which tracked person is the wearer (empty until found) — handy for hiding the wearer's own avatar.

Next

Tips for the wearer — share these with whoever wears the headset.