Polestar Forge

Forge is the tool that makes Polestar's leveling routes. From the game installed on your computer and Polestar's guides it builds the reference data and the world model (elite and group quests included, each with a solo way past), works out how long every walk takes, searches each start's route from level 1 to 60 (each race's own start zone, then one shared route per faction from the Barrens and Westfall), writes the leveling guides from it and checks the result the way a player would follow it. One command does all of it:

forge build --guides guides --out forge-out

and forge-out/report.md says what changed against the guides the routes started from, and check.md every step a player would trip on.

You need Forge if you want to rebuild the routes, test a change to the guides' order, or find out why a quest is or is not in a route. You do not need it to play: the addon ships with its guides already written.

Two words come back on every page. A start is one leveling start, by race and faction (Orc, Human, Skyborne for each side, ...); each start has its own route from level 1 to 60: its own start zone, then its faction's shared route. A cut is one run of the route search for one start, with the files it writes: the route and its two ledgers.

On this page: How it works · Requirements · Install · Updating · First build · How Forge finds the game · The data pack · Leffe's navigation maps · Roads and hubs · Reading the report · Why is a quest in or out? · Overrides · Changing the data · Fixing a generated guide · Troubleshooting · More

How it works#

forge build runs nine stages in order. Each one is skipped when its inputs did not change.

1. grid: the walking grid, built from the game's map files.
2. data: the reference data (quests, NPCs, items, travel) from the game and the other sources.
3. prepare: the walk graphs the walks are priced on.
4. world: each faction's quests, givers, camps and areas.
5. walks: how long every walk between those places takes.
6. routes: each start's own start zone and its faction's shared route, searched from the order of the guides the routes started from (the seed), under the route fixes from player reports; elite and group quests come with a solo fallback (How a route is made).
7. guides: the route written into the leveling guides, the shared route once per faction (The writer).
8. legs: the walk into every step of the written guides, drawn on Leffe's maps when you have them (our grid where his have no way or a detour, as the walks stage chooses; our grid alone without his maps), kept as its corners with each stretch's move and floor and the ground's height every 2 yards, and written beside each start's guides as legs.json (legs-qa.txt lists the walks it left out, and why). Compiling the guides puts them into the race parts, and the arrow follows them in game instead of searching (docs/PACK_FORMAT.md, "Format 7"). forge guide bake --guides <dir> does the same for one written guides folder.
9. report: the written guides played the way a player follows them, compared with the seed's guides, and the route check (check.md): every step a player would trip on, by rule.

Requirements#

• World of Warcraft: Forever installed on the same computer (Forge reads its files, read only).
• A checkout of the Polestar repository: Forge reads its guides/ folder and its tools' data.
• Memory: about 5 to 6 GB of RAM per faction for the walks stage, at the default 8 threads; lower --threads on a smaller machine.
• Disk: several GB for forge-out/ (the walking grid and the walk stores are the largest parts).
• Time: the first build takes a long while, roughly an hour or more (the grid, the walk graphs and every walk are built from nothing; How Forge walks the world has the parts). Later builds redo only what changed and take minutes.

All numbers are approximate and depend on the machine.

Install#

Prebuilt. Each Forge release on the Releases page (opens in a new tab) (tags forge-v*) has one archive per system:

Each holds one program, forge (forge.exe on Windows), with the license files (LICENSE, LICENSE-EXCEPTION.md), the notices (NOTICE.md, THIRD_PARTY.md) and THIRD_PARTY_RUST.md, the license list of the Rust libraries Forge is built from. Unpack it and put forge anywhere on your PATH.

Check the download against the release's SHA256SUMS before you run it:

sha256sum -c --ignore-missing SHA256SUMS                       # Linux
shasum -a 256 -c --ignore-missing SHA256SUMS                   # macOS

On Windows (PowerShell), compare the output of Get-FileHash polestar-forge-windows-x86_64.zip -Algorithm SHA256 with the line for that file in SHA256SUMS.

The binaries are not signed. On macOS, the first start is refused: remove the quarantine flag with xattr -d com.apple.quarantine forge, or right-click forge in Finder and choose Open. On Windows, SmartScreen may warn: choose "More info", then "Run anyway".

Then clone the repository, which holds the guides Forge builds from:

git clone https://github.com/fitzforge/polestar.git

From source. With Rust 1.87 or newer:

git clone https://github.com/fitzforge/polestar.git
cd polestar/rust
cargo build --release -p forge        # the program is rust/target/release/forge

On Windows, build in the "x64 Native Tools Command Prompt" of the Visual Studio Build Tools (or after its vcvars64.bat): from Git Bash, Git's own link comes before the MSVC linker in PATH, and the build stops with link: extra operand. forge build links its stages' folders with symbolic links, which Windows allows with Developer Mode on (Settings > System > For developers) or from an administrator shell.

Check it runs:

forge --help
forge doctor --help

Updating#

Download the new release's archive again, check it against that release's SHA256SUMS, and replace the old forge with the new one. Pull the repository too (git pull), so the guides match. A new Forge may change what a stage writes; the stages it affects run again on the next build.

Your first build#

1. Have the game installed. Forge reads World of Warcraft: Forever's own files (read only; it never writes into the game folder). See How Forge finds the game.

2. Check what Forge finds:

   forge doctor

   It lists the game folder (and how it was found) with every installed build, whether Forever's quest data addon is installed, the data or the data pack, whether the install is complete for the leveling maps, Leffe's navigation maps and the walking grid, with a fix for anything missing; optional things are shown as a note. It exits 1 when forge build could not run.

3. Get the data. In a Polestar checkout that has its own data/sources, Forge uses those. Everyone else will download the public data pack with forge data fetch; it has not been published yet (The data pack).

4. Build. From the Polestar checkout (its guides/ folder holds the current guides):

   forge build --out forge-out

   A build applies the fixes of one checkout: its guides, forever-db/corrections and data/route-fixes.json (the checkout above --guides, else above here; --checkout names it). Build from an up-to-date checkout, or fixes merged since are missing; fixes.md names the commit of every input and warns when they come from different checkouts.

   Useful options:

   Option	What it does
   --starts Orc,Human	only these starts (default all: Orc, Troll, Tauren, Undead, Skyborne-horde, Human, Dwarf, Gnome, NightElf, Skyborne-alliance)
   --wow <folder>	the game folder, when Forge does not find it (remembered for next time)
   --grid <folder>	a walking grid already built (or $POLESTAR_GRID); without it Forge builds one from the game into forge-out/grid
   --allow-incomplete	build the walking grid even when the install lacks files (Troubleshooting)
   --no-<quest-db>	build the data without the community quest database. Without this flag the build stops when no client's AddOns folder holds the community quest database's Forever store (the live _forever_ client first, then a _classic_beta_ one, a test install under ~/Games/*/World of Warcraft, any other client; $WOW_FOREVER_ADDONS names one): without it about a sixth of the quests are missing
   --accept-fewer-quests	take a data build with over 5% fewer quests than the previous build's (else the build stops, naming the missing quests by source)
   --forever-tables saved|client|<tables>	where the data stage reads the Forever client tables (zones, map frames, races, factions, items). Always at the build the walking grid was built from (its index.json), never whatever client is installed: saved (default) reads the copy under data/sources/client-tables/<build>/; client refreshes that copy from the installed client (wow_classic_beta or wowf at the grid's build) and reads it; <tables> reads the game-table export cache data/sources/<tables>/<build>/. The build log names the source and build. Tables missing for the grid's build stop the build
   --allow-build-mismatch	take Forever tables of another build than the grid's (the newest saved or cached, or the installed client's) instead of stopping; the log warns
   --until data|walks	stop after the data stage, or after the walks stage
   --nav grid|leffe|hybrid	which walking maps price the walks (Leffe's navigation maps)
   --threads N	worker threads (default 8)
   --guides <folder>	the guides to start from (default: the checkout's guides/, its generated guides read from the seed)
   --checkout <folder>	the checkout whose fixes the build applies (default: the one above --guides, else above here)
   --root <checkout>	the checkout whose sources to read (default: the nearest folder above here with data/sources)
   --strict	for release builds: fail when a fix no longer applies (Fixing a generated guide), when the route check (check.md) has a blocker, and when the walks would be on our grid alone (no Leffe's maps or saved walks). Every report's first line names the walking maps the build used

5. Run it again after a change. Each stage remembers a key of its inputs in forge-out/.forge/; a stage whose inputs did not change is skipped. Change one guide and only the routes, guides and report stages run again. The routes stage keeps its finished searches in forge-out/.forge/routes-search/: when only the writer, the judge or guide text the route does not read changed, or the walks gained pairs for legs the route walked with none, it reuses them and reruns only the check on the written guides, minutes instead of most of an hour (How a route is made). The writer checks every guide tree it writes as the pack does, so a line the pack refuses stops the build at the routes stage's first write, its searches kept.

What lands in forge-out/:

How Forge finds the game#

Forge needs the folder that holds .build.info and Data/ (for example C:\Program Files (x86)\World of Warcraft, or the same path inside a Wine prefix). It takes the first of:

1. --wow <folder> on the command line,
2. the POLESTAR_WOW_DIR environment variable,
3. the folder it remembered: whenever you pass --wow, Forge saves that folder in its config file (polestar-forge/config.toml in your config folder: ~/.config on Linux, ~/Library/Application Support on macOS, %APPDATA% on Windows; POLESTAR_FORGE_CONFIG names another file),
4. a search: Wine, Proton, Lutris, Bottles and Steam prefixes under your home folder, then the usual Windows and macOS install folders.

forge doctor prints which one it used and every other install it found; forge doctor --forget clears the remembered folder.

One install can hold several builds (the live game, the beta). Forge reads the Forever client (wow_classic_beta) at the build installed now; the reference data records that build, and forge doctor lists each build with its version. The data builders that take a build (forge data build --forever-build <version>) refuse a version other than the installed one, because the files on disk are that version's.

The data pack#

Some inputs are not in the game: Forever's quest data from other projects, the quest facts players and tools have gathered, the walks already priced. Polestar maintainers keep them in the checkout's data/sources. Everyone else will get the data pack, a release asset holding only data we may share, with every source, license and credit in its manifest.json.

No public data pack has been published yet. Once it is, forge data fetch downloads it from the data-pack release; until then it says so, and you build from your own game client (forge build --wow <path>).

forge data fetch                      # the pack of the data-pack release
forge data fetch --dest ~/forge-data  # somewhere else

It downloads the pack, checks its size and BLAKE3 hash and every file against the manifest, and only then replaces the previous pack. The default place is polestar/data-pack in your data folder (~/.local/share on Linux, ~/Library/Application Support on macOS, %LOCALAPPDATA% on Windows), or $POLESTAR_DATA_PACK. forge build uses the pack automatically when the checkout has no data/sources. The walking grid is not in the pack: Forge builds it from your own game (or takes --grid). Forge data has what is in it and how maintainers build it (forge data pack).

Forever's quest data is read from the addon installed in your own client, never from the pack. Without it, Forge still builds, with fewer quest facts; the report says so.

Leffe's navigation maps#

Leffe made navigation maps of Azeroth's continents and lets Polestar use what they give: thank you, Leffe. His maps are private: they are not in the repository or the data pack, and only people Leffe gives access to have them (--leffe <folder> / $POLESTAR_LEFFE_NAV).

What is shared is the walks his maps answered. The data pack's walk stores hold, for every walk a maintainer build asked of his maps, its length and time, plus the zone of each place on his maps (numbers, no map geometry). So everyone builds with the hybrid: Leffe's walks first, and Polestar's own walking grid wherever his maps have no way or a much longer one (a few city parts), and wherever the pack holds no walk of his (a place that is new since the pack was built).

forge build --nav grid|leffe|hybrid forces one (leffe needs his maps; POLESTAR_NAV does the same for forge walks walks only). How Forge walks the world explains both and when each wins.

Building as a contributor#

Without his maps your build is close to the maintainers' but not the same: the walks the pack does not hold, and every leg, come from our grid. That is fine for checking a change. Send the change to the sources (guides, corrections, data/route-fixes.json), not the generated guides: the maintainers rebuild the guides that ship with his maps after merging, and the report of that build is the one that counts. Compare your build with your own build of the same commit without your change, not with the shipped guides.

Roads and hubs#

Two optional layers shape the walks: the roads layer (players prefer roads) and the hubs layer (each faction's towns, so walks avoid the other side's guards). Forge makes them from the installed client, the server project dump and the cached client tables:

forge nav layers roads
forge nav layers hubs --dir <grid folder>

Without them, the prepare stage builds walk graphs with no road preference and no hostile-hub avoidance; the build still runs. How Forge walks the world has the details.

Reading report.md#

The report compares, for every start, the current guides (the chain guides in the report) with the guides Forge wrote (written):

An example of its shape (the values are placeholders, not results; the table has more columns):

# Route report

Sources: guides `guides`, data `forge-out/data/forever` (built …), sim `…`, root `…`; worlds horde …, alliance ….

| start | chain | to | hours | level | quests | zone changes | passed by (never/later) | returns (wasted) | … | log peak |
|---|---|---|---|---|---|---|---|---|---|---|
| Orc | guides | 61 | H.H | 60.00 | N | N | N (N/N) | N (N) | … | N |
| Orc | written | 61 | H.H | 60.00 | N | N | N (N/N) | N (N) | … | N |

## Horde Orc

Route `forge-out/routes/Orc.json`, written `forge-out/guides/Orc`.

Hours are model hours to compare routes with each other, not a promise of /played time. The time model explains the model and The judge every column.

Why is a quest in or out?#

Every route cut writes two ledgers beside it. Ask about one quest:

forge sim why 788 --start Orc --out forge-out

prints where the quest is in Orc's route (its steps, levels and the edits that moved it), or the row of the skip ledger saying why it is not in it. The whole list:

forge sim skips --out forge-out
forge sim skips --reason missing-info --out forge-out

missing-info lists the quests Forge leaves out because something about them is not known for certain (an objective, a giver's place, an item's source), each with what is missing and where the fix goes. It is the "help us with these quests" list. How a route is made has every reason code.

Overrides#

When a route is wrong for a reason the model cannot see, write an override in the checkout's data/route-fixes.json, under overrides. Every build reads that file from the checkout it builds (it is never built into forge); POLESTAR_ROUTE_FIXES names another file for a try-out:

"overrides": {
  "include": [{ "q": 940, "reason": "players take it here", "issue": 647 }],
  "skip":    [{ "q": 98299, "reason": "not offered on Forever", "issue": 229 }],
  "revert":  [{ "q": 109, "edit": "drop" }] }

include puts a quest into the route, skip keeps it out, revert undoes one of the cut's edits. Every cut honors them as hard rules and the ledgers show override as the reason. Data mistakes (a wrong giver, a missing objective) belong in forever-db/corrections instead, so every tool sees the fix. How a route is made has the full format.

Changing the data#

Contributors fix the data in committed files (the guides have two more: data/places.json and data/guide-fixes.json, in the next section). Each correction has a source, the evidence ({ "kind": "in-game-check", "ref": "#647" }; the kinds are in each file's _about, and check-corrections fails without one), and a note in our own words; a route fix has reason and issue:

Check the edit, then build:

forge data check-corrections     # shape, ids, conflicts; exits 1 on an error
forge data build                 # the corrections  (forge build reruns its data stage by itself)
forge data build --kb            # mechanics-public.json -> data/forever/mechanics.json

Corrections apply with or without Forever's quest data; a correction for a record the build lacks becomes that record when it has enough fields, else the build warns. Route fixes take effect in the next routes stage. Forge data has a worked example for each file.

Fixing a generated guide#

After the cutover Forge writes the leveling guides (guides/forever/horde/**, guides/forever/alliance/**). Each starts with # Generated by forge build ... and is listed in guides/GENERATED.json; the next build would undo a hand edit, so CI refuses one (tests/generated-guides.test.js, and the pull-request check Generated guides). Every other guide (class, professions, reputation, dungeons, ...) and the translations stay hand-written. Before the cutover (no GENERATED.json, no header) the leveling guides are still edited by hand on next; the cutover seeds Forge from next, so those edits are kept.

A fix goes into a record the next build applies, whoever builds:

{ "places": [
  { "id": "646-azshara-rimtori", "quest": 3505, "objective": 3,
    "at": { "map": 1447, "x": 59.53, "y": 31.47, "frame": "era" },
    "note": "Magus Rimtori's camp, where the quest's event is", "source": { "kind": "in-game-check", "ref": "PR #646" }, "pr": 646 },
  { "id": "674-gordo-road", "quest": 99141, "objective": 3,
    "path": { "map": 1420, "frame": "era", "points": [[53.8, 53.1], [51.8, 55.4], [43.1, 54.7]] }, "…": "…" },
  { "id": "703-shendar-rathiril", "quest": 93461, "objective": 1, "write": true, "…": "…" } ] }

{ "fixes": [
  { "id": "674-gordo-tip", "at": { "quest": 5481, "goal": "accept" }, "tip": "Gordo walks the road …", "…": "…" },
  { "id": "698-sleeping-bag", "at": { "quest": 79008, "goal": "accept" }, "level": 14, "…": "…" } ] }

Troubleshooting#

Start with forge doctor: it names the problem and the fix for most setups.

Forge's other commands#

Forge also replaces the Node commands that built the data, the guides and the releases (node tools/polestar.js compile, lint, data, release, pack and their neighbors now only print the forge command to run):

forge <command> --help gives each one's options. The contributor tools playtest, find, record, new, dev, install, play, preview and the planner stay on Node (node tools/polestar.js help).

More#

Credits: the full credits and licenses are in rust/NOTICE.md (opens in a new tab) and Credits & data sources, both in each release archive, and in the data pack's manifest.json. Forge's route search adapts ideas from the route-data project (MIT, used with its author's permission); the walks drawn on Leffe's navigation maps are used and published with Leffe's permission (his maps themselves are private); the players' cache export's data is used under CC BY 4.0.