Rares · Docs · Polestar

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.