# Headset Calibration API Reference (Unity)

The public C# API of **AR 51 Headset Calibration**, namespace **`AR51.HeadsetCalibration`**. <Badge>3.0.302</Badge>

For usage, see the [Developer guide](/docs/unity-sdk/headset-calibration/developer-guide/). For the core SDK types, see the [Unity SDK API reference](/docs/sdk-api/unity-api/).

## HeadsetCalibrator

<Badge tone="type">class · sealed</Badge> <Badge>Unity component</Badge>

```csharp
namespace AR51.HeadsetCalibration;

public sealed class HeadsetCalibrator : MonoBehaviour
```

Lines up the headset's world with the AR 51 capture space, automatically and continuously.

<div className="apiPropTable">

| Member | Type | Description |
|---|---|---|
| `RigRoot` | `Transform` (field) | The object that gets lined up. Empty = root of the main camera. |
| `SmoothingSeconds` | `float` (field) | How gently later corrections are applied (seconds). |
| `State` | [`CalibrationState`](#calibrationstate) (get) | How well the headset's world lines up right now. |
| `Hint` | [`CalibrationHint`](#calibrationhint) (get) | What the wearer can do right now; `None` when nothing. |
| `HasSolution` | `bool` (get) | `true` once the headset has been aligned at least once. |
| `HeadsetTracked` | `bool` (get) | The headset reports a valid pose this frame. |
| `HeadsetMounted` | `bool` (get) | The headset is on a head (`true` when the device doesn't say). |
| `SkeletonId` | `string` (get) | The wearer's tracked person, or `null` while finding them. |

</div>

### Events

```csharp
public event Action<CalibrationState, CalibrationState> StateChanged; // (previous, current)
public event Action<CalibrationHint> HintChanged;
```

| Event | Raised when |
|---|---|
| `StateChanged` | The state changes — with the previous and the new state. |
| `HintChanged` | The hint changes. |

### Methods

| Method | Description |
|---|---|
| `ResetCalibration()` | Start fresh (e.g. a new wearer). The view stays where it is until the new alignment is ready. |

## CalibrationHintPanel

<Badge tone="type">class · sealed</Badge> <Badge>Unity component</Badge>

```csharp
namespace AR51.HeadsetCalibration;

public sealed class CalibrationHintPanel : MonoBehaviour
```

Optional in-headset panel that shows the calibrator's hint. Its fields match the [Settings reference](/docs/unity-sdk/headset-calibration/settings-reference/#calibration-hint-panel).

### HintTexts

<Badge tone="type">class · nested · sealed · serializable</Badge>

The message shown for each hint.

| Member | Type | Description |
|---|---|---|
| `StepIntoView` | `string` | Text for the `StepIntoView` hint. |
| `HeadsetTrackingLost` | `string` | Text for the `HeadsetTrackingLost` hint. |
| `FindingYou` | `string` | Text for the `FindingYou` hint. |
| `HoldStill` | `string` | Text for the `HoldStill` hint. |
| `KeepWalking` | `string` | Text for the `KeepWalking` hint. |
| `Aligned` | `string` | The "You're aligned" confirmation. |
| `For(CalibrationHint hint)` | `string` | Returns the text for a hint. |

## CalibrationState

<Badge tone="type">enum</Badge>

| Value | Meaning |
|---|---|
| `NotAligned` | Not lined up yet; the view hasn't been moved. |
| `Aligning` | Roughly lined up; a few steps of walking make it precise. |
| `Aligned` | Lined up; corrections from now on are small and smooth. |
| `Lost` | Was lined up but can't follow right now (e.g. the headset lost tracking); the view stays until it recovers. |

## CalibrationHint

<Badge tone="type">enum</Badge>

| Value | Meaning | Default panel text |
|---|---|---|
| `None` | Nothing to do. | — |
| `StepIntoView` | The cameras see nobody. | Step into the capture area so the cameras can see you. |
| `HeadsetTrackingLost` | The headset lost its own tracking. | Headset tracking lost. Make sure the room is well lit. |
| `FindingYou` | The wearer isn't recognised yet. | Walk a few steps so the system can find you. |
| `HoldStill` | Needs a steady look for a moment. | Hold still for a moment and look straight ahead. |
| `KeepWalking` | Roughly lined up; finishing. | Walk a few more steps to finish aligning. |

## Examples

### Start gameplay once the headset is aligned

Keep your content hidden until the wearer is lined up, then show it. Lost alignment later doesn't hide it again — the view stays put while the calibrator recovers.

```csharp title="StartWhenAligned.cs"
using AR51.HeadsetCalibration;
using UnityEngine;

public class StartWhenAligned : MonoBehaviour
{
    public HeadsetCalibrator Calibrator;
    public GameObject Content; // your gameplay root, inactive at start

    private void OnEnable()
    {
        Calibrator.StateChanged += OnStateChanged;
        Content.SetActive(Calibrator.HasSolution); // already aligned, e.g. after a scene reload
    }

    private void OnDisable()
    {
        Calibrator.StateChanged -= OnStateChanged;
    }

    private void OnStateChanged(CalibrationState previous, CalibrationState current)
    {
        if (current == CalibrationState.Aligned)
            Content.SetActive(true);
    }
}
```

### Reset for a new wearer

Call `ResetCalibration()` when a different person puts the headset on — for example from an operator button. The view stays where it is until the new wearer is aligned.

```csharp title="NewWearerButton.cs"
using AR51.HeadsetCalibration;
using UnityEngine;

public class NewWearerButton : MonoBehaviour
{
    public HeadsetCalibrator Calibrator;

    // Hook this up to a UI Button's OnClick.
    public void OnNewWearer()
    {
        Calibrator.ResetCalibration();
    }
}
```

### Show your own hints

Listen to `HintChanged` and show your own UI — see the complete example in the [Developer guide](/docs/unity-sdk/headset-calibration/developer-guide/#3-build-your-own-ui).