# Lookup

> Codex, sources, generated guides, mount spotting

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

`addon/Polestar/Lookup/` (`Lookup.xml`: Codex, Sources, Guide, Spotter,
Options). Everything is off with `lookup.enabled`; `lookup.tooltip`,
`lookup.altClick` and `lookup.mounts` switch the parts (Discovery → Lookup).

```lua
Polestar.Codex.Load() / IsLoaded() / Meta()       -- the local Polestar_Codex pack through Data.Pack; CODEX_LOADED(meta)
Polestar.Codex.Item(id) / Npc(id) / Object(id) / Quest(id) / Instance(key) / Zone(id) / Faction(id) / Spell(spellId)
Polestar.Codex.Name(kind, id) ; Codex.WithRole(role) ; Codex.Loot(kind, id) ; Codex.Each(kind, fn(id, name, quality, status))

Polestar.Lookup.Sources(kind, id, direct) -> rows, entity  -- ranked for this character; direct: straight-line travel, no route plan (tooltips)
   -- row = { type, src, label, detail, zone, map, x, y, f, travel, effort, cost, available, why, whyText,
   --         chance, price, standing, guideable }
Polestar.Lookup.CuratedGuide(kind, id) -> guideId | nil
Polestar.Lookup.BuildGuide(kind, id, ranked) -> def | nil, reason
Polestar.Lookup.Guide(kind, id, index) -> guideId | nil, reason
Polestar.Lookup.UnitMount(unit) -> { spell, item, name, icon, class } | nil
Polestar.Lookup.Show(query, kind, id)                 -- SHOW_LOOKUP(query, kind, id) for UI/Lookup.lua
Polestar.Lookup.RegisterPlanner(kind, build)          -- build(id) -> { title, steps, ... } | nil, reason: another module's guide kind
Polestar.Lookup.QuestChain(questId, player) -> { quest, ... }, truncated  -- open prerequisites first, the quest last
Polestar.Lookup.QuestStep(quest, from) -> step         -- accept, objectives, turn-in
```

- **Codex records** use the field names of `data/forever/codex/*.json` (see
  Toolchain, "Codex"); the pack holds one compact string per record plus an
  id → name table per group, so search never decodes records, and decoded
  records are cached weakly.
- **Ranking.** A row is unavailable (kept, dimmed, `why` = `faction`, `race`,
  `class`, `level`, `profession`, `reputation`, `done` or `retired`) when the character
  cannot use it now; available rows come first, then by `cost` = travel
  (`ns.TravelCost` from the player to the nearest spawn, giver or dungeon
  entrance; Nav's planner when present) + effort (expected kills from the drop
  chance and the mob's level, a dungeon run per boss kill, a rare's respawn,
  quest objectives and prerequisites, reagents and missing skill, hours for
  reputation and PvP). Race and class masks are Era masks: a race without a
  bit is never excluded. Item tooltips call `Sources` with `direct`: travel is
  the straight-line estimate, never a route plan per spawn (a hover must not
  hitch), so the tooltip's "From …" can name another source than the Lookup
  window's or Alt-click's routed pick (boats and flights).
- **Obtainability.** An item's `status` is `retired` (no longer obtainable:
  shown for reference, its rows unavailable, never guided; its tooltip says so)
  or `nosource`. Search ranks, within a kind, items a curated guide `collects`
  first, then the rest, then retired and source-less ones, each by name match;
  results carry `status` and `curated`, and the UI shows a muted chip and no
  "Guide me" for the unobtainable.
- **Guides.** `Lookup.Guide` opens the curated guide whose `collects` holds the
  item (for a class mount's spell, a guide with the spell's name among its
  `keywords`). Otherwise `BuildGuide` writes the same guide table compiled
  guides use from the chosen source: vendor (goto, buy), drop (goto, kill,
  collect; a dungeon's entrance first), object (goto, interact, collect),
  quest reward (every blocking prerequisite, one of the any-of ones, then
  accept, objectives and turn-in, each with coordinates), craft (train, skill,
  learn, craft at the profession's trainer), reputation (rep, then buy from
  the quartermaster). It is registered in pack `lookup`, category `Lookup`, id
  `lookup/<kind>/<id>`, never saved, and opened in a new tab
  (`Engine.OpenTab`); a saved tab holding one is rebuilt at `ADDON_LOADED`.
  A planner kind (`RegisterPlanner`, letters only; Dungeons' `pickup`, `handin` and `attune`) is
  built by its module's `build(id)` through the same `BuildGuide`/`Guide`
  path (no curated guide, not gated by `lookup.enabled`), registered and
  reopened the same way.
- **Tooltips and clicks.** Item tooltips get the best one or two sources and
  "Alt-click: guide me"; Alt-clicking an item link, bag item or loot item opens
  its guide (Lookup when no source can be guided). The Codex loads
  on the first tooltip that needs it out of combat.
- **Mounts.** `Lookup.UnitMount` reads a player unit's helpful auras with
  `C_UnitAuras.GetAuraDataByIndex` (in `pcall`: `RequiresUnitAuraAccess`; any
  secret value stops the scan, as `SecretWhenUnitAuraRestricted` makes them in
  combat, encounters and PvP matches) and matches the spell against the
  Codex's mount spells (the client's `ItemEffect`: aura spell → item, class
  mounts with their class), else `C_MountJournal.GetMountFromSpell`. The unit
  tooltip gets "Mount: <name>" and its best source; `MOUNT_SPOTTED(unit, info)`
  fires on target change and mouseover; `/polestar mount` opens Lookup at the
  target's (else the mouseover's) mount, `/polestar lookup [text]` searches.

---

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