Core

local ADDON, ns = ... in every file; Polestar = ns is set once in Core/Init.lua (first file loaded). Packs reach it as the global.

Lifecycle#

Polestar.OnInit(fn)    -- ADDON_LOADED("Polestar"). Saved settings are loaded; Get falls back to defaults.
Polestar.OnLogin(fn)   -- PLAYER_LOGIN, in registration order. Player info valid.

SavedVariables may come back nil after a cold client restart on Forever beta builds (reproduced by the community quest database, build 69913, file on disk intact). Never derive guide progress from saved state alone: the current step is always recomputed from live quest state. Saved state only holds preferences, the chosen guide, and manual check-offs; losing it must degrade gracefully.

Message bus#

local h = Polestar.On(msg, fn)   -- fn(...) ; returns handle
Polestar.Off(h)
Polestar.Fire(msg, ...)
Polestar.RegisterEvent(event, fn)    -- game events, one shared hidden frame; fn(event, ...)
Polestar.UnregisterEvent(event, fn)

Messages:

Modules fire their own (TABS_CHANGED, ROUTE_*, TRAIN_DUE, CLASS_TRAINED, GUIDE_OUTLEVELED, QUESTDB_*, CODEX_LOADED, ITEMDB_LOADED, GEAR_UPDATED, FLIGHT_STARTED/FLIGHT_ENDED, QOL_HEARTH_CHANGED, QOL_XP_UPDATED, MOUNT_SPOTTED, RARE_SPOTTED, RARES_HISTORY, SHOW_LOOKUP, SHOW_DUNGEON, SHOW_RARES), documented with their module.

Settings#

Polestar.RegisterDefaults(section, tbl)  -- at file load; section = "ui" | "nav" | "behavior" | ...
Polestar.Get("ui.scale")                 -- dotted path; falls back to defaults
Polestar.Set("ui.scale", 1.1)            -- writes PolestarDB.settings, fires SETTING_CHANGED
Polestar.CharState()                      -- PolestarCharDB, always a table
Polestar.IsNewCharacter()                 -- true when there was no saved PolestarCharDB as the addon loaded
Polestar.FormatDistance(yards, opts)      -- "120 yd", or "110 m" / "1.2 km" under nav.distanceUnit = "metres"

Every distance a player reads goes through FormatDistance (the arrow, the map target's tooltip, the death helper, the rares' toasts and view); text that embeds one takes the formatted string (%s). opts.round = 5 rounds to the nearest 5, opts.compact writes yards from 1000 as "1.2k yd" (Rares.YardsText); metres turn to kilometres from 1000 m. The bug report keeps yards for whoever reads it.

Commands#

Polestar.RegisterCommand(name, fn(argString), help)

/polestar and /pole. No argument fires TOGGLE_FRAME. help lists registered commands with their help lines (already translated: L["..."]). Core registers (Core/Commands.lua): guides, options, show, hide, next, prev (look at the next/previous step; nothing changes), skip (skip the step shown, for good), reset (clear ticks, latches, skips and the saved view for the current guide), guide <id>, status, tabs, tab <n>, close, path (the route choice), welcome (SHOW_WELCOME), packs (Options at Community guides), gamepad (Options at Gamepad), where, report (SHOW_REPORT), discord (SHOW_DISCORD), debug; Nav adds arrow, way and route; modules add theirs (xp, gear, instances, dungeons, lookup, mount, rares, questdb, import (SHOW_IMPORT, Core/Import.lua)).

where prints the player's map and position as two guide lines, zone map <uiMapID> and goto <x>,<y> live (two decimals, the client's live frame, marked live because typed coordinates are read in the Era frame), then "For another goal, add @x,y live", and fires SHOW_COPY with the two lines. In an instance or on a map without a position it prints why instead.

Caught errors and the Polestar Discord#

Polestar.SafeCall(fn, ...)    -- runs fn; an error is noted, then handed to the error handler
Polestar.NoteError(err)       -- notes an error Polestar caught (SafeCall, Hooks' callbacks)
Polestar.Errors() -> { { msg, count, seq }, ... }   -- this session's, oldest first, the last 5 kept
Polestar.NoteBlocked(addon, fn)   -- notes a protected call the game blocked from Polestar or Polestar_*
Polestar.Blocked() -> { { addon, fn, count, at, seq }, ... }   -- this session's, oldest first, the last 5 kept
Polestar.DiscordURL           -- the Polestar Discord's invite

Every message and game-event handler, init and login callback and command runs through SafeCall, and Hooks' callbacks through their own pcall, so the errors Polestar catches are noted by their first line, counted, for the report a player copies (UI, "Reporting a problem"). Polestar never replaces the game's error handler: wrapping it would shift the stack the game and !BugGrabber show for every error. Taint is no Lua error: ADDON_ACTION_BLOCKED and ADDON_ACTION_FORBIDDEN (the addon blamed, then the function) go to NoteBlocked, which keeps those blaming Polestar or a Polestar_* addon with the addon, how often and the time it last came (%H:%M:%S), so a report on a broken gamepad or button does not read "Errors: none". seq, one counter for both lists, says which came last.

Frames under the game's UI#

Polestar.CreateFrameUnder(kind, name, parent, template) -> frame   -- CreateFrame with no parent, then SetParent(parent)

Forever's gamepad interface hooks CreateFrame (Blizzard_GamepadSmartNavigation, SetupFrameHooks): when the parent is, or is under, one of its open panels (the world map, the quest frame, the talents, the settings...), it rebuilds that panel's button groups inside the caller's code. Called from Polestar, the panel's tables are left tainted and the next gamepad action there is blocked ("An action was blocked because of taint from Polestar"; seen in game as a quest reward was taken, then on every panel after it). SetParent is not hooked. So every frame of Polestar's whose parent is a game frame, or is under one (the map canvases, the minimap, the quest reward and talent buttons, the XP bar, and the frames under those), is made through CreateFrameUnder; frames under Polestar's own windows, which hang off UIParent, are made with CreateFrame. No CreateFramePool with a game frame either: it calls CreateFrame with its parent. tests/lua/wow_stub.lua's CreateFrame raises on a call from addon code whose parent is, or is under, a frame addon code did not make (stub.underGameFrames), and tests/nav-mapcanvas.test.js, tests/qol.test.js (the reward marks, the XP bar mark) and tests/talents.test.js (the talent marks) check that none was made.

Gamepad interface#

Polestar.GamepadUI() -> bool   -- Forever's Gamepad interface style is on (read once, as the addon loads)
Polestar.CloseOnEscape(name)   -- add a Polestar window to UISpecialFrames, except with the gamepad interface
Polestar.RunCommand(msg)       -- what /polestar runs; registered as a slash command only with the keyboard and mouse

With Forever's Gamepad interface on (Options, Gamepad, Enable Gamepad UI; C_InputInterfaceStyle, which decides: the CVar InputDeviceInterfaceStyle can stay at Gamepad with the keyboard and mouse, so it is read only on a client without the API), its navigation (Blizzard_GamepadSmartNavigation, FrameControlsManager) opens, closes and focuses the game's windows, popups, menus and chat box from Blizzard's code, and in the same execution makes protected calls (SetPreferredGamepadInteractTarget, RunBinding, DescendStop). Addon code running in that flow gets them blocked, and the "AddOn blocked" popup's own gamepad handling blocks the next one, thousands of times, until the client freezes. An addon whose only code is an empty slash command reproduces it (Blizzard forum threads 2367777 and 2370253). Other Forever addons (EllesmereUI, Olympus, the community quest database) do the same as Polestar: with the gamepad interface on, they keep to their own windows.

Localisation#

Polestar.L[key]: a key is the English text, and a missing key returns itself, so a client without a translation reads English. A locale file (Locales/<locale>.lua, one per language of tools/lib/i18n/locales.js, loaded by Core/Core.xml right after Core/Init.lua and returning at once on another client) fills L for its client, so every file after it may read L at load; Init.lua, which loads before it, reads L only when it prints (the commands register in Core/Commands.lua). docs/TRANSLATING.md describes the files and node tools/polestar.js i18n.

A word with more than one meaning gets a key per meaning: Polestar.LC(context, text) is the translation of "<context>: <text>", and text while there is none: a dungeon boss that is a chest is LC("boss", "Chest").

Names#

Polestar.Names (Core/Names.lua) names quests, NPCs, objects, items, spells, factions, areas, instances, flight points and dungeon encounters in the client's language. The guides and data packs keep their English; where a name is shown or matched, the caller asks Names first and keeps its English when the answer is nil:

Names.Quest(id) / Names.Npc(id) / Names.Object(id) / Names.Item(id) -> name | nil
Names.Spell(id) / Names.Faction(id) / Names.Area(areaID) / Names.Instance(mapID)
  / Names.Taxi(id) / Names.Encounter(id) -> name | nil
Names.Get(kind, id) -> name | nil      -- the above by kind: quest npc object item
                                       -- spell faction area map taxi encounter,
                                       -- else the kind's pack table
Names.Cached(kind, id) -> name | nil   -- never asks the server; items from the pack only
Names.Learn(unit) -> name | nil        -- keeps the name the client shows for unit
Names.Localised() -> bool              -- false on enUS and enGB
Names.Ready() -> bool                  -- the pack is in, or will not load this session
Names.PackName() -> "Polestar_Names_<locale>" | nil
Names.Add(locale, kind, { [id] = name })   -- the pack's files only; any kind

Guide texts#

Polestar.GuideTexts (Core/GuideTexts.lua) shows a guide's own words in the client's language. A compiled guide's texts (its title, why, pitch, pros, cons and reward text; each step's title and note; each goal's note and text) carry the game's names as tokens, {kind:id}, and the guide's names hold each token's English (tools/lib/dsl/tokens.js; docs/PACK_FORMAT.md, "Format 3"). RegisterGuide hands each guide to GuideTexts.Prepare before escaping it, which rewrites every text in place as the pack's translation into the client's language (else the English) with each token filled: Names.Cached for quests, NPCs, objects and items (never asking the server), Names.Get for spells, factions and areas, the client's map name for a zone, L for a profession; else the token's English. A guide's folder and the pack's title and notes are the pack's own texts; a folder named after a class reads as LOCALIZED_CLASS_NAMES_MALE's.

GuideTexts.Prepare(def, live) / GuideTexts.Refresh(def) -> changed
GuideTexts.Load(addon) -> "loaded" | "combat" | nil
GuideTexts.TextsAddon(addon) -> "<addon>_<locale>" | nil   -- nil on English
GuideTexts.PackText(packId, text) -> translation | text
Polestar.RegisterGuideTexts(locale, packId, { pack = {...}, guides = { [id] = {...} } })

• Loading.The translations of a pack are its texts addon for the client's language, <pack addon>_<locale> (load on demand, generated by compile from the pack's locales/<locale>/ files): only that one loads, only on that client, through Data.Pack, at the pack's own ADDON_LOADED. While the pack's files load, its guides show their English names (asking Names then would load the names pack in the middle of another addon's files); at its ADDON_LOADED Core/Guides.lua loads the texts addon and refreshes the pack's guides, their headers and the pack's title and notes, with the names. A texts addon refused in combat loads on PLAYER_REGEN_ENABLED; a names pack landing late (NAMES_LOADED) refreshes every guide; a refresh after login fires GUIDES_REGISTERED, so the guide window, the menus and search read the new texts.
• English clients fill the tokens once at registration and keep nothing else; no texts addon loads. A text in the guide's written (one spelling a name otherwise than its token's English, "Dendrite" for Dendrite Starblaze) reads as the author's words there.
• Data.CheckInstall checks the client's texts addon of our pack like the names pack: never missing, named when its version differs.

Compat — the client's game data goes through here#

UI, Nav and Engine read the client's quests, map, units and items through Polestar.Compat, with these exceptions that call the client themselves: Nav's Blizzard user waypoint (C_Map, C_SuperTrack; Nav/Bridges.lua), the minimap's radius, shape, rotation and indoors state (Nav/Pins.lua; Maps/RouteLines.lua reads them through Pins.MinimapView()), the gamepad's map cursor and A (SoftCursor, IsKeyDown; Nav/Pins.lua), the map frames Polestar draws on (only read; Nav/MapCanvas.lua), the run speed, taxi nodes, hearthstone cooldown and ghost state (GetUnitSpeed, C_TaxiMap, item cooldown, UnitIsGhost; Nav/Travel.lua), the player's height for the walking engine (Compat.GetPlayerUnitPosition, Nav/Walk.lua), the zone art's map art layers and exploration (UI/ZoneArt.lua), the class name in the options (UnitClass, UI/Options.lua), quest level colours (GetQuestDifficultyColor, UI/Dungeons.lua), item names, icons and quality colours (C_Item; UI/Dungeons.lua, UI/GearPick.lua, UI/Lookup.lua, Rares/View.lua), the game's item and spell tooltips and modified clicks on Polestar's item and spell buttons (GameTooltip:SetHyperlink, SetSpellByID, HandleModifiedItemClick, ChatFrameUtil.InsertLink; W.ItemTip, W.SpellTip, W.ItemClick, W.SpellClick in Theme/Widgets.lua), the travel button's secure action button (SecureActionButtonTemplate, CooldownFrameTemplate), its item and spell icons, names and cooldowns (C_Item.GetItemIconByID, GetItemIcon, C_Spell.GetSpellName, GetSpellInfo, C_Spell.GetSpellTexture, GetSpellTexture, C_Container.GetItemCooldown, GetItemCooldown) and IsPlayerSpell when Compat has no IsSpellKnown (Nav/Prompts.lua), the transport alerts' game sound and taskbar flash (PlaySoundFile on the Master channel, FlashClientIcon; Nav/Alerts.lua), and the flight map's node slots and hop lines (GetTaxiMapID, C_TaxiMap.GetAllTaxiNodes, TaxiNodeGetType, GetNumRoutes, TaxiGetNodeSlot, DrawLine on TaxiRouteMap; QoL/Flight.lua), and the transit sync's addon messages and who hears them (C_ChatInfo.RegisterAddonMessagePrefix, C_ChatInfo.SendAddonMessage, CHAT_MSG_ADDON, IsInGuild, IsInGroup, IsInRaid, IsInInstance, GetNormalizedRealmName, UnitName, Ambiguate; Nav/Transit.lua), the hand-off to Shortest Path Forever (ShortestPathForever.API, UnitIsDeadOrGhost; Nav/Handoff.lua), map clicks, /way and the TomTom stand-in (Nav/Journey.lua: IsShiftKeyDown, IsAltKeyDown, IsControlKeyDown, GetMouseFoci or GetMouseFocus, the open chat box through ChatFrameUtil.GetActiveWindow or ChatEdit_GetActiveWindow, WorldMapFrame:AddCanvasClickHandler (kept in Blizzard_MapCanvasSecureUtil's registry, which calls addon handlers through securecallfunction), GetNormalizedCursorPosition, ScrollContainer:IsMouseOver, the GLOBAL_MOUSE_DOWN event, Minimap:HookScript("OnMouseUp"), C_Map.GetMapInfo, C_Map.GetMapInfoAtPosition, C_Map.GetBestMapForUnit, C_Map.GetMapChildrenInfo, hooksecurefunc on TomTom's own table, the TomTom global and SlashCmdList), the cursor on the minimap (GetCursorPosition; Pins.MinimapCursor(), Nav/Pins.lua), the nearby services' tracking menus (Menu.ModifyMenu, Nav/Nearby.lua) and the gamepad and key binding API (C_GamePad, C_InputInterfaceStyle, C_KeyBindings, SetBinding, GetBindingKey, SetOverrideBindingClick, IsKeyDown; UI/Gamepad.lua). Frame and system calls (GetTime, GetServerTime, C_Timer, InCombatLockdown, the cursor, CVars, addon loading, the build and locale) are not routed either. Polestar_Nav is a separate addon whose router (started from Shortest Path Forever's) has no Compat, so it calls the client directly: C_EncodingUtil.DecodeBase64 and C_EncodingUtil.DecompressString with Enum.CompressionMethod.Zlib (decoding a map cluster, Routing/PathGrid.lua), debugprofilestop (the frame budget), C_Timer.After, InCombatLockdown with a CreateFrame frame waiting for PLAYER_REGEN_ENABLED, and geterrorhandler (Routing/PathJobs.lua). The world map is opened only through Compat.OpenWorldMap(uiMapID) (C_Map.OpenWorldMap, the global OpenWorldMap only on a client without it, never in combat; Compat.CanOpenWorldMap() says whether it can): the global opener called from addon code taints the map frame (NAV_QA C3), and tests/compat.test.js rejects any other code that opens or moves the world map. Routing the rest keeps Forever specifics in few places and lets other modules' tests replace Compat with a fake.

Coordinates: map percent x, y in 0–100. World coordinates follow C_Map.GetWorldPosFromMapPos: wx is the north–south axis (larger is north), wy is the east–west axis (larger is west), in yards.

Compat.IsSecret(v)              -> bool   (a secret value: comparing, indexing or parsing it throws)
Compat.Readable(v)              -> v | nil (a secret value reads as unknown)
Compat.Now()                    -> seconds since the epoch, server clock
Compat.GetPlayerInfo()          -> { name, realm, guid, level, xp, xpMax, race, class, faction }
                                   -- race = raceFile ("Human","Scourge",...), class = classFile ("WARRIOR"), faction = "Alliance"|"Horde"|"Neutral"
Compat.GetPlayerFaction()       -> "Alliance" | "Horde" | nil  (UnitFactionGroup; nil when neutral, unread or secret;
                                   -- the walking router's profile, Nav/Walk.lua)
Compat.GetPlayerMapPosition()   -> uiMapID, x, y | nil      (nil in instances / unknown)
Compat.GetPlayerWorldPosition() -> continentID, wx, wy | nil  (via MapToWorld of the above)
Compat.GetPlayerUnitPosition()  -> wx, wy, z | nil, instanceID | nil  (UnitPosition; the one place it is read; nil while secret;
                                   -- z nil also when the client reports exactly 0, as Forever's does)
Compat.MapToWorld(uiMapID, x, y, frame) -> continentID, wx, wy | nil
                                   -- frame "e": use registered Era frame for uiMapID (see Map frames); nil: live client
Compat.WorldToMap(continentID, wx, wy, uiMapID) -> x, y | nil
Compat.GetMapName(uiMapID)      -> string | nil
Compat.MapName(uiMapID)         -> string | nil   (the client's name, else the Codex zone's)
Compat.GetAreaName(areaID)      -> string | nil   (C_Map.GetAreaInfo: the area's name in the client's language)
Compat.GetContinentMap(uiMapID) -> continent uiMapID | nil
Compat.GetPlayerFacing()        -> radians | nil   (0 = north, counter-clockwise positive)
Compat.GetZoneText()            -> zone, subzone
Compat.IsQuestCompleted(questID)       -> bool   (flagged completed / turned in)
Compat.IsOnQuest(questID)              -> bool
Compat.IsQuestReadyForTurnIn(questID)  -> bool
Compat.GetQuestObjectives(questID)     -> { { text, type, finished, numFulfilled, numRequired }, ... } | nil
Compat.GetQuestTitle(questID)          -> string | nil (client cache; may be nil)
Compat.GetOfferedQuests(source)        -> { questID, ... } | nil   (source "gossip" | "greeting" | "detail")
Compat.IsQuestTrivial(qlvl, level)     -> bool   (grey for that level)
Compat.GetItemCount(itemID, includeBank) -> number   (includeBank: the bank's too)
Compat.GetItemQuality(itemID)          -> 0..7 | nil (nil while not cached)
Compat.ItemQualityHex(quality)         -> "ffrrggbb" | nil
Compat.ItemIcon(itemID)                -> icon | nil (C_Item.GetItemIconByID; no cache needed)
Compat.SpellIcon(spellID)              -> icon | nil
Compat.ItemLink(itemID)                -> link | nil (nil while not cached)
Compat.RequestItem(itemID)             -> bool   (cached; else requested: GET_ITEM_INFO_RECEIVED follows)
Compat.SpellLink(spellID)              -> link | nil
Compat.RequestSpell(spellID)           -> bool   (cached; else requested: SPELL_DATA_LOAD_RESULT follows)
Compat.GetBindLocation()               -> string | nil
Compat.IsOnTaxi()                      -> bool
Compat.GetCurrentTaxiNode()            -> name of the open taxi map's node | nil
Compat.GetNpcID(unit)                  -> number | nil   (from UnitGUID)
Compat.InCombat()                      -> bool
Compat.IsInInstance()                  -> bool, instanceType ("party" | "raid" | "pvp" | ... inside)
Compat.IsIndoors()                     -> bool | nil (the client's indoor state; nil without IsIndoors or when secret)
Compat.IsShiftKeyDown()                -> bool
Compat.AddOnPresent(name)              -> bool   (installed and enabled: loaded, or loadable after Polestar)
Compat.Supports(feature)               -> bool   ("skill" | "spell" | "faction" | "explore" | "achievement")
Compat.GetSkillRank(skillLineOrName)   -> rank, maxRank | nil  (profession/secondary skill)
Compat.IsSpellKnown(spellID)           -> bool
Compat.GetSpellCooldown(spellID)       -> start, duration (GetTime seconds; 0, 0 when ready or secret)
Compat.GetFactionStanding(factionID)   -> standingID (1 Hated .. 8 Exalted), value, barMin, barMax, name | nil
Compat.IsAreaExploredAt(uiMapID, x, y) -> bool | nil   (C_MapExplorationInfo)
Compat.GetAchievement(id)              -> { completed, name, criteria = { { text, completed, cur, max }, ... } } | nil

Map frames#

Guide coordinates from Era-sourced data are in the Era map frame. Four Forever maps changed frame versus Era (the community quest database evidence: Mulgore, Eastern Plaguelands, Redridge Mountains, Stormwind City), and more may. Packs embed the Era world bounds for every map they reference:

Polestar.RegisterMapFrames({ era = { [uiMapID] = { c = continentMapID, left = wy0, right = wy1, top = wx0, bottom = wx1 }, ... } }, packId)

packId nil is Polestar itself (its data addons, class trainers). Frames from Polestar and our pack (guides) win for a map both cover, whatever the load order; another pack only adds maps they lack (lint warns where its frame differs).

For frame "e": wx = top + (bottom - top) * y/100, wy = left + (right - left) * x/100. Compat.MapToWorld(map, x, y, "e") uses that; everything downstream (distance, arrow, pins) works in world coordinates and converts back to live map percent with Compat.WorldToMap. Coordinates without f are live-frame (recorded in Forever) and use C_Map.GetWorldPosFromMapPos directly.

Core services: Data, Hooks, Search#

Shared by every module (summarised in docs/SUITE.md, "Runtime services"); each file's header lists its full API.

Polestar.Data.Pack(name) -> loaded, reason|nil   -- C_AddOns.LoadAddOn once per session; never in combat ("combat", retried later)
Polestar.Data.Info(name) -> { loaded, reason, memoryKB }

Polestar.Hooks.ItemLines(owner, fn(tooltip, link, itemID))       -- GameTooltip, ItemRefTooltip
Polestar.Hooks.UnitLines(owner, fn(tooltip, unit))               -- GameTooltip
Polestar.Hooks.ObjectLines(owner, fn(tooltip, objectID, name))   -- GameTooltip; either may be nil
Polestar.Hooks.ItemClick(owner, fn(link, itemID))                -- modified clicks on chat links, bag and loot items
Polestar.Hooks.AddLine(tooltip, left, right?, r, g, b, rr, rg, rb)

Polestar.Search.Query(text, opts) -> results, counts, more   -- opts = { kinds, limit = 60, perKind, offset, subtitles = false }
   -- result = { kind, id, title, subtitle, quality, score, status, curated }; exact > prefix > word prefix > substring
Polestar.Search.Subtitle(result) ; Search.KINDS ; Search.Status() -> codexLoaded, reason

Hooks owns the client hooks: TooltipDataProcessor.AddTooltipPostCall (Item, Unit, Object) and a hooksecurefunc post-hook of HandleModifiedItemClick, which bag buttons, loot buttons and chat links (SetItemRef) all reach. One entry per owner, callbacks in registration order, each in its own pcall; forbidden tooltips and secret values are skipped. Search matches guides (titles, keywords, folded once per guide list) and the Codex kinds through the pack's prebuilt index (Codex.Index(kind): one string of folded names per kind), so a keystroke is a few plain string.find calls and never decodes a record. Each kind reads at most 200 candidates per query, best tiers first (more[kind] says there were more); a one-letter query matches name prefixes only. Only the results returned are named, and subtitles are filled per shown row (Search.Subtitle). Generated lookup/ guides are not listed.

Measured with the real pack (lua5.1, tests/lookup-codex.test.js setup): the pack loads in about 20 ms (4.4 MB; it never loads at login), the first query costs 7 ms (guide headers), a keystroke 1.5–4 ms (1 to 8 letters), a detail page (Lookup.Sources) 0.1 ms for a mount up to 10 ms for an item with 40 drop sources.

Guide data (compiled Lua) — the toolchain/Engine contract#

Generated by tools/polestar.js compile from .guide sources (docs/GUIDE_FORMAT.md) into the pack's addon folder: the generated TOC, Pack.lua, MapFrames.lua, Guides.lua (one RegisterGuide per guide, each built in its own function) and LICENSE-DATA.txt, plus LICENSE.txt (the pack's LICENSE) when the pack folder has one. Ours is addon/Polestar_Guides/; a community pack's is <pack>/dist/<folder>/. The full contract for pack authors' tools is docs/PACK_FORMAT.md.

local ADDON = ...
Polestar.RegisterPack({ addon = ADDON, id = "guides", format = 2, title = "Polestar Guides",
  author = "Polestar", version = "0.2.0", license = "GPL-3.0-only" })   -- optional: website, source, notes

Polestar.RegisterGuide({
  id = "forever/alliance/human/01-elwynn-forest",
  pack = "guides",
  title = "Elwynn Forest",
  faction = "Alliance",            -- "Alliance" | "Horde" | nil (either)
  races = { "Human" },             -- raceFile list or nil (any)
  classes = nil,                   -- classFile list or nil (any)
  minLevel = 1, maxLevel = 13,
  category = "Leveling",
  zone = 1429, zoneName = "Elwynn Forest",
  next = "forever/alliance/02-westfall",   -- or nil
  author = "Polestar", version = 1,
  group = true,                    -- or nil: a goal of the route (not optional) needs a group
  reward = { { spell = 23161, spellName = "Summon Dreadsteed" } },  -- or nil: what the goal gives (format 2)
  why = "...",                     -- or nil: one line on why it is worth doing (format 2)
  steps = {
    {
      title = "Deputy Willem",     -- optional
      note = "...",                -- optional, player-facing
      only = { classes = { "WARRIOR" }, races = { "Human" }, factions = { "Alliance" } },  -- optional, AND across keys, OR within
      when = { { k = "level", op = "<", n = 6 }, { k = "onquest", q = { 788 } } },  -- optional (format 4): conditions checked during play, all must hold
      along = "camp",              -- optional (format 4): true or a later step's label; the route passes over the step
      label = "camp",              -- optional (format 4): the step's name, unique in the guide
      goals = { goal, ... },       -- at least one
    },
  },
})

The guide registry (Core/Guides.lua)#

Every guide belongs to a registered pack. The rules a pack meets (ids, no overrides, clashes, map frames, format, problems, literal text, packs on disk and their statuses) are in PACK_FORMAT.md, "Rules Polestar enforces"; lint applies the same ones (tests/packs-parity.test.js). Where Core/Guides.lua implements them:

• Ids: Guides.RESERVED (reserved pack ids) and Guides.OwnsId (which prefix a pack owns: forever/ and draft/ for guides, lookup/ for the internal lookup pack, registered with internal = true and never listed or switchable, every <author>/ that is a valid, unreserved pack id for imported (below), <id>/ for every other pack). An id another pack's guide holds is refused, so an imported guide never takes a pack's place.
• Clashes: guides and map frames a refused pack's files register are dropped until that addon's ADDON_LOADED; guides registered before their pack are refused, their ids kept in a per-pack list and listed as guide-refused problems when it comes.
• Format: Guides.FORMATS (the formats this Polestar reads, 1 to 4); Guides.Validate checks each guide against the REQUIRED verb table (Guides.VERBS).
• Problems: each refusal goes on the pack's record, problems = { { kind = "pack-refused"|"guide-refused"|"no-guides", guide?, message } }, and to ns.Debug.
• Literal text: ns.EscapeText (| doubled), ids excepted.
• Packs on disk: Guides.ScanInstalled, at login before GUIDES_REGISTERED, gives every addon whose TOC has X-Polestar-Pack and never registered a record from its TOC.

Polestar.RegisterPack(meta) -> ok, err
Polestar.RegisterGuide(def) -> ok, err      -- def.pack must be registered and own def.id; validates shape
Polestar.RegisterMapFrames(frames, packId)
Polestar.Guides.Packs() -> { record, ... }  -- every pack but internal ones and `imported`, ours first, then by title
Polestar.Guides.Pack(id) -> record | nil
Polestar.Guides.PackShown(id) -> bool
Polestar.Guides.SetPackShown(id, shown)     -- PolestarDB.packs[id].off; fires PACKS_CHANGED(id)
Polestar.Guides.ProblemCount() -> n         -- over every listed pack (the Options dot)
Polestar.Guides.OwnsId(packId, guideId) -> bool
Polestar.Guides.SuggestSources() -> { packId, ... }  -- "guides", then shown packs with leveling guides (never `imported`)
Polestar.Guides.SuggestSource() -> packId   -- behavior.suggestFrom when it can, else "guides"
Polestar.Guides.OfferedBy(id) -> { guide, ... }      -- shown guides whose route choice offers id now (Engine.RouteOffered)
Polestar.Guides.DropImported(id) -> bool    -- takes an imported guide out (Import.Delete), nothing else

Polestar.Import.Decode(text) -> entry | nil, reason   -- entry = { format, license, guide, frames }
Polestar.Import.Preview(text) -> info | nil, reason   -- info: entry, id, title, author, version, steps, minLevel, maxLevel, faction, license, state ("new"|"update"|"same"|"older"), have
Polestar.Import.Save(entry) -> ok, reason             -- checks again, registers, stores
Polestar.Import.Delete(id) -> bool
Polestar.Import.List() -> { { id, title, author, version, license, steps, problem }, ... }  -- by title
Polestar.Import.Load()                                -- at login
Polestar.Import.LIMITS                                -- { length = 50000, steps = 60, payload = 262144, text = 4096 }

Engine#

Polestar.Guides.Get(id) -> guide | nil
Polestar.Guides.List() -> { header, ... }   -- header = guide without steps, plus stepCount
Polestar.Guides.Suggestions() -> { id, ... } -- the leveling guides of the suggestion source (Guides.SuggestSource) for the player's faction/race/class/level, best first; ours fill in where it has none; none fits: the nearest upcoming one alone
Polestar.Guides.Suggest() -> id | nil       -- the first of Suggestions()

Polestar.Engine.GetGuide() -> guide | nil
Polestar.Engine.SetGuide(id)                -- persists CharState().guide, recomputes, fires GUIDE_CHANGED
Polestar.Engine.GetStepIndex() -> i | nil
Polestar.Engine.GetStepCount() -> n
Polestar.Engine.GetStepView(i) -> view | nil
Polestar.Engine.Next() / Prev() / Goto(i)    -- look at another step; changes nothing (Goto un-skips its target)
Polestar.Engine.Skip() -> stepIndex         -- skip the step shown, saved; fires PLAYER_SKIPPED_STEP
Polestar.Engine.Unskip(i) -> bool           -- undo a skip
Polestar.Engine.GetLiveStep() -> i | nil    -- the first open step, whatever step is shown
Polestar.Engine.LevelTarget(level?) -> N, stepIndex | nil   -- the first `level N` goal from the step shown for this character (step `only`/`when`, goal `only`; skips left out) with N above `level` (default: the character's); QoL's XP bar mark
Polestar.Engine.StartGate(id) -> gate | nil -- a Class guide this character cannot start yet: { level } or { pre, preTitle }, with giver, map (see "Not yet available")
Polestar.Engine.ToggleGoal(stepIndex, goalIndex) -> bool   -- tick any goal but a note done, or clear its check-off
Polestar.Engine.SkipGoal(stepIndex, goalIndex) -> bool     -- skip an optional goal, or bring it back
Polestar.Engine.AimGoal(stepIndex, goalIndex) -> bool      -- lead the arrow to a goal of the current step (row click)
Polestar.Engine.GetAlong() -> { { index, title, goals = { goal view, ... } }, ... }  -- open goals of along steps behind the live step
Polestar.Engine.AimAlong(stepIndex, goalIndex) -> bool     -- lead the arrow to one of them (row click); holds while it is listed
Polestar.Engine.GetWaypoint() -> waypoint | nil
Polestar.Engine.GetProgress() -> doneSteps, totalSteps

Smart logic#

Focus: one person at a time#

A step's goals form groups, walked in authored order: a goal joins the current group when it has the same "who", else starts a new one. "Who" is the goal's NPC (npc, or the chosen candidate's for smart goals) or object (object) for accept, turnin, talk, train, vendor, sethome, getfp, learn, buy and interact goals; every other goal (goto, kill, collect, use, complete, explore, level, skill, craft, rep, achieve, note, and NPC verbs without an NPC) is "here". An interact for a quest objective (quest: totems, mounds, cages, braziers) is "here" too: it is field work beside the kills, not a visit, so it shows with them instead of waiting behind them; a plain interact (no quest) is still a visit. So a hub step reads person by person, and a field step (goto the camp, kill, collect) stays one group. A goal that does not apply to the character (only, grey-skipped, never-had) joins the group around it instead of starting one, so a class-only line between two goals at the same person never splits that person's group.

• Done:a group is done when none of its applicable goals still blocks (done, na, skipped or optional). Focus is the first group that is not done; nil when the step is done.
• View:GetStepView(i) adds groups = { { kind = "npc"|"object"|"here", npc, object, name, map, x, y, f, goals = { goalIndex, ... }, done, pending }, ... } (pending: blocking goals still open) and focus = groupIndex; each goal view carries group = groupIndex. name is the NPC's or object's name (nil for "here"); map/x/y/f its position (the first located goal of the group).
• Current goal and waypoint:the view's current is the goal the window marks and the arrow leads to: in the focus group, the first open blocking goal, else the first open optional one (not skipped); a "Go to" naming the step (the group's header, an area) only when nothing else is open. The arrow goes to the goal the player chose in the current step (AimGoal, a cycled spot or candidate) while it is open, else the current goal's own place (its coordinates, its spawn area, the source of its item), else the header's, else the focus group's first open located goal (blocking, then optional, then notes), else a quest's current goal at the place of the focus group (a goto already reached) or of the nearest group before it for the same quest (the giver of a bare complete), never of a later group; nil on a done step (no focus). Reaching the place of any other goal of the step arrives at its header. A focus change fires STEP_UPDATED(step) and WAYPOINT_CHANGED like any other progress.
• Out-of-order play still counts: finishing a later person's goals marks that group done; the focus stays on the first open group.

Route choice ("Choose your path")#

A guide whose next lists several guides compiles to next (the author's default, the first) plus nextChoices (all of them, in order); each option may carry pitch, pros, cons (see GUIDE_FORMAT). next <id> when ... adds nextWhen (format 4: option id -> predicates, as a step's when), and nextChoices then lists the options even when there is one.

Polestar.Engine.GetRouteChoice(fromId) -> { from, fromTitle, recommended, chosen, joinsAt,
    options = { { id, title, zoneName, minLevel, maxLevel, pitch, pros, cons, seconds,
                  quests, steps, recommended, chosen, outleveled, open }, ... } } | nil
Polestar.Engine.ChooseRoute(fromId, toId) -> bool   -- remembers, loads, fires ROUTE_CHOSEN
Polestar.Engine.PendingRouteChoice() -> fromId | nil -- the active tab's finished guide waiting for a choice
Polestar.Engine.RouteChoiceFor(id) -> fromId | nil  -- the choice that offers guide `id` to this character
Polestar.Engine.RouteOffered(fromId, toId) -> bool  -- fromId's `next` names toId and its `when`, if any, holds now
Polestar.Engine.NextGuide(fromId) -> id | nil       -- where the hand-off goes now; nil: none offered, or the player chooses
Polestar.Engine.OfferRouteChoice() -> fromId | nil  -- /polestar path: fires ROUTE_CHOICE
Polestar.Engine.GuideFocus(id) -> x, y | nil       -- live-frame percent of where the guide is for this character, for the
                                                    -- guide menu's zone art: open in a tab and unfinished, the current
                                                    -- step's first goal on the guide's zone map (`zone`); else (or when
                                                    -- that step is elsewhere) its first goal on it: a route option's focusX/Y

• Options are the nextChoices that fit the character (faction, race, class) and are offered now: an option with nextWhen only while its predicates hold (Own.optionHolds, Own.predicateHolds on the live state, checked each time the options are listed: routeOptions, ChooseRoute, RouteOffered, so Guides.OfferedBy, the guide menu's "Next" line and its suggested follow-ups, and "Up next" on a finished guide); nothing is stored. outleveled when the level is at or past the option's maxLevel. seconds is TravelCost from the player to the option's first located goal; quests counts the accepts this character gets there; joinsAt names the guide every option continues to, when they share one.
• Recommended:not outlevelled, then the quickest to reach (1-minute bands), then the author's order.
• At completion (with behavior.autoNextGuide, and the guide either auto-loaded or seen incomplete): the remembered choice (CharState().routes[fromId]), else the only option offered, else with behavior.routeChoice = "recommended" the recommended one. With none offered (every option's when fails) the guide ends there, as without next. Otherwise the finished guide stays in its tab and ROUTE_CHOICE(fromId) fires once, after the evaluation.
• Fresh start:with no saved tabs, when the suggested guide is an option of a choice the character fits, and the character is at most one level into that guide's range, login also fires ROUTE_CHOICE (the suggested route stays loaded meanwhile).
• ChooseRoute loads the option in place of the finished guide, else of an open option of the same choice (changing route), else in the active tab.
• Never-had quests:a turn-in, complete or objective goal for a quest the character neither has nor has done, and that its guide does not accept (for this character) at or before that step, does not apply (status na): it was picked up on another route, or skipped. chainNeeds follows every route option but one whose when can no longer hold (Own.optionClosed: a level<N or level<=N the character is past, a !turnedin quest handed in); the chain is built again once a kept conditional option closes. The hand-in plan (Core/RoutePlan.lua) treats a guide with a conditional option like a choice not made yet, unless the remembered choice is an unconditional option.
• UI (UI/RouteChoice.lua, frame PolestarRouteChoice): one card per option. Each card opens on the zone's art (UI.ZoneArt, below) framed on focusX/focusY (where the route starts), lightly desaturated, fading into the card with the zone's name on it. Polestar ships no zone art; without the API or art for the map, a stretch of the night band stands in. Straight under the art, at the same y on every card, the stat row: levels (in text), travel time and quest count. Then the state chip, the pitch, at most 3 pros and 2 cons one line each (the full lists in the card's tooltip), on a grid every card shares so rules and lists line up; the recommended card has the accent ring and the primary button; "From now on, take the recommended zone" sets behavior.routeChoice; "Decide later" and the header ✕ close. It waits out combat. The guide window's completed state and the out-levelled banner open it when a choice applies; Options → Guide → Automation → "Where to level next". POLESTAR_CLIENT_ART=<folder> lets preview draw real map art from a local cache of decoded client tiles (base and overlay tiles, maps.json with each map's artID); those renders go to <folder>/preview/, never into docs/.

Tabs (several guides at once)#

Polestar.Engine.GetTabs() -> { { guideId, title, category, stepIndex, stepCount, done, total, complete }, ... }, activeIndex
Polestar.Engine.OpenTab(guideId [, activate])  -> index   -- already open: just activates it (when activate ~= false)
Polestar.Engine.CloseTab(index)                            -- the last tab may be closed (no guide)
Polestar.Engine.SelectTab(index)
Polestar.Engine.MoveTab(from, to)

Up to 6 tabs per character, persisted as CharState().tabs = { guideId, ... } and CharState().activeTab. Every single-guide call above (GetGuide, SetGuide, GetStepIndex, GetStepView, Next, ..., GetWaypoint, GetProgress) acts on the active tab; SetGuide(id) replaces the active tab's guide (opening a first tab when none exist). Each tab keeps its own step state; per-guide manual and skip state stays keyed by guide id. Selecting a tab fires GUIDE_CHANGED (and STEP_CHANGED, WAYPOINT_CHANGED) for the newly active guide; any tab change fires TABS_CHANGED(tabs, activeIndex). The waypoint follows the active tab only. Automation considers the current and next two steps of every open tab. autoNextGuide replaces the finished guide within its own tab. On login, saved tabs reopen; Guides.Suggest() opens a first tab only when none survive (SavedVariables can come back nil). Each tab in the guide window reads Title (min–max) like the menu's rows; a narrow tab cuts the title, never the range (DESIGN, Guide-window tabs).

{
  index = 3, title = "Kobold Camp", note = "...",
  status = "current" | "done" | "skipped" | "upcoming" | "na",
  goals = {
    {
      index = 1, t = "kill",
      status = "done" | "active" | "pending" | "na",
      text = "Kill Kobold Vermin",        -- plain default rendering, no color codes
      verb = "Kill", subject = "Kobold Vermin",
      subjectKind = "quest" | "npc" | "item" | "place" | "object" | "level" | "text",
      detail = "for Kobold Camp Cleanup",  -- or nil
      progress = { cur = 3, max = 10 } | nil,
      manual = true | false,               -- UI shows a checkbox when true
      optional = false, note = nil,
      map = 1429, x = 47.6, y = 35.1, f = nil,   -- when the goal has coordinates
      quest = 7, npc = 6, item = nil,
      -- A collect's compiled source (GUIDE_FORMAT "What the compiler fills
      -- in"): enemy = an NPC not of the character's faction.
      source = { name, kind = "npc" | "object", rank, enemy } | nil,
      -- The compiled `group` (group content), shown as the goal's group line.
      party = { kind = "elite" | "dungeon" | "raid" | "group", rank, name, size } | nil,
      -- The reading flow (below): starterOf, starter, folded, header.
    },
  },
}

{ map = 1429, x = 47.6, y = 35.1, f = nil, label = "Kill Kobold Vermin", stepIndex = 3, goalIndex = 2, kind = "kill", r = 8 }