# 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.

## Next

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