Forge internals

This page is for people changing Forge itself: how the Rust workspace is laid out, how forge build runs its stages and decides what to redo, how a port was checked against the JavaScript it replaced, and the rules the code follows. Polestar Forge is the user's entry point; the other pages explain each part: data, nav, model, routes, writer, judge.

What Forge is for#

Forge makes Polestar's leveling routes and writes them into guides, end to end, from the installed game client and the guide sources:

1. read the game's data and build the reference data (data/forever),
2. build each faction's world (quests, givers, camps, areas),
3. price the walks between the places a route can visit,
4. improve each start's route, starting from the shipped (v1) guides,
5. write the improved route into the guides,
6. judge the result and write a report.

It is one Rust workspace built twice from the same code: native (the build pipeline, all cores) and WebAssembly (the parts a browser tool needs, single-threaded). The addon itself stays Lua.

Two decisions shape everything else:

• v2 is v1 improved.Many players use the shipped guides and like them; their reports are about missed quests, small things and back-and-forth. Each start's route starts from v1's own order and changes only by local edits that make it faster in the model while v1's deliberate orders and the guards still hold (routes).
• The objective is the fastest route to 60, measured in the model's hours (model). The guards (take a hub's quests, finish an area once, pick up what you pass, never come back for work that was available, train on the way, grind little) keep the route the kind players want; the judge (judge) checks them on the written guides.

Routes are class-agnostic: each faction has race start routes for levels 1 to about 12, then a route from 12 to 60 through that faction's zones and the contested ones. Class quest chains are separate class guides; group content is not planned into the solo route.

The workspace#

rust/ is a Cargo workspace (rust/Cargo.toml, members crates/*, GPL-3.0-only, edition 2021, Rust 1.87 or newer). Each crate does one job; a crate never reaches into another's files.

The browser never runs the router (its bundles are hundreds of MB per continent): it reads walk stores.

Crate names and paths: rust/crates/forge-<name>, Rust paths forge_<name>::....

The binary#

forge has one entry point (crates/forge/src/main.rs). forge build and forge data pack|fetch live there; forge doctor and every other command is a module in crates/forge/src/cli/ with pub fn main(), reading its arguments through cli::args():

Every command prints its usage with --help and exits 0. Developer-only tools stay separate binaries in the forge-devtools crate (travel-parity, navcch, landing_diff); build one with cargo build --release -p forge-devtools --bin <name>. sim-hash is forge-sim's own binary, so it also builds for WebAssembly.

forge build: stages, keys, staging#

forge build --out <dir> runs eight stages into --out, then writes the fixes ledger:

How a port was checked#

Every stage replaced a JavaScript tool that already shipped routes or data, and landed only when it matched it:

• Byte parity where the output is a file: the data builders, the guide compiler, travel, trainers, professions, dungeons, codex and gear write the same bytes as the JavaScript builder run fresh on the same inputs. The goldens under rust/tests/golden hold the JavaScript output and the tests rerun these comparisons (travel-parity against a live JavaScript travel build).
• Event parity for the model: every event's level and time equal the JavaScript evaluator's on v1's chains (within the reference file's rounding).
• Row parity for the knowledge base's SQLite file (typed rows compared table by table).
• Native equals WebAssemblysim-hash runs the same replays under both and compares hashes.

JavaScript number semantics are kept where outputs depend on them (forge-core::jsnum: toFixed, Math.round, String(number), -0 printed as 0). Comparisons written as !(a < b) stay that way because they differ from a >= b when a value is NaN; the workspace's clippy settings allow these forms (rust/Cargo.toml, [workspace.lints.clippy]).

Building, testing, CI#

cd rust
cargo build --release -p forge          # target/release/forge
cargo test --release --workspace        # parity tests skip with a reason when their inputs are missing
cargo fmt --all --check
cargo clippy --workspace --all-targets --release -- -D warnings
cargo check --target wasm32-unknown-unknown --no-default-features --lib \
  -p forge-core -p forge-guide -p forge-world -p forge-sim -p forge-nav -p forge-judge -p forge-writer -p forge-gamedata \
  -p forge-wasm
(cd crates/forge-wasm && wasm-pack build --release --target web --out-dir www/pkg --no-typescript)

The browser planner's page (crates/forge-wasm/www-build/build.sh <checkout> <sim dir> <local dir> name=<guides> ...) also bundles the JavaScript planner page from tools/planner (build.mjs, esbuild) and its static assets (export-assets.js); those steps stay JavaScript.

The forge workflow (.github/workflows/forge.yml) runs these on every change under rust/, checks every command's --help and every documentation block marked <!-- ci --> (rust/scripts/doc-commands.sh), builds the forge binary for Linux, Windows and macOS, and attaches them to a forge-v* release.

Parity tests that need the game client, a built grid or the JavaScript references skip with a note when those are missing, so CI passes without them; run them locally before changing a stage.

Large builds use a lot of memory (a walks stage, a full test run). On a shared machine cap them, for example systemd-run --user --scope -p MemoryMax=6G -p MemorySwapMax=0 cargo test ..., and use -j 4.

Rules for the work#

• Every number in the docs and the report is measured on committed code.
• Tests pin behavior (parity, rules, edge cases), not wording.
• Nothing is called better than v1 without the judge's numbers and a player's read of the guides.
• Every Forge result records the data it ran on, so a public-data build is never mistaken for an official one.
• Dependencies must be GPL-3.0-compatible (MIT, Apache-2.0, BSD, zlib, CC0). Credits and licenses: rust/NOTICE.md (opens in a new tab) and the data pack's manifest.json.
• Private material never enters the repository or the data pack; forge data pack refuses to build when it finds any (data).

Environment variables#

Every variable Forge reads. Command-line options win over them where both exist.

Crates we build on#

Adopt a crate where the current change needs it; don't rewrite finished, parity-tested code to fit one.