Handbook

A community addon is your own guides for Polestar, published as your own addon. Players install it next to Polestar, and its guides appear in Polestar's guide menu under Community guides, with your name on them. You write guides as plain text (.guide files, GUIDE_FORMAT.md), and Polestar's tools check them, play them to the end without the game, and build the addon. A community addon is built from a pack: a folder with a pack.json and .guide files.

Setup#

A pack lives in its own folder (usually its own git repository). The tools come from a clone of Polestar:

git clone <Polestar's repository URL> polestar
cd polestar
npm link                 # puts `polestar` on your PATH; the tools have no npm dependencies
polestar doctor          # checks everything below and prints the fix for each
cd ..                    # back out: your pack gets its own folder beside the clone, not inside it

Without npm link, run node <polestar clone>/tools/polestar.js <command> wherever this page says polestar <command>.

You need:

$LUA picks a Lua interpreter when you have several. polestar doctor exits with code 1 when Node or the reference data is missing, since every command needs them. Without the reference data (the folder missing, or holding none of its core files) lint, compile, dev, install, pack and play stop before reading any guide, with one error naming the folder, and exit with code 1; dev then does not start watching. playtest stops too, with an error naming the missing files. A folder missing only some of the core files is a warning naming them, and the guides are checked.

The reference data is what fills in quest titles, givers and coordinates. data build assembles it from the sources listed in Polestar's THIRD_PARTY.md (polestar help data names them); until Polestar ships the open data, it reads some of them from addons installed with your game.

Codespaces. A pack made by polestar new from a Polestar clone whose origin is an http(s) or SSH URL carries .devcontainer/devcontainer.json: open the pack's repository in GitHub Codespaces and you get Node 24, Lua 5.1, the tools linked and the reference data built, with nothing to install. (install and dev need the game, so in a codespace use play and playtest instead.)

A first pack in 15 minutes#

# in the folder that holds your Polestar clone, not inside the clone
polestar new joes-routes          # asks for the id, title, author and licence
cd joes-routes
polestar dev --play               # lint and build on every save, with the playground

1. polestar new [dir] asks for the pack id, title, author and license (or takes --id, --title, --author, --license; --yes accepts the defaults: the id from the folder name, the title from the id, the author from git config user.name, CC-BY-4.0). Without a terminal to ask in (a script, a CI job) it writes nothing and exits 1 unless all four or --yes are given. It refuses a folder that is not empty, and a folder holding only .git counts as not empty: run new first, then git init in the folder. It writes:
   • pack.json (the manifest, PACK_FORMAT.md) and guides/example.guide, a short guide that lints clean, plays to the end and hands over to one of Polestar's guides (it has no author line: a guide without one takes the pack's author);
   • README.md for players (install, credits) and for you (build, test);
   • LICENSE for the license you chose: for MIT the full text with your name and the year; for GPL-3.0-only your pack's title, Copyright (c) <year> <author> and the short GPL notice, then the license text; for CC-BY-4.0 and CC0-1.0 the name and official address; for any other license a one-line reminder to paste its full text;
   • .gitignore (dist/, drafts/);
   • .vscode/tasks.json: lint as the default build task, so VS Code underlines the lines with problems, and playtest as a test task;
   • AGENTS.md, and CLAUDE.md pointing to it: how a coding agent works in the pack (below, "With an AI assistant"), and the polestar-guide-pack skill in .agents/skills/ and .claude/skills/;
   • .github/workflows/pack.yml (lint and playtest on every push and pull request, with read-only access to your repository; on a version tag the same job builds the zip, and a second job, run only once that passes, attaches it to a GitHub release: the only job allowed to write) and .devcontainer/ (Codespaces). Both clone Polestar and build its reference data with polestar data build --no-web-xp --no-<web-db>: that skips the quest lookups on community web sites (Forever XP databases) and the web database cache (a fresh clone has none), but the build still clones the Era quest database and downloads the client tables from the game-table export. So they need the address of Polestar's public repository. new reads it from your clone's git remote get-url origin and writes it as https, quoted: an SSH address (git@host:owner/repo.git, ssh://) or an http:// one becomes its https form, and any user name, password, query (?…) or fragment (#…) is dropped. With no origin, or one that is neither http(s) nor SSH (a local path, say), it leaves both out and says why.
2. polestar dev watches pack.json and the .guide files. On every save it lints (printing the problems) and, without errors, builds the pack into the game's AddOns folder (--dest <dir> picks another; --no-game skips it). With --play it also starts the playground and reloads it on every build. In AddOns it never writes over a folder it did not build for this pack (the folder rule, below).
3. polestar play (or dev --play) runs the real Polestar against a simulated world, with your pack loaded after our guides, and prints the address to open in your browser: open the guide menu, find your pack under "Community guides", load a guide and play it with the side panel. Options > Community guides shows your pack's row and any problems.
4. polestar install inside the pack (or polestar install <dir> from anywhere) builds it and installs it into the game, when you are not running dev.
5. In game: the first time, restart the game so the client sees the new addon; after that, /reload shows every change. Open the guide menu (/polestar guides) and pick your guide under "Community guides".

Four ways to write guides#

GUIDE_FORMAT.md is the language, with a cookbook of examples; GUIDE_CHEATSHEET.md puts every line of it on one page. Whatever way you start, finish with lint and playtest (below).

By playing#

Record your own play and turn it into a draft:

polestar install --recorder        # in the Polestar clone (not the pack): installs Polestar_Recorder with Polestar
# in game: /psrec on, play the route, then log out
polestar record import             # copies the sessions out of SavedVariables
polestar record list
polestar record draft <session>    # writes drafts/<faction>-<race>-<date>-<time>.guide

Inside a pack, record draft writes into the pack's drafts/ folder with a guide id under <pack id>/draft/. A draft carries coords live (your recorded positions are in the client's own map frame). Edit it, give it a proper id, move it out of drafts/ into your guides, and lint it. Drafts are compiled only with --include-drafts.

From the simulator#

polestar sim export --result <file> --out <dir> turns a simulator route into skeleton guides, one per zone visit, with a visits.json. Their ids are sim/<faction>/<race>/NN-zone, which lint refuses in a pack: rename each under <pack id>/ and update the next lines that chain them. The best routes Polestar's simulator has found ship with Polestar once its open data lands; until then a result exists only where you ran the simulator yourself (docs/SIMULATION.md).

By hand#

Look up every id instead of guessing it:

polestar find "westfall stew"

accept 36  # Westfall Stew, level 10: Verna Furlbrow, Westfall 59.9,19.4
turnin 36  # Westfall Stew: Salma Saldean, Westfall 56.4,30.5

polestar find "kobold camp cleanup"

accept 7  # Kobold Camp Cleanup, level 2: Marshal McBride, Elwynn Forest 48.9,41.6
turnin 7  # Kobold Camp Cleanup: Marshal McBride, Elwynn Forest 48.9,41.6
# 7.1 = kill Kobold Vermin x10

polestar find Hogger --kind npc --faction Alliance
polestar find westfall --kind guide --race Human   # our guides a Human can follow, for `next`
polestar find 36 --json                 # ids, levels, zones, coordinates as JSON

polestar find --kind inn                # every inn, as `sethome` and `hearth` name it

sethome "Goldshire"  # Innkeeper Farley (npc 295), Elwynn Forest 43.8,65.8

polestar find --kind flight --faction Alliance   # every flight point, as `getfp` and `fly` name it

getfp "Sentinel Hill"  # Sentinel Hill, Westfall, Alliance: Thor (npc 523), Westfall 56.6,52.7

zone map 1429
goto 42.11,65.93 live

With an AI assistant#

An AI assistant can help you turn your own material into guides: your notes, routes you played, guides you wrote. Two ways work well:

• A chat assistant.Give it GUIDE_FORMAT.md (or GUIDE_CHEATSHEET.md) and your material, and ask for .guide text. Paste the result into your pack and run polestar lint.
• A coding agent in the pack folder.polestar new writes AGENTS.md (and CLAUDE.md, which points to it): look up every id, name and coordinate with polestar find --json and never guess one; repeat polestar lint --format json and polestar playtest until both pass; write only from the author's own material. It also writes the polestar-guide-pack skill (the workflow and the guide format on one page) into .agents/skills/ and .claude/skills/; for an older pack, copy skills/polestar-guide-pack/ from your Polestar clone into both, or run npx skills add fitzforge/polestar --skill polestar-guide-pack in the pack folder.

The ground rule: an assistant's quest ids, NPC ids, place names and coordinates are guesses until find, lint and playtest confirm them. Assistants write plausible numbers that are wrong. Check every id with find, and do not publish until lint has no errors and playtest plays every guide to the end.

Testing#

Every command below works on the pack in the folder you run it in (or the nearest parent holding pack.json); give a pack folder as its one argument (polestar lint ../joes-routes, the same as --pack ../joes-routes) to work on another.

Lint and compile read Polestar's guides as context, so your next is checked against them, and so are quests across the hand-over: a quest your guide accepts counts as turned in when our guide you hand over to turns it in, but your guide cannot turn in a quest that only our guides accept (that is the "never accepted earlier" error). Problems in our own guides are not shown.

Publishing#

polestar pack       # lints, builds and writes dist/<folder>-<version>.zip

The zip holds the addon folder (the TOC, Pack.lua, MapFrames.lua, Guides.lua, LICENSE-DATA.txt and the picture file of every image line, GUIDE_FORMAT.md "Pictures"), byte for byte reproducible, with the pack's LICENSE as LICENSE.txt when the pack folder has one.

The TOC places the community addon in the game's AddOns list for you: titled "Polestar Community: <title>" (your title as it is when it already starts with that), grouped with Polestar, in the Quests category, with your notes as its description, or "Community addon for Polestar by <author>" when pack.json has none. Polestar's own menus and the Community guides page show your title as you wrote it. Community addons built before this name read "Polestar Pack: <title>" until rebuilt; Polestar reads both.

Upload the zip to:

• CurseForge and Wago: a new addon project for World of Warcraft: Forever (the Classic game version matching the TOC's Interface). Mark Polestar as a required dependency on the listing, so the app installs it with your pack.
• GitHubwith the template's workflow, push a version tag (v1.2.0) and the workflow builds the zip and attaches it to a release.

Raise version in pack.json for every release. The guides' license is the one in pack.json (license, and the LICENSE file new wrote, which the zip ships). For a license new has no text for, it writes one placeholder line into LICENSE; lint warns until you replace it with the license's text. Polestar's LICENSE-EXCEPTION.md lets you distribute packs built by its compiler, including the reference data the compiler places in them, under terms of your choice; the pack's LICENSE-DATA.txt names that data's sources. It does not cover guide text copied from Polestar's own guides.

Players see your title, author, version, license, guide count, website and source on the Community guides page, and "By <author> · <pack> <version> · <license>" in each guide's details. Each pack is made and supported by its author: put where to report problems in your README and on the listing.

Polestar suggests the next guide from its own guides unless the player picks your pack under Suggest guides from (Options > Community guides); only packs with Leveling guides are offered there. With your pack picked, Polestar's guides still fill in wherever yours have nothing for the character (another race, another level range).

Updating#

• Change the guides, raise version, run polestar pack and upload.
• Players' progress is keyed to guide ids: keep a guide's id when you revise it. Removing a guide only closes its tabs; a player's tabs come back if it returns.
• After a game patch raises the client's interface number, the game marks every addon built for the old one out of date. Update your Polestar clone (git pull), rebuild (polestar pack) and upload: the TOC takes the interface number from Polestar's. Until then players can tick Load out of date AddOns in the game's AddOns list.
• When Polestar adds a new pack format, packs in the old one keep working (PACK_FORMAT.md, "Versioning").

In game: statuses and problems#

Options > Community guides (/polestar packs) lists every pack the game has installed, ours first. The rules behind the statuses and problems below are in PACK_FORMAT.md, "Rules Polestar enforces". Each row has a status:

Lint messages#

Every message comes with file:line: error|warning: message (file: alone when it is about a whole file or folder), and most with a hint: line saying how to fix it. Errors stop compile, pack, install, dev, play and playtest; warnings print. These are the ones about packs, plus the guide checks authors meet most; the rest are listed in GUIDE_FORMAT.md ("Validation").

Where things are#

• GUIDE_FORMAT.md: the guide language, its checks and a cookbook.
• GUIDE_CHEATSHEET.md: every line of the guide language on one page, with an example each.
• PACK_FORMAT.md: the pack rules: pack.json, ids, the folder rule, the TOC and Lua the compiler writes, what Polestar refuses and the statuses it shows.
• polestar help <command>: every option of every command.