# 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`](/docs/unity-sdk/headset-calibration/api-reference/#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](/docs/unity-sdk/headset-calibration/settings-reference/#calibration-hint-panel).

### 3. Build your own UI

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

```csharp title="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 [Calibration Demo sample](/docs/unity-sdk/headset-calibration/install/#try-the-demo-scene)'s **`CustomHintExample.cs`** is a complete version of this.

## Good to know

:::warning[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.
- **Placing the capture space with SkeletonConsumer's Origin?** The calibrator places the camera rig through it, so moving or rotating the Origin moves the player together with the skeletons. Keep the Origin unscaled and level (rotate it around its vertical axis only); the Console warns otherwise. Don't put the Origin inside the camera rig — it would move with the rig, so the calibrator warns and doesn't follow it. The rig may be inside the Origin. Needs 3.0.3.3R or newer.

## Next

[Tips for the wearer](/docs/unity-sdk/headset-calibration/wearer-tips/) — share these with whoever wears the headset.