# Tracker HUD

# Tracker HUD

The tracker HUD shows up to **3 achievements** you follow, with live progress. Since 3.0.0 it uses cards in the KyuubiSoft style, and one toast announces every unlock.

:::note
The HUD is new in 3.0.0 and has not been tested in game yet.
:::

---

## Tracker cards

Each card shows:

- the achievement icon with its difficulty ring,
- "category · difficulty" and the percent,
- the name and a progress bar with the count.

A footer line gives a short hint.

The tracker has a fixed place on the left of the screen, below the pet HUD, so it does not cover the HUDs of other KyuubiSoft mods. Since 3.1.6 nobody can move it: there is no position choice in the book settings, in `/kssettings` or in the admin window, and positions saved by older versions are ignored.

## Tracking achievements

- In the [achievement book](./ui-pages), press **Track** in the detail panel. **In tracker** shows it is already tracked; **Tracker full** shows the limit is reached.
- A tracked achievement leaves the tracker when it unlocks.
- With **Track the next stage automatically** (default on), the next stage of a chain is tracked when one stage unlocks.

## Settings

Every player sets their own tracker in the book settings (gear in the book header) or, with KyuubiSoft Core 2.8.0 or newer, in the shared settings window `/kssettings`. Changes apply at once.

| Setting | Default |
|---------|---------|
| Show the tracker | on |
| Progress | on |
| Track the next stage automatically | on |
| Hide the tracker when empty | on |
| Achievements in the tracker | 3 (1 to 3) |

## When the HUD hides

- While the world map is open.
- When the player turned it off, or when nothing is tracked and **Hide the tracker when empty** is on.

The HUD is attached when the player is ready in the world (also after a world change) and is put back automatically when another mod or a window removed custom HUDs.

---

## Unlock toast

One toast per unlock bundles the achievement, the points, the title (in its colour) and the reward hint. It appears when `notifications.displayMode` is `banner` (default for new installs) or `both`; `chat` sends one chat line instead. `notifications.displayDurationMs` sets how long the toast stays.

The toast appears right below the compass. It shares the rows there with the toasts of the other KyuubiSoft mods: it takes the highest free row and goes lower only while another toast is still on screen, so toasts never cover each other. The "Rewards waiting" hint after join uses the same rows. This needs KyuubiSoft Core 2.9.9 or newer.

---

## Server options

```json
"trackerHud": {
  "enabled": true
}
```

| Option | Default | Description |
|--------|---------|-------------|
| `enabled` | `true` | Turns the tracker HUD off for everyone |

The older key `trackerHud.position` is ignored.

---

## Troubleshooting

| Problem | Check |
|---------|-------|
| HUD not shown | Is something tracked? Is **Show the tracker** on? Is `trackerHud.enabled` true? |
| Progress does not move | Playtime counts in steps; creative mode is not counted by default (`tracking.ignoreCreativeMode`) |
| Shared HUD space with other mods | Since 3.0.0 every mod has its own HUD slot; no extra mod is needed. Since 3.1.6 the tracker and the toast have fixed places that do not overlap with the other KyuubiSoft HUDs |