# Rares

> Rare NPCs and treasures

Page: https://polestar.guide/docs/contributors/architecture/rares (Polestar docs > Contributors > Architecture)

`addon/Polestar/Rares/` (`Rares\Rares.xml`, loaded after `UI\UI.xml`):
`Rares.lua` (settings `rares.*`, history, the decision), `Detect.lua` (client
events), `Pins.lua` (map layers), `Toast.lua` (the alert), `Options.lua`
(Discovery → Rares: When a rare shows up, How rares are noticed, History; Map
→ Rares & travel → Rares and treasures), `View.lua` (the hub section).
Everything is off with `rares.enabled`; a detection path that is off has no
event registered.

```lua
Polestar.Rares.Decide(s, ctx) -> action, reason   -- pure; "alert" | "hold" | "record" | "skip"
Polestar.Rares.Sighting(s, where) -> action, reason -- decide, record, alert (RARE_SPOTTED)
Polestar.Rares.History() -> { [key] = { kind, id, name, level, t, first, n, map, x, y, src, alerted, dead } }
Polestar.Rares.Info(kind, id) -> { kind, id, name, level, levelMax, elite, instance, spawns, loot } | nil
Polestar.Rares.BuildPins(o) -> pins                 -- pure pin selection
Polestar.Rares.Show(kind, id)                       -- SHOW_RARES: the hub section at it
```

- **Detection** (APIs verified against `.ref/wow-ui-source-forever`, 1.60.1):
  vignettes (`VIGNETTE_MINIMAP_UPDATED`, `VIGNETTES_UPDATED`,
  `C_VignetteInfo.GetVignetteInfo` / `GetVignettePosition`; Forever's world
  map adds `VignetteDataProvider`): a creature behind a vignette is a rare, a
  game object a treasure, with its exact position; nameplates
  (`NAME_PLATE_UNIT_ADDED` + `UnitClassification` "rare" | "rareelite"),
  target (`PLAYER_TARGET_CHANGED`) and mouseover (`UPDATE_MOUSEOVER_UNIT`).
  A unit counts when the client calls it rare or the Codex (if loaded) knows
  its NPC as one. Secret values read as unknown. Event payloads only: a GUID
  is looked at once per 3 s, the full vignette scan runs at most every 2 s
  and never in combat. Nothing is detected inside instances.
- **The decision**: off, instance, path off, players and pets, not a rare →
  skip; muted (`rares.ignored`) → skip; dead, alerts off, treasure alerts
  off, or alerted within `rares.cooldown` minutes → recorded only; in combat
  without `rares.combatAlerts` → held until `PLAYER_REGEN_ENABLED` (dropped
  after a minute); else the alert (`RARE_SPOTTED(alert)`, sound
  `rares.soundKit` when `rares.sound`).
- **History**: account-wide per realm, `PolestarDB.rares.history[realm][key]`
  (`"rare:<npc>"`, `"treasure:<object>"`, `"name:<name>"` without an id), at
  most 400 entries; the cooldown reads `alerted` (epoch seconds), so it
  survives a reload. Losing it only resets cooldowns and the Seen list.
- **Toast** (`PolestarRareToast`): name, "Level n Rare · 85 yd · Zone"
  (vignettes: the distance; units: "in sight"; a vignette without a position:
  "known spawn 120 yd"), "Set waypoint" (the vignette's position, asked again
  on the click and on parent maps when the player's map lacks it; a unit:
  where it was seen; else the nearest known spawn on the player's continent,
  or no waypoint) and "Show rare" (the section),
  `rares.toastSeconds` with a drain line, held under the cursor, draggable
  (`rares.toastPoint`).
- **Pins**: layers `rares.rare` and `rares.treasure` through `Polestar.Pins`,
  world map and minimap per kind (`rares.worldRares`, `worldTreasures`,
  `minimapRares`, `minimapTreasures`; all off by default, Map → Rares & travel →
  Rares and treasures); one pin per distinct spawn (spawns of
  one rare within 1.5 map percent share it), rares at grey levels left out
  with `rares.hideGrey`, elites ringed, ones seen in the last two hours
  glowing. Click: the section; Shift-click: waypoint. The Codex loads when
  the world map opens with a world kind on, or after login with a minimap
  kind on. A layer is due once its minimap kind is on, or its world kind is
  on and the world map has opened; only then are its records decoded, 40 per
  frame, never inside `Codex.Load` (`CODEX_LOADED` only schedules a refresh
  for the next frame), so a search or tooltip that loads the Codex pays
  nothing for the pins.
- **Section** (hub, order 50): nav Rares / Treasures / Seen with counts, the
  hub search filters by name or zone; list by zone (the player's first) or,
  under Seen, newest first; the selection shows Drops (its signature drop
  from `Codex.Loot`: the best quality, then the highest item level; no loot
  table, no drop rates; click opens Lookup, Alt-click `Lookup.Guide`), Where (`Lookup.Sources(kind, id)`: spawns with travel; a
  click sets the waypoint) and Seen. "Look up" opens it in Lookup.

---

Next page: [Talents](https://polestar.guide/docs/contributors/architecture/talents.md) · Every docs page: https://polestar.guide/llms.txt · All docs in one file: https://polestar.guide/llms-full.txt