# Building from source

> Clone the repository, build the reference data and the addon, run the checks, and find your way round the project.

Page: https://polestar.guide/docs/contributors/building (Polestar docs > Contributors)

This part is for working on Polestar itself: players need only the
[Quick start](https://polestar.guide/docs/players/quick-start), guide authors the [Community guides](https://polestar.guide/docs/players/community-guides)
section. [docs/README.md](https://polestar.guide/docs/contributors/docs-map) maps every document, and
[CHANGELOG.md](https://polestar.guide/docs/reference/changelog/0-2-6) lists what changed in each release.

Node 24 or later (no npm dependencies) and Lua 5.1 (`lua5.1`, `luac5.1`) for
the tests. Building the data needs a local Forever client: it reads the
client's tables and installed addons.

```sh
node tools/polestar.js data build         # reference data into data/forever/ (local)
node tools/polestar.js questdb build      # the Polestar_QuestDB pack
node tools/polestar.js lint               # check every guide
node tools/polestar.js compile            # build addon/Polestar_Guides
node --test "tests/**/*.test.js"          # the test suite
node tools/polestar.js preview            # render the UI to docs/preview/*.svg
node tools/polestar.js install --recorder # into a detected Forever or beta client
node tools/polestar.js version            # the release version in package.json, guides/pack.json and every addon TOC
node tools/polestar.js pack               # release zips and SHA256SUMS into dist/
```

`npm test` runs the suite. [CI](https://github.com/fitzforge/polestar/blob/next/.github/workflows/ci.yml) runs it on every
push to main and every pull request, where the tests that need the locally
built data skip with a reason, and fails when the committed textures or UI
renders differ from a fresh `media` or `preview` build; with the data built,
all pass locally. `install`
finds the client under Wine, Proton and similar prefixes in your home folder,
or takes `$WOW_FOREVER_ADDONS` or `--dest <Interface/AddOns>`; `--link`
symlinks the folders instead, so an edit needs only a `/reload`.

Releases are built on a maintainer's machine, because the data addons come
from the game client's tables: [docs/RELEASING.md](https://polestar.guide/docs/contributors/releasing) has
the steps and what each zip carries.

`node tools/polestar.js help` lists every command and `help <command>` its
options; [tools/README.md](https://polestar.guide/docs/contributors/tools) groups them, lists the generated
files and gives the rebuild order after a data change.

## The playground: the real addon in a browser

```sh
node tools/polestar.js play              # prints http://127.0.0.1:8077/
node tools/polestar.js play --fresh      # a new level 1 character, default settings
```

One long-lived Lua 5.1 process runs Polestar, its guides and the built data
packs against the simulated world of the tests. The page shows a 1920x1080
game screen with the hub and the guide window; click, hover, scroll, drag,
type into search boxes and run slash commands from the chat line. A side
panel sets the look, jumps through a guide, opens any window and changes the
character, position and time. Zone paintings come only from a local folder
of your own client's art (`--art`); without it the world is dark.

## The route planner: guides played on the real map

```sh
node tools/polestar.js planner art       # once: the map art (~330 MB downloaded, ~250 MB built; local only)
node tools/polestar.js nav build         # once: the navigation grid for terrain-aware walks (~750 MB, ~15-25 min; local only)
node tools/polestar.js planner           # prints http://127.0.0.1:8078/
node tools/polestar.js planner mcp       # the same commands for an AI agent (MCP over stdio)
```

The planner is Nivek_Gaming's idea ([@Nivek_Gaming](https://x.com/Nivek_Gaming)
on X): his route planning inspired this tool and the navigation grid
behind it. Thank you, Nivek.

Pick a guide and a character and the route plays on the game's own minimap
terrain, zone by zone or as the whole 1-60 route across the continents: each
step's start time and duration split into travel, combat, talking and
waiting, the level and XP, the quest log and items, the spawn areas and the
path. The clock is the simulator's model ([docs/SIMULATION.md](https://polestar.guide/docs/contributors/simulation)),
so treat absolute hours as estimates and compare steps against each other.
With the navigation grid built (`node tools/polestar.js nav build`, local
only) every walk follows the terrain, the walks between mobs in a kill area
too: around mountains, into caves and buildings, swimming, dropping off
ledges, mounted from level 40, at the speed of the character's class (Ghost
Wolf, Travel Form...). Flights follow the flight master's real path. The
first playback of a route shows straight lines while its walks are routed in
the background ("Routing…" in the footer), then "Routed N of M legs" (and
the hops between spawns); routes are cached under `data/local/nav`, so the
next start is immediate. A walk the grid cannot route stays a straight line,
marked ≈ in the steps list.
Layers adds Walkable (what the grid can walk: blocked, steep, climb, water,
indoors, zoomed in) and Arrow aids (the crossings and approach chains of
`nav aids`).
In Edit mode, drag a waypoint, add one with a click, bend a travel line into
a new labelled waypoint ("Cross the bridge"), or change any goal or
step in its form: every edit is written into the `.guide` file at once
(undo with Ctrl+Z; Changes lists and reverts them; Compile builds the addon
folder), so `dev` picks it up too. Given a pack folder it edits that pack;
`planner mcp` lets an assistant read routes, edit them and drive the open
page while you watch (`claude mcp add polestar-planner -- node tools/polestar.js planner mcp`).
The map art is the Forever client's own, fetched from the game-table export and never
committed or shipped.

## Measuring routes with recordings

```sh
node tools/polestar.js record watch     # import sessions as the game saves them
node tools/polestar.js record import    # or import once
node tools/polestar.js data build       # fold recordings into the reference data
node tools/polestar.js record report    # how long each guide step really took
```

`record report [--guide <text>] [--json]` lists, per step, passes, median
and p75 time, XP per hour, time in combat, deaths, turn-ins and travel, then
the slowest steps, steps far over the guide's median and detours. Reloads,
AFK breaks (idle time counts at most 5 minutes), going back a step and other
tabs are accounted for.

At Forever's launch, the data is rebuilt and the simulator rerun to take in
the new zones ([docs/SIMULATION.md](https://polestar.guide/docs/contributors/simulation), "Refresh").

## Project layout

| Path | What lives there |
|---|---|
| [`addon/Polestar`](https://github.com/fitzforge/polestar/tree/next/addon/Polestar) | The addon: engine, navigation, UI, modules, textures drawn in code ([addon/README.md](https://polestar.guide/docs/contributors/addon); every addon: [docs/ARCHITECTURE.md, "Overview"](https://polestar.guide/docs/contributors/architecture#overview)) |
| [`addon/Polestar_Guides`](https://github.com/fitzforge/polestar/tree/next/addon/Polestar_Guides) | The compiled guides (generated by `compile`) |
| [`addon/Polestar_ItemDB`](https://github.com/fitzforge/polestar/tree/next/addon/Polestar_ItemDB) | Item stats for gear advice: `Items.lua` from `itemdb build`, `Forever.lua` from `gear build` |
| [`addon/Polestar_Nav`](https://github.com/fitzforge/polestar/tree/next/addon/Polestar_Nav) | The arrow's walking routes: Polestar's walking router, started from Shortest Path Forever's by Cillian Berragan (GPL-3.0-or-later), on Polestar's walking maps of Eastern Kingdoms, Kalimdor and Zephras Isle, grown from his format (`nav pack`; [CREDITS.md](https://github.com/fitzforge/polestar/blob/next/addon/Polestar_Nav/CREDITS.md)) |
| [`addon/Polestar_Recorder`](https://github.com/fitzforge/polestar/tree/next/addon/Polestar_Recorder) | The optional session recorder |
| [`guides/forever`](https://github.com/fitzforge/polestar/tree/next/guides/forever) | The guide sources: leveling, professions, reputation, exploration, Legacy, collectibles |
| [`tools`](https://github.com/fitzforge/polestar/tree/next/tools) | The command line (`polestar.js`), the guide compiler, the simulator, data importers, texture and preview renderers, the playground ([tools/README.md](https://polestar.guide/docs/contributors/tools)) |
| [`tests`](https://github.com/fitzforge/polestar/tree/next/tests) | `node --test` suites; `tests/lua` is the simulated game client they run the addon in ([tests/README.md](https://polestar.guide/docs/contributors/tests)) |
| [`docs`](https://github.com/fitzforge/polestar/tree/next/docs) | Architecture, guide format, simulation, the suite's scope, UI renders ([docs/README.md](https://polestar.guide/docs/contributors/docs-map)) |
| `data/` | Local build products and recordings, gitignored |

[docs/ARCHITECTURE.md](https://polestar.guide/docs/contributors/architecture) describes the modules and their
contracts, [docs/SUITE.md](https://polestar.guide/docs/contributors/suite) the suite and what is out of
scope (best-in-slot lists, loot browsing, talent builds), and
[docs/DESIGN.md](https://polestar.guide/docs/contributors/design) the visual system.

---

Next page: [From source to game](https://polestar.guide/docs/contributors/source-to-game.md) · Every docs page: https://polestar.guide/llms.txt · All docs in one file: https://polestar.guide/llms-full.txt