Architecture
Contributor3 min readUpdated
The contract between the addon's modules, the compiled guide data, the toolchain and the tests.
Polestar is a leveling-guideOne route, written as a .guide file and compiled to Lua; its id reads like forever/alliance/human/01-elwynn-forest. system for World of Warcraft: Forever (client
1.60.1, ## Interface: 16001, install folder _classic_beta_ during beta).
This file is the contract between modules: the code follows it, and a change
to a contract changes this file with it.
Reference material, checked out locally (gitignored):
.ref/wow-ui-source-forever/— Blizzard's Forever UI source (Gethe/wow-ui-source, branchforever).Interface/AddOns/Blizzard_APIDocumentationGenerated/*.luadeclares every C API function and event with argument types. Verify every client API you call against it; a retail or Era assumption is not evidence.- The live client's AddOns folder, as found by
tools/lib/addons.js($WOW_FOREVER_ADDONS, then the detected clients:<client>/_classic_beta_/Interface/AddOns/; read-only for reference; EllesmereUI'sSKINNING_API.mdlives there).
Overview#
Polestar is a set of addons, a folder of guides and the Node tools that turn one into the other. The addons:
| Addon | What it holds | Built by (node tools/polestar.js …) | In git | Ships |
|---|---|---|---|---|
Polestar (addon/Polestar/) | The addon: engine, navigation, quests, gear, maps, quality of life, Lookup, Dungeons, Rares and every window | hand-written, plus a few generated data files | Yes | Yes |
Polestar_Guides (addon/Polestar_Guides/) | Polestar's own packAn addon of guides for Polestar, built by the compiler from a folder with a pack.json (the folder is a pack too); Polestar's own is Polestar_Guides (pack id guides). (pack id guides) | compile, from guides/ | yes (generated) | Yes |
| community addons | Addons by other authors (X-Polestar-Pack in their TOC; docs/PACKS.md, docs/PACK_FORMAT.md) | the same compiler, from their own repositories | in their own repositories | by their authors |
Polestar_ItemDB (addon/Polestar_ItemDB/) | Item stats and Forever reward choices for the gear advice; loaded on demand | itemdb build (Items.lua), then gear build (Forever.lua) | yes (generated) | Yes |
Polestar_Names_<locale> (addon/Polestar_Names_deDE/ … zhTW/) | Quest, NPC, object and item names in one client language, for Polestar.Names; loaded on demand, only the client's own, never in English | i18n names, from the community names database (pinned) and the Era quest database | yes (generated) | Yes |
Polestar_QuestDB (addon/Polestar_QuestDB/) | The quest database behind quest markers and tooltips; loaded on demand | questdb build | no (local, gitignored) | yes, when built |
Polestar_Codex (addon/Polestar_Codex/) | Lookup's CodexLookup's database of items, mounts, pets, recipes, NPCs, rares, quests, zones, dungeons and treasures, with where each comes from (codex build, the Polestar_Codex addon)., and the Dungeons and Rares data; loaded on demand | codex build, from release-safe inputs (--local-extras builds a local-only one) | no (generated, gitignored) | yes, always: pack fails without it |
Polestar_Nav (addon/Polestar_Nav/) | Polestar's walking router (started from Shortest Path Forever v1.16.0 by Cillian Berragan, GPL-3.0-or-later; Polestar's since 2026-10-16) with Polestar's walking maps of Eastern Kingdoms, Kalimdor and Zephras Isle (maps format 2, grown from his format) and the walk's chokepoints, for the arrow's walking routes; loaded on demand at login, never while an installed Shortest Path Forever guides (the target handed to it, or a journey of its own running; Nav, "In-game walking routes (Polestar_Nav)", "Hand-off to Shortest Path Forever") | the router hand-written (Routing/); nav pack (the maps, PACK.json, from the navigation grid and the ground layers) | Yes | yes, always |
Polestar_Travel (addon/Polestar_Travel/) | Zone crossings for the travel planner, from an optional local crossings file; loaded with Polestar | travel build | no (local, gitignored) | no, never packaged (Nav, "Travel planner and zone crossings") |
Polestar_Recorder (addon/Polestar_Recorder/) | The optional standalone recorderThe optional Polestar_Recorder addon that records play; record import turns its sessions into data/recordings. of play sessions, for authoring | hand-written | Yes | yes, as its own zip |
Read the rest of this section283 words
A guide goes from a .guide file to the game in four steps. An author
writes it in a pack (guides/ for Polestar's own). lint and
compile parse it and fill in names, places and coordinates from the
reference dataThe game facts in data/forever/*.json (quests, NPCs, objects, items, zones, map frames and more) that the compiler and the data builds read; built locally by data build. in data/forever. compile writes the result as Lua into the
pack's addon folder (addon/Polestar_Guides for ours). install copies that
folder into the game, where the pack registers its guides with
Core/Guides.lua at load time and the Engine plays them ("Guide data" and
"Engine" below).
Where to look next: docs/README.md maps every document; addon/README.md lists every addon file with its public table; tools/README.md lists the commands, every generated file and the rebuild order; tests/README.md describes the test layers and the fake client.
addon/Polestar/Polestar.toc loads eleven XML manifests in this order. Each
module's manifest lists that module's files.
The module sections below follow this order.
Core\Core.xml Core: namespace, lifecycle, events, settings, Compat, guide registry, Engine, automation, commands
Theme\Theme.xml Theme + widget kit
Nav\Nav.xml Waypoint arrow, map/minimap pins, travel planner, TomTom bridge
Quests\Quests.xml Quest database access, markers, tooltips, quest levels
Gear\Gear.xml Item stats, stat weights, upgrade tooltips, reward picks
Maps\Maps.xml World map: no fog of war, coordinates, zone levels, dungeon and travel pins, instances
QoL\QoL.xml Quality-of-life helpers
Lookup\Lookup.xml Codex, sources, generated guides, mount spotting
Dungeons\Dungeons.xml Dungeon quest journal data
UI\UI.xml Guide window, guide menu, zone art, Lookup and Dungeons views, route choice, options
Rares\Rares.xml Rare NPCs and treasures: detection, pins, alerts, view
Talents\Talents.xml Talent plans: the hub section, talent frame marks, reminderManifests use only <Script file="..."/> and <Include file="..."/> (paths
relative to the XML file, backslashes allowed). The test harness parses the
TOC and these manifests, so tests always load exactly what the client loads.
Globals#
Only these globals may be assigned anywhere under addon/ (enforced by
tests/syntax.test.js via luac -l):
Polestar, PolestarDB, PolestarCharDB, PolestarRecorderDB,
SLASH_POLESTAR<n>, SLASH_POLESTARREC<n>, SLASH_POLESTARWAY<n> (/way,
claimed only while no addon has it), BINDING_HEADER_POLESTAR,
BINDING_NAME_POLESTAR_*, in Polestar_Nav only Polestar_NavEngine
(the engine's handoff), PolestarPathData (the walking maps) and, in
Routing/Costs.lua only, Polestar_NavCosts (the router's ground-class
costs), and in Nav/Journey.lua only TomTom (its stand-in, set while TomTom is not
installed and cleared when it stands down; "Nav API").
Everything else is local or lives on the Polestar table. Named frames must
be prefixed Polestar.