" (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. - **GitHub**: with 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](https://polestar.guide/docs/reference/license-exception) 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 title> <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: | Status | The row says | Fix | |---|---|---| | `on` | the switch on, the guide count | — | | `off` | the switch off: the player hid the pack's guides | switch it on; its tabs come back | | `disabled` | "turned off in the AddOns list", with **Enable and reload** | press it, or enable the addon in the AddOns list | | `not-loaded` | "not loaded: <the client's reason>" (out of date, a dependency missing), or "not loaded" when the client gives none | out of date: rebuild with an updated clone, or tick "Load out of date AddOns"; dependency missing: install or enable the addons on the pack's `## Dependencies` line (the AddOns list names them) | | `too-new` | "needs Polestar <version> or newer", or "needs a newer Polestar" when its TOC gives no `X-Polestar-Needs` | update Polestar | | `refused` | "refused: <reason>" | one of the pack problems below | | `broken` | "broken: registered no guides" | see `no-guides` below | While any pack has problems, the page's entry in the Options sidebar carries a dot, and the row shows "<n> problems" with **Show** (the list) and **Copy report** (the pack, its version, Polestar's version, the client build and every problem, selected for copying: players can paste it into a bug report). Problems have three kinds: | Kind | Message | Fix | |---|---|---| | `pack-refused` | Pack id <id> is not valid: 2 to 32 lower-case letters, digits or hyphens, starting with a letter or digit. | fix `id` in `pack.json` and rebuild | | `pack-refused` | Pack id <id> is reserved for Polestar. — plus " 1 guide dropped." or " <n> guides dropped." when it dropped any | pick another id | | `pack-refused` | Pack id <id> is already taken by <addon>; <addon> was refused. — plus " 1 guide dropped." or " <n> guides dropped." when it dropped any | the refused pack's guides stay out, even under the holder's ids. Two installed addons claim one id: pick an id of your own (`<author>-<name>`); players remove one of the two | | `pack-refused` | The pack is missing format. / The pack is missing <field>. | rebuild with `polestar compile`; a hand-written `Pack.lua` needs every field (PACK_FORMAT.md) | | `pack-refused` | Needs Polestar <version> or newer. / Needs a newer Polestar. (no `X-Polestar-Needs` in the TOC) | the player updates Polestar | | `pack-refused` | Only Polestar's own Lookup pack may register as internal. — plus the dropped guides, as above, when its id is also reserved or taken | remove `internal` from `RegisterPack` | | `guide-refused` | Guide <id> was refused: its id must start with <prefix>. | start every guide id with `<pack id>/` | | `guide-refused` | Guide <id> was refused: it was registered before its pack. | `Pack.lua` must load first: rebuild with `polestar compile` | | `guide-refused` | Guide <id> was refused: <reason> (`missing title`, `no steps`, `step 3 has no goals`, `step 3 goal 2: unknown verb …`, `step 3 goal 2: kill needs target`, `step 3 goal 2: coordinates outside 0-100`, …). | the guide's table breaks the format: rebuild with `polestar compile`, which never writes such a table; with your own tools, PACK_FORMAT.md | | `no-guides` | Registered no guides. | the addon loaded but registered nothing, usually a Lua error in its files: turn on `/console scriptErrors 1`, `/reload`, and read the error; rebuilding with `polestar compile` fixes a damaged folder | Nothing goes to chat: every refusal happens while the packs load or in the scan at login, so the row's **Show** and **Copy report** are where to read them. Below the list, **Suggest guides from** picks where suggestions come from (Publishing, above), and **About community guides** tells players in plain words what a community addon is, with a **Read more:** link to [GUIDE_PACKS.md](https://polestar.guide/docs/players/community-guides). A pack's website and that link open the copy window, with the address selected to copy. ## 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"). | Message | Fix | |---|---| | no reference data: the folder does not exist / the folder holds none of quests.json, npcs.json, …, so no quest, NPC or place can be looked up | run `polestar data build` in the clone, or point `--data <dir>` at a built folder (and `--context-data <dir>` when our guides' data is missing too); `--no-data` checks guides that give every quest title, name and place themselves | | missing <file>.json, … (warning) | the reference data is partly built: run `polestar data build` again | | no pack.json in <dir> | create `pack.json` with `id`, `title`, `author`, `version` and `license` (or run `polestar new`) | | pack.json is not valid JSON (…) | a missing value, quote or comma; JSON allows no trailing commas or comments | | pack.json must hold one JSON object | write `{ "id": "...", "title": "...", "author": "...", "version": "...", "license": "..." }` | | missing `<key>` | add the key with your own value | | `<key>` must be a string | put the value in quotes | | `<key>` contains control characters (line breaks, tabs or other invisible characters) | keep the value on one line | | `<key>` is N characters long; at most M fit | shorten it | | pack id "<id>" is malformed: 2 to 32 lowercase letters, digits and dashes, starting with a letter or digit | pick an id like `<author>-<name>`, e.g. `joe-routes` | | pack id "<id>" is reserved for Polestar ("guides", "forever", "lookup", "draft", "polestar" are) | pick another id | | version "<v>" is malformed: one word of letters, digits, ".", "+" and "-", at most 32 characters | write a version like `1.2.0` | | website "<url>" must start with https:// or http:// | write the full address | | folder "<name>" is malformed: 1 to 64 letters, digits, "_" and "-" / folder "<name>" looks like one of Polestar's own addons | pick a folder like `PolestarPack_JoesRoutes`, or leave `folder` out | | unknown key `<key>` (ignored) (warning) | remove it; `pack.json` takes the keys in PACK_FORMAT.md | | `<key>` contains "\|", which prints literally in game (warning; the same for a guide's title, folder, pitch, pros, cons and author, step titles and tips, goal texts and notes, and names given in quotes) | drop the `\|`: Polestar shows text as written, so colour and link codes do not work | | guide id "<id>" is outside pack "<pack>": its guide ids start with <prefix> | start the id with `<pack id>/` | | `next` points to unknown guide "<id>" | a guide of your pack or one of Polestar's: list ours with `polestar find --kind guide <text>` | | `next` offers <faction> guide "<id>" after a <faction> guide | hand over to a guide of the same faction | | no <races> character can follow <id> (it is for <its races> only) | the `next` guide's `race` or `class` leaves out every character of yours: pick one for the same races (or classes) with `polestar find --kind guide <zone> --race <Race>` | | LICENSE still holds the placeholder line `polestar new` writes, not the license text (warning) | replace the line with the full text of your license | | map <id>: this pack's Era frame differs from the one Polestar's guides register; in game Polestar's wins, so coordinates on this map may be off (warning) | mark the coordinates on that map `live` or retake them with `/polestar where` | | `kill` npc <id> (<name>) is elite; … / <item> drops only from elites (<names>); … / quest <id> (<title>) is elite … (warning in packs) | Polestar's own house rule (errors in our guides): in a Leveling guide make the goal `optional` with the tip "<name> is elite: grouping up is advised." | | quest <id> (<title>) needs <Profession> <rank>, and the guide does not train it before here: characters without it never see this goal (warning, Leveling guides) | the quest giver offers it only to characters with that profession, and Polestar hides its goals from the others: make the goal `optional`, or `train <Profession>` (and `skill <Profession> <rank>` above rank 1) earlier in the guide | | sethome/hearth/getfp/fly "<location>": no inn has that bind location / no inn stands there (an inn's area or the zone it is in) / no flight point has that name / no flight point lands there (its town, an inn's area or the zone it is in); the game never reports that name, so the goal never checks off by itself (warning) | write the place as the game names it: the hint offers the closest known names (`did you mean "Grom'gol Base Camp"?`); `polestar find --kind inn` and `polestar find --kind flight` list them all. Checked against the inns and flight points of `data/forever/travel.json` (GUIDE_FORMAT.md, "Validation") | The folder rule (PACK_FORMAT.md, "TOC fields"): `compile`, `install` and `dev` write a pack folder only when it is absent, empty, or built for the same pack id (its TOC carries the "Generated by `node tools/polestar.js compile`" line); anything else is refused. (`pack` writes only the zip, and `play` builds into a fresh temporary folder, so the rule never stops them.) `compile` and `dev` print `refusing to write into <dir>: <reason>`. `install` lints and builds the pack, then checks the AddOns folder before it writes or copies anything and prints `refusing to install: <AddOns>/<folder>: <reason>`; it then writes the build into `<pack>/dist/<folder>` before copying, so the same rule there prints `install failed: refusing to write into <pack>/dist/<folder>: <reason>`. The reasons are the same everywhere: | Message | Fix | |---|---| | refusing to write into <dir>: it is not a generated community addon (no TOC with the "Generated by …" line); move it away first | a folder of the same name that Polestar did not write is in the way (in AddOns or `dist/`): move or rename it, or set `folder` in `pack.json` | | refusing to write into <dir>: it holds the community addon "<other id>", not "<id>"; set "folder" in pack.json to a folder name of your own | another pack builds into the same folder name (folder names come from titles, so two packs titled alike collide): set `folder` in `pack.json` | | refusing to write into <dir>: it is not a folder / refusing to install: <AddOns>/<folder> exists and is not a folder | a file has the pack folder's name: move or rename it, or set `folder` in `pack.json` | ## Where things are - [GUIDE_FORMAT.md](https://polestar.guide/docs/authors/guide-format): the guide language, its checks and a cookbook. - [GUIDE_CHEATSHEET.md](https://polestar.guide/docs/authors/cheatsheet): every line of the guide language on one page, with an example each. - [PACK_FORMAT.md](https://polestar.guide/docs/authors/community-guide-format): 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. --- # Guide format cheatsheet > The guide format on one page: every header line, goal and condition, with what it does and a short example. Page: https://polestar.guide/docs/authors/cheatsheet (Polestar docs > Guide authors) Every line a `.guide` file can hold, with what it does and a short example. The full rules, the checks `polestar lint` runs and worked examples are in [GUIDE_FORMAT.md](https://polestar.guide/docs/authors/guide-format); packs are in [PACKS.md](https://polestar.guide/docs/authors/handbook). `polestar find <text>` looks up the ids the examples use. A guide is a header (lines in column 0) followed by steps; the lines inside a step are indented. Words are separated by spaces, `"double quotes"` hold several words as one, and keywords ignore case. ## Header Before the first `step`. `guide`, `title`, `levels` and `zone` are required. | Header line | What it does | Example | |---|---|---| | `guide <id>` | First line: the guide's id, starting with your pack id and `/` | `guide joe-routes/goldshire` | | `title <text>` | The name players see in the guide menu | `title Goldshire to Westfall` | | `levels <min>-<max>` | The character levels the guide is for | `levels 5-10` | | `zone <Name>` | The zone the guide's coordinates are in, until a step names another | `zone Elwynn Forest` | | `zone map <uiMapID>` | The same, by map id | `zone map 1429` | | `faction <Faction>` | Only for `Alliance` or `Horde` characters | `faction Alliance` | | `race <Race>, ...` | Only for these races (see Conditions) | `race Human, Dwarf` | | `class <Class>, ...` | Only for these classes | `class Warrior, Paladin` | | `category <Category>` | The guide menu category: `Leveling` (default), `Class`, `Professions`, `Reputation`, `Legacy`, `Exploration`, `Collectibles`, `Miscellaneous` or `Dungeons` | `category Professions` | | `folder <text>` | The guide menu folder to list it under | `folder Mounts · Level 40` | | `keywords <word>, ...` | Extra words the guide menu search finds it by | `keywords wolf, meat` | | `collects <item>, ...` | Items the guide obtains; Lookup opens this guide for them | `collects 750` | | `reward item <item> ...` | What the guide's goal gives, shown with its icon in the guide menu; several items on one line are a choice of one; repeatable | `reward item 1251 2581` | | `reward spell <id> "Name"` | A spell the goal teaches (a mount, a form, a demon) | `reward spell 5784 "Summon Felsteed"` | | `reward text <words>` | A reward without an id | `reward text Shen'dralar reputation` | | `why <text>` | One short line in the guide menu: why the goal is worth doing (Class guides need it and `reward`) | `why Your own mount at 40.` | | `author <name>` | Credits a guide to someone other than the pack's author | `author Joe` | | `version <N>` | A whole number you raise when the guide changes (default 1) | `version 2` | | `coords era` / `coords live` | The map frame of the coordinates you type (default `era`; `record draft` writes `live`) | `coords live` | ## Steps and text | Line | What it does | Example | |---|---|---| | `step [title]` | Starts a step; it is done when its goals are | `step Kobold camp` | | `tip <text>` | A note for the whole step, shown in the guide window | `tip Pull one kobold at a time.` | | `image <path> [<w>x<h>]` | A picture (a `.tga` or `.blp` in the pack folder) shown under the step's tip, such as a screenshot of a cave mouth | `image media/fargodeep-mine.tga` | | `zone <Name>` / `zone map <uiMapID>` | Inside a step: the zone for coordinates from here on, also for the steps after it (after a step with `only` that sets one, name the zone again) | `zone Elwynn Forest` | | `only <condition>, ...` | Inside a step: the step is only for matching characters | `only Hunter` | | `when <predicate>` | Inside a step: the step is only for characters in that state when the route gets there (see Conditions checked during play) | `when level<6` | | `along [until <label>]` | Inside a step: the route never stops there; its goals are done along the way, listed under the next steps until done (or until the labelled step) | `along until camp` | | `label <name>` | Inside a step: names it for an `along until` before it | `label camp` | | `loop` | Inside a step: its `goto` points are the places to search, in order, for the step's kill, collect and interact goals without `@x,y` | `loop` | | `note <text>` | A line of information; never holds the player up | `note The camp is busy at night.` | | `level <N>` | Reach level N, grinding if need be | `level 2` | | `level <N>.<fraction>` / `level <N>+<XP>` | Reach a point inside level N: 12.5 is halfway through 12, 12+2500 is 2500 XP into it (to whole percent; needs Polestar 0.2.6) | `level 12.5` | | `# <text>` | A note for you and other authors; players never see it | `# check the patrol route` | | `<goal> -- <text>` | Shows the text under that goal | `accept 783 -- He stands at the abbey gate` | ## Places and travel | Line | What it does | Example | |---|---|---| | `goto <x>,<y> ["Label"]` | Walk to a spot; checked off on arrival, when a later goal of the step is done, or, ending its step, when the next step's quest work is done | `goto 47.6,35.1 "Kobold camp"` | | `r <yards>` | How close `goto` counts as arrived (default 8) | `goto 42.9,65.6 "Goldshire" r 30` | | `@<x>,<y>` | Places any goal at these coordinates instead of the data's | `talk 197 @48.9,41.6` | | `map <uiMapID>` | The map this goal's `@` coordinates are on | `kill 69 map 1429 @45,40` | | `era` / `live` | The map frame of this goal's coordinates, overriding `coords` | `goto 40,60 live` | | `explore <x>,<y> ["Area"]` | Discover the map area at these coordinates | `explore 41,65 "Goldshire"` | | `sethome "<Location>"` | Bind the hearthstone at an inn, named as the game reports it | `sethome "Goldshire"` | | `sethome nearest` | Bind at the nearest inn of the player's faction | `sethome nearest` | | `hearth "<Location>"` | Use the hearthstone; done on landing there | `hearth "Goldshire"` | | `getfp "<Flight point>"` | Learn a flight path from its flight master | `getfp "Stormwind"` | | `fly "<Town>"` | Take a flight; done on landing there | `fly "Stormwind"` | `polestar find --kind inn` and `polestar find --kind flight` list the names `sethome`, `hearth`, `getfp` and `fly` take. ## Quests | Line | What it does | Example | |---|---|---| | `accept <quest> ["Title"]` | Take a quest; the giver and title come from the data | `accept 783` | | `turnin <quest> ["Title"]` | Hand a quest in | `turnin 783` | | `lvl <N>` | On `accept`: the level the quest needs, shown beside it | `accept 7 lvl 2` | | `complete <quest> ["Title"]` | Finish every objective of a quest; give it a place (`@x,y`, or a `goto` before it) when its objectives have one, or the arrow has nowhere to point | `complete 7 @48.5,31.0` | | `npc <id>` | Which NPC gives or takes the quest, when the data knows several | `accept 5261 npc 196` | | `object <id>` / `item <id>` | The same for a quest started or ended at an object, or started by an item | `accept 9400 object 1617` | | `"<text>"` | Right after an id: the quest title, or the name of the NPC, object or item, for content missing from the data; after the modifiers: the text players see instead of the generated one | `accept 9201 "The First Step"` | | `xp <N>` / `money <amount>` | On `turnin`: what it pays (`money 1g50s`, `7s` or copper) | `turnin 9201 xp 210 money 1s` | | `choose <item> ...` / `reward <item> ...` | On `turnin`: the rewards to pick from, and the ones given outright | `turnin 5261 choose 159 2589 reward 4306` | | `direct` | On `turnin`: handed in straight from the giver's window, with no `accept` (Distracting Jarven, the cloth donations). Buy or collect what it asks for with `buy`/`collect`: the quest never enters the log, so nothing tracks objectives for it | `turnin 9300 direct` | ## Killing and collecting | Line | What it does | Example | |---|---|---| | `kill <npc>` / `kill "<Name>"` | Kill a mob; `quest Q.O` ties it to a quest objective | `kill 6 x10 quest 7.1` | | `x<N>` | How many (kills, items, purchases, crafts) | `kill "Cloth Kobold" x5 @65,75` | | `quest <quest>.<objective>` | Counts the goal by that quest objective, numbered as the quest log lists them (`quest <quest>` alone lets the data find it) | `interact 1617 quest 9400.1` | | `collect <item> ["Name"]` | Gather or loot items; without `quest`, counted in the bags | `collect 750 x8` | | `nearest` | On `collect`: the closest place mobs drop the item, by level and faction | `collect 4306 x10 nearest` | | `interact <object>` | Click a game object | `interact 2843` | | `use <item>` | Use an item | `use 1210 @47.6,35.1` | ## People, items and errands | Line | What it does | Example | |---|---|---| | `talk <npc>` | Speak to an NPC | `talk 197` | | `train class` | Visit the nearest trainer of the player's class | `train class only Warrior,Mage` | | `train <npc>` | Visit that trainer | `train 911 only Warrior,Paladin` | | `vendor nearest` / `vendor <npc>` | Sell and repair, at the closest vendor or that one | `vendor nearest` | | `buy <item> ["Name"]` | Buy an item; `nearest` picks the closest vendor selling it | `buy 159 x5 nearest` | ## Professions | Line | What it does | Example | |---|---|---| | `train <Profession> [Rank]` | Learn a profession or its next rank (`Apprentice`, `Journeyman`, `Expert`, `Artisan`) at the nearest trainer | `train Mining Journeyman` | | `skill <Profession> <N>` | Reach skill N (quote names of two words) | `skill "First Aid" 40` | | `learn <spell> ["Name"]` | Learn a recipe; from a trainer, or with `nearest` from the closest vendor of its recipe | `learn 3276` | | `craft <spell> ["Name"]` | Craft a recipe, `x<N>` times | `craft 3275 x5` | | `until <N>` | On `craft`: until the profession reaches N | `craft 3275 until 40` | ## Reputation and challenges | Line | What it does | Example | |---|---|---| | `rep <Faction> <Standing>` | Reach a standing (`Neutral` to `Exalted`) with a faction, by name or id | `rep Stormwind Friendly` | | `achieve <id> "Name"` | Complete an achievement or Legacy Challenge | `achieve 9001 "Kobold Catcher"` | | `criteria <n>` | On `achieve`: one criterion of it | `achieve 9001 "Kobold Catcher" criteria 2` | ## Conditions `race`, `class` and `only` take a comma list of names. Names in one group match any of them; the groups must all match: `only Warrior,Paladin,Dwarf` is a Dwarf who is a Warrior or a Paladin. | Line | What it does | Example | |---|---|---| | `only <condition>, ...` | After a goal: the goal is only for matching characters | `kill 299 only Hunter` | | `Warrior` `Paladin` `Hunter` `Rogue` `Priest` `Shaman` `Mage` `Warlock` `Druid` | Classes | `only Warrior,Paladin` | | `!<Class>` | Every class but this one | `only !Hunter` | | `Human` `Dwarf` `Gnome` `NightElf` `Orc` `Troll` `Tauren` `Undead` (or `Scourge`) `Skyborne` | Races; Skyborne plays on both sides | `only Dwarf,Gnome` | | `Alliance` `Horde` | Factions | `only Alliance,Mage` | ## Conditions checked during play One predicate per `when` line; a step with several needs all of them. `!` turns any of them around but `level`. Once the route has passed the step, the outcome stays. | Line | The step applies while | Example | |---|---|---| | `when level<N` (`<=`, `>`, `>=`) | the character's level compares so; N may be a point inside a level (`12.5`, `12+2500`) | `when level>=10` | | `when onquest <quest>, ...` | any of the quests is in the log | `when onquest 783` | | `when complete <quest>` | the quest is ready to turn in | `when complete 7` | | `when turnedin <quest>` | the quest is handed in | `when !turnedin 9201` | | `when available <quest>` | the quest can be taken now | `when available 9200` | | `when has <item> [xN]` | the bags hold N or more | `when !has 159 x5` | | `when zone "<Name>"` / `when subzone "<Name>"` | the player is there | `when subzone "Goldshire"` | | `when bound "<Location>"` | the hearthstone is bound there | `when !bound "Goldshire"` | ## Route choices and optional steps | Header line | What it does | Example | |---|---|---| | `next <id>, <id>, ...` | Several guides after this one: the player picks one, the first is your suggestion | `next joe-routes/westfall, joe-routes/redridge` | | `next <id> when <predicate>` | One guide per line, offered only while the predicate (as on a step's `when`) holds when this guide ends; `next` lines add up. One option left: Polestar goes on to it; none: the guide ends there | `next joe-routes/redridge when level>=15` | | `pitch <text>` | On a guide offered as a choice: one line on its card | `pitch Short walks between quests.` | | `pro <text>` / `con <text>` | One advantage or drawback per line, under the pitch | `pro Ends at a flight point` | | Line | What it does | Example | |---|---|---| | `optional` | After a goal: the step can be finished without it | `kill 299 optional` | | `group [N]` | After a goal: it needs a group (of N players, 2-40); the guide window says so. Elites, dungeon and raid quests are found from the data without it | `kill 299 group 3` | ## Handing over with `next` | Header line | What it does | Example | |---|---|---| | `next <id>` | The guide that follows when this one ends: one of yours or one of Polestar's (`polestar find --kind guide <zone>` lists them with who can follow them) | `next joe-routes/westfall` | --- # Guide format > The .guide language in full: header, steps, goals, conditions, what the compiler fills in, validation and a cookbook. Page: https://polestar.guide/docs/authors/guide-format (Polestar docs > Guide authors) Every line of the format on one page, with an example each: [GUIDE_CHEATSHEET.md](https://polestar.guide/docs/authors/cheatsheet). This page has the full rules. Guides are written as `.guide` text files in a pack (Polestar's own: `guides/`; a community pack: any folder holding a `pack.json`, see [PACKS.md](https://polestar.guide/docs/authors/handbook)) and compiled to Lua by `node tools/polestar.js compile`. The compiler fills in names, titles and coordinates from the reference data in `data/forever/`, so a line can be as short as `accept 783`. Anything you write explicitly wins over the data. Without the reference data the compiler stops with one error, unless `--no-data` says to compile guides that give every title, name and place themselves. Worked examples of every goal are in the Cookbook at the end of this page. ``` guide joe-routes/northshire title Northshire Valley faction Alliance race Human levels 1-6 zone Elwynn Forest next joe-routes/elwynn step Deputy Willem accept 783 -- He stands at the abbey gate turnin 783 accept 7 accept 33 accept 5261 npc 196 step Kobold camp tip Pull one kobold at a time until level 3. kill 6 x10 quest 7.1 collect 750 x8 quest 33.1 optional step Back to the abbey turnin 7 train only Warrior,Paladin -- Llane Beshere is inside the abbey level 4 ``` ## Lexical rules - UTF-8, one guide per file. Blank lines are ignored. - `#` starts an author comment (dropped) when it is the first non-blank character of a line or follows whitespace outside a quoted string. - ` -- ` (space, two dashes, space) starts a **player-facing note** for the goal on that line; the rest of the line is the note. - Header lines and `step` lines start in column 0. Lines inside a step are indented (any spaces or tabs). - Tokens are whitespace-separated. `"double quoted"` is one token, with `\"` and `\\` escapes. Keywords are case-insensitive; IDs are integers. ## Header Every line before the first `step`. | Key | Required | Value | |---|---|---| | `guide` | yes, first line | id: `[a-z0-9_-]+` parts joined by single `/` (none leading or trailing), unique across all guides; it starts with the pack's id and `/` (`joe-routes/elwynn`; Polestar's own guides: `forever/`) | | `title` | yes | rest of line | | `levels` | yes | `<min>-<max>` | | `zone` | yes | default zone: map name from `data/forever/zones.json`, or `map <uiMapID>` | | `faction` | no | `Alliance` or `Horde` | | `race` | no | comma list (see Conditions) | | `class` | no | comma list | | `next` | no | id of the guide that follows, or several ids separated by commas: a **route choice**. The player picks where to level next in the "Choose your path" window; the first id is the author's default. Every option must be the guide's own faction. Repeatable: each line adds its guides in order, and `next <id> when <predicate>` offers that guide only while the predicate holds at the hand-off (see "Conditional hand-offs"). | | `category` | no | default `Leveling`; others: `Class` (class quest chains, mounts and weapons; pair with a `class` header), `Professions`, `Reputation`, `Legacy`, `Exploration`, `Collectibles`, `Miscellaneous` (side chains and collections that fit no other category: the Cozy Sleeping Bag), `Dungeons` | | `folder` | no | the guide menu folder this guide is listed under, any category (e.g. `Mounts · Level 40`, `Companion pets · Vendors`). Guides sharing a folder sort by faction (yours first), then level. Without it: the category's folder (Leveling: by faction and level band). | | `keywords` | no | comma list of extra words the guide menu search matches (e.g. the colours a mount guide covers); an empty entry is an error, a repeated one a warning | | `collects` | no | comma list of item ids this guide obtains (a mount guide: every colour it sells). Compiled as `collects = { ... }`; the Lookup module opens this guide for those items instead of building one. Malformed or repeated ids are errors; an id missing from `items.json` is a warning. | | `reward` | no (a warning on a `Class` guide without it) | what the guide's goal gives, shown first in the guide menu's details with its icon and the game's tooltip. Repeatable, one entry per line: `reward item <item> ["Name"] [quality] ...` (entries as in `choose`; several on one line are a choice of one), `reward spell <spellId> "Spell name"` (a mount, a form, a demon, an ability; the name is required; the id is the spell the player ends up with, as the Forever client's `SpellName` table has it: `reward spell 691 "Summon Felhunter"`, not the quest's "Teach" spell) or `reward text <words>` (anything without an id: reputation, experience). A spell written as `reward text` shows a glyph instead of its icon and no tooltip, and tests/guides-class.test.js fails on one for the guide's class. The details list the entries given outright under "Reward", then the choices under "Choose one", each group in header order. An item's name defaults to `items.json`; an id missing there needs its name. Compiled as `reward = { { item, itemName, quality, choice }, { spell, spellName }, { text } }`. | | `why` | no (a warning on a `Class` guide without it) | one short line in the guide menu's details: why the goal is worth doing, in the author's words | | `author` | no | default: the pack's author (`pack.json`) | | `version` | no | integer, default `1` | | `coords` | no | `era` (default) or `live`: the map frame of coordinates typed in this guide (`@x,y`, `goto`, `explore`). Era-frame ones compile with `f = "e"`; on a map without Era bounds they compile live. `record draft` writes `coords live`. | | `pitch` | no | one line selling the zone, shown on its card in the route choice window (required, as a warning, when the guide is a route option) | | `pro` / `con` | no | repeatable: one advantage / disadvantage per line, shown under the pitch. Keep them short, factual and true for every race that can choose the route. | A route choice, as excerpts of two guides' headers (a pack's Tirisfal guide offering our Barrens or its own Silverpine): ``` # guides/tirisfal.guide next forever/horde/02-the-barrens, joe-routes/silverpine # guides/silverpine.guide pitch Undercity's backyard: a compact forest with the Forsaken's own story and short walks between quests. pro Ends in the Undercity, where the next guide starts: no zeppelin ride con Hunters, Shamans and Druids have no trainer here: they train next in Orgrimmar at about 22 ``` Characters arrive at a route option from any of its predecessors, so its turn-ins of earlier quests must not assume one starting zone; the engine skips a turn-in or objective for a quest the character never had (see ARCHITECTURE, "Route choice"). ## Steps ``` step [title] <directive | goal> ... ``` Step directives: | Directive | Effect | |---|---| | `zone <Name>` / `zone map <uiMapID>` | Current zone for coordinates from here on (sticky across later steps, also when its step has `only`: after a class trip, the next step everyone sees names its zone again). | | `only <cond>[,<cond>...]` | The step applies only to matching characters. | | `when <predicate>` | The step applies only while the predicate holds when the route reaches it; several `when` lines must all hold. See "Conditions checked during play". | | `along [until <label>]` | The route never stops at the step: its goals are done along the way, listed under the steps after it. See "Along the way". | | `label <name>` | Names the step, for an `along until` before it. | | `tip <text>` | Player-facing step note (compiled to `step.note`). | | `image <path> [<w>x<h>]` | A picture shown in the guide window under the step's tip, while the tip is open, scaled to the window's width (at most 160 high): a screenshot of a spot that is hard to find, such as a cave mouth. `<path>` is the file's place in the pack folder, `/` between folders (`media/fargodeep-mine.tga`), a `.tga` or `.blp` file; without the extension the `.tga`, else the `.blp`. The file ships in the pack's addon folder at that path. `<w>x<h>` is the size it is drawn at (only the ratio counts: `512x256` is twice as wide as high); without it the compiler reads the file's own. One per step; a step with no `tip` reads "Picture of this spot" above it. See "Pictures" in the Cookbook. | | `loop` | The step's `goto` points, in order, are the places to search for its kill, collect and interact goals instead of a path to walk: see "Spawn areas", Loop. | A step must contain at least one goal. ## Goals ``` <verb> <positional args> <modifiers...> [-- note] ``` | Verb | Positional | Notes | |---|---|---| | `accept` | `<questId> ["Title"]` | Title and quest giver from data; a quoted title overrides it (required if the quest is not in data). | | `turnin` | `<questId> ["Title"]` | Turn-in NPC/object from data. | | `complete` | `<questId> ["Title"]` | Finish all objectives. | | `kill` | `<npcId>` or `"Target name"` | Pair with `quest Q.O` to track a quest objective. | | `collect` | `<itemId> ["Item name"]` | Pair with `quest Q.O`; otherwise tracked by bag count `xN`. `npc <id>` names the NPC who hands the item over, for an item nothing drops and no data lists a source for (a quest report given in a gossip window): the target button then has someone to target, and the point is that NPC's spawn unless you place it. `collect <item> xN nearest` (no `quest`) compiles to farm spots: clusters of normal or rare mobs that drop the item at 2% or more, outside towns and guard posts, each with the zone's safety (`A`/`H` faction zone, `AH` contested), mob level range, items per kill and spawn count; at most 16 per continent, spread over safety and 10-level bands. The engine picks one by the player's level, faction and travel time. | | `goto` | `<x>,<y> ["Label"]` | Coordinates are mandatory here. A label that is a subzone's name as the game spells it (`"Fargodeep Mine"`, not `"Fargodeep Mine's mouth"`) gets its area ("Places by ID"); at a cave's or mine's mouth the goto then also counts as arrived once the player walks into it past the point (in that subzone and indoors). | | `talk` | `<npcId>` | | | `interact` | `<objectId>` | Click a game object. | | `use` | `<itemId> ["Item name"]` | | | `sethome` | `"Location"` or `nearest` | Inn location as the game names it (the bind location it reports), e.g. `"Goldshire"`. Without `npc` the compiler names the inn's innkeeper, so the arrow leads to them ("What the compiler fills in"); `npc <id>` picks one yourself. `sethome nearest` binds at the nearest own-faction inn when the step comes up. Lint warns about a location no inn has (`polestar find --kind inn`). Completes on every client language: binding at the inn's innkeeper, or a bind location the client names as the inn's area (see "Places by ID"). A player with "Set your home at the guide's inn" on (Quality of Life, Travel; off by default) has Polestar bind and confirm when they talk to that innkeeper (for `nearest`, any innkeeper the compiler listed for it), never at another inn. | | `hearth` | `"Location"` | Done when the zone or subzone where you land has that name: an inn's location or the zone it is in, in the client's language when the compiler finds its area ("Places by ID"). Lint warns about any other name. | | `getfp` | `"Location"` | Discover a flight path: the flight point's name (`"Stormwind, Elwynn"`) or its part before the comma (`"Stormwind"`). The compiler adds its taxi node, so it completes on every client language ("Places by ID"), and without `npc` that node's flight master, so the arrow leads to them ("What the compiler fills in"); `npc <id>` picks one yourself. Lint warns about a name no flight point has (`polestar find --kind flight`). | | `fly` | `"Location"` | Take a flight: the flight point's town (`"Stormwind"`), as the flight map picks the node by it. Done when the zone or subzone where you land has that name (in the client's language when the compiler finds its area, "Places by ID"); where the landing area is named differently (`"Stormwind City"`), the goal checks off only through a later goal of its step. Lint warns about a name that is no flight point's town, inn location or zone they are in. | | `train` | `[npcId]`, `<Profession> [Rank]`, or `class` | `train First Aid` / `train Mining Expert`: the nearest own-faction trainer of that profession and rank (`Apprentice`, `Journeyman`, `Expert`, `Artisan`; ranks taught by a book or quest point at its vendor or quest giver). Without a rank: the highest rank whose minimum skill (0/50/125/225) the last earlier `skill` (or `craft … until`) target for that profession in the guide reaches, Apprentice when there is none, and always above a rank the guide already trained. `train class`: the nearest trainer of the player's class. Resolved at runtime from the player's faction and position. | | `buy` | `<itemId> ["Item name"]` | Use `xN` for quantity. Add `nearest` to send the player to the closest own-faction vendor selling it. | | `vendor` | `[npcId]` or `nearest` | Sell junk / repair; `nearest` picks the closest own-faction vendor. | | `level` | `<N>`, `<N>.<fraction>` or `<N>+<XP>` | Reach level N (grind if needed). `level 12.5` reaches halfway through level 12 and `level 12+2500` 2500 XP into it (converted to a share of the level with the 1.12 XP table): done at level 12 with that share of the level's XP, or at any later level, and the guide window reads "Reach level 12 (50%)". The share is kept to whole percent; one that rounds to 0% or 100% is an error (write `level 12` or `level 13`), as is XP past the level's total; `level 12.0` is plain level 12. A guide that uses either form is written in pack format 4 (see "Conditions checked during play"). | | `note` | `<text...>` | Informational line; never blocks. Quotes optional. | | `skill` | `<Profession> <N>` | Reach skill rank N (`Alchemy`, `Blacksmithing`, `Enchanting`, `Engineering`, `Herbalism`, `Leatherworking`, `Mining`, `Skinning`, `Tailoring`, `Cooking`, `Fishing`, `First Aid`, quoted when multi-word). | | `learn` | `<spellId> ["Name"]` | Learn a recipe or spell (trainer or recipe item); name from `professions.json`. A trainer-taught spell points at every trainer of its rank (a smart target; `npc <id>` fixes one); `learn <spellId> nearest` for a recipe sold by vendors sends the player to the closest own-faction vendor of the recipe item. | | `craft` | `<spellId> ["Name"]` | Craft a recipe; `x<N>` crafts, or `until <N>` = until the recipe's profession reaches N. | | `rep` | `<Faction> <Standing>` | Reach a standing (`Neutral`, `Friendly`, `Honored`, `Revered`, `Exalted`) with a faction named in `factions.json`, or `rep <factionId> <Standing>`. | | `explore` | `<x>,<y> ["Area"]` | Discover the map area at those coordinates (current zone). | | `achieve` | `<achievementId> ["Name"]` | Complete an achievement / Legacy Challenge; `criteria <n>` targets one criterion. | **Quests the route leaves out.** Quest automation accepts and hands in only the `accept` and `turnin` goals of the step in play and the next two. When the game then opens a window of its own at the same NPC (the next quest of the chain, or the NPC's other quests) and none of those is a goal there, Polestar closes it (Options, Guide, Automation, "Close offers the guide skips", on by default). To keep such a follow-up in front of the player, give it an `accept` in the same step or the next two. **Smart targets.** `nearest` (and the profession/class forms of `train`) compile to a *candidate set* instead of one NPC: every matching NPC in the data with its faction. At runtime the engine keeps the candidates the character may use (faction, and race or class where it matters) and picks the cheapest by travel time from where the player stands, re-deciding on zone changes. Explicit npc ids stay fixed. Profession guides should use these forms instead of per-race branches. Sources: profession trainers from `professions.json`; class trainers from `trainers.json` (`node tools/polestar.js trainers build`: `train <npcId> only <Class>` goals in `guides/`, recorded trainer visits, and a curated list verified against `npcs.json`; without the file, the curated list); innkeepers from the `innkeeper` and `vendor nearest` from the `repair` role in `npcs.json`; `buy … nearest` from the item's `vendors`; `collect … nearest` from the item's droppers (see `collect`); `learn … nearest` from the recipe item's `vendors`; a trainer-taught `learn` from the profession rank's trainers in `professions.json`. Only factions the goal can apply to are kept, and each set keeps one candidate per town (within 250 yards), nearest to the previous goal first. Smart targets take no coordinates. Modifiers, in any order after the positional arguments: | Modifier | Meaning | |---|---| | `@x,y` or `@ x,y` | Coordinates (0–100) in the current zone. | | `map <uiMapID>` | Zone for this goal's `@` coordinates only. | | `npc <id>` / `object <id>` / `item <id>` | Explicit entity (e.g. which quest giver). | | `quest <id>` / `quest <id>.<objective>` | Quest objective link (1-based objective, numbered in the order the game's quest log lists them; `polestar find <quest id>` prints them). | | `x<N>` | Count. | | `"text"` | Display text override (for `goto`: the label). A quoted token directly after the entity id of `kill`, `talk`, `interact`, `train` or `vendor` (like `collect`/`use`/`buy`) names that entity instead, for new Forever content missing from the data. | | `r <yards>` | Arrival radius (`goto`, default 8). | | `lvl <N>` | Minimum level shown on an `accept`. | | `optional` | Never blocks the step. | | `group [N]` | Needs a group, of `N` players (2–40) when given (`kill 1234 group 3`, `accept 7583 group 5`). The guide window says "Group of 3 advised" (or "Group advised") under the goal. Overrides what the compiler derives: see "Group content". | | `only <cond>[,<cond>...]` | Goal applies only to matching characters. | | `era` / `live` | Map frame of this goal's typed coordinates, overriding `coords`. | | `choose <item> ["Name"] [quality] ...` | `turnin` only: the reward choices, shown under the turn-in and in its tooltip. Each entry is an item id, optionally its quoted name and a quality word (`poor` `common` `uncommon` `rare` `epic` `legendary` `artifact` `heirloom`); entries follow one another (`choose 6480 918 "Deviate Hide Pack" common`). Names and qualities default to `items.json`; an id missing there needs its name. Display only: a named unknown id is not a warning. | | `reward <item> ["Name"] [quality] ...` | `turnin` only: items given outright, same entries as `choose`. | | `xp <N>` | `turnin` only: the XP it pays. Shown with the rewards, and used for the route-level check when the quest has no `xp` in the data. | | `money <amount>` | `turnin` only: copper (`money 350`) or `1g50s` / `7s` / `25c` forms. | | `direct` | `turnin` only: the quest is handed in straight from the giver's window, with no `accept` (Distracting Jarven 308, the repeat cloth donations). It needs no earlier accept, and its availability, prerequisites and exclusive quests are checked as an `accept`'s are. The quest never enters the log, so it carries no objectives: get what it asks for with a plain `buy` or `collect` (without `quest`). The goal checks off on the hand-in itself and stays checked after a `/reload`, so a repeatable does not come back as undone. | ## Conditions Comma-separated names, case-insensitive: - Classes: `Warrior Paladin Hunter Rogue Priest Shaman Mage Warlock Druid`. A class may be negated with `!` (`only !Hunter`). - Races: `Human Dwarf Gnome NightElf Orc Troll Tauren Undead Skyborne` (compiled to the client's race file names, UnitRace's second return; `Undead` → `Scourge`). Skyborne plays on both sides: a guide's `faction` or an `only` faction picks the side. Unknown race names are passed through with a warning (new Forever races). - Factions: `Alliance Horde`. Classes OR together, races OR together, factions OR together; the three groups AND. `only Warrior,Paladin,Dwarf` = (Warrior or Paladin) and Dwarf. ## Conditions checked during play `only` says who a step is for; `when` says in which state. A step with `when` applies only while its predicate holds, checked on the character's live state while the step is the current one or still ahead. Several `when` lines must all hold; for "one or the other", write the step twice. ``` step Back to Gornek when onquest 788 when level<6 turnin 788 ``` | Predicate | Holds when | |---|---| | `level<N`, `level<=N`, `level>N`, `level>=N` | the character's level compares so with N (1-60); `level` takes no `!`. N may be a point inside a level as for the `level` goal: `when level<12.5` holds below level 12 and in its first half | | `onquest <quest>[,<quest>...]` | any of the quests is in the log | | `complete <quest>` | the quest is in the log, ready to turn in | | `turnedin <quest>` | the quest is handed in | | `available <quest>` | the quest can be taken now: not in the log or done, the level reached, its prerequisites done and none of the quests that close it taken or done (the compiler copies these from the data, as for an `accept`) | | `has <item> [xN]` | the bags hold N (default 1) or more | | `zone "<Name>"` | the zone text reads so (the zone as the game names it) | | `subzone "<Name>"` | the subzone text reads so | | `bound "<Location>"` | the hearthstone is bound there (a bind location, as for `sethome`) | `!` in front of any predicate but `level` turns it around: `!onquest 788` holds while the quest is not in the log, `!has 159 x5` while the bags hold fewer than five. Names can be quoted or bare. **Once the route moves past a step, its outcome stays.** Polestar stores whether the step's `when` held at that moment (once the quest log can be read after login), and reads that from then on: a "buy water" step passed because the bags were full is stored as skipped and does not come back when the water runs out, and a step that applied stays done. The player can unskip such a step like any other; it then applies whatever its `when`. Resetting the guide's progress forgets the stored outcomes. While its `when` fails, a step counts as one that does not apply: like a step for another class, it never holds the guide, and a turn-in whose only accept is in such a step goes with it. A step with `when onquest Q` (or `when complete Q`) can hand in Q with no `accept Q` before it: "hand it in if you picked it up elsewhere". A `turnin` whose quest is accepted earlier only in steps with `when` warns: characters who passed those steps never see it, so give it the same `when` or a `when onquest`. Zone, subzone and bind location names work on every client language: the compiler gives each its area ID where the data names one (see "Places by ID"), and Polestar compares the game's own name for it, then the name you wrote. ### Conditional hand-offs `next <id> when <predicate>` makes one `next` option conditional: one guide, one predicate from the table above, one line per guide (naming a guide twice is an error, so an option has one condition). `next` lines repeat, each adding its guides in order; one without `when` is always offered, and the comma form works as before. ``` guide joe-routes/durotar next joe-routes/barrens-early when level<12 next forever/horde/02-the-barrens ``` Polestar checks the condition on the character as they are when it lists the options: at the end of the guide, that decides where it goes. An option whose `when` does not hold is left out of the "Choose your path" window, the guide menu's "Next" line, `/polestar path` and a route change. With one option left Polestar goes on to it without asking; with none the guide ends there, like a guide without `next`. Nothing is stored: the condition is checked again each time. A subzone is looked up in the zone where the guide ends. A pack with a `when` anywhere (on a step or a `next` option), or a `level` goal inside a level (`level 12.5`), is written in pack format 4, which Polestar 0.2.6 and later read (docs/PACK_FORMAT.md); a pack without stays readable by older versions. ## Along the way `along` marks a step whose goals the player does on the way, without stopping the route: "kill 8 boars on your way to Goldshire and back". The route passes over the step at once. From then on its open goals are listed in the guide window under the current step, "Along the way" (up to six, with their progress; not in the compact window), until they are done. Clicking one points the arrow at it, if it has a place, until it is done. "Then:" and Up next leave along steps out. With `along until <label>`, the list ends when the route reaches the step carrying `label <label>`, done or not. The label must be on a later step of the same guide. ``` step Boars on the way along until camp kill 113 x8 quest 33.1 step Goldshire goto 42.1,65.9 "Goldshire" step Back at the camp label camp turnin 33 ``` The route goes straight from "Boars on the way" to "Goldshire", and the boar count shows under the steps until "Back at the camp". If the boars are needed before going on, hand the quest in at the labelled step, as here: the turn-in waits for the kills. Along suits goals the game counts wherever the player is: quest objectives (`kill`, `collect`, `interact`, `use` with `quest`), quests taken or handed in, bag counts (`collect`, `buy`), `level`, `skill`, `explore`. A goal Polestar checks off only on the step the route is on (`goto`, `talk`, `hearth`, `getfp`, `fly`, `vendor`, `train` but a profession's, and `kill`, `interact` or `use` without `quest`) never checks off in an along step and warns. An along step can have `only` and `when` like any step: one that does not apply when the route passes it is never listed, nor is one the player skipped. A label names one step: letters, digits, `-` and `_`, in the case written (`label Camp` is not `camp`), once per guide. A pack with `along` or `label` is written in pack format 4, like `when`. ## What the compiler fills in | Missing | Filled from | |---|---| | quest title | `quests.json` | | quest giver / turn-in target | `start` / `end` of the quest; `npc`/`object` modifiers pick one explicitly | | coordinates | the target's spawns, trying maps in order: the current zone, then maps the guide already used (most recent first), then anywhere. On the chosen map: the spawn nearest the previous goal when that goal is on the same map, else the centroid of the highest-priority candidate | | `kill` target name | `npcs.json` | | `collect` coordinates | every drop source with spawns, ranked as above (zone, used maps, nearness), then by drop chance. On the chosen map only the likely sources count (at least half the best chance there). Where elites (rank 1-3, hostile) drop the item beside normal mobs or objects, each at 1% or more, only the normal ones count, whatever the elites' chance, and a place of theirs with more elite spawns than its own within its radius (at least 70 yd) is an alternative spot: the point and the arrow lead to the normal mobs, not into the elite camp. An item only elites drop there keeps them. For a quest objective, mobs 3 or more levels above the quest (their lowest level) are left out where their higher chance would push the likely sources nearer the quest's level under that bar: those set it instead (a level 7 quest's seeds come from the level 5 Timberlings beside the giver, not the level 10 Elder Timberlings across the zone) | | `collect` source `from`, `fromAlso`, `fromId`, `fromAlsoId`, `fromKind`, `fromRank`, `fromFaction` | a `collect` (quest objectives too) whose item has one source with spawns, or one that drops it at 50% or more, and at most 8 sources at 2% or more (not cloth that drops everywhere); where normal mobs or objects and elites both drop it at 1% or more, only the normal ones are named, as the arrow leads to them (so are they where a rare tops the droppers and normal mobs drop it at 50% or more, and the sources near a quest's level where mobs 3 or more levels above it would crowd them out, as for the coordinates): the source's name, a second source of the same kind at 50% or more, their ids, `npc` or `object`, the NPC's rank (1 elite, 2 rare elite, 3 boss, 4 rare) and faction (`A`, `H`, `AH`; none for a hostile mob). The goal line names it, in the client's language by its id: "Kill Grell or Grellkin for Fel Moss" for an enemy, "Collect Oats from Sack of Oats" otherwise (nothing added for an object named as the item); with author `text` the line under it says "Kill Aean Swiftriver (rare elite)" or "From <name>"; a quest started by that item reads as one line ("Runed Scroll: kill Aean Swiftriver (rare elite)") | | `collect` source NPCs `fromNpcs` | every `collect` placed among its sources, whether the data placed the point or the author did and the data has the target there (as `spots`): the creatures its point and spawn areas belong to, the one the point itself belongs to first, then the other likely sources there (as above), at most 5. Objects are left out, as a macro can only target a creature. An item nothing drops gets the NPCs the data lists as its vendors instead, where they have spawns: those hand it over in their gossip window (the Warsong Scout's update), and nothing else would name them; a `collect` whose author named an `npc` carries that instead. The target button names them, in the client's language by their ids, before the item's own droppers, whose drop chances rank them over the whole world: for an item many creatures drop, those are mostly in other zones | | profession, recipe, trainer | `professions.json` (skill line, recipe name, created item, reagents, recipe item; a trainer-taught `learn` gets every trainer of the rank that teaches it, both factions (a smart target), unless `npc <id>` names one). Classic profession names resolve without it. | | faction | `factions.json` by name (lowest id on ties) or id | | objective index | the quest's objective whose `id` matches the npc/item, when `quest Q` has no `.O` | | count | the linked objective's count | | Era frame flag `f = "e"` | when coordinates come from Era-frame data, or were typed in an `era` guide/goal | | spawn areas `spots` | every goal placed at an NPC or object that spawns at more than one place, and hand-placed `@x,y` goals whose target the data also knows: see "Spawn areas" below | | group content `group` | elite work, dungeon and raid quests and goals on an instance map: see "Group content" below | | escort `escort` | the accept, `complete` and objective goals of an escort quest: see "Escort quests" below | | height `z` | a goal at an NPC or object: the height of that NPC's or object's spawn (`spawnz.json`), so the walk ends on its floor: see "Heights" below | | place area `area` | `sethome`, `hearth`, `fly` and `getfp` (their location) and `goto` (its label): the AreaTable area of that name, so the goal completes and reads right on every client language: see "Places by ID" below | | taxi node `node` | `getfp`: its flight point's taxi node (`travel.json`): see "Places by ID" below | | `sethome` innkeeper `npc`, `npcName` and coordinates | a `sethome "Location"` without `npc`: the innkeeper of the one inn (`travel.json`) whose bind location is that name (ignoring case) and who serves every faction the goal applies to (a neutral town's goblin serves both). None when no such inn has one: the Alliance innkeeper's inn on a goal for both factions gets none | | `getfp` flight master `npc`, `npcName` and coordinates | a `getfp "Location"` without `npc`: the flight master of the taxi node it gets (`travel.json`), the one node of that name or town serving every faction the goal applies to. None when there is no such node: Booty Bay, with one flight master per faction, on a goal for both factions gets none | | name tokens `{kind:id}`, `names` | the game's names in every text a player reads, so each shows in the client's language: see "Names in texts" below | | (a note dropped) | a goal's `--` note that only names the goal's own NPC, object, target or item (`accept 6181 -- Quartermaster Lewis`): the goal shows that name already, in the client's language | **Names in texts.** A text the player reads (the guide's `title`, `why`, `pitch`, `pros`, `cons` and `reward text`; a step's title and `tip`; a goal's `--` note and display text) names quests, NPCs, places and items in English. The compiler writes each name it can tell apart as a token, `{kind:id}`, so the addon shows the game's own name there on every client language (docs/TRANSLATING.md, "Guide texts"), and a translator writes only the words around it. It looks, longest name first and with its exact case, for: the names the step's own goals give (quests, givers and enders, targets, items, collect sources, smart-target candidates, rewards, reagents, quest objectives, spells, factions, professions), then the whole guide's, the zones of its maps and the AreaTable areas in them, then any zone and any open-world area whose name is unique, the professions and their reagents, and any NPC, object or item of the data whose name has two words or an apostrophe, then the client's spell names (the Forever `SpellName` table of the client build `meta.json` names, cached beside the data: any spell of two words or more, or with an apostrophe or colon; a one-word class or profession ability only in Class and Professions guides, or after "cast" or "your"; none another thing of the game shares, no profession rank spell, no spell owning something ("Blizzard's designers"), and no one-word spell used as a verb: taking an object or opening a sentence that goes on in lower case, "Polymorph a naga"; nor a name of a faction of the client's `Faction` table, "Burning Blade"). A place, NPC or object the game names with a leading "The" matches without it ("Molsen Farm" is the game's "The Molsen Farm"), and a zone or area ending "City" without that ("Stormwind"). An NPC of the step's or the guide's own goals also matches by its first name ("Dalinda" for Dalinda Malem) where that word has four letters or more, no other NPC of the step (or guide) shares it, no other NPC of the data starts with it ("Defias" stays words), and the word after it is not the rest of the NPC's name ("Lashtail raptors"). Other languages show the game's name there, and an English client reads the author's own words (the compiled guide's `written`). A name in its English plural ("Harvest Watchers"), in lower case ("the Jansen Stead") or inside a longer word stays words, as does a name right next to a capitalised word or before "of <Capitalised>" that would make it a longer name the data lacks ("Rot Hide" gnolls, "Young Wetlands Crocolisks", "Cleft of Shadow", "Elixirs of Shadow Power"; a possessive, a profession rank or a sentence's opening word does not count), and a one-word name the pack's texts also use as a lower-case word ("Barracks"), and two names a space apart (a name the data lacks, "Longshore Murloc Gills"). You may write a token yourself, `{npc:240}`: its kind and id must be in the data. `i18n guides stats` counts the tokens, by kind and by where the compiler found them. **Spawn areas.** Mobs, quest objects and some NPCs spawn at more than one place, and a player who finds nothing where the arrow led must be able to try the others. So a goal placed at an NPC or object gets every place its target spawns: `spots = { { x, y, r, n, alt }, ... }`, each the centre (map percent, in the goal's own `map` and frame `f`), radius in yards covering its spawns (measured through the map's Era frame, else its Forever one: Zephras Isle, Riverglades and the other maps Forever added have only that), and spawn count of one cluster of the target's spawns (for `collect`: the likely sources' spawns on that map, mobs, objects and nodes, as chosen above). Every known spawn on the goal's map lies in a spot (the reference data's evenly spread points and the ones its per-map cap left out, `more` in docs/ARCHITECTURE.md, "Reference data"). Spots with `alt = true` are the other places it spawns: the arrow never picks one on its own, but the world map marks them (fainter) and moving on by hand reaches them (the arrow button, a click on the arrow, a click on a mark). The clusters come from the quest database's clustering (`tools/lib/questdb/cluster.js`). Same map only. The goal keeps its `x`/`y` as the default point. A target with a single spawn on the map gets no `spots`. - **Places** (6 spawns or fewer: a named NPC or a quest object that appears at one of a few places, or the handful of mobs an objective needs): every place is a spot the arrow may pick, spawns within 70 yd of each other being one place, radius at least 15 yd. Places within 250 yd of their centre work as camps (below); further apart, kill, collect and interact goals search them like an area objective (`spread = true`, a walk from the goal's point). - **Camps** (90% of the spawns within 250 yd of their centre): clusters of 70 yd, widened for thinly spread mobs to twice the median spacing between neighbouring spawns (at most 250 yd); radius at least 15 yd. The arrow picks among the clusters of two or more (all of them when none has two), nearest to the goal's `x`/`y` first, at most 6; lone spawns and clusters past the 6 follow as alternatives. At runtime the waypoint is the spot nearest the player and the arrow counts the whole area as arrived. - **Area objectives** (spawns reaching further: raptors all over the northern Barrens) also get `spread = true`. Clusters as for camps; every cluster counts, lone spawns too, each at least as wide as the spacing between spawns (40-150 yd); beyond 12 the searched ones are spread evenly over the area (farthest-point picks from the cluster nearest the goal's point), ordered as a walk from the goal's point, and the rest follow as alternatives. At runtime the player searches spot by spot: the arrow says "Search here" inside a spot (never "Arrived"), moves on to the nearest spot not visited lately once the player leaves it, and the map shades every region the spots cover. - **Strays** (every goal the data places, any verb, whose target has more than 6 spawns on the map): when the spawns, linked wherever two lie within 300 yd of each other, mostly (three quarters or more) form one area, a group of one or two spawns apart from the rest is a stray: a mob or two on their own, hundreds of yards from the camps. A stray is an alternative, and a goal point at one (the spawn nearest the previous goal) moves to the nearest other spot, so the arrow leads to the area that holds the target. A sparse trail of three or more spawns is not a stray; nor is anything of a target with 6 spawns or fewer, or one spread over a zone with no area holding most of it. A stray can still be the place a step means (a named mob that drops the item too): place such a goal by hand (`@x,y`), or put it in the step at the camp. - **Hand-placed** (`@x,y`): the author's point is the spot the arrow takes, wide enough for any place of the target it stands in, and every other place the data knows follows as an alternative. Only where the data agrees: a point more than 50 yd from every spawn of an NPC to meet, or more than 250 yd from every spawn of a mob or object to kill, collect or click, places the target where the data does not (Forever moved it) and gets no `spots`. A route through gathering nodes lists every node place of the zone wherever its point lies. - **Loop** (a step with a `loop` line, for a search the data does not shape the way you want: a circuit through camps, round a lake): the step's `goto` points, in order, become the spawn areas of each of its `kill`, `collect` and `interact` goals that has no `@x,y` of its own and picks no place at runtime (`nearest`), with `spread = true`. The goal's point is the first goto, the spots are exactly the gotos (no alternatives, no spawn count `n`), each as wide as its goto's `r` (default 30 yd), and the gotos leave the step (their labels with them), so the player searches the points one after another as in an area objective. Compile-time only: the compiled step has no `loop`. It is an error when the step has fewer than two gotos, gotos on different maps or frames, an `optional` or `only` goto, or no goal to place. ``` step Kobold camps loop goto 47.6,35.1 goto 49.0,32.4 r 20 goto 52.3,26.8 kill 6 x10 quest 7.1 ``` See docs/ARCHITECTURE.md, Smart logic, "Spawn areas". **Heights.** In stacked places (the Undercity's quarters under its streets, a tower's floors) a point on the map is several places, and the walking route ends on whichever floor its engine picks. So a goal whose point stands for an NPC or object gets that entity's height, `z` (world yards), from `data/forever/spawnz.json` (the server database's spawn positions, which `data build` writes): the z of the entity's nearest spawn on the goal's instance map (its world point's, in the goal's frame), when that spawn is within 15 yards of the point. Nothing is guessed: an NPC only Forever has, or one Forever moved more than 15 yards, gets none, and without `spawnz.json` no goal gets one. These goals can get one, their point being the NPC's or object's (its spawn, or your `@x,y` at it): - `accept` and `turnin` at their NPC or object (not a quest from an item); - `talk`, `kill` (the spawn nearest the previous goal; a point at the centre of many spawns is seldom within 15 yards of one), `interact`; - `buy`, `train`, `vendor`, `sethome`, `getfp` and `learn` naming an `npc` (a `sethome` or `getfp` also with the innkeeper or flight master the compiler names). The same rule gives a height, each from its own point, to the other spawn places of such a goal (`spots`: a place within 15 yards of one of its spawns; the centre of a camp farther from each gets none) and to every candidate of a smart target (`nearest`, class and profession trainers, by the candidate's own NPC), so the walk to the place or NPC the arrow picks ends on its floor too. `goto` and `explore` (places), `collect` (a farming spot among the item's sources, also `collect … nearest`'s farm spots) and `use` never get one. `compile` prints how many got one ("heights: N of M NPC or object goals, N of M smart-target candidates and N of M spawn spots got z"). In the game the walk is searched with the height and asked again without it when that finds no route or one ending more than 30 yards above or below it. **Places by ID.** The game names places in the player's language ("Sombre-Comté" on a French client for "Darkshire") and guides name them in English, so the compiler gives a goal that names a place that place's ID, and Polestar compares IDs, or names the game gives in the same language: - `area`: on `sethome`, `hearth`, `fly` and `getfp` the area their location names, on `goto` the one its label names, from the client's AreaTable (the newest Forever build `data build` caches in `data/sources/<tables>/`): of the areas with that name (any case), the one in the goal's zone when the goal has a map, else the open world's (Eastern Kingdoms and Kalimdor, not Forever's copies of a town elsewhere). A name two areas share there gets none. In the game a `hearth` or `fly` is done when the zone or subzone text is that area's name in the client's language (`C_Map.GetAreaInfo`), a `goto` also when the player goes indoors in that subzone (a cave or mine, never a zone), and the guide window shows that name. - `node`: on `getfp`, the taxi node of its flight master (`npc`), else of the one flight point (`travel.json`) of that name or town serving every faction the goal applies to (Booty Bay has one per faction, so a goal for both gets none). In the game the goal is done once the flight map lists that node as known. - `sethome` completes by its inn: `travel build` gives every inn its area, and binding at the innkeeper the goal names (or the innkeeper of the inn its location names) completes it. A name with no single match gets nothing and the goal keeps matching by its English name, as before; the guide sources do not change. `compile` prints how many got one ("areas: N of M place goals got an area", "nodes: N of M getfp goals got a taxi node"). ## Group content Every goal that needs a group says so in the guide window, under the goal (once per card when several goals share it), and a guide with such a goal on its route (not `optional`) carries a "Group" chip in the guide menu. The compiler writes `group` on the goal, first match wins: 1. the author's `group [N]`: `{ kind = "group", size = N }` ("Group of N advised"; "Group advised" without `N`); 2. a dungeon or raid: a goal with a quest (`accept`, `turnin`, `complete`, or an objective goal with `quest`) that the simulator's solo filter counts as a dungeon or raid quest (tools/lib/sim/solo.js): the quest's area in `quests.json` lies in an instance, and its giver, its ender or one of its objectives has no open-world spawn (a breadcrumb into the instance stays an open-world quest); or a goal placed on a map drawn only on an instance: `{ kind = "dungeon" | "raid", name = "Dire Maul" }` ("Dungeon: Dire Maul", "Raid: Molten Core"); 3. elite work, the same test as the Leveling-guide elite rule (Validation): a `kill` of an npc of rank 1–3 hostile to a side the goal applies to, or a `collect` whose every located dropper is one: `{ kind = "elite", rank }` ("Elite: group advised", "Rare elite: group advised", "Boss: group advised"). The instances come from the Forever client's `Map.csv`, `AreaTable.csv` and `UiMapAssignment.csv` in the `sources` folder beside the data folder (`data/sources/<tables>/<build>/` for `data/forever`; `data build` and `codex build` cache them). Without them only `group [N]` and elite work apply. The guide's `group = true` is set when any goal that is not `optional` has `group`. ## Escort quests An escort quest's NPC walks off with whoever took the quest last and is gone until it respawns. The guide window says so under the quest's accept, `complete` and objective goals (once per card): "Escort: if the NPC is not there, wait for it to respawn". Its turn-in has no such line. The compiler writes `escort = true` on those goals (`tools/lib/dsl/escort.js`) when the quest's own words say escort: an `event` objective's text ("Escort Miran to the excavation site") or the quest's `objectiveText` ("Escort the captive fire elemental out of Dun Modr"). A quest's `escort` in `quests.json` wins, set by `tools/lib/data/corrections.json` with its source: `true` for an escort worded otherwise ("Protect Volcor until you reach the road"), `false` for a quest whose text wrongly says escort (Lost! 4492 carries the objective of the escort after it). There is no modifier: a wrong label is a data fix. ## Validation Errors fail `compile` and `lint`; warnings print. Errors: - syntax errors, unknown verbs or modifiers, malformed IDs or coordinates - duplicate guide ids; `next` pointing to an unknown guide - a `next` guide (or route option) no character of this guide can follow: of the other faction, or whose `race` or `class` leaves none of this guide's characters (no race in common, no class in common, or no race of this guide that can be one of its classes): `no Human character can follow forever/alliance/dwarf-gnome/01-dun-morogh (it is for Dwarf/Gnome only)`. A partial overlap is fine - a step with no goals - quest, npc, item or object id unknown in data **and** no explicit name/title - profession, faction or spell unknown in data **and** no quoted name; a faction not in `factions.json` also needs its id (`rep <factionId> "Name" <Standing>`); `achieve` always needs its quoted name - `rep` standing outside 1–8 / Hated–Exalted; `craft` with both `xN` and `until` - empty quoted strings (names, titles, labels, notes) - a step label used twice in a guide, an `along until` naming no label, or a label on its own step or an earlier one - `era`/`live` on a goal without typed coordinates - an `image` path that is absolute, leaves the pack folder (`..`), uses `\`, names a file other than `.tga` or `.blp`, or has a character other than letters, digits, `_`, `-` and `/`; a malformed size (`512x256`); a second `image` in a step - `choose`/`reward` without item ids, an item listed twice, a reward item missing from `items.json` without a name; malformed `money` or `xp`; a `group` size that is not a whole number from 2 to 40 - a smart target (`nearest`, `train <Profession>`, `train class`, `collect … nearest`) with no candidate in the data or with coordinates; `collect … nearest` without `xN` or with `quest`; `nearest`/`train class` with an `npc` (`train <Profession> npc <id>` keeps that trainer); an unknown profession in `train` - `turnin`/`complete`/objective goals for a quest that is never accepted earlier in this guide or in a guide that chains into it via `next`, unless the turn-in is `direct` (for a repeatable quest its giver also takes back, the hint suggests `turnin <id> direct`) - `turnin … direct` for a quest the chain accepts earlier (drop `direct`), and `complete` or an objective goal for a quest handed in `direct` - `accept` for a quest whose `races`/`classes` exclude every character the step or goal can apply to - coordinates outside 0–100 - required elite work in a `Leveling` guide (a warning in other packs; elite work may appear there only as an `optional` extra, with the tip `<Target> is elite: grouping up is advised.`): a non-`optional` `kill` of an npc of rank 1–3 (elite, rare elite, boss) hostile to a side the goal applies to (a friendly one is a talk credit), or `collect` of an item whose every located dropper is such an npc; `lint` also errors on a non-`optional` quest goal of a quest the cached simulator world (below) excludes as `elite`, unless the goal was already reported as elite Warnings: - a `when` predicate naming a quest or item the data lacks, a zone not in `zones.json`, a bind location no inn has, or a subzone that names no single area; a step whose `when level` leaves none of the guide's levels, or that asks for one predicate both ways (`onquest 7` and `!onquest 7`): no character sees it - a goal in an `along` step that Polestar checks off only on the step the route is on (see "Along the way"): it never checks off there - an `accept` whose prerequisites (`pre`, any one suffices) are none of them turned in earlier in the chain - an `accept` above the level the route plausibly reaches (when XP data exists) - an `accept` of a quest whose `excl` (exclusive) quest is accepted or turned in earlier in the chain: the game does not offer it while that quest is in the log or done - a non-`optional` `accept` never turned in later in the guide or the guides after it, checked for every route choice; when a next guide's race or class leaves out the characters still holding the quest, the warning says so (its turn-ins do not count for them) - `complete` on a quest with no objectives: the turn-in is the action; use `turnin` - a `turnin` whose quest's objectives ask for an item the world gives (a drop, an object, a vendor or a container; not one the quest or an NPC hands over) that no earlier goal in the guide or a guide chaining into it gets: a goal for the item (`collect`, `buy`), one linked to its objective (`kill … quest Q.O`), or a `complete` of the quest - a `complete` with no place (no coordinates and no `goto` earlier in its step) on a quest whose objectives have places (an npc or object with spawns, an item with a placed dropper or vendor): the arrow has nowhere to point; write a goal per objective - explicit coordinates more than 50 yards from every known spawn of the entity - ids missing from data but given explicit names/coordinates (new Forever content) - objective-capable goals with no coordinates - `quest Q.O` past the quest's objectives (the warning lists them as `7.1 = kill Kobold Vermin x10`), or an objective goal whose target is none of the quest's objectives - a `craft` before any `learn` of that spell earlier in the chain (free starter recipes excepted); `until <N>` past the recipe's grey skill - a coordinate on a map other than the step's zone that the guide never sets as a zone (catches a target resolved onto another continent) - coordinates without `map` on a zone set in a step for some characters only, when the other characters who see them are in another zone (a class trip's `zone Moonglade` holding for the rest of Darkshore) - profession, faction or spell missing from data but given a quoted name - a `goto` right before a goal that already leads to the same place: the next goal (notes skipped) is located within 200 yards of the goto point, measured to the edge of its nearest spawn area (see `goto` under "Places") - a quest item that vanishes after a while (items.json `duration`, from the Forever client's ItemSparse) carried longer than it lasts: from the goal that gets it (an `accept` whose quest hands it over, a `collect`, a `buy`) to a later `turnin` that needs it or `use` of it, timed from the latest goal that got more of it (`buy 13320 x2` serves two turn-ins, the second measured from the purchase), with the simulator's travel and kill times over the guide's goals (docs/SIMULATION.md, "Keeping the guides' fixes"): ``item 10439 (Durnan's Scalding Mornbrew) lasts 5 minutes, but the route takes about 11:29 from here to the `turnin` that spends it (line 196)``. Goals for other characters and `optional` ones are left out, so the estimate errs short - a smart target with no candidate for a faction the goal applies to (and, for `train class`, for a class that faction's allowed races can be); a `train <Profession>` whose default rank needs more skill than any earlier `skill` target - a `sethome`, `hearth`, `getfp` or `fly` location the game never reports, ignoring case: `sethome` against the inns' bind locations, `hearth` against those and the zones the inns are in, `getfp` against the flight points' names and their part before the comma (these three as the addon matches them); `fly` against the flight points' towns (the name the flight map picks the node by, even where the landing area is named differently), the inns' locations and the zones they are in. The hint names the closest known places (`did you mean "Feathermoon Stronghold"?`). Inns and flight points come from `data/forever/travel.json`; without it (or without the inns or the flight points in it) those goals are not checked - a `|` in text the player sees (`title`, `folder`, `pitch`, `pro`, `con`, `author`, step titles and tips, goal texts and notes, quoted names): it prints literally in game - another pack's Era frame for a map Polestar's guides also use, with other bounds: in game Polestar's wins, so coordinates on that map may be off - an `image` whose file the pack folder lacks (the step then shows no picture), a file whose size the compiler cannot read (not a TGA or BLP) when the line gives none, and a picture whose sides are not powers of two (256, 512, 1024), which the game may not draw - `lint` only, with a simulator world cached in `data/sim` (or `--sim <dir>`): a non-`optional` quest goal in a `Leveling` guide on a quest the solo filter excludes (dungeon, raid, pvp, rare drop, reputation, repeatable or profession; `elite` is an error, above); a `turnin … direct` is no repeatable to grind and is left out of the repeatable check These quest checks count a goal only for the characters its `only` (and the quest's own race and class masks) leaves. Most messages carry a `hint:` line saying how to fix them. ## Output `compile` writes the pack's addon folder (Polestar's: `addon/Polestar_Guides/`; another pack's: `dist/<folder>/`): the generated TOC, `Pack.lua`, `MapFrames.lua` (Era bounds for referenced maps), `Guides.lua` (one `RegisterGuide` per guide, each in its own function) and `LICENSE-DATA.txt`, plus the pack folder's `LICENSE` copied as `LICENSE.txt` when it has one, the picture file of every `image` the compiler found, at its path in the pack folder, and beside it a texts addon per language the pack's `locales/` translates (docs/TRANSLATING.md, "Guide texts"). [PACK_FORMAT.md](https://polestar.guide/docs/authors/community-guide-format) describes them. Output is deterministic: the same inputs give byte-identical files. ## Cookbook Worked examples, from guides that lint clean and play to the end. Every id here was looked up with `polestar find`; look up yours the same way. ### Quests: `accept`, `complete`, `collect`, `turnin` ``` {9} step Goldshire tip Marshal Dughan and Remy stand in front of the inn. accept 62 accept 47 step Fargodeep Mine goto 39.5,80.0 "Fargodeep Mine" complete 62 -- Walk through the mine collect 773 x10 quest 47.1 -- Gold Dust from the kobolds step Back in Goldshire turnin 62 turnin 47 ``` The compiler fills in each quest's title, giver, turn-in NPC and coordinates. `quest 47.1` ties the collect to the quest's first objective, so the guide window counts it from the quest log. `complete` finishes every objective of a quest with nothing more specific to track. ### Killing: `kill` ``` kill 299 x8 optional -- Young Wolves around the camp kill 6 x10 quest 7.1 ``` A `kill` with `quest Q.O` counts from the quest log; without it the player ticks it ("Patterns" below). Kill, collect and interact goals get spawn areas from the data, so the arrow leads to the nearest camp. `polestar find <quest id>` lists a quest's objectives as `7.1 = kill Kobold Vermin x10`: the `7.1` is the `quest 7.1` to write. ### Places: `goto`, `explore` ``` goto 39.5,80.0 "Fargodeep Mine" goto 46.0,55.0 live "Lift to the bluff" explore 39.5,80.0 "Fargodeep Mine" ``` Typed coordinates are in the Era map frame unless the guide says `coords live` or the goal says `live`. In game, `/polestar where` gives your own position as `zone map <id>` and `goto <x>,<y> live`, ready to paste, and the `@x,y live` form for any other goal. Use `goto` for travel and approach waypoints (a boat dock, a pass, a cave mouth on a long ride) and for objectives the data has no location for. Kill, drop, NPC and object goals carry their own location, so the arrow leads to them directly; lint warns on a `goto` whose next goal is located within 200 yards of it. It keeps a `goto` followed by another `goto`, by a goal without a location, an `optional` one, one for other characters (`only`) or one on another map, a kill or drop whose target spawns nowhere in the data (an instance boss placed at its entrance), and gotos in steps with `fly` or `hearth`. A `goto` counts as done on arrival, once a later goal of its step is done, or, when only other gotos, notes and goals for other characters follow it in its step, once the next step for the character is done with a quest goal of it done: a cave's mouth in a step of its own no longer sends back a player who already did the work inside. The goto still holds when that next step has no quest goal (training, a level, travel), is for some classes or races only (`only`), was skipped, or was passed only because its quests are unavailable, when the quest goal done is itself `only`, and when `optional` goals follow the goto in its own step: that is where they are done. ### Pictures: `image` ``` step Fargodeep Mine tip The mouth is easy to miss from the road: the picture shows it. image media/fargodeep-mine.tga goto 39.5,80.0 "Fargodeep Mine" ``` A screenshot helps where words and the arrow do not: a cave mouth hidden in a hillside, the right door of a building. Take it in game (Print Screen saves it in the game's `Screenshots` folder), crop it to the spot, and save it as a `.tga` at a power-of-two size such as 512x256 or 512x512 in your pack folder, for example `media/`. The guide window draws it under the step's tip as wide as the window (at most 160 high), in the ratio of the file or of `<w>x<h>` when the line gives one. Folded to one line, the tip hides it; a player who turned step tips off sees none. Lint warns when the file is not there, and `compile` copies it into the addon folder. The game may only find a picture added while it runs after a restart; `dev` rebuilds when a `.guide` file or `pack.json` is saved, so save the guide once the picture is in place. An import string carries the `image` line but not the file, so an imported guide shows no picture. ### People and things: `talk`, `interact`, `use` ``` talk 295 optional interact 176793 quest 5545.1 -- Bundles of wood lie under the trees use 5411 quest 754.1 @51.8,68.4 -- Winterhoof Cleansing Totem ``` ### Travel: `sethome`, `hearth`, `getfp`, `fly` ``` sethome "Goldshire" npc 295 -- Innkeeper Farley, inside hearth "Goldshire" getfp "Thunder Bluff" npc 2995 -- Tal, on the top of the bluff fly "Crossroads" ``` Locations are written as the game names them; `polestar find --kind inn` and `polestar find --kind flight` list the names (every inn and flight point, with coordinates). `sethome nearest` binds at the nearest inn of the player's faction instead. ### Errands: `train`, `buy`, `vendor`, `level`, `note` ``` vendor nearest buy 159 x5 nearest -- Refreshing Spring Water train class level 9 note You can train First Aid with any trainer of it in a city. ``` `nearest` and `train class` pick the trainer or vendor at runtime, by the player's faction and where they stand. ### Professions: `train`, `learn`, `craft`, `skill` ``` step First Aid train First Aid learn 3275 craft 3275 until 40 skill "First Aid" 40 ``` ### Reputation and challenges: `rep`, `achieve` ``` rep Stormwind Friendly optional achieve 6 "Level 10" optional ``` `achieve` always needs the achievement's quoted name. ### Class- and race-only steps A header `race` or `class` limits the whole guide; `only` limits one step or one goal: ``` guide joe-routes/mulgore title Bloodhoof Village faction Horde race Tauren levels 6-10 zone Mulgore step Hunters only only Hunter train class -- your next spells step Class quests note "Your class quest starts in Thunder Bluff." only Warrior,Shaman ``` A goal's `only` comes after its arguments, so a `note` with one needs its text in quotes. `only !Hunter` is every class but Hunters. Playtest plays each class a guide names, plus one it never names. ### Route choices `next` with several ids lets the player choose where to level next; the first is the default. Each option needs a `pitch`, and may have `pro` and `con` lines: ``` guide joe-routes/mulgore next joe-routes/thunder-bluff, forever/horde/02-the-barrens guide joe-routes/thunder-bluff pitch Train, shop and take the flight to the Crossroads. pro Every trainer in one city con A long ride down the lift next forever/horde/02-the-barrens ``` ### Optional extras `optional` goals never hold the step: side quests, a rare, a reputation along the way. An elite in a Leveling guide belongs here, with the tip "<Name> is elite: grouping up is advised." ``` accept 184 optional -- Only if you looted a Westfall Deed: right-click it kill 299 x8 optional ``` ### Handing over to our guides A pack's guide may end by handing over to any of Polestar's guides. Pick one its characters can follow: `polestar find --kind guide <zone>` prints each guide's level range and who it is for, and `--race`/`--class` keep only the ones such a character can follow: ```sh polestar find --kind guide westfall --race Human ``` ```output next forever/alliance/02-westfall # Westfall (12-17), Alliance # its next: forever/alliance/03-darkshore next forever/collectibles/pets/chicken-egg # Chicken Egg (1-60), Alliance … (the other collectible guides set in Westfall follow) ``` A guide for Humans cannot hand over to the Dwarf and Gnome guide (`… # Dun Morogh (1-13), Dwarf/Gnome only`): lint stops it. Start the next guide near the level yours ends at, and put its id in `next`: ``` next forever/alliance/02-westfall ``` Lint and playtest load Polestar's guides beside yours, so the handover is checked and played: a hand-over that does not land on our guide with something to do, or lands on one that does not apply to the character (`no Human can follow it`), is reported as stuck at the hand-over. An option with `when` that does not hold when the played guide ends is no hand-over; with none offered the guide ends there. Turn-ins in our guide of quests your guide accepted count too. ### With an AI assistant An assistant can draft guides from your own notes and routes; [PACKS.md](https://polestar.guide/docs/authors/handbook) ("With an AI assistant") explains how, and the ground rule: its ids and coordinates are guesses until `find`, lint and playtest confirm them. ### Patterns **Several objectives at once.** The goals of one step are open together: each counts as soon as it is done, in any order, and the step ends when every goal that holds it is done. The arrow leads to the first open one (click a row to aim at another). Put objectives the player works in the same area in one step: ``` step Kobolds and wolves kill 6 x10 quest 7.1 -- Kobold Vermin collect 750 x8 quest 33.1 -- Tough Wolf Meat, from the wolves ``` **An optional side chain.** Mark every goal of the side quest `optional`: it never holds a step, the player may dismiss it, and lint does not ask for its turn-in. Keep it in steps that also have a goal that holds them: a step of `optional` goals only is done at once, and the guide moves past it. ``` step Deputy Willem turnin 783 accept 7 accept 5261 optional -- a short errand to Eagan Peltskinner step Kobolds kill 6 x10 quest 7.1 turnin 5261 optional -- Eagan stands by the path ``` The turn-in, objectives and `complete` goals of a quest whose accepts in the guide are all `optional` apply only while the quest is in the log or handed in. A player who never took it doesn't see them. So a side quest's turn-in can have a step of its own, written without `optional`: the step holds and leads the arrow to the ender for a player who took the quest, and the guide passes it for everyone else. ``` step Murlocs collect 780 quest 46 collect 247826 x1 optional -- Croaky's Head: Croaky accept 91740 optional step Ridgepoint Tower turnin 91740 -- only for players who took it ``` **Leveling up before moving on.** `level <N>` holds its step until the character reaches level N. End a guide with it when the next guide's zone needs a level the route may not reach by itself: ``` {2} step Ready for Westfall level 12 ``` **A bare `kill <npc>`** (no `quest`) is a check-off: Polestar does not count the kills, so the player ticks the goal in the guide window, and until they do it holds the step, unless it is `optional`. Tie a kill that serves a quest to the objective with `quest Q.O` so the quest log counts it. --- # Community guide format > The contract between a community guide and Polestar: pack.json, the addon the compiler writes, the rules, import strings, versioning. Page: https://polestar.guide/docs/authors/community-guide-format (Polestar docs > Guide authors) The contract between a community addon and Polestar, for anyone building tools of their own. Authors who use Polestar's tools never write any of this by hand: they write `pack.json` and `.guide` files ([GUIDE_FORMAT.md](https://polestar.guide/docs/authors/guide-format)) and `polestar compile` writes the rest. The handbook is [PACKS.md](https://polestar.guide/docs/authors/handbook). > **Tip:** > Building a tool that generates guides? The simplest path is to write a > pack (`pack.json` and `.guide` files) and let `polestar lint`, > `polestar playtest` and `polestar pack` check and build it. Write the > addon described below yourself only when that is not an option. **On this page:** [`pack.json`](https://polestar.guide/docs/authors/community-guide-format#packjson) · [The addon](https://polestar.guide/docs/authors/community-guide-format#the-addon) · [TOC fields](https://polestar.guide/docs/authors/community-guide-format#toc-fields) · [Rules Polestar enforces](https://polestar.guide/docs/authors/community-guide-format#rules-polestar-enforces) · [Format 3](https://polestar.guide/docs/authors/community-guide-format#format-3) · [Format 4](https://polestar.guide/docs/authors/community-guide-format#format-4) · [Import strings](https://polestar.guide/docs/authors/community-guide-format#import-strings) · [Versioning](https://polestar.guide/docs/authors/community-guide-format#versioning) A community addon is an addon for World of Warcraft: Forever that depends on Polestar and registers guides with it. It is built from a pack: a folder with a `pack.json` and `.guide` files. In the format, every such addon is a pack; Polestar's own guides are a pack too (`Polestar_Guides`, pack id `guides`). ## `pack.json` The pack's manifest, in the root of the pack's folder. Every tool works on the pack folder given as its one argument (`polestar lint ../joe-routes`) or with `--pack <dir>`, else on the nearest `pack.json` in the current folder or a parent. ```json { "id": "joe-routes", "title": "Joe's Routes", "author": "Joe", "version": "1.2.0", "license": "CC-BY-4.0", "website": "https://github.com/joe/joe-routes", "source": "Written from my own play", "folder": "PolestarPack_JoesRoutes" } ``` | Key | Required | Value | |---|---|---| | `id` | yes | the pack id: `^[a-z0-9][a-z0-9-]{1,31}$` (2 to 32 lower-case letters, digits and hyphens, starting with a letter or digit), not reserved (below) | | `title` | yes | shown to players; at most 64 characters | | `author` | yes | shown to players; at most 64 characters | | `version` | yes | one word of letters, digits, `.`, `+` and `-`, starting with a letter or digit, at most 32 characters (`1.2.0`) | | `license` | yes | the license of the pack's guides, as an SPDX id where one exists (`CC-BY-4.0`, `CC0-1.0`, `MIT`, `GPL-3.0-only`); at most 64 characters | | `website` | no | `https://` or `http://` address; at most 200 characters | | `source` | no | where the guides come from, in the author's words; at most 200 characters | | `notes` | no | one line for the AddOns list, shown when the player points at the pack there; at most 200 characters (default "Community addon for Polestar by <author>") | | `folder` | no | the addon's folder name: 1 to 64 letters, digits, `_` and `-`, not `Polestar` and not starting with `Polestar_` (in any case); default `PolestarPack_` and the title in CamelCase (`Joe's Routes` → `PolestarPack_JoesRoutes`), or the id when the title has no letters or digits | Every value is a string on one line. A missing required field, or a value that breaks these rules, is a lint error; an unknown key is a warning; a `|` in a displayed value is a warning (it prints literally in game). The pack folder holds `pack.json`, the `.guide` files in any layout, `drafts/` (Recorder drafts, compiled only with `--include-drafts`), `dist/` (build output) and the picture files its `image` lines name (`.tga` or `.blp`, at any path inside the folder, such as `media/`). The compiler reads every `.guide` file under the folder except in `dist/`, `drafts/`, `node_modules/` and folders whose name starts with a dot. ## The addon `polestar compile` writes `dist/<folder>/` (ours: `addon/Polestar_Guides/`): ``` PolestarPack_JoesRoutes/ PolestarPack_JoesRoutes.toc Pack.lua Polestar.RegisterPack({ ... }) MapFrames.lua Polestar.RegisterMapFrames({ ... }, "joe-routes") Guides.lua one Polestar.RegisterGuide({ ... }) per guide LICENSE-DATA.txt the reference data sources the guides draw on LICENSE.txt the pack folder's LICENSE, copied as is (only when it has one) media/cave.tga each picture an `image` line names, at its path in the pack folder PolestarPack_JoesRoutes_deDE/ one texts addon per language the pack translates PolestarPack_JoesRoutes_deDE.toc Texts.lua Polestar.RegisterGuideTexts("deDE", "joe-routes", { ... }) LICENSE.txt as above ``` **Texts addons.** A pack whose `locales/<locale>/` folder holds translations (docs/TRANSLATING.md, "Guide texts") gets, beside its folder, one load-on-demand addon per language, `<folder>_<locale>`. Polestar loads the client's own once the pack's files are in, and no other: a German client never reads the French texts. Its TOC carries `## LoadOnDemand: 1`, `## Dependencies: Polestar`, `## X-Polestar-Texts: <pack id>` and `## X-Polestar-Locale: <locale>` with the generated-folder marker, and `Texts.lua` makes one call: ```lua Polestar.RegisterGuideTexts("deDE", "joe-routes", { pack = { ["Joe's Routes"] = "Joes Routen" }, -- the pack's title and notes, its guides' folders guides = { ["joe-routes/elwynn"] = { ["{npc:240} stands outside the inn."] = "{npc:240} steht vor dem Gasthaus." } }, }) ``` Each table maps a text's English, name tokens and all, to its translation; a text without one shows in English. `compile`, `install` and `dev` write and replace a texts addon folder by the same rule as the pack folder (its marker and `X-Polestar-Texts`), and remove the one of a language the pack no longer translates; `pack` puts each into the zip as a folder of its own. The file set is fixed: a new guide changes `Guides.lua`, never the file list, so `/reload` shows every change and only a pack's first install needs a restart of the game (`LICENSE.txt` is a text file the game never loads); so does the first texts addon of a language, below. Each guide's table is built inside its own function in `Guides.lua`, so Lua 5.1's constant limit applies per guide. ### TOC fields ``` ## Interface: 16001 ## Title: Polestar Community: Joe's Routes ## Notes: Community addon for Polestar by Joe ## Author: Joe ## Version: 1.2.0 ## Category: Quests ## Group: Polestar ## Dependencies: Polestar ## X-Polestar-Pack: joe-routes ## X-Polestar-Format: 3 ## X-Polestar-Needs: 0.2.5 ## X-License: CC-BY-4.0 ## X-Website: https://github.com/joe/joe-routes # Generated by `node tools/polestar.js compile` from pack.json and the .guide files. Do not edit: rebuild with that command. Pack.lua MapFrames.lua Guides.lua ``` | Field | Value | |---|---| | `Interface` | copied from `addon/Polestar/Polestar.toc` at build time | | `Title` | "Polestar Community: " and `pack.json` `title` (the title alone when it already starts so), so the AddOns list reads the addon as a community addon. Community addons built before this prefix carry "Polestar Pack: " until rebuilt; Polestar recognises both. Polestar's own menus show the title without it. Polestar's own pack (`guides`) gets no prefix | | `Author`, `Version` | from `pack.json` | | `Notes` | `pack.json` `notes`, else "Community addon for Polestar by <author>" | | `Category` | `Quests`, Polestar's category in the AddOns list | | `Group` | `Polestar`: the AddOns list shows the pack under Polestar's own entry, beside Polestar's own addons. Not written for Polestar's own pack | | `Dependencies` | `Polestar`: the client loads Polestar first | | `X-Polestar-Pack` | the pack id. Polestar lists every addon carrying it on the Community guides page, loaded or not | | `X-Polestar-Format` | the pack format (below) | | `X-Polestar-Needs` | the first Polestar version that reads that format, so an older Polestar can say which version the pack needs | | `X-License` | `pack.json` `license` | | `X-Website` | `pack.json` `website`, only when given | The comment line is the **generated-folder marker**, and with `X-Polestar-Pack` it makes the folder rule: `compile` (its output folder), `install` (`dist/<folder>/` and the folder in AddOns, where a symlink is replaced without the check) and `dev` (the folder in AddOns) write a pack folder only when it is absent, empty, or carrying the generated marker and no other pack's id. Anything else is refused: a folder without the marker as "not a generated community addon", one generated for another pack as holding that pack, with the hint to set `folder` in `pack.json`. `pack` builds a community addon's zip in memory, and `play` writes into a new temporary folder, so neither touches an existing pack folder. ## Rules Polestar enforces `Core/Guides.lua` applies these at registration; lint reports the same ones before a pack is built (`tests/packs-parity.test.js` holds the two together). 1. **Ids.** Pack ids match `^[a-z0-9][a-z0-9-]{1,31}$`; `guides`, `forever`, `lookup`, `draft`, `polestar` and `imported` are reserved. Every guide id starts with `<pack id>/`, except in Polestar's own packs: `guides` (the addon `Polestar_Guides`) owns `forever/` and `draft/`, Polestar's internal `lookup` pack owns `lookup/`, and `imported` (the guides pasted as import strings, below) owns every `<author>/` that is a valid pack id nobody reserves. 2. **No overrides.** A guide id outside its pack's prefix is refused. A pack may register one of its own ids again, which replaces that guide. An id a guide of another pack already holds is refused too ("Guide <id> was refused: <pack> already holds that id."): only an imported guide can share a prefix with a pack. 3. **Clashes.** A pack whose id is already registered is refused whole, and the problem names both addons; a pack with a reserved id is refused whole with "Pack id <id> is reserved for Polestar.". Either way the guides and map frames its files register for that id while it loads are dropped, never given to the holder, and the dropped guides are counted in the problem. A pack with a malformed id, no `format` or a required field missing is refused too ("Pack id <id> is not valid: …", "The pack is missing <field>."), and its guides are dropped without a problem each. A guide registered before its pack is refused (listed once the pack registers); one for a pack that never registers is ignored, since there is no row to list it on. 4. **Map frames.** A pack may add Era map frames for maps Polestar's lack; for a map both cover, Polestar's win whatever the load order (lint warns when the bounds differ). Frames for a pack that is not registered, or was refused, are dropped. 5. **Format.** A pack declaring a format Polestar does not read is refused whole, with the status `too-new` and "Needs Polestar <X-Polestar-Needs> or newer." ("Needs a newer Polestar." when its TOC has no `X-Polestar-Needs`). An unknown verb or a malformed field inside a known format refuses only that guide. 6. **Visible problems.** Every refusal is recorded against its pack with a kind: `pack-refused` (the pack), `guide-refused` (one guide, with its id), `no-guides` (the addon loaded but registered no guides, usually a Lua error in its files). The Community guides page shows them. 7. **Text prints literally.** Every string a pack registers is escaped once, at registration (`|` doubled), so colour and link codes do not work. A guide's ids (`id`, `pack`, `next`, `nextChoices`) are left as written. 8. **Missing guides keep their place.** Saved tabs of a guide whose pack is missing or switched off reopen in their old place when it comes back. 9. **Packs on disk.** At login Polestar lists every addon whose TOC carries `X-Polestar-Pack`, loaded or not, with a status. A registered pack is `on`, `off` (switched off on the Community guides page), `refused`, `too-new` (a newer format) or `broken` (registered no guides). One that never registered is, in this order of precedence, `too-new`, `disabled` (turned off in the AddOns list), `not-loaded` (the client did not load it: out of date, a dependency missing) or `broken`. Only guides of packs that are on are shown, searched and suggested. Suggestions come from Polestar's guides unless the player picks a pack under **Suggest guides from** on the Community guides page; only packs with Leveling guides are offered there, and Polestar's guides fill in where the chosen pack has nothing for the character. ## Format 3 The format the compiler writes for a pack whose guides have no `when` (on a step or a `next` option), `along` or `label`, and whose `level` goals have no `frac` (format 4, below). Format 2 is format 1 with the two `group` keys (a guide's and a goal's) and a guide's `reward` and `why`, marked "format 2" below; Polestar 0.2.4 and later read it. Format 3 is format 2 with **name tokens** in the texts and a guide's `names`, marked "format 3" below; Polestar 0.2.5 and later read it. A format 1 or 2 pack is the same without them and keeps loading. **Name tokens** (format 3). The game's names inside the texts a player reads (a guide's `title`, `why`, `pitch`, `pros`, `cons` and reward `text`; a step's `title` and `note`; a goal's `note` and `text`) are written `{kind:id}`: `{npc:240}`, `{object:68}`, `{item:1528}`, `{quest:176}`, `{zone:1429}` (a uiMapID), `{area:87}` (an AreaTable ID), `{spell:5487}`, `{faction:72}`, `{skill:182}` (a profession's skill line). Polestar shows each as the game names it in the client's language (Polestar.Names, the client's map and area names, the profession's translation), else as the guide's `names` give it, so an English client reads the text as its author wrote it (a text that spells a name otherwise, "Dendrite" for Dendrite Starblaze, is in the guide's `written` with the author's words). The compiler writes the tokens (GUIDE_FORMAT.md, "Names in texts"); an older Polestar would show them as written, hence the format. ## Format 4 Format 3 with a step's **`when`**: the conditions checked during play (GUIDE_FORMAT.md, "Conditions checked during play"), a step's **`along`** and **`label`** (GUIDE_FORMAT.md, "Along the way"), a `level` goal's **`frac`**: a point inside the level, and a guide's **`nextWhen`**: conditional hand-offs (GUIDE_FORMAT.md, "Conditional hand-offs"). Polestar 0.2.6 and later read it. The compiler writes a pack in format 4 only when its guides use one of them; any other pack stays in format 3, so the Polestar it needs does not change. An older Polestar would show every conditional step to every character, stop the route at every along step, count `level 12.5` done at level 12 and offer every `next` option (it ignores keys it does not know), hence the format. `when` is a list of predicates, each a table with its kind `k`, `neg = true` to turn it around, and the kind's keys; a step applies while all of them hold: | `k` | Keys | Holds when | |---|---|---| | `"level"` | `op` (`"<"`, `"<="`, `">"`, `">="`), `n`; optional `frac` (0 < frac < 1) | the character's level compares so with `n`; with `frac`, the level plus the share of it done (XP / XPMax) compares so with `n + frac` | | `"onquest"` | `q`: a list of quest ids | any of them is in the log | | `"complete"` | `q` | the quest is in the log, ready to turn in | | `"turnedin"` | `q` | the quest is handed in | | `"available"` | `q`; optional `minLevel`, `pre`, `preAll`, `closedBy` (as on an `accept`) | the quest is not in the log or done, the level is reached, one of `pre` and every one of `preAll` is done, and none of `closedBy` is in the log or done | | `"has"` | `item`; optional `n` (default 1) | the bags hold `n` or more | | `"zone"`, `"subzone"` | `name`; optional `area` | the zone (subzone) text reads as the area's name in the client's language, or as `name` | | `"bound"` | `name`; optional `area` | the bind location reads so | ```lua { title = "Back to Gornek", when = { { k = "onquest", q = { 788 } }, { k = "level", op = "<", n = 6 } }, goals = { ... } } ``` A `when` that is not a non-empty list, or a predicate of another kind or without its keys, refuses the guide. Once the route has moved past a step, Polestar stores whether its `when` held (per character, guide and step) and reads that from then on. `label` is a string, the step's name, unique in the guide. `along` is `true`, or the `label` of a later step: the route passes over the step, and its open goals are listed under the steps after it until they are done or the route reaches that labelled step. ```lua { title = "Boars on the way", along = "camp", goals = { ... } }, { title = "Goldshire", goals = { ... } }, { title = "Back at the camp", label = "camp", goals = { ... } }, ``` A `label` that is not a string or names a second step, or an `along` that is neither `true` nor the label of a later step, refuses the guide ("step N: bad label", "step N: duplicate label <name>", "step N: bad along"). `frac` on a `level` goal (format 4) is the share of the level's XP the goal asks for, a number with 0 < frac < 1: `{ t = "level", level = 12, frac = 0.5 }` is done at level 12 with XP / XPMax >= 0.5, or at any later level. A goal's `frac` outside that refuses the guide ("bad frac"); a `level` predicate's, "bad when". `nextWhen` maps a `next` option to its predicates, the same tables as a step's `when`: `{ ["joe-routes/barrens-early"] = { { k = "level", op = "<", n = 12 } } }`. Every key must be one of `nextChoices`, which the compiler writes whenever `nextWhen` is there, even for one option. Polestar offers an option only while its predicates hold, checked on the character's live state each time it lists the options; with one option offered it goes on to it without asking, with none the guide ends there. Nothing is stored. A `nextWhen` that is not a table, a key that is not in `nextChoices` or a malformed predicate list refuses the guide. ### `RegisterPack(meta)` ```lua local ADDON = ... Polestar.RegisterPack({ addon = ADDON, id = "joe-routes", format = 3, title = "Joe's Routes", author = "Joe", version = "1.2.0", license = "CC-BY-4.0", website = "https://github.com/joe/joe-routes", source = "Written from my own play", }) ``` | Field | Required | Value | |---|---|---| | `addon` | yes | the addon's folder name (the file's first vararg) | | `id` | yes | the pack id (rule 1) | | `format` | yes | `3` (`1` or `2` for a pack of that format) | | `title`, `author`, `version`, `license` | yes | non-empty strings | | `website`, `source`, `notes` | no | strings | Returns `ok, err`. Call it once, in the first file the TOC loads, before any guide. ### `RegisterGuide(def)` One table per guide; returns `ok, err`. ```lua Polestar.RegisterGuide({ id = "joe-routes/elwynn", pack = "joe-routes", title = "Elwynn Forest", faction = "Alliance", minLevel = 5, maxLevel = 10, category = "Leveling", zone = 1429, zoneName = "Elwynn Forest", next = "forever/alliance/02-westfall", author = "Joe", version = 1, steps = { { title = "Goldshire", goals = { { t = "accept", quest = 62, title = "The Fargodeep Mine", npc = 240, npcName = "Marshal Dughan", minLevel = 4, qlvl = 7, map = 1429, x = 42.11, y = 65.93, f = "e" }, } }, }, }) ``` Guide keys (the compiler writes them in this order): | Key | Required | Value | |---|---|---| | `id` | yes | the guide id, under the pack's prefix | | `pack` | yes | the registered pack id | | `title` | yes | string | | `faction` | no | `"Alliance"` or `"Horde"`; absent: either | | `races` | no | list of race file names (`"Human"`, `"Scourge"`, `"NightElf"`, …); absent: any | | `classes` | no | list of class file names (`"WARRIOR"`, …); absent: any | | `minLevel`, `maxLevel` | no | numbers | | `category` | no | `"Leveling"` (default), `"Class"`, `"Professions"`, `"Reputation"`, `"Legacy"`, `"Exploration"`, `"Collectibles"`, `"Miscellaneous"`, `"Dungeons"`; the compiler passes another name through with a warning | | `folder` | no | the guide menu folder | | `keywords` | no | list of extra search words | | `collects` | no | list of item ids the guide obtains | | `reward` | no | format 2: what the guide's goal gives, shown first in the guide menu's details, in order: `{ item = 20536, itemName = "Soul Harvester", quality = 3, choice = true }` (an item; `choice` when one of several to choose from; the name shows in the client's quality colour when the item is cached, else the compiled `quality`'s), `{ spell = 23161, spellName = "Summon Dreadsteed" }` or `{ text = "Shen'dralar reputation" }`; an entry with none of `item`, `spell` or `text` refuses the guide | | `why` | no | format 2: one line on why the goal is worth doing, shown under the reward | | `zone`, `zoneName` | no | the default zone's uiMapID and name | | `next` | no | the id of the guide that follows: one of the pack's or one of Polestar's | | `nextChoices` | no | list of guide ids offered as a route choice (the first is the default); with `nextWhen`, every option, even one | | `nextWhen` | no | format 4: `{ [<guide id>] = { <predicate>, ... } }`, an option of `nextChoices` offered only while its predicates hold (Format 4, above) | | `pitch` | no | one line for the route choice card | | `pros`, `cons` | no | lists of short lines under the pitch | | `author` | no | string; the compiler writes the pack's author when the guide names none | | `version` | no | number | | `group` | no | `true` (format 2): a goal of the guide's route that is not `optional` needs a group; the guide menu shows a "Group" chip | | `names` | no | format 3: `{ ["npc:240"] = "Marshal Dughan", ... }`, the English of every name token the guide's texts hold (a token it lacks is shown as written) | | `written` | no | format 3: `{ ["Back to {npc:3649}"] = "Back to Dendrite", ... }`, a text whose names its tokens' English in `names` would spell otherwise, with the author's words an English client reads | | `steps` | yes | list of steps, at least one | Step keys: `title` (optional), `note` (optional, player-facing), `image` (optional: `{ file = "media\\cave", w = 512, h = 256 }`, the step's picture: `file` its path in the pack's addon folder without the extension, `\` between folders, `w` and `h` its size in pixels; Polestar shows it under the step's tip, and an imported guide, which has no addon folder, shows none), `only` (optional: `{ classes = { ... }, races = { ... }, factions = { ... } }`, AND across keys, OR within; Polestar also reads an entry `"!X"` as "not X", but the compiler writes positive lists only), `when` (optional, format 4: the step's conditions checked during play, below) and `goals` (at least one). Goal keys common to every verb: `t` (the verb), `text` (display text), `note`, `optional` (`true`: never blocks the step), `only` (as on a step), `map`, `x`, `y` (0 to 100, together), `z` (optional, with them: the height of the NPC or object the point stands for, below), `f` (`"e"`: the Era map frame; absent: the live frame), `r` (arrival radius in yards), `spots` (every place the goal's target spawns, below; with `map`), `group` (format 2: the goal needs a group, below). | Verb `t` | Required | Optional | |---|---|---| | `accept` | `quest`, `title` | `npc`/`npcName`, `object`/`objName`, `item`/`itemName`, `minLevel`, `qlvl`, `pre`, `preAll`, `closedBy`, `preTitles` | | `turnin` | `quest`, `title` | `npc`/`npcName`, `object`/`objName`, `rewards = { choices = { { item, itemName, quality } }, items = { ... }, xp, money }`, `direct` | | `complete` | `quest`, `title` | — | | `kill` | `target` | `title`, `npc`, `count`, `quest`, `oi`, `spread` | | `collect` | `item`, `itemName` | `title`, `count`, `quest`, `oi`, `spread`, `from`, `fromAlso`, `fromId`, `fromAlsoId`, `fromKind`, `fromRank`, `fromFaction`, `fromNpcs`, `npc`, `npcName`, `candidates` | | `goto` | `map`, `x`, `y` | `text`, `r`, `area` | | `talk` | `npc`, `npcName` | — | | `interact` | `object`, `objName` | `title`, `quest`, `oi`, `spread` | | `use` | `item`, `itemName` | `title`, `quest`, `oi` | | `sethome` | `location`, or `candidates` | `npc`, `npcName`, `area` | | `hearth` | `location` | `area` | | `getfp` | `location` | `npc`, `npcName`, `node`, `area` | | `fly` | `location` | `area` | | `train` | — | `npc`, `npcName`, `class`, `skill`, `skillLine`, `rank`, `rankMax`, `candidates` | | `buy` | `item`, `itemName` | `count`, `npc`, `npcName`, `candidates` | | `vendor` | — | `npc`, `npcName`, `candidates` | | `level` | `level` | `frac` (format 4) | | `note` | `text` | — | | `skill` | `skill`, `level` | `skillLine` | | `learn` | `spell`, `spellName` | `skillLine`, `npc`/`npcName`, `item`/`itemName`, `candidates` | | `craft` | `spell`, `spellName` | `item`/`itemName`, `count`, `untilSkill`, `skillLine`, `reagents = { { item, itemName, count } }` | | `rep` | `faction`, `factionName`, `standing` (1 to 8) | — | | `explore` | `map`, `x`, `y` | `text` | | `achieve` | `achievement`, `achievementName` | `criteria` | The fields: | Field | Value | |---|---| | `quest`, `npc`, `object`, `item`, `spell`, `faction`, `achievement` | numeric ids | | `title`, `npcName`, `objName`, `itemName`, `spellName`, `factionName`, `achievementName`, `target` | names | | `count` | number to collect, kill or buy; on `craft`, the number of items to make | | `oi` | 1-based quest objective index (`C_QuestLog.GetQuestObjectives`) | | `minLevel` | the level an `accept` needs; `qlvl` the quest's level (number or string) | | `pre` | prerequisite quest ids, any one suffices; `preAll` every one needed | | `closedBy` | quest ids that close this one once taken or done | | `preTitles` | `{ [questId] = title }` for the quests those name | | `profLine`, `profName`, `profRank` | on any goal of a quest only characters with a profession can take: its skill line id, name and the rank it needs; the goal is hidden from characters without it | | `location` | an inn, flight point or zone name as the game shows it | | `class` | `true` on `train`: the nearest trainer of the player's class | | `skill` | a profession name; `skillLine` its skill line id | | `rank`, `rankMax` | on `train`: the profession rank (1 Apprentice to 4 Artisan; Polestar also reads a rank name or a skill cap) and its skill cap (written by the compiler, not read by Polestar) | | `level` | on `level`: the level to reach; on `skill`: the skill to reach | | `frac` | on `level` (format 4): the share of the level's XP to reach, 0 < frac < 1 (above) | | `untilSkill` | on `craft`: craft until the profession reaches this skill | | `reagents` | `{ { item, itemName, count } }` | | `standing` | 1 Hated to 8 Exalted | | `criteria` | an achievement's criterion index | | `z` | the height (world z, yards) of the NPC or object the goal's `x`,`y` stands for, so the walking route ends on its floor (an Undercity quarter rather than the street above it). Polestar 0.2.4 and later pass it to the walking engine while the arrow leads to that point, and ask again without it when the route found with it fails or ends more than 30 yards above or below it. A spot (`spots`) and a smart target's candidate (`candidates`) may carry their own `z`, which Polestar 0.2.5 and later pass the same way when the arrow leads there (#180). The compiler fills it in (GUIDE_FORMAT.md, "Heights"); a hand-written pack may leave it out. Older Polestar ignores it, so it does not change the format | | `area` | the AreaTable area ID (`C_Map.GetAreaInfo`) of the place a `sethome`, `hearth`, `fly` or `getfp` location or a `goto` label names. Polestar 0.2.5 and later complete a `hearth` or `fly` when the zone or subzone text is that area's name in the client's language, accept a `sethome` bind location that reads so, count a `goto` arrived when the player goes indoors in that subzone (a cave or mine past its mouth; never for a zone), and show that name in place of the English one. The compiler fills it in (GUIDE_FORMAT.md, "Places by ID"); without it the goal matches by its English name. Older Polestar ignores it, so it does not change the format | | `node` | on `getfp`: the taxi node ID (`C_TaxiMap` `nodeID`) of its flight point. Polestar 0.2.5 and later count the goal done once the flight map lists that node as known, instead of comparing names. Filled in like `area`; older Polestar ignores it | | `spots` | spawn places `{ { x, y, z, r, n, alt } }`: centre in the goal's map and frame, its height (optional, see `z`), radius in yards, spawn count; `alt = true` for another place the target spawns, which the arrow takes only when the player moves on to it (the world map marks it) | | `spread` | `true` with `spots`: an area objective, searched spot by spot | | `from`, `fromAlso`, `fromKind`, `fromRank`, `fromFaction` | a `collect`'s main source: name, a second source of the same kind dropping it at 50% or more, `"npc"` or `"object"`, rank (1 elite, 2 rare elite, 3 boss, 4 rare), faction `"A"`, `"H"` or `"AH"` | | `fromId`, `fromAlsoId` | the ids of `from` and `fromAlso` (of kind `fromKind`): Polestar names them in the client's language (`Polestar.Names`), keeping `from`/`fromAlso` where it has no name; older Polestar ignores them | | `npc`, `npcName` | a `collect` whose guide names the NPC who hands the item over (`npc <id>`), for an item nothing drops: the target button targets them first. The farm spot a `collect … nearest` goal settles on carries the same pair | | `fromNpcs` | a `collect`'s source creatures where the goal stands: `{ { npc, npcName } }`, the one its point belongs to first, then the other likely sources there, at most 5 (GUIDE_FORMAT.md, "What the compiler fills in"). Newer Polestar gives them to the target button, named in the client's language by their ids, before the item's own droppers from the quest database, whose drop chances rank them over the whole world. Older Polestar ignores them, so it does not change the format | | `candidates` | smart targets: `{ { npc, npcName, map, x, y, z, f, faction, races, classes, lvl, rate, spawns } }` (`z` optional, see `z`); Polestar picks the nearest usable one at runtime | | `rewards` | `{ choices = { { item, itemName, quality } }, items = { ... }, xp, money }` (money in copper) | | `direct` | `true` on a `turnin`: the quest is handed in straight from the giver's window and never enters the quest log, so the goal needs no `accept` before it and carries no objectives. Polestar counts it done on the hand-in itself and stores that, so a repeatable stays done after a reload | | `escort` | `true` on the accept, `complete` and objective goals of an escort quest: the guide window says under the goal that the NPC may have to respawn (GUIDE_FORMAT.md, "Escort quests"). Older Polestar ignores it | | `group` | format 2: the goal needs a group, shown under it in the guide window: `{ kind = "elite", rank = 1 }` (rank 1 elite, 2 rare elite, 3 boss: "Elite: group advised"), `{ kind = "dungeon", name = "Dire Maul" }` ("Dungeon: Dire Maul"), `{ kind = "raid", name = "Molten Core" }` ("Raid: Molten Core"), `{ kind = "group", size = 3 }` ("Group of 3 advised"; without `size`, "Group advised"). The compiler derives it or takes the author's `group [N]` (GUIDE_FORMAT.md, "Group content"); Polestar shows nothing for a kind it does not know | Polestar 0.1.0 reads every verb above; 0.2.4 and later read the `group` keys; 0.2.4 and later read `z`; 0.2.5 and later read `area`, `node` and `direct`. ARCHITECTURE.md ("Guide data") describes when the Engine counts each goal done. ### `RegisterMapFrames(frames, packId)` ```lua Polestar.RegisterMapFrames({ era = { [1429] = { c = 0, left = 1535.417, right = -1935.417, top = -7939.583, bottom = -10254.166 }, }, }, "joe-routes") ``` The Era world bounds of every map the pack's guides place a goal or a candidate on, where the reference data has them: `c` the continent, `left`/`right` world Y, `top`/`bottom` world X. For a map Polestar already covers, Polestar's bounds win (rule 4). Call it after `RegisterPack`: the frames of a pack that is not registered are dropped. ## Import strings One compiled guide as one line of text, for a player to paste on Polestar's Import page instead of installing an addon (GUIDE_PACKS.md, "Import strings"). `polestar export <file.guide>` writes it (`tools/lib/pack/importstring.js`); `addon/Polestar/Core/Import.lua` reads it. ```text !PS1!<checksum>!<body> ``` | Part | Value | |---|---| | `!PS1!` | the string format, version 1. A later format gets another number; Polestar refuses one it does not know with "This import string needs a newer Polestar." | | `<checksum>` | the Adler-32 of the payload (the JSON below, as UTF-8 bytes), 8 hex digits | | `<body>` | the payload, compressed with zlib (RFC 1950) and written in base64 (`A`–`Z`, `a`–`z`, `0`–`9`, `+`, `/`, `=` padding) | Whitespace anywhere in a pasted string is dropped first (a chat window may wrap it). The payload is JSON: ```json { "format": 3, "license": "CC-BY-4.0", "guide": { "id": "yendi/cozy-sleeping-bag", "title": "Cozy Sleeping Bag", "...": "...", "steps": [ ... ] }, "frames": { "1429": { "c": 0, "left": 1535.417, "right": -1935.417, "top": -7939.583, "bottom": -10254.166 } } } ``` | Key | Required | Value | |---|---|---| | `format` | yes | the guide data's format (above): 4 when a step has `when`, else 3; Polestar refuses a format it does not read | | `license` | yes | the license of the guide, from the pack's `pack.json` | | `guide` | yes | one guide exactly as `RegisterGuide(def)` takes it, without `pack`: the keys above, numbers rounded as `Guides.lua` writes them, `preTitles` with the quest ids as the object's keys | | `frames` | no | `RegisterMapFrames`'s `era` table for the maps its goals use, by uiMapID. Polestar takes a frame only for a map the guide's goals or their smart targets stand on, and only where no one (Polestar, a community addon, an earlier import) has registered one | Polestar reads it as data only. The client's own decoders (`C_EncodingUtil.DecodeBase64` and `DecompressString`, the ones the walking maps use) unpack it; Polestar parses the JSON itself (objects, arrays, strings, numbers, `true`, `false`; no `null`, nested 12 deep at most) and builds the guide field by field from the keys this page lists, each with its type. A key it does not know refuses the string, naming the key ("This import string holds a field Polestar does not read (guide.steps[3].goals[1].onLoad)."). Nothing in a string is ever run: the reader never hands its text to `loadstring` or anything like it. Then the guide meets the rules above, as a community addon's would, plus: - at most 50,000 characters in the string, 256 KB of payload, 60 steps, and 4,096 bytes in any one text or key (a longer one is refused, naming it, before any text is filled in; `export` refuses it too); - its id is `<author>/<name>`, under no reserved id and no id of a community addon the player has installed (registered or only listed); - `next` and every `nextChoices` entry name one of Polestar's guides (`forever/`, `draft/`) or a guide already imported; - `Guides.Validate` passes (the message is the Community guides page's: "Guide <id> was refused: <reason>."). A refused string saves nothing. An accepted one is kept account-wide in `PolestarDB.imports[<guide id>]` as its payload, and registered at every login through the same checks under the reserved pack `imported`. A guide's `version` (a number) against the stored one's decides Import, Update (higher) or nothing (equal or lower). Imported guides are listed in the guide menu as **Imported** under Community guides, credited "By <author> · Imported · <license>", never on the Community guides page, and never suggested. ## Versioning - The format number changes when a verb, a field or a field's meaning is added or changed. Polestar ignores keys it does not know; an unknown verb refuses the guide. - Polestar keeps reading every format it has shipped, so a published pack keeps working when Polestar updates. - The compiler writes the first Polestar version that reads the pack's format into the TOC as `X-Polestar-Needs`. Format 1 is read by Polestar 0.1.0 and later, format 2 (the `group`, `reward` and `why` keys) by 0.2.4 and later, format 3 (name tokens) by 0.2.5 and later, format 4 (a step's `when`, `along` and `label`, a `level` goal's `frac`, a guide's `nextWhen`) by 0.2.6 and later. - A pack in a format this Polestar does not read registers nothing; the Community guides page shows it as `too-new` with "Needs Polestar <version> or newer." (rule 5). --- # Translating > The languages and their status, the locale file, formats, the glossary, the i18n commands, and adding or reviewing a language. Page: https://polestar.guide/docs/authors/translating (Polestar docs > Guide authors) Polestar follows the game's language: a German client reads Polestar's interface in German, and any text without a translation in English. The translation tools are adapted from the translated names database (@moust4ki), GPL-3.0. ## Languages `node tools/polestar.js i18n status` lists every language with how much of it is translated (`--markdown` prints the table for the README and release notes). The list, with each language's status and translators, is `tools/lib/i18n/locales.js`. - **reviewed**: written or checked by a native speaker. The tools never fill or rewrite its translations. German (`deDE`, thecodingcortex), Latin American Spanish (`esMX`, CDVolvik), French (`frFR`, Yendi). - **ai**: made by a machine. On that client, Options > About says so and links to the Discord. Spanish of Spain (`esES`), Korean (`koKR`), Brazilian Portuguese (`ptBR`), Russian (`ruRU`), Chinese (`zhCN`, `zhTW`). Spain's and Latin America's clients use different words for game terms (mazmorra, calabozo), so `esES` and `esMX` are separate files. English clients (`enUS`, `enGB`) read the English text. ## The file Each language has one file, `addon/Polestar/Locales/<locale>.lua`, and one for the optional Recorder's few chat lines, `addon/Polestar_Recorder/Locales/<locale>.lua`, written the same way: ```lua -- German (deDE). ... local _, ns = ... if not (GetLocale and GetLocale() == "deDE") then return end local L = ns.L -- Core/Commands.lua L["Toggle guide window"] = "Guide-Fenster ein-/ausblenden" -- L["Next step"] = "" ``` - The key, between `L[` and `]`, is the exact English text the code shows. Leave it byte for byte as it is; translate the right-hand side only. - A line starting `-- L[` is not translated yet and shows in English. To translate it, remove the `-- ` and write the translation between the quotes. - Lines are grouped under the file that first uses them (`-- Core/Commands.lua`), so you can see where a text appears. Your own comment lines and group headers stay as you wrote them. - A key `"context: text"` (`"boss: Chest"`) is one meaning of a word: translate the text after the colon, in that meaning. - The block at the end, `-- No longer in the code (its English changed or it went away): reuse or delete.`, keeps your translations of texts the code no longer has, commented out. When the English of a text changed, its new key is in the file as a `-- L[...] = ""` line: copy your old translation there, adapt it, and delete the old line. ## Formats Keep every `%s`, `%d`, `%.1f` of the key, of the same kind, in the same order. If the sentence needs another order, number them all: `"%2$s niveau %1$d"`. Keep `|4singular:plural;` (translate both forms), `|cAARRGGBB…|r` colours and `|T…|t` textures. In a text with a `%s` or `%d`, write a percent sign `%%`. ## Game terms and the glossary Where the game names something itself, Polestar shows the game's word and there is nothing to translate: reputation standings, item qualities, the Alliance and the Horde, gear slots, the Dungeon Journal. For the rest, use the game's vocabulary. `tools/lib/i18n/glossary/<locale>.json` holds about forty terms (quest, step, flight master, hearthstone, dungeon…) with the word chosen for that language: the game client's own word first, then the reviewed translators' choice. `i18n check` warns where the translation of a text holding one of those terms does not use the glossary's word. A warning is a question, not an error: fix the line, or keep your wording where it reads better. ```json "flight master": { "term": "Flugmeister", "client": "MINIMAP_TRACKING_FLIGHTMASTER" } ``` `term` is the word; `match` (optional) lists the forms that count, compared without case or accents anywhere in the translation (`["annehm", "angenommen"]`); `client` names the game's string the word comes from; `note` is any remark. The English terms are `TERMS` in `tools/lib/i18n/glossary.js`. The game's strings (Blizzard's GlobalStrings) are not in the repository: download them for your language from `https://<tables>/db2/GlobalStrings/csv?build=<build>&locale=<locale>` into `data/sources/<tables>/` (ignored by git) when you need them. ## Commands - `node tools/polestar.js i18n sync [<locale>...]` adds every text the code gained to the file, commented out at the end of its file's group, and moves translations of texts the code lost to the block at the end. It never changes a line that holds a translation. A language named that has no file gets one, loaded from `addon/Polestar/Core/Core.xml` (a new Recorder file goes in `Polestar_Recorder.toc` by hand). Without a locale it updates every existing file. It covers Polestar and the Recorder; `--addon Polestar_Recorder` (or `Polestar`) limits it, and `status`, `keys` and `import` to that one (Polestar's by default). - `node tools/polestar.js i18n check [<locale>...]` lists each language's translated and missing counts and fails on a file Lua cannot load, a stale key (a translated text the code no longer has, outside the end block), a key set twice, or a translation whose formats differ from the English. Missing translations are fine. CI runs it (`npm run i18n:check`), and `npm test` runs the same checks (`tests/i18n.test.js`). - `node tools/polestar.js i18n status` prints the table of languages. - `node tools/polestar.js i18n keys` lists every key with the files and lines that use it. - `node tools/polestar.js i18n import <locale> <file.lua>...` merges translations written elsewhere: a file that returns `{ ["English"] = "translation" }`, sets `L["English"] = "..."`, or calls `ns.AddTranslations` (the translated names database's layout). It fills only texts not translated yet, refuses a broken format, and puts texts the code lacks in the end block. - `node tools/polestar.js i18n fit [<locale>[=<file>]...]` lays out every preview scene and every Options page in English and each language, and lists the translated text the window would cut with an ellipsis or let cross its edge (`deDE=my-deDE.lua` checks a file of your own). Write your translation as long as it needs to be: the layout makes room (labels and descriptions wrap, controls size to their text), and a text this still lists is a layout bug to report, not yours to shorten. `--slack 1.15` measures about as wide as the game's own font. - `node tools/polestar.js i18n leaks [<locale>...]` runs the addon in each language and lists the English it leaves on screen, grouped by where it came from ("English left on screen" below). `--scene guide,options` runs only those scenes, `--guide <id>,...` puts other guides in the guide window, `--json` prints one document, `--update-baseline` rewrites the baseline (below). ## For developers Write every player-facing text as a literal `L["..."]` (or `ns.LC("context", "text")`) where it is used, so `i18n keys` finds it. After adding, changing or removing texts, run `node tools/polestar.js i18n sync` and commit the locale files with the change: a stale key fails `npm test`. A text looked up through a variable (`L[category]`) must be listed in `DATA_KEYS` in `tools/lib/i18n/keys.js` (the Dungeons attunement notes are read from `tools/lib/codex/attunements.json` there); a generator writes its prose as literal keys (`talents build`: the plan notes in `Talents/Builds.lua`). Data that names a game thing carries its id, never its English name alone, so the display can ask `Polestar.Names` for it. A game term the client names (`ITEM_QUALITY3_DESC`, `FACTION_HORDE`…) is read from the client, not put in `L`, and its English value goes in `tests/lua/wow_stub.lua`. Tests that need a translated client fake a language Polestar does not ship: `fakeLocale('itIT', { ... })` (`tests/helpers/locale.js`). ## English left on screen `node tools/polestar.js i18n leaks` checks that nothing English reaches the screen on a client in another language, so a new feature cannot add English unnoticed. It runs the addon on the client stub (`tests/lua`) in each language with the shipped translations, names addon and guide texts, and has the client answer in "its language": every name the client itself gives (quest titles, item, zone, map, area, spell, faction, class and race names, the player's name) comes back as a placeholder holding no word. Scenes then drive the windows: the guide window step by step with every tooltip, all guides (both with every step shown, whatever class, race or faction it is for), the welcome, the picker, Options, Lookup, Dungeons, Rares, talents, the journey planner, Polestar's tooltip lines, every slash command, the world map and alerts, and the Recorder. Every text the addons put up is recorded (font strings and buttons, tooltips, chat, popups, menus) with its scene and the line that set it. A word of three or more Latin letters is English left on screen unless it is the language's own or `tools/lib/i18n/leaks-allow.json` allows it: - **The language's own words.** Russian, Korean and Chinese have none in Latin letters. German, Spanish, French and Portuguese learn the words of their real translations (interface strings and guide texts), after cutting what is the same in every language (products, slash commands and their arguments, tokens, formats): a translation that equals its English, or copies most of it, teaches nothing. - **Names the client gave.** Every name `Polestar.Names` returned in the run is the client's, in whole and by its words. - **The allow list**: product and people's names (Polestar, Discord, TomTom, the font credits...), terms every client shows in English (XP, PvP, Shift, Ctrl+C), patterns for links, files, versions, slash commands with their documented arguments (`slashArguments` and every registered command; the prose after one is checked), guide ids and format directives, and per language the names and words it writes as English does (Uldaman; German Navigation). What a scene types (a search, a command's arguments) does not count where a text repeats it. Each finding names its source: - **interface string not translated**: a key the language's file leaves empty (`i18n sync`, then translate it); - **guide text not translated**: a guide text its texts file leaves empty (`i18n guides sync`); - **name missing from the names pack**: `Polestar.Names` was asked and had no name, so the guide's English showed (`i18n names`); - **English name, Polestar.Names not asked**: the code shows a name from a guide or the data without asking `Polestar.Names` for it by its id; - **English a translation keeps**: the words are ones a translation of the language writes as in English (a Forever-only place such as Hyjal Summit); - **English in the code**: a literal or a data text that does not go through `L`. `tools/lib/i18n/leaks-baseline.json` lists, per language, what cannot be fixed in Polestar yet, each with a reason and the scenes it shows in: names as `"kind:id"` (`no-source`: no source of `i18n names` has it, mostly Forever's own NPCs, objects and items, which the client shows once the player has seen them; `same-as-english`: every source names it as in English, which `i18n names` records in `data/local/names-same-as-english.json` for the baseline), and texts as `"text:<the text>"` whose English a translation keeps (`kept-english`). A text whose only English is such is no finding. It fails (exit 1) on any finding, on a scene that stops with an error, and on a baseline entry that no longer shows in English in scenes that all ran (so the file only shrinks: remove the entry, or run with `--update-baseline`, which also adds the names and kept texts a new guide leaves in English, and never takes English from the code or an untranslated string or guide text). `npm test` runs a part of it (`tests/i18n-leaks.test.js`: Russian and Simplified Chinese; the guide window on three guides, Options, the picker, and Lookup, Dungeons and Rares where the Codex and quest database are built), and plants English to show the check finds it: an interface string "translated" as its English, English the code writes out, dropped guide texts (a paladin's among them) and prose after a slash command. Every scene needs the Codex and the quest database built (`codex build`, `questdb build`): without them the addon is an incomplete install with its own warnings, so the scenes skip, as on CI; run `i18n leaks` before a pull request that changes what the addon shows. A text that is right to show in Latin letters goes on the allow list with the reason in its group, never to make a finding go away. Developer output stays English on purpose: the guide lines `/polestar where` prints and the details block of a bug report, both read by maintainers, are on the allow list. ## Game names Names of quests, NPCs, objects, items, instances, dungeon encounters, factions and flight points are not translated by hand: they are the game's own. A client in another language reads them from the client where it has them (quest titles, item names) and from Polestar's names addon of its language, `Polestar_Names_<locale>`, loaded only on that client. A name no source has stays English. The client is the truth: a name it shows in play (an NPC targeted, moused over or talked to, a quest-giving object opened) is kept, per language, and shown from then on. docs/ARCHITECTURE.md, "Names", has the details. - `node tools/polestar.js i18n names [<locale>...]` rebuilds the addons. Per id the first source with a name wins: the client's own tables in that language (the game-table export), the Forever web database in that language (what is cached under `data/sources/<web-db>/names`), the community names database (cloned into `data/sources/<names-db>` at the commit pinned in `tools/lib/i18n/names.js`, every file checked against its sha256) and the Era quest database's `db/<locale>` (the clone `data build` uses). It keeps only the ids the compiled guides, the quest database (`questdb build`, or `--questdb <dir>`), the Codex's data (`codex build`, or `--codex <dir>`) and the travel data name. A name equal to the English one is not stored (a later source's translation wins), nor is one marking unused content (`[PH]`, `(DNT)`...). The client tables come from the newest build that has them all in English and every language; without one the build stops (`--no-tables` leaves them out on purpose). The web database names are read from the cache in `data/sources/<web-db>/names/`, and without it that source is empty. `--offline` reads only the caches, `--no-<quest-db>` leaves the community names database out. It prints, per language, how many ids of each kind have no name. Commit the folders it writes. - A wrong name is fixed at its source: in the client (it changes there), in the community names database (tell Yendi, then move the pin to his new commit and rebuild) or, for one only the Era quest database has, in the Era quest database. - To move the pin, read what changed in Ding's `Ding/DB/`, then set the commit, version and sha256s of `DING` in `tools/lib/i18n/names.js`; a file that differs from its pin stops the build. - A new language needs its the web database path (`LOCALE_PATHS` in `tools/lib/codex/<web-db>.js`, for the cache and the packs' credit), a the community names database file and `DING` pin if Ding has it, its AddOns-list text (`tools/lib/i18n/toc.js`) and the folder's entry in the release list (`tools/lib/dsl/project.js` takes every locale of `locales.js`). ## The AddOns list The game's AddOns list shows each addon's title and notes in the client's language from its TOC's `## Title-<locale>` and `## Notes-<locale>`. Every Polestar addon's are written once in `tools/lib/i18n/toc.js` (Polestar and Codex stay as they are); the generated TOCs take them from there, the hand-written ones (Polestar, Polestar_Nav, Polestar_ItemDB, Polestar_Recorder) carry the same lines, and `tests/i18n-toc.test.js` checks that every TOC under `addon/` has all nine and that they match. ## Guide texts A guide's own words (its title, why and route-choice lines, each step's title and tip, each goal's note and label) are translated per pack, in the pack's `locales/` folder: `guides/locales/<locale>/` for Polestar's own, one file per guide at the guide's path (`forever/alliance/02-westfall.lua`), plus `_pack.lua` for the pack's own texts (its title and notes, its guides' menu folders). A file returns the English of each text with its translation: ```lua return { -- Step 1: Sentinel Hill -- {npc:234} Gryan Stoutmantle · {npc:821} Captain Danuvin ["{npc:234} and {npc:821} stand at the top of the stone tower."] = "{npc:234} und {npc:821} stehen oben auf dem Steinturm.", ["Fill the vial at the well"] = "", } ``` - **Names are not translated.** The compiler writes the game's names inside a text as tokens, `{npc:234}` (kinds: npc, object, item, quest, zone, area, spell, faction, skill), and the game shows each in the client's language. The comment above the line lists them with their English. Keep every token of the English, as many times, wherever the sentence needs it; add none. A text that is only names (a step titled after its NPC) has no line. - A token marked `(no name in this language: may be words)` is an object no source names in your language (a district's sign, a tavern): the game would show it in English. Write its name in your words instead; `i18n guides check` accepts the translation without that token. - A name the text uses in the English plural stays words ("Harvest Watchers"): the comment `-- plural, as words: Harvest Watchers = {npc:115} Harvest Watcher` gives its NPC. Translate the plural yourself from the game's singular name (Polestar_Names_<locale>, `i18n names`), or, where the game has no name for it in your language, write the singular's token in the translation: `"Bandidos ({npc:251918})"`, `"{npc:251918} ×8"`. A token of that line is allowed though the English has none. - `""` is not translated yet: the English shows. Keep the key byte for byte. - Keep the line breaks (`\n`) of the English. - `-- No longer in the guide (its English changed or it went away)` heads the translations whose English the guide lost, commented out; `i18n guides check` names the new English of a changed one where it can tell. Copy the translation to the new line, adapt it, and delete the old one. - The files are written whole by sync: comments you add are rewritten. The compiler puts each language's translations into the pack's texts addon for it, `<pack folder>_<locale>` (`Polestar_Guides_deDE`), which only that client loads, on demand (docs/PACK_FORMAT.md, "Texts addons"). Commit the locale files and the texts addons `compile` writes. - `node tools/polestar.js i18n guides sync [<locale>...]` writes every guide's file and `_pack.lua` for each language named (without one: each the pack has a folder for): every text in reading order, the translations kept, the lost ones moved to the end. `--pack <dir>` names another pack. - `node tools/polestar.js i18n guides check [<locale>...]` fails on a file Lua cannot load, a translation that leaves out or adds a token or a line break, a stale translation, or a file no guide has. `lint` and `compile` warn about the same, and leave a broken translation out (the English shows). - `node tools/polestar.js i18n guides stats` sizes the work: the texts that need words, with their words and characters, in all and per guide folder, and how many names the compiler made tokens. ## Adding a language Add it to `LOCALES` in `tools/lib/i18n/locales.js` with its status and translators (and to `ns.AI_LOCALES` in `addon/Polestar/Core/Init.lua` when its status is `ai`), then run `node tools/polestar.js i18n sync <locale>`. ## Reviewing an AI-made language Play with it, correct what reads wrong, and open a pull request that also sets its `status` to `"reviewed"` with your name in `translators` (`tools/lib/i18n/locales.js`) and removes it from `ns.AI_LOCALES` (`addon/Polestar/Core/Init.lua`). --- # Writing guides with an AI agent > The polestar-guide-pack skill: the ground rules and workflow an AI agent follows to write, fix and build a pack's guides. Page: https://polestar.guide/docs/authors/agent-workflow (Polestar docs > Guide authors) A community addon is built from a pack: a folder with a `pack.json` and `.guide` text files. Polestar's tools check the guides against the game's data, play them to the end without the game, and build the addon. The `polestar` command comes from a Polestar clone (`npm link` in it); without it, run `node <polestar clone>/tools/polestar.js <command>` instead. Run every command from the pack's folder. The guide format, every line of it: [references/guide-format.md](https://github.com/fitzforge/polestar/blob/next/skills/polestar-guide-pack/references/guide-format.md). Read it before writing a guide. ## Ground rules - **An id or a coordinate is a guess until `find`, `lint` and `playtest` confirm it.** Look up every quest, NPC, object and item id, every inn and flight point name and every guide id with `polestar find` before you write it. Never write one from memory: ids in this game differ from other versions of it. When `find` has no match, say so to the author instead of inventing a value. - **Leave out what the data fills in.** `accept 7` is enough: the compiler adds the title, the quest giver and the coordinates. Type coordinates only for `goto` and `explore`, or for a place the data does not know. - **Routes a player can do alone.** A leveling guide never requires an elite, a dungeon or a group quest: lint stops required elite work. Group content goes in as an `optional` goal with the tip `<Name> is elite: grouping up is advised.` - **The author's own material only.** Write from the author's notes, routes they played (`polestar record`) or guides they wrote. Never copy text, step lists or routes from guides you did not write, Polestar's own guides included: hand over to them with `next` instead. - **Pack naming.** `pack.json`'s `title` is the pack's own name (`Joe's Routes`), one that cannot be taken for Polestar's own addons. The build titles the addon "Polestar Community: Joe's Routes" and groups it under Polestar in the game's AddOns list; the addon page should say the same: a community addon for Polestar, by its author. Every guide id starts with the pack id and a slash (`joe-routes/westfall`). ## Workflow 1. **Start the pack** (skip when `pack.json` exists). The folder must be empty or missing: ```sh polestar new joe-routes --id joe-routes --title "Joe's Routes" --author Joe --yes cd joe-routes ``` It writes `pack.json`, `guides/example.guide` (a guide that lints and plays: replace it), README, LICENSE and editor and CI files. `polestar doctor` checks Node, Lua and the reference data when a command fails for want of them. 2. **Look up every id and place**, as JSON: ```sh polestar find "Kobold Camp Cleanup" --kind quest --json # the quest, its giver, turn-in and objectives polestar find 7 --kind quest --json # a quest by id polestar find "Kobold Vermin" --kind npc --json # an NPC or mob polestar find --kind inn --faction Alliance # names sethome and hearth take polestar find --kind flight --faction Alliance # names getfp and fly take polestar find westfall --kind guide --race Human # Polestar guides to hand over to with next ``` A number matches every kind with that id (`find 783` prints quest 783, NPC 783 and item 783): add `--kind`. Each result's `line` is a guide line ready to paste. A quest's `objectives` list each objective's `index` (the `n` of `quest <id>.<n>`, numbered as the quest log lists them) and the `id` of the mob, item or object it needs: use that id in the `kill`, `collect` or `interact`, not one found by name (a name search for "Mottled Boar" also returns Dire and Elder Mottled Boars). 3. **Write the guide** in `guides/<name>.guide` with the ids found. Keep a step to one place or one batch of work. A step is done when every goal in it that is not `optional` is. 4. **Lint until it reports no errors and no warnings:** ```sh polestar lint --format json ``` Each diagnostic has `file`, `line`, `severity`, `message` and often a `hint` saying how to fix it. `"ok": true` only means no errors: a wrong objective number (`quest 788.2` for a quest with one objective) is a warning, and playtest still passes. Fix every warning too, or tell the author why one stays (new Forever content the data does not know yet). Aim for `"errors": 0, "warnings": 0`; run lint again after every change. 5. **Playtest until every guide plays to the end:** ```sh polestar playtest polestar playtest --filter westfall --class Mage # one guide, one class ``` Every line must read `ok`. A `stuck ... at step N` line names the goal the simulated character could not finish: a wrong id, an objective number, a goal for a quest it never got, a place it cannot reach. Fix it and run lint and playtest again. 6. **Try it and build it.** `polestar play` opens the real addon in a browser with the pack loaded; `polestar install` copies the pack into the game, and `polestar dev` rebuilds it there on every save. When lint and playtest pass: ```sh polestar pack # writes dist/<folder>-<version>.zip ``` Raise `version` in `pack.json` for each release. **One small guide** (a quest chain, an item, a mount, an errand; at most 60 steps) can go out as an import string instead, a line players paste on Polestar's Import page (`/polestar import`) with nothing to install: ```sh polestar export guides/cozy-sleeping-bag.guide > cozy.txt ``` `export` lints the pack first and refuses a guide with errors; the string carries the guide and the pack's `license`. Raise the guide's own `version` header with each new string: it decides Import or Update in the game. A `next` must lead to one of Polestar's guides or to a guide the player imports first. A route or a set of guides stays a community addon (`polestar pack`). ## Example A short guide, every id from `polestar find`, that lints clean and plays to the end (write your pack id in place of `joe-routes`): ``` guide joe-routes/northshire title Northshire Valley faction Alliance race Human levels 1-4 zone Elwynn Forest step Deputy Willem accept 783 -- He stands at the abbey gate turnin 783 accept 7 step Kobold camp tip Pull one kobold at a time. kill 6 x10 quest 7.1 step Back to the abbey turnin 7 ``` `quest 7.1` ties the kills to the quest's first objective, so the guide window counts them from the quest log. A `kill` without it is a check-off the player ticks by hand. ## When something is unclear - `polestar help <command>` lists every option of a command. - Polestar's docs in the clone: `docs/GUIDE_PACKS.md` (what a pack is and how to publish one), `docs/GUIDE_FORMAT.md` (the full format and every lint check), `docs/GUIDE_CHEATSHEET.md` (every line on one page), `docs/PACKS.md` (the pack handbook, with every lint message and its fix) and `docs/PACK_FORMAT.md` (pack.json and the built addon). --- # Slash commands > Every /polestar command and its help line, from the addon’s command registry. Page: https://polestar.guide/docs/reference/commands (Polestar docs > Reference) Polestar's slash commands, as the addon registers them, with the help line `/polestar help` prints for each. `/pole` works wherever `/polestar` does, and `/polestar` on its own shows or hides the guide window. With the gamepad interface on, the game's chat box cannot run addon commands safely, so Polestar registers none: the key bindings and the minimap button open everything instead. ## /polestar | Command | What it does | Defined in | |---|---|---| | `/polestar` | Show or hide the guide window | | | `/polestar help` | List every command in chat | | | `/polestar import` | Open the Import page; import clear / import delete <id>: remove imports | [Core/Import.lua:648](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Import.lua#L648) | | `/polestar show` | Show the guide window | [Core/Commands.lua:46](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L46) | | `/polestar hide` | Hide the guide window | [Core/Commands.lua:47](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L47) | | `/polestar guides` | Choose a guide | [Core/Commands.lua:48](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L48) | | `/polestar options` | Open settings | [Core/Commands.lua:49](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L49) | | `/polestar debug` | Toggle debug output | [Core/Commands.lua:50](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L50) | | `/polestar next` | Look at the next step (skips nothing) | [Core/Commands.lua:55](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L55) | | `/polestar prev` | Look at the step before | [Core/Commands.lua:59](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L59) | | `/polestar skip` | Skip the step shown, for good (the window offers the undo) | [Core/Commands.lua:63](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L63) | | `/polestar reset` | Clear ticks and skips for the current guide | [Core/Commands.lua:67](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L67) | | `/polestar guide` | Switch to a guide by id | [Core/Commands.lua:73](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L73) | | `/polestar status` | Show the current guide and step | [Core/Commands.lua:90](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L90) | | `/polestar tabs` | List the open guide tabs | [Core/Commands.lua:113](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L113) | | `/polestar tab` | Switch to guide tab <n> | [Core/Commands.lua:127](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L127) | | `/polestar close` | Close the current guide tab | [Core/Commands.lua:137](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L137) | | `/polestar path` | Choose (or change) where to level next | [Core/Commands.lua:146](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L146) | | `/polestar welcome` | Show the welcome again | [Core/Commands.lua:152](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L152) | | `/polestar where` | Print your map and position as guide lines | [Core/Commands.lua:159](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L159) | | `/polestar report` | Report a problem with the step on screen | [Core/Commands.lua:170](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L170) | | `/polestar discord` | The invite to the Polestar Discord | [Core/Commands.lua:171](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L171) | | `/polestar packs` | Open the Community guides page | [Core/Commands.lua:173](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L173) | | `/polestar gamepad` | Open the Gamepad page: button names and bindings | [Core/Commands.lua:174](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L174) | | `/polestar arrow` | Waypoint arrow: show, hide, reset | [Nav/Nav.lua:556](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Nav.lua#L556) | | `/polestar way` | Point the arrow at x y on your current map (no argument clears it) | [Nav/Nav.lua:585](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Nav.lua#L585) | | `/polestar route` | Show the travel route to the current target | [Nav/Travel.lua:2216](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Travel.lua#L2216) | | `/polestar near` | Point the arrow at the nearest trainer, class trainer, repair, reagents, vendor, innkeeper, bank, auction house, flight or stable master | [Nav/Nearby.lua:445](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Nearby.lua#L445) | | `/polestar skipleg` | Skip the travel route's current leg (a Hearthstone, teleport, flight, ride or portal: plan the rest without it; a walk or lift: mark it done) | [Nav/Prompts.lua:383](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Prompts.lua#L383) | | `/polestar questdb` | Quest database status | [Quests/Options.lua:83](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Quests/Options.lua#L83) | | `/polestar gear` | Gear advice: weights in use, or compare an item link | [Gear/Gear.lua:785](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Gear/Gear.lua#L785) | | `/polestar instances` | Instance limits, runs and lockouts (instances clear: forget them) | [Maps/Instances.lua:435](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Maps/Instances.lua#L435) | | `/polestar xp` | XP per hour, time to level and level splits | [QoL/XP.lua:351](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/QoL/XP.lua#L351) | | `/polestar mount` | Look up your target's mount | [Lookup/Spotter.lua:252](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Lookup/Spotter.lua#L252) | | `/polestar lookup` | Search guides, items, mounts, NPCs and quests | [Lookup/Spotter.lua:253](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Lookup/Spotter.lua#L253) | | `/polestar dungeons` | Dungeon quests, bosses and entrances | [Dungeons/Dungeons.lua:389](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Dungeons/Dungeons.lua#L389) | | `/polestar rares` | rares [test]: open Rares, or show a sample alert | [Rares/Rares.lua:514](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Rares/Rares.lua#L514) | | `/polestar talents` | Open your talent plan | [Talents/Talents.lua:426](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Talents/Talents.lua#L426) | ## Other commands | Command | What it does | Defined in | |---|---|---| | `/way <x> <y> [label]` | Points the arrow at a spot, for addons and players used to `/way`. Claimed only while "Let other addons set waypoints" (Options, Integrations) is on and no other addon owns `/way` | [Nav/Journey.lua](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Journey.lua) | | `/psrec <command>` (or `/polestarrec`) | The Recorder, for guide authors: `status`, `on`, `off`, `mark`, `maps`, `talents`, `legacy`, `factions`, `skills`, `clear`. On its own it prints the status | [Polestar_Recorder/Commands.lua](https://github.com/fitzforge/polestar/blob/next/addon/Polestar_Recorder/Commands.lua) | --- # Options > Every setting in the options window, page by page, with its default and what it does. Page: https://polestar.guide/docs/reference/options (Polestar docs > Reference) Every setting in Polestar's options window (`/polestar options`), page by page, with its default and what it does, read from the addon's own options registry. A page opens directly with `/polestar options <page>`. Filter below by name, key or any word of its description. ## Guide Opens with `/polestar options guide` The guide window, the arrow and its routes, and what Polestar does for you. ### Window #### What it shows | Setting | Default | What it does | |---|---|---| | **Show the window** `ui.shown` | On | Also /polestar, or the key binding. (Switch) | | **Compact mode** `ui.compact` | Off | Only the header and the current step's goals. (Switch) | | **Step tips** `ui.showNotes` | On | The author's tip under the goals, one line until clicked. (Switch) | | **Expand step tips** `ui.notesOpen` | On | Start each step with its tip in full instead of one line. (Switch) | | **Upcoming steps** `ui.upcoming` | 0 | How many steps the Up next list holds; 0 turns it off. (Slider (0 to 6)) | | **Expand Up next** `ui.upcomingOpen` | Off | Start with the upcoming steps listed instead of collapsed. (Switch) | #### Combat | Setting | Default | What it does | |---|---|---| | **In combat** `ui.combat` | Keep visible | What the window does while you fight. Choices: Keep visible, Fade out, Hide. (Choice) | #### Dungeons | Setting | Default | What it does | |---|---|---| | **In dungeons** `ui.instance` | Keep visible | What the window does in dungeons and raids. /polestar or the key binding opens it there until you leave. Choices: Keep visible, Hide. (Choice) | #### Position | Setting | Default | What it does | |---|---|---| | **Lock window** `ui.locked` | Off | Prevents moving and resizing. (Switch) | | **Lock arrow and buttons** `ui.lockHud` | Off | Stops stray drags on the arrow, the action buttons and the flight and instance timers. Shift-drag still moves them. (Switch) | | **Grow upward** `ui.growUp` | Off | Keep the bottom edge in place, so longer steps extend the window up. (Switch) | | **Bar at the bottom** `ui.barsBottom` | Off | With Grow upward, put the tabs and the step bar at the bottom edge, next to where the window is pinned. (Switch) | | **Reset position** | — | Put the guide window back in its corner. (Action) | ### Arrow & routes #### Arrow | Setting | Default | What it does | |---|---|---| | **Show arrow** `nav.arrow` | On | Points to the current goal. Its look and colours are under Appearance, Arrow. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Arrival time** `nav.arrowEta` | On | Estimated time under the distance. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Distances** `nav.distanceUnit` | Yards (the game's unit) | How the arrow, map tooltips, rares and the death helper show distances. Choices: Yards (the game's unit), Metres. (Choice) | | **Arrival sound** `nav.arrivalSound` | On | A soft chime when you reach a waypoint. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Reset arrow position** | — | Back to the top of the screen. Drag the arrow to move it. Greyed out while Shortest Path Forever guides: it does this itself. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Action) | #### Routes | Setting | Default | What it does | |---|---|---| | **Plan travel routes** `nav.travel` | On | Flights, boats and your hearthstone when they are faster. Off: the arrow points straight at the goal. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Walk real paths** `nav.navRouting` | On | The arrow follows paths on the ground around cliffs, water and walls, on Polestar's walking maps, with Shortest Path Forever's router by Cillian Berragan. Off: it points straight at each stop. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Route lines** `nav.routeLines` | On | The way to the goal on the world map and the minimap: dots where you walk, lines where you fly, sail or ride, the legs after this one fainter. Drawn as Shortest Path Forever by Cillian Berragan draws them. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Class teleports** `nav.teleports` | On | Routes may start with a Teleport spell you know (a mage's city teleports, a druid's Moonglade) when it is faster. A city teleport needs a Rune of Teleportation in your bags. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Share boat times** `nav.shareTransit` | Off | Riding a boat, zeppelin, tram or lift times it; your guild and group get those times and you get theirs, so the arrow can say when the next one leaves. (Switch) | | **Shift-click a map to go there** `nav.mapPlan` | On | Shift-click the world map or minimap and the arrow takes you there; Alt-click works over map icons. Click the spot again to clear it. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Route style** `nav.routeStyle` | Balanced | Fastest: the shortest walk, over hills and across fields. Balanced: roads that aren't much longer, and round hills. Roads: stays on roads even when they're longer; the safest way, not the quickest. Greyed out while Shortest Path Forever guides: it does this itself. Choices: Fastest, Balanced, Roads. (Choice) | | **Nearby services in map menus** `nav.nearbyMenu` | On | The world map's and minimap's tracking menus find the nearest trainer, vendor, inn, bank and more (/polestar near). (Switch) | | **Nearby services button** `nav.nearbyButton` | On | A button in the guide window's header, left of the menu, finds the nearest vendor, repair, inn, flight master or trainer and points the arrow there. (Switch) | | **Show the journey** `nav.journeySteps` | On | The route's steps in the guide window with a time for each, counting down: walks, lifts, boats and flights. Click the current step to skip it. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | #### Other waypoints | Setting | Default | What it does | |---|---|---| | **Blizzard waypoint** `nav.blizzardWaypoint` | Off | Also set the game's own map pin and tracking. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Mirror to TomTom** `nav.tomtom` | On | Adds the target as a TomTom waypoint when TomTom is loaded. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Use TomTom's arrow** `nav.useTomTomArrow` | Off | Hides Polestar's arrow in favour of TomTom's. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | #### Along the route | Setting | Default | What it does | |---|---|---| | **Travel button** `nav.castPrompt` | On | When the route says to hearth or teleport, a button under the arrow casts it. Right-click the arrow to skip a leg. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Transport alerts** `nav.alerts` | On | Before your boat, zeppelin or tram comes in: 30 seconds ahead at the dock, 20 before the next stop on board. Never for lifts or in combat. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Show a banner** `nav.alertBanner` | On | A small card near the top of the screen with a countdown. Click it to dismiss. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Play the transport's sound** `nav.alertSound` | On | The ship's bell, the zeppelin's horn or the tram, on the Master channel so you hear it with the game in the background. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Flash the taskbar icon** `nav.alertFlash` | On | The game's icon flashes while the game is in the background. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Show a sample alert** | — | See the banner and hear the boat's bell. (Action) | ### Automation #### Quests | Setting | Default | What it does | |---|---|---| | **Accept guide quests** `behavior.autoAccept` | On | Only quests in the next steps of your open guides. Hold Shift to skip. (Switch) | | **Turn in guide quests** `behavior.autoTurnin` | On | Never picks between rewards. Hold Shift to skip. (Switch) | | **Close offers the guide skips** `behavior.closeSkipped` | On | After Polestar accepts or turns in a quest, closes the quest window the NPC opens next when the guide skips its quests. Hold Shift to keep it open. (Switch) | | **Warn about missable quests** `behavior.warnClosing` | Off | Before you take a quest that closes another for good, says which in chat and leaves the accept to you. (Switch) | | **Skip grey quests** `behavior.skipGrey` | Off | Leaves out grey quests and their turn-ins, unless a later quest needs them first. (Switch) | #### Guides | Setting | Default | What it does | |---|---|---| | **Pick a guide for me** `behavior.autoSelectGuide` | On | Opens the suggested guide when no tab is open. (Switch) | | **Continue to the next guide** `behavior.autoNextGuide` | On | Loads the follow-up guide in the same tab when one finishes. (Switch) | | **Where to level next** `behavior.routeChoice` | Let me choose | Where a guide offers more than one zone to continue in (/polestar path). Choices: Let me choose, Take the recommended zone. (Choice) | | **Trainer reminders** `behavior.trainReminder` | Every 2 levels | A note in the guide window, with the nearest trainer of your class, when new skills are waiting. Choices: Every 2 levels, Every level, Off. (Choice) | | **Reset guide progress** | — | Manual check-offs and skips, current guide. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Action) | ## Appearance Opens with `/polestar options appearance` Colours, type, window frames and the arrow. Everything repaints as you change it; right-click a setting to reset it. ### Colour & type #### Accent | Setting | Default | What it does | |---|---|---| | **Accent colour** `ui.accent` | false | Click to pick your own, right-click to go back to the scheme's. (Colour) | | **Class colour** `ui.classAccent` | Off | The accent follows your class: warlock purple, shaman blue, druid orange. Picking your own accent turns this off. (Switch) | #### Background | Setting | Default | What it does | |---|---|---| | **Colour scheme** `ui.scheme` | Dusk | How deep the night runs. Dusk is the default, Night the darkest, Graphite a neutral grey; EllesmereUI takes its panel colour and accent. Choices: Dusk, Night, Graphite. (Choice) | | **Background colour** `ui.bgColor` | false | The ground of every Polestar window. Right-click to go back to the scheme's. Text always stays legible: a colour too light for it is darkened. (Colour) | | **Brightness** `ui.brightness` | 0 | Lifts or lowers every background together. Right-click to reset. (Slider (-1 to 1)) | | **Background opacity** `ui.bgOpacity` | 0.94 | The background opacity of every Polestar window: how much of the world shows through. Right-click to reset. (Slider (0 to 1)) | #### Type & motion | Setting | Default | What it does | |---|---|---| | **Font** `ui.font` | The skin's font | The skin's font (the default: the game's own, Fira Sans in Halo), the game's, Inter, Fira Sans, or EllesmereUI's. Choices: The skin's font, Game font, Inter, Fira Sans. (Choice) | | **Reduce motion** `ui.reduceMotion` | Off | No sliding or popping; fades stay short. (Switch) | ### Windows #### Frame | Setting | Default | What it does | |---|---|---| | **Skin** `ui.skin` | Polestar | Polestar's own look (the default), Halo (no frame, a soft dark veil, Fira Sans), Hearth (warm game colours), or the game's own art: WoW Forever, Blizzard and Classic. Style, compact mode and the colours you pick work in each. Choices: Polestar, Halo, Hearth, Blizzard, Classic. (Choice) | | **Window border** `ui.border` | On | The line around every Polestar window. (Switch) | | **Border colour** `ui.borderColor` | false | Click to pick your own, right-click to go back to the scheme's hairline. (Colour) | | **Accent border** `ui.borderAccent` | Off | The border takes your accent colour. Picking your own border colour turns this off. (Switch) | | **Border thickness** `ui.borderSize` | 1 | In screen pixels; a thicker border grows outward. Right-click to reset. (Slider (1 to 4)) | | **Starlit band** `ui.band` | On | The night sky with its stars across the top of every window. Off: the plain background. (Switch) | | **Window shadow** `ui.shadow` | On | The soft shadow under every window. (Switch) | #### Guide window | Setting | Default | What it does | |---|---|---| | **Style** `ui.style` | Standard | Transparent drops every background and border; text is outlined and the controls appear when you hover the window. Choices: Standard, Transparent. (Choice) | | **Window scale** `ui.scale` | 1 | (Slider (0.6 to 1.6)) | | **Width** `ui.width` | 340 | (Slider (260 to 560)) | | **Window opacity** `ui.opacity` | 1 | The whole guide window, text included. The background's own opacity is under Colour & type. (Slider (0.3 to 1)) | #### Menus | Setting | Default | What it does | |---|---|---| | **Menu scale** `ui.menuScale` | 1 | The guide menu and this window; applies when you let go. Right-click to reset. (Slider (0.7 to 1.4)) | ### Arrow #### Arrow | Setting | Default | What it does | |---|---|---| | **Arrow style** `nav.arrowStyle` | The skin's arrow | Greyed out while Shortest Path Forever guides: it does this itself. Choices: The skin's arrow, 3D, Flat, Halo, Hearth. (Choice) | | **Arrow scale** `nav.arrowScale` | 1 | Greyed out while Shortest Path Forever guides: it does this itself. (Slider (0.5 to 2)) | | **Arrow opacity** `nav.arrowAlpha` | 1 | Greyed out while Shortest Path Forever guides: it does this itself. (Slider (0.2 to 1)) | #### Colours | Setting | Default | What it does | |---|---|---| | **Arrow colour** `nav.arrowColor` | false | The arrow on its way; the target's pin on the maps and the route's stops wear it too. Right-click to go back to the accent. (Colour) | | **Arrival colour** `nav.arrowNearColor` | false | The arrow as it closes on the target, and the ring when you arrive. Right-click to go back to jade. (Colour) | ## Map Opens with `/polestar options map` What Polestar draws on the world map and the minimap. Quest, rare and travel icons start off. ### Guide & quests #### Guide | Setting | Default | What it does | |---|---|---| | **Guide pins on the world map** `nav.worldPins` | On | The arrow's target, the stops of its travel route, the step's other goals, the areas their mobs and objects spawn in, and the route lines. (Switch) | | **Guide pin on the minimap** `nav.minimapPins` | On | The arrow's target, the areas it spawns in, and the route line. (Switch) | | **Trail dots along the travel route** `nav.trailDots` | On | Moving dots from you to the target on the world map and the minimap, along the travel route, while route lines are off. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Minimap button** `maps.minimapButton` | Off | A Polestar button on the edge of the minimap. Click to show or hide the guide, right-click for settings, drag to move it. (Switch) | #### Quest markers | Setting | Default | What it does | |---|---|---| | **Available quests** `qol.availableQuests` | Off | Mark quest givers with quests you can accept now. (Switch) | | **Quests above your level** `qol.questLevelWindow` | Your level | Mark quests up to this many levels above yours. (Slider (Your level to Your level)) | | **Low-level quests** `qol.lowLevelQuests` | Off | Also mark grey quests that are far below your level. (Switch) | | **World map objectives** `qol.mapObjectives` | Off | Mark mob areas, item sources and objects for quests in your log. (Switch) | | **Objective areas** `qol.objectiveAreas` | Off | Shade the area each group of mobs or objects spreads over on the world map. (Switch) | | **Turn-ins** `qol.turnInMarkers` | Off | Mark who to return to once a quest is ready. (Switch) | | **Minimap markers** `qol.minimapObjectives` | Off | Show the same quest markers on the minimap. (Switch) | | **Highlight step quests** `qol.guideHighlight` | On | Enlarge and light up the markers of the quests in your guide's current step. (Switch) | | **Dim other quests** `qol.guideDim` | Off | While a guide runs, fade every quest marker that is not part of its current step. (Switch) | ### Rares & travel #### Rares and treasures | Setting | Default | What it does | |---|---|---| | **Rares on the world map** `rares.worldRares` | Off | Every known spawn point. Click one to see it in Rares; Shift-click for a waypoint. (Switch) | | **Treasures on the world map** `rares.worldTreasures` | Off | Every known treasure spot. (Switch) | | **Rares on the minimap** `rares.minimapRares` | Off | Loads the Codex at login. (Switch) | | **Treasures on the minimap** `rares.minimapTreasures` | Off | Loads the Codex at login. (Switch) | | **Hide rares below your level** `rares.hideGrey` | Off | Rares too low to give experience leave the map. (Switch) | #### Dungeons and travel | Setting | Default | What it does | |---|---|---| | **Dungeon entrances** `maps.dungeonPins` | Off | Marks each dungeon entrance with its level range. Click to open the dungeon's guide, or to set a waypoint when there is none; Shift-click always sets a waypoint. Needs the Codex pack. (Switch) | | **Flight masters** `maps.taxiPins` | Off | Your faction's and neutral flight masters: green when known, amber when not yet discovered. The tooltip lists destinations and flight times. (Switch) | | **Boats and zeppelins** `maps.dockPins` | Off | Docks, zeppelin towers and the Deeprun Tram, with where they go. (Switch) | | **Inns** `maps.innPins` | Off | Innkeepers; the one your Hearthstone is bound to is marked. (Switch) | | **Travel icons on the minimap** `maps.travelMinimap` | Off | Shows the flight masters, docks and inns turned on here on the minimap as well. (Switch) | ### Zones #### Zones | Setting | Default | What it does | |---|---|---| | **Unexplored areas** `maps.reveal` | Revealed and tinted | Shows the parts of each zone you have not explored yet, so the whole map is there before you visit. Tinted keeps them apart from where you have been. Choices: Hidden, Revealed, Revealed and tinted. (Choice) | | **Zone level ranges** `maps.zoneLevels` | On | Shows each zone's level range on the continent and zone maps, coloured by difficulty for your level. (Switch) | #### Coordinates | Setting | Default | What it does | |---|---|---| | **Coordinates** `maps.coords` | On | Shows your position and the cursor's position under the world map. (Switch) | | **Coordinates on the minimap** `maps.minimapCoords` | Off | A small readout of your position at the bottom of the minimap. (Switch) | ## Questing Opens with `/polestar options questing` Quest information, rewards and gear advice, and the quest buttons. ### Quests #### Quest database | Setting | Default | What it does | |---|---|---| | **Quest database** `qol.questDB` | On | Quest, NPC and item data for markers and tooltips, loaded when one of them is on (about 5 MB of memory). (Switch) | #### Tooltips and quest log | Setting | Default | What it does | |---|---|---| | **Quest tooltips** `qol.questTooltips` | On | Name the quests a mob, item or object is for, with your progress. (Switch) | | **Nameplate icons** `qol.nameplateIcons` | Off | Show a quest icon and your progress, like 3/10, on nameplates of mobs you still need. (Switch) | | **Quest levels** `qol.questLevels` | On | Show quest levels, like [12], wherever the game lists quests without them. (Switch) | #### Faster questing | Setting | Default | What it does | |---|---|---| | **Instant quest text** `qol.instantQuestText` | On | Shows quest text at once instead of fading it in (Forever's own option). (Switch) | | **Skip single-option gossip** `qol.skipGossip` | On | Picks the only option of NPCs without quests. Hold Shift to read it. (Switch) | | **Faster auto-loot** `qol.fastLoot` | On | Takes the whole corpse at once when auto-loot is on. (Switch) | | **Hide combat errors** `qol.hideErrors` | Off | Hides "Not enough rage", "Out of range" and cooldown messages. Other errors still show. (Switch) | #### Party | Setting | Default | What it does | |---|---|---| | **Share my quest progress with my party** `party.share` | Off | Party members who run Polestar see your counts under their quest goals. Nothing goes to chat. (Switch) | | **Show my party's progress in the guide** `party.show` | Off | Their counts under your quest goals, and who lacks a quest you took. (Switch) | ### Rewards & gear #### Quest rewards | Setting | Default | What it does | |---|---|---| | **Mark quest rewards** `qol.rewardHighlight` | On | On the reward choices, a green arrow marks each upgrade for your spec (with Gear advice on), a thin frame in your accent colour the one to take, and a coin the one that sells for most. (Switch) | | **Take the best reward** `qol.rewardAutoPick` | Off | Chooses that reward for you when you complete the quest. Hold Shift to choose yourself. (Switch) | | **Wear reward upgrades** `qol.rewardEquip` | Off | Puts on what a turn-in gives when it is an upgrade for your spec (with Gear advice on), once it reaches your bags and you are out of combat. Hold Shift at the turn-in to skip. (Switch) | #### Gear advice | Setting | Default | What it does | |---|---|---| | **Gear advice** `gear.enabled` | On | Score items for your class and talents and point out upgrades. (Switch) | | **Stat weights** `gear.spec.PALADIN` | Automatic (talents) | Which levelling weights score your items. Automatic follows the talent tree with the most points. Choices: Automatic (talents), Holy (healer), Protection (tank), Retribution. (Choice) | | **Tooltip comparison** `gear.tooltip` | On | Show on item tooltips how much better or worse an item is than what you wear. (Switch) | | **Upgrade arrows in bags** `gear.bagArrows` | On | A green arrow on each item in your bags that is an upgrade for your spec, in the game's bags and in Baganator. (Switch) | | **Reward pick in the guide** `gear.rewards` | On | Under a turn-in step, name the reward to take: an upgrade with its gain, else the best one you can use. The marks on the game's reward panel are under Quest rewards. (Switch) | | **Reward pick on tooltips** `gear.pickTooltip` | On | On a quest reward's tooltip, say whether it is the upgrade to take. (Switch) | #### Comparison | Setting | Default | What it does | |---|---|---| | **Upgrade threshold** `gear.minUpgrade` | 1.0% | Smaller gains than this are not called upgrades. (Slider (0.0% to 10.0%)) | | **Pair with bag items** `gear.useBags` | On | Against a worn two-hander, weigh a one-hander together with the best off-hand piece in your bags. (Switch) | ### Talents #### Talent plan | Setting | Default | What it does | |---|---|---| | **Talent plans** `talents.enabled` | On | Follow a talent plan for your class and spec (/pole talents). (Switch) | | **Mark the talent frame** `talents.overlay` | On | A ring on the next talent in your plan and a flag on points the plan does not spend. (Switch) | | **Pick numbers** `talents.badges` | On | Where each talent comes in your plan's order (#1, #2, ...). (Switch) | | **Plan in tooltips** `talents.tooltip` | On | A line in each talent's tooltip: where it comes in the plan, or that it is off the plan. (Switch) | | **Remind me of unspent points** `talents.reminder` | On | A chat line naming the plan's next talent when a point is waiting. (Switch) | ### Buttons #### Action buttons | Setting | Default | What it does | |---|---|---| | **Quest item button** `qol.itemButton` | On | A button for the current step's quest item, with count, cooldown and range. Bind it under Key Bindings > AddOns. (Switch) | | **Target button** `qol.targetButton` | On | Targets the current step's mobs by name; each click moves to the next name. Bindable. (Switch) | | **Rare button** `qol.rareButton` | On | Shows a button that targets a rare Polestar spotted nearby, until it dies or is out of sight. Bindable. (Switch) | | **Hearthstone button** `qol.hearthButton` | On | Shows your Hearthstone while the guide says to hearth. Bindable. (Switch) | | **Mark what they target** `qol.markTarget` | Off | The target button and the step key put a raid icon on the mob and the NPC they target; out of combat, a press that finds neither clears your target. Your party sees the icons; in a raid only the leader and assistants can set them. (Switch) | | **Icon on mobs** `qol.markMob` | \|TInterface\TargetingFrame\UI-RaidTargetingIcon_8:0\|t 8 | A new one each press skips the NPCs' icon and leaves a mob that has one as it is. Choices: \|TInterface\TargetingFrame\UI-RaidTargetingIcon_1:0\|t 1, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_2:0\|t 2, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_3:0\|t 3, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_4:0\|t 4, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_5:0\|t 5, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_6:0\|t 6, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_7:0\|t 7, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_8:0\|t 8, A new one each press. (Choice) | | **Icon on NPCs** `qol.markNpc` | \|TInterface\TargetingFrame\UI-RaidTargetingIcon_1:0\|t 1 | A new one each press, so the last few NPCs keep theirs. Every press counts, even one that marks nothing. Choices: \|TInterface\TargetingFrame\UI-RaidTargetingIcon_1:0\|t 1, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_2:0\|t 2, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_3:0\|t 3, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_4:0\|t 4, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_5:0\|t 5, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_6:0\|t 6, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_7:0\|t 7, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_8:0\|t 8, A new one each press. (Choice) | | **Button size** `qol.buttonScale` | 1 | Scale of the quest item, Hearthstone, target and rare buttons. Drag one to move them all. (Slider (0.6 to 1.6)) | | **Target name position** `qol.buttonTextSide` | Right | Where the target's name shows around the target button: right, left, above or below. Choices: Right, Left, Above, Below. (Choice) | | **Reset button positions** | — | Put the buttons back in their default spot. (Action) | ## Discovery Opens with `/polestar options discovery` Lookup, the dungeon journal and rares: finding things in the world. ### Lookup #### How to get anything | Setting | Default | What it does | |---|---|---| | **Lookup** `lookup.enabled` | On | Search every item, mount, pet, NPC and quest, and see where it comes from (/pole lookup). (Switch) | | **Sources on item tooltips** `lookup.tooltip` | On | The best one or two places to get an item, ranked for this character. (Switch) | | **Alt-click an item for a guide** `lookup.altClick` | On | Alt-click an item link, bag item or loot to open a guide that gets it. (Switch) | | **Spot other players' mounts** `lookup.mounts` | On | Name the mount of a player you target or point at, and where it comes from (/pole mount). (Switch) | ### Dungeons #### Dungeon Journal | Setting | Default | What it does | |---|---|---| | **Dungeons** `dungeons.enabled` | On | A page per dungeon and raid: every quest with where to get it, its chain and rewards, the bosses and the entrance. (Switch) | ### Rares #### When a rare shows up | Setting | Default | What it does | |---|---|---| | **Rares** `rares.enabled` | On | Watch for rare NPCs and treasures and keep when you last met them (/pole rares). Their map pins are under Map, off by default. (Switch) | | **Alert for rares** `rares.alerts` | On | A card with its name, level and distance, and a waypoint to it. (Switch) | | **Alert for treasures** `rares.treasureAlerts` | On | Treasures the client marks on the minimap. (Switch) | | **Once per rare every** `rares.cooldown` | 10 | The same rare stays quiet this long after an alert. (Slider (1 to 60)) | | **Alert stays for** `rares.toastSeconds` | 20 | Hovering the alert holds it. (Slider (5 to 60)) | | **Alert during combat** `rares.combatAlerts` | Off | Off: an alert waits for the fight to end, if the rare was seen in the last minute. (Switch) | | **Play a sound** `rares.sound` | On | One sound with each alert. (Switch) | | **Sound** `rares.soundKit` | Raid warning | Played through the Master channel. Choices: Raid warning, Ready check, Boss whisper. (Choice) | | **Show a sample alert** | — | See where the alert sits; drag it to move it. (Action) | #### How rares are noticed | Setting | Default | What it does | |---|---|---| | **Minimap markers** `rares.vignettes` | On | Rares and treasures the client marks on the minimap (vignettes), with their exact distance. (Switch) | | **Nameplates** `rares.nameplates` | On | A rare's nameplate coming into view. Needs enemy nameplates on. (Switch) | | **Your target** `rares.target` | On | Targeting a rare. (Switch) | | **Under the cursor** `rares.mouseover` | On | Pointing at a rare in the world. (Switch) | #### History | Setting | Default | What it does | |---|---|---| | **Forget rares met on this realm** | — | Clears the Seen list, alert cooldowns and the glow on recently seen pins. (Action) | ## Quality of Life Opens with `/polestar options qualityoflife` Small conveniences: travel, invitations, merchants and trackers. ### Travel #### Flight masters | Setting | Default | What it does | |---|---|---| | **Open the flight map** `qol.flightAutoOpen` | On | Talking to a flight master opens the map directly. Hold Shift for the gossip. (Switch) | | **Mark the route's destination** `qol.flightHighlight` | On | Marks where the travel route flies next on the flight map. You still choose the flight. (Switch) | #### Hearthstone | Setting | Default | What it does | |---|---|---| | **Set your home at the guide's inn** `qol.autoBind` | Off | When the step sets your home and you talk to its innkeeper, binds your Hearthstone there. Never at another inn. Hold Shift to skip. (Switch) | #### Flight timer | Setting | Default | What it does | |---|---|---| | **Flight timer** `maps.flightTimer` | On | While flying, shows the destination and the time left. Learns each route's real duration for this character; drag to move. (Switch) | | **Forget learned flight times** | — | Clears this character's recorded flight durations; estimates are used until they are flown again. (Action) | #### Death | Setting | Default | What it does | |---|---|---| | **Corpse or Spirit Healer** `qol.deathHelper` | On | As a ghost, points the arrow at the faster way back: your corpse or the nearest Spirit Healer. (Switch) | | **Release in battlegrounds** `qol.autoReleasePvP` | Off | Releases your spirit at once when you die in a battleground, unless you can resurrect yourself or someone offers to. Hold Shift to stay. (Switch) | ### Social #### Requests | Setting | Default | What it does | |---|---|---| | **Accept summons** `qol.acceptSummon` | Off | Takes a summon at once, unless you are in combat. Hold Shift to decide yourself. (Switch) | | **Accept resurrections** `qol.acceptResurrect` | Off | Takes a resurrection as soon as it can, unless the caster is in combat. Never in Hardcore. Hold Shift to decide yourself. (Switch) | | **Join friends' parties** `qol.acceptPartyFriends` | Off | Accepts party invitations from friends, Battle.net friends and your guild, unless joining would leave a queue. Hold Shift to decide yourself. (Switch) | #### Blocking | Setting | Default | What it does | |---|---|---| | **Decline other party invitations** `qol.declinePartyStrangers` | Off | Declines party invitations from anyone who is not a friend or in your guild. (Switch) | | **Decline guild invitations** `qol.declineGuildInvites` | Off | Declines guild invitations, except from friends. (Switch) | | **Decline duels** `qol.declineDuels` | Off | Declines duel requests, except from friends and your guild. (Switch) | ### Vendors #### Merchants | Setting | Default | What it does | |---|---|---| | **Sell grey items** `qol.sellJunk` | On | Sells Poor-quality items when a merchant opens and prints the total. Never sells anything else. (Switch) | | **Repair** `qol.autoRepair` | On | Repairs all gear at merchants who can, when you can afford it. Hold Shift to skip. (Switch) | | **Guild bank first** `qol.repairGuild` | Off | When your guild rank may, the guild bank pays for repairs and your money covers the rest. (Switch) | | **Buy for the guide** `qol.buyGoals` | Off | When the step asks you to buy something and the merchant sells it, buys what you still need after selling and repairing. Optional buys and anything over 50g are left to you. Hold Shift to skip. (Switch) | #### Trainers | Setting | Default | What it does | |---|---|---| | **Learn new spells** `qol.trainAll` | Off | Learns every spell a class trainer offers that you can afford, and prints the total. Profession trainers are left alone. Hold Shift to skip. (Switch) | ### Trackers #### Experience | Setting | Default | What it does | |---|---|---| | **XP tracker** `qol.xpTracker` | On | XP per hour, time, kills and quests to level, and level splits (/pole xp). (Switch) | | **Guide level on the XP bar** `qol.xpTargetMark` | On | A mark at the end of the game's XP bar with the level the guide wants you to reach before it moves on, and how many levels away that is when it is more than one. (Switch) | | **Reset session** | — | Start this session's XP per hour from zero. (Action) | #### Instances | Setting | Default | What it does | |---|---|---| | **Track instances** `maps.instances` | On | Records dungeon and raid entries, time and experience per run. /pole instances lists them. (Switch) | | **Compact display** `maps.instanceDisplay` | Off | Shows the hourly instance count and the current run while it matters; drag to move. (Switch) | #### Instance limits | Setting | Default | What it does | |---|---|---| | **Instances per hour** `maps.perHour` | 5 | Classic allows 5 new instances per hour per account. Forever may differ; adjust if it does. (Slider (1 to 10)) | | **Instances per day** `maps.perDay` | 30 | Classic Era allows 30 new instances per 24 hours per account; 0 ignores the daily cap. Forever may differ. (Slider (0 to 60)) | | **Clear instance history** | — | Forgets recorded entries and runs (the server's own limit is not affected). (Action) | ## Integrations Opens with `/polestar options integrations` Settings for other addons Polestar works with, shown when they are installed. ### EllesmereUI | Setting | Default | What it does | |---|---|---| | **Match EllesmereUI accent** `ui.matchAccent` | On | Follow EllesmereUI's accent, live. Picking your own accent turns this off. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Switch) | | **Match EllesmereUI font** `ui.matchFont` | Off | Follow EllesmereUI's font, live. Choosing another font turns this off. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Switch) | ### TomTom | Setting | Default | What it does | |---|---|---| | **Let other addons set waypoints** `nav.answerTomTom` | Off | Without TomTom installed, waypoints other addons set through TomTom, and /way, point Polestar's arrow. Addons that expect TomTom's own settings may not work with it on. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Follow TomTom's arrow** `nav.followTomTom` | Off | With TomTom installed, the arrow goes wherever TomTom's arrow points, routed like any goal. (Switch) | ### Shortest Path Forever | Setting | Default | What it does | |---|---|---| | **Hand guiding to Shortest Path Forever** `nav.spfHandoff` | Off | Shortest Path Forever's arrow, route and journey take you to each goal. Polestar's arrow, route lines, journey steps, travel button, transport alerts, map clicks and /way step aside; the guide window and map pins stay. Off: Polestar guides, and steps aside only while a journey you started in Shortest Path Forever runs. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Switch) | ### The community quest database | Setting | Default | What it does | |---|---|---| | **Show planned turn-ins in the community quest database** `routePlan.<quest-db>` | Off | Completed quests in the community quest database's tracker show their Polestar turn-in step. Earlier, skipped and unplanned hand-ins are flagged. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Switch) | ## Community guides Opens with `/polestar options guidepacks` Guides made by other players: switch them on or off, and choose where suggestions come from. This page is drawn by its own code: it shows status and actions rather than settings. ## Gamepad Opens with `/polestar options gamepad` Play Polestar with a gamepad: its windows, its buttons and your bindings. The bindings take keys too. ### Navigation #### Your gamepad | Setting | Default | What it does | |---|---|---| | **Button names** `gamepad.glyphs` | Automatic | The names and shapes Polestar shows for your gamepad's buttons. Automatic reads them off the gamepad. Choices: Automatic, Xbox (A, B, X, Y), PlayStation (shapes). (Choice) | | **Navigate Polestar's windows** `gamepad.navigate` | On | While a Polestar window is open, the D-pad moves through it, A selects, B closes, LB and RB change tabs, Y restores a default. Out of combat; the game gets every button back when the window closes. (Switch) | | **Button hints** `gamepad.hints` | On | A bar under the window says what each button does, and B sits on the close button. (Switch) | | **Use with the keyboard and mouse** `gamepad.withMouse` | Off | Off, Polestar uses the gamepad only with the game's gamepad interface (Options, Gamepad, Enable Gamepad UI). On, also with the keyboard and mouse interface, while the gamepad is turned on in the game's options and plugged in. (Switch) | ### Key bindings #### The guide | Setting | Default | What it does | |---|---|---| | **Next step** | — | (Key binding) | | **Previous step** | — | (Key binding) | | **Browse the guide with the gamepad** | — | The guide window holds the gamepad until B: the D-pad picks a line, A points the arrow there or uses the item, X shows its details, LB and RB change steps, Y minimizes the window. A window that opened by itself, such as a route choice, waits for this button before it takes the gamepad. (Key binding) | | **Toggle guide window** | — | (Key binding) | #### Windows | Setting | Default | What it does | |---|---|---| | **Open the guide menu** | — | (Key binding) | | **Open Polestar options** | — | (Key binding) | | **Report a problem** | — | (Key binding) | #### Quest buttons | Setting | Default | What it does | |---|---|---| | **Use quest item** | — | (Key binding) | | **Target quest mob** | — | (Key binding) | | **Target rare** | — | (Key binding) | | **Use Hearthstone** | — | (Key binding) | | **Use the step button** | — | Step action: NPC, quest item, mob or Hearthstone (Key binding) | | **Use the travel button** | — | Use the route's Hearthstone or teleport (Key binding) | ## Recorder Opens with `/polestar options recorder` The data recorder for guide authors. This page is drawn by its own code: it shows status and actions rather than settings. ## About Opens with `/polestar options about` Why Polestar exists, its commands and its credits. This page is drawn by its own code: it shows status and actions rather than settings. ## Settings without a control Defaults the addon keeps that no row above shows: window positions, remembered choices and values other settings derive from. Reset page in the options window clears a page; these reset with them. ### 26 saved settings | Key | Default | |---|---| | `behavior.suggestFrom` | `"guides"` | | `gear.spec.DRUID` | `"auto"` | | `gear.spec.HUNTER` | `"auto"` | | `gear.spec.MAGE` | `"auto"` | | `gear.spec.PRIEST` | `"auto"` | | `gear.spec.ROGUE` | `"auto"` | | `gear.spec.SHAMAN` | `"auto"` | | `gear.spec.WARLOCK` | `"auto"` | | `gear.spec.WARRIOR` | `"auto"` | | `maps.minimapButtonAngle` | `225` | | `maps.timerPos` | `false` | | `maps.trackerPos` | `false` | | `nav.journeyOpen` | `true` | | `nav.lineStyle` | `"dots"` | | `nav.openmapDots` | `true` | | `nav.sparkleColor` | `"gold"` | | `nav.sparkleDensity` | `5` | | `nav.sparkleFlow` | `0.5` | | `nav.sparkleIntensity` | `0.75` | | `nav.sparkleLater` | `false` | | `nav.sparkleMax` | `140` | | `nav.sparkleSize` | `14` | | `nav.sparkleSubtlety` | `0.35` | | `rares.ignored` | `false` | | `rares.toastPoint` | `false` | | `ui.pickerFaction` | `"auto"` | --- # Key bindings > Every key binding and gamepad action, and which take a chord. Page: https://polestar.guide/docs/reference/bindings (Polestar docs > Reference) Polestar's key bindings, under **Polestar** in the game's Key Bindings (AddOns), in the order the Gamepad page of Polestar's options lists them. Every action takes a key; the ones marked below also take a gamepad chord (two buttons at once) on that page. The buttons are secure clicks the game runs itself, so they take a key or a single gamepad button but not a chord. | Action | Group | Gamepad chord | Binding | |---|---|---|---| | **Next step** | Guide | Yes | `POLESTAR_NEXT` | | **Previous step** | Guide | Yes | `POLESTAR_PREV` | | **Browse the guide with the gamepad** | Guide | Yes | `POLESTAR_FOCUS` | | **Toggle guide window** | Guide | Yes | `POLESTAR_TOGGLE` | | **Open the guide menu** | Windows | Yes | `POLESTAR_MENU` | | **Open Polestar options** | Windows | Yes | `POLESTAR_OPTIONS` | | **Report a problem** | Windows | Yes | `POLESTAR_REPORT` | | **Use quest item** | Buttons | No | `CLICK PolestarQuestItemButton:LeftButton` | | **Target quest mob** | Buttons | No | `CLICK PolestarTargetButton:LeftButton` | | **Target rare** | Buttons | No | `CLICK PolestarRareButton:LeftButton` | | **Use Hearthstone** | Buttons | No | `CLICK PolestarHearthButton:LeftButton` | | **Use the step button** | Buttons | No | `CLICK PolestarStepButton:LeftButton` | | **Use the travel button** | Buttons | No | `CLICK PolestarTravelButton:LeftButton` | ## Gamepad defaults The gamepad settings as they start, before any change on the Gamepad page: | Setting | Default | |---|---| | `gamepad.glyphs` | `"auto"` | | `gamepad.hints` | `true` | | `gamepad.navigate` | `true` | | `gamepad.withMouse` | `false` | --- # Guide format reference > Every header line, step line and goal the guide compiler takes, with the modifiers each accepts. Page: https://polestar.guide/docs/reference/guide-lines (Polestar docs > Reference) Every line the guide compiler takes, read from its own tables (`tools/lib/dsl/parse.js`): the header lines, the lines inside a step, and each goal with the modifiers it accepts. The words and examples are the cheatsheet's; the [full rules](https://polestar.guide/docs/authors/guide-format) are in the guide format. Try them here: edit the guide on the left and the guide window on the right follows. ## Header lines In column 0, before the first `step`: `guide`, `title`, `levels`, `zone`, `faction`, `race`, `class`, `next`, `category`, `folder`, `keywords`, `collects`, `reward`, `why`, `author`, `version`, `coords`, `pitch`, `pro`, `con`. | Line | What it does | Example | |---|---|---| | `guide <id>` | First line: the guide's id, starting with your pack id and `/` | `guide joe-routes/goldshire` | | `title <text>` | The name players see in the guide menu | `title Goldshire to Westfall` | | `levels <min>-<max>` | The character levels the guide is for | `levels 5-10` | | `zone <Name>` | The zone the guide's coordinates are in, until a step names another | `zone Elwynn Forest` | | `zone map <uiMapID>` | The same, by map id | `zone map 1429` | | `zone <Name>` / `zone map <uiMapID>` | Inside a step: the zone for coordinates from here on, also for the steps after it (after a step with `only` that sets one, name the zone again) | `zone Elwynn Forest` | | `faction <Faction>` | Only for `Alliance` or `Horde` characters | `faction Alliance` | | `race <Race>, ...` | Only for these races (see Conditions) | `race Human, Dwarf` | | `class <Class>, ...` | Only for these classes | `class Warrior, Paladin` | | `next <id>, <id>, ...` | Several guides after this one: the player picks one, the first is your suggestion | `next joe-routes/westfall, joe-routes/redridge` | | `next <id> when <predicate>` | One guide per line, offered only while the predicate (as on a step's `when`) holds when this guide ends; `next` lines add up. One option left: Polestar goes on to it; none: the guide ends there | `next joe-routes/redridge when level>=15` | | `next <id>` | The guide that follows when this one ends: one of yours or one of Polestar's (`polestar find --kind guide <zone>` lists them with who can follow them) | `next joe-routes/westfall` | | `category <Category>` | The guide menu category: `Leveling` (default), `Class`, `Professions`, `Reputation`, `Legacy`, `Exploration`, `Collectibles`, `Miscellaneous` or `Dungeons` | `category Professions` | | `folder <text>` | The guide menu folder to list it under | `folder Mounts · Level 40` | | `keywords <word>, ...` | Extra words the guide menu search finds it by | `keywords wolf, meat` | | `collects <item>, ...` | Items the guide obtains; Lookup opens this guide for them | `collects 750` | | `reward item <item> ...` | What the guide's goal gives, shown with its icon in the guide menu; several items on one line are a choice of one; repeatable | `reward item 1251 2581` | | `reward spell <id> "Name"` | A spell the goal teaches (a mount, a form, a demon) | `reward spell 5784 "Summon Felsteed"` | | `reward text <words>` | A reward without an id | `reward text Shen'dralar reputation` | | `choose <item> ...` / `reward <item> ...` | On `turnin`: the rewards to pick from, and the ones given outright | `turnin 5261 choose 159 2589 reward 4306` | | `why <text>` | One short line in the guide menu: why the goal is worth doing (Class guides need it and `reward`) | `why Your own mount at 40.` | | `author <name>` | Credits a guide to someone other than the pack's author | `author Joe` | | `version <N>` | A whole number you raise when the guide changes (default 1) | `version 2` | | `coords era` / `coords live` | The map frame of the coordinates you type (default `era`; `record draft` writes `live`) | `coords live` | | `pitch <text>` | On a guide offered as a choice: one line on its card | `pitch Short walks between quests.` | | `pro <text>` / `con <text>` | One advantage or drawback per line, under the pitch | `pro Ends at a flight point` | ## Step lines Indented inside a step, beside its goals: `zone`, `only`, `tip`, `image`, `when`, `label`, `along`, `loop`. | Line | What it does | Example | |---|---|---| | `zone <Name>` | The zone the guide's coordinates are in, until a step names another | `zone Elwynn Forest` | | `zone map <uiMapID>` | The same, by map id | `zone map 1429` | | `zone <Name>` / `zone map <uiMapID>` | Inside a step: the zone for coordinates from here on, also for the steps after it (after a step with `only` that sets one, name the zone again) | `zone Elwynn Forest` | | `only <condition>, ...` | Inside a step: the step is only for matching characters | `only Hunter` | | `only <condition>, ...` | After a goal: the goal is only for matching characters | `kill 299 only Hunter` | | `tip <text>` | A note for the whole step, shown in the guide window | `tip Pull one kobold at a time.` | | `image <path> [<w>x<h>]` | A picture (a `.tga` or `.blp` in the pack folder) shown under the step's tip, such as a screenshot of a cave mouth | `image media/fargodeep-mine.tga` | | `when <predicate>` | Inside a step: the step is only for characters in that state when the route gets there (see Conditions checked during play) | `when level<6` | | `when level<N` (`<=`, `>`, `>=`) | the character's level compares so; N may be a point inside a level (`12.5`, `12+2500`) | `when level>=10` | | `when onquest <quest>, ...` | any of the quests is in the log | `when onquest 783` | | `when complete <quest>` | the quest is ready to turn in | `when complete 7` | | `when turnedin <quest>` | the quest is handed in | `when !turnedin 9201` | | `when available <quest>` | the quest can be taken now | `when available 9200` | | `when has <item> [xN]` | the bags hold N or more | `when !has 159 x5` | | `when zone "<Name>"` / `when subzone "<Name>"` | the player is there | `when subzone "Goldshire"` | | `when bound "<Location>"` | the hearthstone is bound there | `when !bound "Goldshire"` | | `label <name>` | Inside a step: names it for an `along until` before it | `label camp` | | `along [until <label>]` | Inside a step: the route never stops there; its goals are done along the way, listed under the next steps until done (or until the labelled step) | `along until camp` | | `loop` | Inside a step: its `goto` points are the places to search, in order, for the step's kill, collect and interact goals without `@x,y` | `loop` | ## Goals 24 verbs, each a line inside a step: [`accept`](https://polestar.guide/docs/reference/guide-lines#accept) [`turnin`](https://polestar.guide/docs/reference/guide-lines#turnin) [`complete`](https://polestar.guide/docs/reference/guide-lines#complete) [`kill`](https://polestar.guide/docs/reference/guide-lines#kill) [`collect`](https://polestar.guide/docs/reference/guide-lines#collect) [`goto`](https://polestar.guide/docs/reference/guide-lines#goto) [`talk`](https://polestar.guide/docs/reference/guide-lines#talk) [`interact`](https://polestar.guide/docs/reference/guide-lines#interact) [`use`](https://polestar.guide/docs/reference/guide-lines#use) [`sethome`](https://polestar.guide/docs/reference/guide-lines#sethome) [`hearth`](https://polestar.guide/docs/reference/guide-lines#hearth) [`getfp`](https://polestar.guide/docs/reference/guide-lines#getfp) [`fly`](https://polestar.guide/docs/reference/guide-lines#fly) [`train`](https://polestar.guide/docs/reference/guide-lines#train) [`buy`](https://polestar.guide/docs/reference/guide-lines#buy) [`vendor`](https://polestar.guide/docs/reference/guide-lines#vendor) [`level`](https://polestar.guide/docs/reference/guide-lines#level) [`note`](https://polestar.guide/docs/reference/guide-lines#note) [`skill`](https://polestar.guide/docs/reference/guide-lines#skill) [`learn`](https://polestar.guide/docs/reference/guide-lines#learn) [`craft`](https://polestar.guide/docs/reference/guide-lines#craft) [`rep`](https://polestar.guide/docs/reference/guide-lines#rep) [`explore`](https://polestar.guide/docs/reference/guide-lines#explore) [`achieve`](https://polestar.guide/docs/reference/guide-lines#achieve). ### accept | Line | What it does | Example | |---|---|---| | `accept <quest> ["Title"]` | Take a quest; the giver and title come from the data | `accept 783` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `object` `item` `lvl` ### turnin | Line | What it does | Example | |---|---|---| | `turnin <quest> ["Title"]` | Hand a quest in | `turnin 783` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `object` `reward` `choose` `xp <N>` `money <amount>` `direct` ### complete | Line | What it does | Example | |---|---|---| | `complete <quest> ["Title"]` | Finish every objective of a quest; give it a place (`@x,y`, or a `goto` before it) when its objectives have one, or the arrow has nowhere to point | `complete 7 @48.5,31.0` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` ### kill | Line | What it does | Example | |---|---|---| | `kill <npc>` / `kill "<Name>"` | Kill a mob; `quest Q.O` ties it to a quest objective | `kill 6 x10 quest 7.1` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `quest` `xN` ### collect | Line | What it does | Example | |---|---|---| | `collect <item> ["Name"]` | Gather or loot items; without `quest`, counted in the bags | `collect 750 x8` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `quest` `xN` `nearest` ### goto | Line | What it does | Example | |---|---|---| | `goto <x>,<y> ["Label"]` | Walk to a spot; checked off on arrival, when a later goal of the step is done, or, ending its step, when the next step's quest work is done | `goto 47.6,35.1 "Kobold camp"` | Takes `"text"` `optional` `only` `group [N]` `map` `r` `era/live` ### talk | Line | What it does | Example | |---|---|---| | `talk <npc>` | Speak to an NPC | `talk 197` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` ### interact | Line | What it does | Example | |---|---|---| | `interact <object>` | Click a game object | `interact 2843` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `quest` ### use | Line | What it does | Example | |---|---|---| | `use <item>` | Use an item | `use 1210 @47.6,35.1` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `quest` ### sethome | Line | What it does | Example | |---|---|---| | `sethome "<Location>"` | Bind the hearthstone at an inn, named as the game reports it | `sethome "Goldshire"` | | `sethome nearest` | Bind at the nearest inn of the player's faction | `sethome nearest` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` ### hearth | Line | What it does | Example | |---|---|---| | `hearth "<Location>"` | Use the hearthstone; done on landing there | `hearth "Goldshire"` | Takes `"text"` `optional` `only` `group [N]` ### getfp | Line | What it does | Example | |---|---|---| | `getfp "<Flight point>"` | Learn a flight path from its flight master | `getfp "Stormwind"` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` ### fly | Line | What it does | Example | |---|---|---| | `fly "<Town>"` | Take a flight; done on landing there | `fly "Stormwind"` | Takes `"text"` `optional` `only` `group [N]` ### train | Line | What it does | Example | |---|---|---| | `train class` | Visit the nearest trainer of the player's class | `train class only Warrior,Mage` | | `train <npc>` | Visit that trainer | `train 911 only Warrior,Paladin` | | `train <Profession> [Rank]` | Learn a profession or its next rank (`Apprentice`, `Journeyman`, `Expert`, `Artisan`) at the nearest trainer | `train Mining Journeyman` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` ### buy | Line | What it does | Example | |---|---|---| | `buy <item> ["Name"]` | Buy an item; `nearest` picks the closest vendor selling it | `buy 159 x5 nearest` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `xN` `nearest` ### vendor | Line | What it does | Example | |---|---|---| | `vendor nearest` / `vendor <npc>` | Sell and repair, at the closest vendor or that one | `vendor nearest` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` ### level | Line | What it does | Example | |---|---|---| | `level <N>` | Reach level N, grinding if need be | `level 2` | | `level <N>.<fraction>` / `level <N>+<XP>` | Reach a point inside level N: 12.5 is halfway through 12, 12+2500 is 2500 XP into it (to whole percent; needs Polestar 0.2.6) | `level 12.5` | Takes `"text"` `optional` `only` `group [N]` ### note | Line | What it does | Example | |---|---|---| | `note <text>` | A line of information; never holds the player up | `note The camp is busy at night.` | Takes `optional` `only` `@x,y` `map` `r` `era/live` ### skill | Line | What it does | Example | |---|---|---| | `skill <Profession> <N>` | Reach skill N (quote names of two words) | `skill "First Aid" 40` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` ### learn | Line | What it does | Example | |---|---|---| | `learn <spell> ["Name"]` | Learn a recipe; from a trainer, or with `nearest` from the closest vendor of its recipe | `learn 3276` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `item` `nearest` ### craft | Line | What it does | Example | |---|---|---| | `craft <spell> ["Name"]` | Craft a recipe, `x<N>` times | `craft 3275 x5` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `xN` `until <N>` ### rep | Line | What it does | Example | |---|---|---| | `rep <Faction> <Standing>` | Reach a standing (`Neutral` to `Exalted`) with a faction, by name or id | `rep Stormwind Friendly` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` ### explore | Line | What it does | Example | |---|---|---| | `explore <x>,<y> ["Area"]` | Discover the map area at these coordinates | `explore 41,65 "Goldshire"` | Takes `"text"` `optional` `only` `group [N]` `map` `r` `era/live` ### achieve | Line | What it does | Example | |---|---|---| | `achieve <id> "Name"` | Complete an achievement or Legacy Challenge | `achieve 9001 "Kobold Catcher"` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `criteria <n>` --- # Command line > Every polestar command of the toolchain, with its usage as the command prints it. Page: https://polestar.guide/docs/reference/cli (Polestar docs > Reference) Polestar's command line, the toolchain for guides, data and releases. Run a command as `node tools/polestar.js <command>` from a clone, or as `polestar <command>` after `npm link`. `--help` after any command prints its usage and runs nothing. Each entry below is that usage, as the command prints it. | Command | What it does | |---|---| | [`changelog`](https://polestar.guide/docs/reference/cli#polestar-changelog) | Changelog fragments in changes/: add, check, show, and build into CHANGELOG.md | | [`codex`](https://polestar.guide/docs/reference/cli#polestar-codex) | Build Lookup's Codex (data/forever/codex + the Polestar_Codex pack) | | [`compile`](https://polestar.guide/docs/reference/cli#polestar-compile) | Compile a pack into its community addon folder | | [`data`](https://polestar.guide/docs/reference/cli#polestar-data) | Build reference data (data/forever/*.json) from the Era quest database, the community quest database, Blizzard map tables and recordings | | [`dev`](https://polestar.guide/docs/reference/cli#polestar-dev) | Rebuild a pack into the game on every save | | [`doctor`](https://polestar.guide/docs/reference/cli#polestar-doctor) | Check Node, Lua, the reference data, the AddOns folder and pack.json | | [`draft`](https://polestar.guide/docs/reference/cli#polestar-draft) | Generate a first-draft leveling route (.guide) from the reference data | | [`dungeons`](https://polestar.guide/docs/reference/cli#polestar-dungeons) | Import DungeonJournal: dungeon data (data/forever/dungeons.json) | | [`exploration`](https://polestar.guide/docs/reference/cli#polestar-exploration) | Build or check the generated exploration guides | | [`export`](https://polestar.guide/docs/reference/cli#polestar-export) | Print the import string of one guide | | [`find`](https://polestar.guide/docs/reference/cli#polestar-find) | Look up quests, NPCs, objects, items, inns, flight points and guides as guide lines | | [`gear`](https://polestar.guide/docs/reference/cli#polestar-gear) | Build the upgrade-advice data (Forever item stats, reward choices, stat weights) from installed addons and sims | | [`i18n`](https://polestar.guide/docs/reference/cli#polestar-i18n) | interface translations (status, check, sync, keys, import, fit, leaks), guide texts (guides) and the names addons (names) | | [`install`](https://polestar.guide/docs/reference/cli#polestar-install) | Install the addons into the Forever client | | [`itemdb`](https://polestar.guide/docs/reference/cli#polestar-itemdb) | Build the Polestar_ItemDB data addon (item stats) from client tables | | [`lint`](https://polestar.guide/docs/reference/cli#polestar-lint) | Check .guide files without writing output | | [`maps`](https://polestar.guide/docs/reference/cli#polestar-maps) | Build world map data (zone level ranges, zone art overlays) | | [`media`](https://polestar.guide/docs/reference/cli#polestar-media) | Regenerate the addon textures (tools/media/*.js -> addon/Polestar/Media) | | [`nav`](https://polestar.guide/docs/reference/cli#polestar-nav) | Terrain navigation from the client geometry (build the grid, route between map points) and Polestar's walking router with its maps (Polestar_Nav) | | [`new`](https://polestar.guide/docs/reference/cli#polestar-new) | Start a pack in a new folder from the template | | [`pack`](https://polestar.guide/docs/reference/cli#polestar-pack) | Build the release zips, or a community addon's zip | | [`planner`](https://polestar.guide/docs/reference/cli#polestar-planner) | Plan routes: play a guide on the map and edit it (local page, MCP) | | [`play`](https://polestar.guide/docs/reference/cli#polestar-play) | Play with the real addon in the browser (local playground) | | [`playtest`](https://polestar.guide/docs/reference/cli#polestar-playtest) | Play a pack's guides to the end for every class | | [`preview`](https://polestar.guide/docs/reference/cli#polestar-preview) | Render the guide window, picker and options to docs/preview/*.svg | | [`profession`](https://polestar.guide/docs/reference/cli#polestar-profession) | Build professions.json; draft a crafting guide; build or check the generated gathering guides | | [`qol`](https://polestar.guide/docs/reference/cli#polestar-qol) | Build the Quality of Life module data (spirit healers, flight masters, reagent vendors) | | [`questdb`](https://polestar.guide/docs/reference/cli#polestar-questdb) | Build the load-on-demand quest database addon (markers, tooltips) | | [`readme`](https://polestar.guide/docs/reference/cli#polestar-readme) | Redraw the README's art: brand (docs/assets) and charts (docs/assets/charts) | | [`record`](https://polestar.guide/docs/reference/cli#polestar-record) | Polestar Recorder sessions: import, watch, draft guides, measure routes (report) | | [`regen`](https://polestar.guide/docs/reference/cli#polestar-regen) | Regenerate committed files after merging contributor PRs (compile + i18n sync + preview + media) | | [`release`](https://polestar.guide/docs/reference/cli#polestar-release) | Release tooling: patch scope check, patch preparation, release notes | | [`sim`](https://polestar.guide/docs/reference/cli#polestar-sim) | simulate and optimize leveling routes (docs/SIMULATION.md) | | [`talents`](https://polestar.guide/docs/reference/cli#polestar-talents) | Build or check Talents/Builds.lua (talent plans) | | [`trainers`](https://polestar.guide/docs/reference/cli#polestar-trainers) | Build trainers.json and Core/ClassTrainers.lua (class trainers) | | [`travel`](https://polestar.guide/docs/reference/cli#polestar-travel) | Build the travel network (flights, boats, inns, learned paths, zone crossings), import zone crossings, test routes and draft approach chains from recordings | | [`version`](https://polestar.guide/docs/reference/cli#polestar-version) | Show or set the release version (package.json, guides/pack.json and addon TOCs) | ## polestar changelog Changelog fragments in changes/: add, check, show, and build into CHANGELOG.md ```sh polestar changelog --help ``` ```output usage: node tools/polestar.js changelog <add|check|show|build> [options] Each change's changelog entry is its own file, changes/<slug>.md: front matter naming its section, then the entry as CHANGELOG.md writes it, a markdown list item wrapped at 78 columns (changes/README.md). add <players|authors|contributors> write a fragment for that section ("For players", "For guide authors", "For contributors"). The entry is --text or stdin; plain text becomes one list item, wrapped. The file is named --name, else the entry's first words; an existing file is never overwritten. check every fragment has a known section and an entry starting "- ", and CHANGELOG.md has no ## Unreleased section; names each fault, exit 1 show print the entries the next release gathers, as a ## Unreleased section; writes nothing build <version> add ## <version> (<date>) to CHANGELOG.md above the newest release, with each section that has entries, in order, and the entries by file name; then delete the fragments. Refuses when CHANGELOG.md has that version already, when there are no fragments or when one is faulty options: --root <dir> the checkout to work on (default the repository) --name <slug> add: the fragment's file name, without .md --text <entry> add: the entry (default stdin) --date <date> build: the release date, YYYY-MM-DD (default today, UTC) ``` ## polestar codex Build Lookup's Codex (data/forever/codex + the Polestar_Codex pack) ```sh polestar codex --help ``` ```output usage: node tools/polestar.js codex build [options] node tools/polestar.js codex parity [--ours <dir>] [--against <dir>] node tools/polestar.js codex attune [--addons <dir>] [--ours <dir>] Builds Lookup's Codex: every item, mount, pet, recipe, NPC, rare, quest, zone, dungeon and treasure, with where each item comes from, and the Dungeons journal. Release-safe inputs only: the data/forever/*.json tables (<era-db>, <quest-db> facts, recordings, corrections), the Forever client's tables (the newest 1.60+ build <tables> lists, cached under data/sources/<tables>/; meta.json records it), the installed <leveling-bis> (MIT) and Polestar's own guides. Writes data/forever/codex/*.json and the load-on-demand pack addon/Polestar_Codex with its LICENSE-DATA.txt; `pack` ships that folder in the release zip. --addons <dir> the Forever client's Interface/AddOns (default: detected) --build <version> <tables> Forever build (default: newest listed) --offline use cached client tables only (the newest cached build holding every table the Codex reads) --out <dir> JSON output (default data/forever/codex; with --local-extras data/local/codex-extras) --pack <dir> pack output (default addon/Polestar_Codex; with --local-extras data/local/codex-extras/Polestar_Codex) --local-extras also merge the installed <loot-db> (GPL-2.0), <rares-db> (All Rights Reserved) and data/forever/dungeons.json (DungeonJournal, no licence). For this machine only: the pack's meta says local and `pack` refuses to ship it. A release build also reads the <web-db> Forever facts cached in data/sources/<web-db>/codex/ (tools/lib/codex/<web-db>.js), when present. A release build compares itself with the last --local-extras build (when data/local/codex-extras exists), entity by entity, writes data/local/codex-parity.json and .md and records the match per kind in its meta (`parity`). `codex parity` reruns that comparison on two built folders (default ours data/forever/codex, against data/local/codex-extras). `codex attune` compares the built Dungeons journal (--ours, default data/forever/codex) with the installed Attune addon (no licence: read on this machine only, never in a build): each dungeon's quests per side and every journal quest's rewards, written to data/local/dungeon-quests-audit.md (and .json), and the attunement chains to data/local/attunements-audit.md. --ours <dir> parity: the release build (default data/forever/codex) --against <dir> parity: the internal build (default data/local/codex-extras) ``` ## polestar compile Compile a pack into its community addon folder ```sh polestar compile --help ``` ```output usage: node tools/polestar.js compile [<dir>] [options] Compiles a pack's .guide files (docs/GUIDE_FORMAT.md) into its community addon folder, as its pack.json describes it: the generated TOC, Pack.lua, MapFrames.lua, Guides.lua and LICENSE-DATA.txt, plus the pack's LICENSE file as LICENSE.txt when it has one. The pack is the one in <dir> (or --pack), else the nearest folder holding a pack.json (this one or a parent), else our guides/. Another pack is checked with our guides as context and written to <pack>/dist/<folder>/; ours to addon/Polestar_Guides/. Nothing is written when there are errors, nor without reference data (`data build`): compile then stops with one error before reading any guide, unless --no-data says to compile without it. options: <dir>, --pack <dir> the pack folder (holding pack.json) --guides <dir> our pack's guide sources in another folder (default guides/) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context for another pack (default guides/) --context-data <dir> reference data for the context (default data/forever/) --no-data compile without reference data: every quest title, NPC name and place must be given in the guide --out <dir> pack folder (default addon/<folder>/ for ours, <pack>/dist/<folder>/ for another pack) --include-drafts also compile the pack's drafts/** --format <f> diagnostics as text (default), json (one document on stdout, no summary) or github (workflow annotations) --quiet print errors only ``` ## polestar data Build reference data (data/forever/*.json) from the Era quest database, the community quest database, Blizzard map tables and recordings ```sh polestar data --help ``` ```output usage: node tools/polestar.js data build [options] Builds data/forever/*.json (quests, npcs, objects, items, zones, map-frames, factions, meta) from <era-db> (MIT), <quest-db>'s Forever store (installed with <quest-db> for the Forever client; read locally, facts only ship), Blizzard Classic Era and Forever client tables (<tables> CSV) and data/recordings/*.json. Precedence: recordings > <quest-db>-forever > <era-db>. Also spawnz.json: every NPC and object spawn's height on Eastern Kingdoms and Kalimdor from <server-db> <server-db> (GPL-3.0, facts), which the compiler gives goals at an NPC or object; with --offline and no cached dump it is left out with a warning. The same dump's quest_template gives the objective counts <quest-db> and <era-db> lack (left null without it, with a warning). Downloads are cached under data/sources/. options: --offline use cached sources only (no git, no HTTP) --<era-db> <dir> use this <era-db> checkout as is (default: cache clone) --<quest-db> <dir> <quest-db> folder (or the AddOns folder holding it) (default: auto-detected in the Forever client, as `install` finds it) --no-<quest-db> build without <quest-db> --build <version> <tables> Classic Era build (default: newest listed) --forever-build <v> <tables> Forever build (default: newest 1.60+ wow_classic_beta) --no-forever skip the Forever client tables (zones and frames from Era only) --no-web-xp skip quest XP lookups on <talents-site> / <changes-site> for quests <quest-db> has no XP for (results cached in data/sources/webxp/) --no-<web-db> skip <web-db> Forever's change notes (XP, levels) and its XP for quests still without any (the zone lists cached in data/sources/<web-db>/, when present) --recordings <dir> recordings folder (default: data/recordings) --out <dir> output folder (default: data/forever) --sources <dir> source cache folder (default: data/sources) --cap <n> max spawn points per entity per map (default 24) --built-at <iso> timestamp for meta.json (default: now, or SOURCE_DATE_EPOCH) ``` ## polestar dev Rebuild a pack into the game on every save ```sh polestar dev --help ``` ```output usage: node tools/polestar.js dev [<dir>] [options] On a pack (<dir>, --pack, or run inside one): watches pack.json and the pack's .guide files. On every save it lints, printing the diagnostics, and without errors compiles the pack into <AddOns>/<folder>, then reloads the playground when --play started one. In game, /reload shows the change; a pack's first build needs one restart of the game. A folder in AddOns is replaced only when it is empty or a generated build of the same pack. Ctrl-C stops. Without reference data (`data build`) dev stops at once with one error, unless --no-data says to build without it. options: --dest <dir> the Interface/AddOns folder (default: the one install finds) --no-game do not write into AddOns (lint, and the playground) --play also start the playground with the pack loaded (client art and SavedVariables folder as play finds them) --port <n> the playground's port (default 8077; 0 picks a free one) --no-data build without reference data: every quest title, NPC name and place must be given in the guide <dir>, --pack <dir> the pack folder, holding pack.json (default: the nearest pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) ``` ## polestar doctor Check Node, Lua, the reference data, the AddOns folder and pack.json ```sh polestar doctor --help ``` ```output usage: node tools/polestar.js doctor [<dir> | --pack <dir>] Checks what the Polestar tools need, one line per check (`ok` or `fix`, with the fix for Windows, macOS and Linux): node Node 24 or newer (every command) lua a Lua 5.1 interpreter: lua5.1, LuaJIT, or a `lua` that is 5.1 (play, playtest and record import; $LUA picks one) data the reference data, data/forever/ (every guide command) addons the game's AddOns folder: $WOW_FOREVER_ADDONS, else the client install finds (install and dev; or pass them --dest) pack.json inside a pack (or given its folder), the pack's manifest Exit code 1 when the Node or reference-data check fails, else 0. ``` ## polestar draft Generate a first-draft leveling route (.guide) from the reference data ```sh polestar draft --help ``` ```output usage: node tools/polestar.js draft --faction <Alliance|Horde> --race <Race> --zone <name> [--zone <name>...] --levels <min>-<max> [options] Generates an efficient first-draft route (docs/GUIDE_FORMAT.md) from the reference data: hub-style accepts and turn-ins, objective areas ordered by nearest neighbour + 2-opt over world distances, level gating by estimated XP. options: --class <Class> route for one class; otherwise class quests get "only <Class>" --start-quest <id> begin at this quest's giver --start <x,y> begin at these coordinates in the first zone --id <guide id> default forever/<faction>/<race>/<zones>-<min>-<max> --title <text> default "<zones> <min>-<max>" --next <guide id> header "next" --done <ids|file.guide> quests already turned in (comma list, or the turnins of a guide); repeatable --trainer <Class>:<npc> a class trainer the data does not mark; repeatable --keep-breadcrumbs end with optional accepts of breadcrumbs leading out of the area --data <dir> reference data (default data/forever) --out <file> write the guide here (default stdout) --quiet no summary on stderr Races: Human Dwarf Gnome NightElf Orc Troll Tauren Undead Skyborne; a new race takes its bit as <Name>:<bit> (e.g. Newrace:512). ``` ## polestar dungeons Import DungeonJournal: dungeon data (data/forever/dungeons.json) ```sh polestar dungeons --help ``` ```output usage: node tools/polestar.js dungeons build [options] Reads the installed DungeonJournal addon (ForeverDungeonJournal) and writes data/forever/dungeons.json: dungeons with levels, entrance and bosses, quests with chains, XP, money, rewards, shareability and where they start and end (docs/ARCHITECTURE.md). The Dungeons section of the hub reads it through the Codex (`codex build`). DungeonJournal publishes no licence: the output is gitignored and stays local. --source <dir> the ForeverDungeonJournal folder (default: WOW_FOREVER_ADDONS, else the Forever clients `install` detects) --data <dir> reference data (default data/forever) --json print the report as JSON ``` ## polestar exploration Build or check the generated exploration guides ```sh polestar exploration --help ``` ```output usage: node tools/polestar.js exploration build [options] node tools/polestar.js exploration check [options] build: rewrites guides/forever/exploration/*.guide, one guide per continent and level range plus Zephras Isle, from the Forever client's map tables (<tables> CSV, cached in <sources>/<tables>), data/forever (zones, map frames, flight masters from travel.json) and the zone order in tools/lib/exploration/spec.js. Run `compile` afterwards. check: builds the same guides in memory and exits 1 when a committed guide differs (writes nothing). --offline use cached tables only --build <version> <tables> build (default: newest listed) --data <dir> reference data (default data/forever) --sources <dir> source cache (default data/sources) --stdout print the guides instead of writing them (build only) ``` ## polestar export Print the import string of one guide ```sh polestar export --help ``` ```output usage: node tools/polestar.js export <file.guide> [options] Prints the import string of the one guide in <file.guide>: a line of text a player pastes into Polestar's Import page (/polestar import) to get the guide without installing anything (docs/GUIDE_PACKS.md, "Import strings"). The guide belongs to a community pack: the nearest folder above the file holding a pack.json, whose id is the guide id's prefix and whose license the string carries. The pack is linted first, with our guides as context, and a guide with errors is refused. A string holds one guide of at most 60 steps and 50000 characters; anything bigger, or a set of guides, is a community addon (`polestar pack`). The string goes to stdout, everything else to stderr, so `polestar export my.guide > my.txt` keeps only the string. options: --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) --quiet print errors only ``` ## polestar find Look up quests, NPCs, objects, items, inns, flight points and guides as guide lines ```sh polestar find --help ``` ```output usage: node tools/polestar.js find <text> [options] Searches the reference data (quests, NPCs, objects, items, inns and flight points) and our guides. A number matches ids exactly; other text matches names (and a guide's id and zone, an inn's or flight point's zone), ignoring case. Each result prints as a guide line ready to paste, with what it is in a comment. A quest also prints its turn-in line and its objectives (the `quest <id>.<n>` of an objective goal); a guide prints who it is for and the guide its own `next` offers; an inn prints the name `sethome` and `hearth` take, a flight point the one `getfp` and `fly` take: 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 sethome "Goldshire" # Innkeeper Farley (npc 295), Elwynn Forest 43.8,65.8 getfp "Sentinel Hill" # Sentinel Hill, Westfall, Alliance: Thor (npc 523), Westfall 56.6,52.7 next forever/alliance/02-westfall # Westfall (12-17), Alliance # its next: forever/alliance/03-darkshore `find --kind inn` and `find --kind flight` without a text list them all. Exit code 1 when nothing matches. options: --kind <k> only quest, npc, object, item, inn, flight, guide --faction <f> only what Alliance or Horde can use (quests by race, NPCs and inns by who they are friendly to, flight points by their side, guides by faction) --race <r> only what this race can use (Human, Orc, Dwarf, NightElf, Undead, Tauren, Gnome, Troll, Skyborne): quests by race, NPCs, inns and flight points by side, guides by faction and race --class <c> only what this class can use: quests and guides by class --limit <n> at most n results (default 20; a full list of inns or flight points: all) --json print the results as a JSON array: every result has kind, id, name and line; quests level, zone, x, y, starts, ends, turnin and objectives; guides levels, zone, faction, races, classes and next; inns (id: the innkeeper) names, npc, npcName, zone, map, x, y; flight points node (the full name), faction, npc, npcName, zone, map, x, y --data <dir> reference data (default data/forever/) --guides <dir> our guides (default guides/) ``` ## polestar gear Build the upgrade-advice data (Forever item stats, reward choices, stat weights) from installed addons and sims ```sh polestar gear --help ``` ```output usage: node tools/polestar.js gear build [--addons <dir>] node tools/polestar.js gear fetch build: the data behind Polestar's upgrade advice: addon/Polestar_ItemDB/Forever.lua <leveling-bis> (MIT): Forever item stats over the Era table, and quest reward choices addon/Polestar/Gear/SpecData.lua stat weight bands per spec and level (Polestar's weights blended with <gear-sim>, MIT), racial traits Reads the installed <leveling-bis> and the <gear-sim> cache under data/sources/<gear-sim> (no network). Run `itemdb build` first. fetch: refresh the <gear-sim> cache (pinned commits). --addons <dir> the client's Interface/AddOns (default: detected) ``` ## polestar i18n interface translations (status, check, sync, keys, import, fit, leaks), guide texts (guides) and the names addons (names) ```sh polestar i18n --help ``` ```output usage: node tools/polestar.js i18n <status|check|sync|keys|import|fit|leaks|names|guides> [options] Polestar's interface translations (docs/TRANSLATING.md): one file per locale, addon/Polestar/Locales/<locale>.lua, and the same for the Recorder, addon/Polestar_Recorder/Locales/<locale>.lua. Locales: deDE, esES, esMX, frFR, koKR, ptBR, ruRU, zhCN, zhTW. check and sync read both addons; status, keys and import read Polestar's unless --addon names the other. i18n status per locale: its language, status (reviewed or ai), translators, and how many keys it translates. --markdown prints a table for the README and release notes. i18n check [<locale>...] fails (exit 1) on a file Lua cannot load, a stale key (one the code no longer has), a key set twice, or a translation whose %s/%d/%1$s, |4one:many; or |c/|r/|T escapes differ from the English. Warns where a translation leaves out its glossary's word (tools/lib/i18n/glossary). Missing translations are fine: the English shows. i18n sync [<locale>...] adds the keys the code gained to each file as -- L["English"] = "" lines under their file's group, and moves translations of keys it lost to a commented block at the end. Never rewrites a translation. A locale named that has no file gets one, loaded from Core/Core.xml (the Recorder's TOC lists its own). i18n keys every interface key with where it is used. i18n import <locale> <file.lua>... merges translations written apart (a file that returns { ["English"] = "translation" }, sets L["English"], or calls ns.AddTranslations) into the locale's file: only into keys not translated yet; a broken format is refused; keys the code lacks go to the commented block at the end. i18n fit [<locale>[=<file>]...] lays out every preview scene and every Options page and tab in English and in each locale (or those named; <file> stands in for the shipped file, such as a pull request's), in the game font and in Inter, and lists the text the window cuts with an ellipsis, cuts after its last line or lets cross its edge. Text cut the same way in English (a long guide or item name) is left out. Fails (exit 1) when a locale has any. CJK is measured 1em wide. i18n leaks [<locale>...] runs the addon on the client stub in each locale (or those named) with its shipped translations, names pack and guide texts, the client's own names as placeholders, through every scene (or those --scene names), and lists the English left on screen: a Latin word of 3+ letters in a text, tooltip, chat line or menu that none of the locale's own texts uses and tools/lib/i18n/leaks-allow.json does not allow, grouped by where it came from (an untranslated interface string or guide text, a name missing from the names pack, a name Polestar.Names was not asked for, English in the code). Fails (exit 1) on any, or on a scene that errors. Scenes (--scene; default all): guide, guides, welcome, picker, options, lookup, dungeons, rares, talents, journey, tooltips, slash, more, recorder. i18n names [<locale>...] builds the names addons addon/Polestar_Names_<locale>: the names of quests, NPCs, objects, items, instances, encounters, factions and flight points (and the objectives of dungeon event quests) in each language. Per id, the first source with a name wins: the Forever client's tables (<tables>, &locale=), <web-db>'s Forever database in that language (list pages and tooltips, read only from what is already cached in data/sources/<web-db>/names), <names-db> (pinned commit and sha256s, cloned into data/sources/<names-db>), then <era-db>'s db/<locale>. Only the ids the compiled guides, the quest database, the Codex's data and the travel data name. A language left without names loses its folder. i18n guides sync [<locale>...] writes a pack's texts in other languages (docs/TRANSLATING.md, "Guide texts"): <pack>/locales/<locale>/<guide path>.lua per guide and _pack.lua for the pack's own texts, each with every text that needs words, the game's names as {kind:id} tokens, "" while not translated. Keeps every translation; one whose English the guide lost moves to a commented block at the end. Without a locale: every language the pack has a folder for. i18n guides check [<locale>...] fails (exit 1) on a texts file Lua cannot load, a translation that leaves out or adds a name token or a line break, a stale translation (its English changed or went away: the new English is named when it can be told) or a file no guide has. Missing translations are fine. i18n guides stats the texts to translate: unique texts, words and characters (tokens left out), in all and by guide folder; the names the compiler made tokens, by kind and source; the notes dropped for naming only their goal. options: --json status, check, keys, names, fit, leaks, guides: one JSON document on stdout --scene <a,b> leaks: only these scenes --guide <id,...> leaks: the guides the guide scene shows (default a few) --jobs <n> leaks: runs at a time (default one per core) --update-baseline leaks: write tools/lib/i18n/leaks-baseline.json: add the names no source has that the runs showed in English, drop the entries that no longer show --slack <n> fit: measure every glyph n times wider (1.15: about the client's own font) --pack <dir> guides: the pack (default our guides/) --data <dir> guides: the reference data (default data/forever) --markdown status: a Markdown table --no-<quest-db> names: leave <names-db> out (its base data is <quest-db>'s) --no-tables names: leave the client tables out (otherwise a missing table stops the build) --offline names: no downloads; the cached clones and tables --build <version> names: this Forever client build (default the newest <tables> lists) --sources <dir> names: the client-table and <web-db> cache (default data/sources) --ding <dir> names: this <names-db> checkout (default data/sources/<names-db>) --<era-db> <dir> names: this <era-db> checkout (default data/sources/<era-db>) --guides <file> names: the compiled guides (default addon/Polestar_Guides/Guides.lua) --questdb <dir> names: the built quest database (default addon/Polestar_QuestDB) --codex <dir> names: the Codex's data (default data/forever/codex) --travel <file> names: the travel data (default addon/Polestar/Nav/TravelData.lua) --chokepoints <file> names: the walking map's chokepoints, for the lifts' objects (default addon/Polestar_Nav/Nav/Chokepoints.lua) --out <dir> names: where the addon folders go (default addon/) --addon <name> status, check, sync, keys, import: Polestar or Polestar_Recorder only ``` ## polestar install Install the addons into the Forever client ```sh polestar install --help ``` ```output usage: node tools/polestar.js install [<dir>] [options] Installs addon/Polestar, addon/Polestar_Guides and addon/Polestar_Nav, plus the data addons Polestar_QuestDB, Polestar_ItemDB, Polestar_Codex and the names addons Polestar_Names_<locale> when they have been built (and with --recorder, addon/Polestar_Recorder) into World of Warcraft: Forever's AddOns folder. Given another pack (<dir>, --pack, or run inside one) it lints and builds that pack into <pack>/dist/<folder>/ instead and installs that folder; an existing <AddOns>/<folder> is replaced only when it is empty or a generated build of the same pack (its TOC's X-Polestar-Pack names this pack's id). Without reference data (`data build`) it stops with one error, unless --no-data says to build without it. Destination, first match wins: --dest <dir> the Interface/AddOns folder to install into $WOW_FOREVER_ADDONS same, from the environment auto-detect Wine/Proton/Faugus/Lutris/Bottles prefixes under your home folder, and native installs (C:\Program Files (x86)\World of Warcraft on Windows, /Applications/World of Warcraft on macOS); a "_forever_" or "_classic_beta_" client folder whose .flavor.info names Forever (wow_forever*) or the classic beta options: --link symlink the folders instead of copying (edit, then /reload) --recorder also install Polestar_Recorder --dry-run print what would happen, change nothing --addons <dir> source folder holding the addons (default addon/) --no-data a pack only: build it without reference data (every quest title, NPC name and place given in the guide) <dir>, --pack <dir> the pack folder, holding pack.json (default: the nearest pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) ``` ## polestar itemdb Build the Polestar_ItemDB data addon (item stats) from client tables ```sh polestar itemdb --help ``` ```output usage: node tools/polestar.js itemdb build [options] Writes the load-on-demand data addon addon/Polestar_ItemDB (Items.lua + TOC): stats of every equippable Classic Era item (item level, required level, inventory type, armor, weapon damage and speed, primary stats and the equip bonuses Polestar.Gear scores), from Blizzard client tables (<tables> CSV: ItemSparse, Item, ItemEffect, SpellEffect). Size budget: 1024 KiB. --offline use cached tables only --build <version> <tables> Classic Era build (default: newest listed) --sources <dir> source cache (default data/sources) --out <dir> default addon/Polestar_ItemDB ``` ## polestar lint Check .guide files without writing output ```sh polestar lint --help ``` ```output usage: node tools/polestar.js lint [<dir>] [options] Runs every compile check (syntax, data lookups, cross-guide validation) on a pack without writing anything: the pack in <dir> (or --pack), else the nearest folder holding a pack.json (this one or a parent), else our guides/. Exit code 1 on errors. Another pack is checked with our guides as context (its `next` and turn-ins see our chains; their own diagnostics are not shown). When the simulator has cached a world (`sim`), also warns on leveling goals its solo filter excludes. Without reference data (`data build`) lint stops with one error before reading any guide, unless --no-data says to check without it. options: <dir>, --pack <dir> the pack folder (holding pack.json) --guides <dir> our pack's guide sources in another folder (default guides/) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context for another pack (default guides/) --context-data <dir> reference data for the context (default data/forever/) --no-data check without reference data: every quest title, NPC name and place must be given in the guide --sim <dir> simulator cache with world-<faction>.json (default data/sim/, used only with the default --data) --include-drafts also check the pack's drafts/** --format <f> text (default), json (one document on stdout, no summary) or github (workflow annotations) --quiet print errors only ``` ## polestar maps Build world map data (zone level ranges, zone art overlays) ```sh polestar maps --help ``` ```output usage: node tools/polestar.js maps <build|overlays> [options] build: zone level ranges for the world map (hostile creature levels per zone, spawn-weighted P10..P90; heuristic in tools/lib/maps/zonelevels.js) -> addon/Polestar/Maps/ZoneLevels.lua. --data <dir> data/forever (npcs.json, zones.json) --lua <file> output (default: addon/Polestar/Maps/ZoneLevels.lua) overlays: every world map overlay of every zone map (the explored-area paintings), from the client's DB2 tables via <tables>, so the zone art shows a map without fog of war -> addon/Polestar/UI/ZoneArtOverlays.lua. --build <ver> client build (default: 1.60.1.70338, the Forever client) --sources <dir> source cache folder (default: data/sources) --offline use cached tables only --lua <file> output (default: addon/Polestar/UI/ZoneArtOverlays.lua) ``` ## polestar media Regenerate the addon textures (tools/media/*.js -> addon/Polestar/Media) ```sh polestar media --help ``` ```output usage: node tools/polestar.js media [generator ...] Runs every generator in tools/media/ (or only the named ones) against addon/Polestar and lists the files written. ``` ## polestar nav Terrain navigation from the client geometry (build the grid, route between map points) and Polestar's walking router with its maps (Polestar_Nav) ```sh polestar nav --help ``` ```output usage: node tools/polestar.js nav build [--continents 0,1] [--force] [--offline] [--workers N] [--out <dir>] [--product ] node tools/polestar.js nav path <map> <x>,<y> <map> <x>,<y> [--class C] [--level N] [--frame era|forever] [--json] [--dir <dir>] node tools/polestar.js nav aids [--out <file>] [--lua <file>] [--report] [--continents 0,1] [--workers N] [--reference <file>] [--dir <dir>] node tools/polestar.js nav pack [--cells N] [--date <YYYY-MM-DD>] [--dir <grid dir>] [--layers <dir>] [--out <dir>] | nav pack --check [--out <dir>] node tools/polestar.js nav check [--out <dir>] node tools/polestar.js nav eval [--nav <Polestar_Nav dir>] [--baseline <dir or eval .json>] [--routes <file>] [--sweep] [--style fastest|balanced|roads] [--out <file.json>] node tools/polestar.js nav layers roads [--c 0|1] [--allowlist] [--offline] [--product ] node tools/polestar.js nav layers hubs [--dir <grid dir>] [--offline] build the navigation grid of every continent map-frames.json names (or --continents): client geometry per ADT tile through the CASC cache (data/sources/casc), walkable surfaces, links, regions and the abstract graph, in worker threads, written to data/local/nav (--out). A tile already built is kept unless --force; --offline only reads cached client files. path a route between two map points: <map> a uiMapID, <x>,<y> percent on it (the Era frame unless --frame forever). Prints yards, seconds by class, falls and the simplified points (map percent of the first map); --json prints the whole result. --class (e.g. Druid) and --level (default 10) choose the movement profile. aids the arrow's aids from the grid (--dir, default data/local/nav; tools/lib/nav/aids.js): zone crossings, open borders and approach chains in the crossings schema, validated, written to aids.json in the grid's folder (--out: another file). --lua writes them as a Crossings.lua for a local test (never into addon/Polestar_Travel); to build a test copy of the data addon: node tools/polestar.js travel build --offline --crossings data/local/nav/aids.json --travel-addon <test folder> --json <test folder>/travel.json --lua <test folder>/TravelData.lua Pockets are tested in --workers threads (default: up to 6). --report also plans every consecutive pair of located goals in our guides with the addon's planner without and with the aids and writes aids-report.json and aids-report.md next to --out, comparing with the reference crossings file (--reference, default data/local/crossings.json; read only). pack Polestar's walking maps of maps 0 (Eastern Kingdoms), 1 (Kalimdor) and 2991 (Zephras Isle) from the grid (--dir, default data/local/nav; it needs grid version 4: nav build --out data/local/nav4, then --dir data/local/nav4) and the ground layers (--layers, default data/local/nav-layers: roads and hubs, from nav layers), in maps format 2: a ground class per surface (road, gentle or steep slope, indoor, indoor city, Alliance and Horde hubs) and every graph edge priced per faction (tools/lib/nav/pack.js, grown from a port of Shortest Path Forever's (Cillian Berragan) gen_nav.py and pack_nav.py), with Chokepoints.lua (lifts, bridges, gates, tunnels, cave and building mouths, passes; tools/lib/nav/chokepoints.js), into addon/Polestar_Nav (--out): Nav/Nav<map>*.lua, Nav/Chokepoints.lua, PACK.json (grid build, cells, date, sizes, sha256 of every file) and Nav/Nav.xml. --cells cuts each ADT tile into N x N cells (default 128, 4.17 yd); --date dates the generated headers (default today; the same grid, layers, cells and date give the same bytes). --check only compares the folder with PACK.json. check the walking maps match PACK.json and Nav/Nav.xml lists them. eval the walking router run standalone (LuaJIT, else Lua 5.1; a folder without its own Routing takes the repository's) on a folder's maps (--nav, default addon/Polestar_Nav): the route corpus (--routes, default tools/lib/nav/eval/routes.json) with each route's metrics (yards, seconds, the share of the drawn line our grid at data/local/nav3 cannot walk, off-road share, yards in hostile hubs, steepest climb, indoor yards on data/local/nav4's indoor surfaces outside the capitals, yards per zone, swumYards: yards over water; a layer not built yet reads n/a) and expectations; a route with a level (the character's) is priced with zone danger as the addon prices it (x3 at 4+ levels above; more than 10 above x20; the start's and goal's zones exempt; tools/lib/maps/zonelevels.js), and a route's own danger ({ "<uiMapID>": multiplier }) is laid over it; --sweep also searches, per zone with located guide goals and per side, from the zone's flight master (else its first goal) to every goal. --baseline runs the same on another folder (or reads an earlier --out report) and judges the acceptance checks A1-A8; exit 1 when one fails. --style prices every search in a route style (fastest, balanced or roads; default balanced), the baseline's too. --out writes the whole report. layers the ground layers under data/local/nav-layers. roads: per grid column, the share of the ground the client paints with a road texture (tools/lib/nav/layers/roads.js), from each tile's tex0 ADT (its texture layers and alpha maps) and the reviewed allowlist tools/lib/nav/layers/road-textures.json, texture names from the wowdev community listfile (downloaded once to data/sources/listfile; build time only), for maps 0 and 1 (--c: one of them), into roads/<c>/<col>_<row>.bin. --allowlist instead rewrites the allowlist from every texture both maps' tiles use (never with --c): one whose tileset path names a road, path, cobble, street or trail; one naming dirt, footprint, brick or gravel, or listed under reviewed, when its shape is a road's (most of its weight in long, narrow, elongated strips); with every measure (review it). hubs: each faction's towns and outposts (tools/lib/nav/layers/hubs.js): its guards and service NPCs (quest givers, vendors, trainers, flight masters, innkeepers, bankers, repairers) from the <server-db> <server-db> spawns and creature templates, judged by the client's FactionTemplate table, clustered, named by the AreaTable area under them (the grid's area ids, --dir, default data/local/nav4), into hubs.json. ``` ## polestar new Start a pack in a new folder from the template ```sh polestar new --help ``` ```output usage: node tools/polestar.js new [dir] [options] Starts a pack in [dir] (default: the current folder), which must be empty or missing (run it before `git init`: a folder holding .git is not empty): pack.json, an example guide, README.md, LICENSE, .gitignore, VS Code tasks, AGENTS.md / CLAUDE.md for AI assistants, the polestar-guide-pack skill (skills/ in this clone) in .agents/skills/ and .claude/skills/, and a GitHub workflow and a dev container that install Polestar from this clone's origin remote. The origin must be an http(s) or SSH URL; it is written as https, without a user name, password, query or fragment. With no origin, or any other kind, those two are left out. Asks for each value not given, unless --yes accepts the defaults; without a terminal to ask in, it writes nothing and exits 1 unless --yes or all four values are given. options: --id <id> pack id, e.g. joe-routes (default: from the folder name) --title <text> pack title (default: from the id) --author <name> author (default: git config user.name) --license <spdx> licence, e.g. CC-BY-4.0, CC0-1.0, MIT, GPL-3.0-only (default CC-BY-4.0) --yes accept the defaults for every value not given ``` ## polestar pack Build the release zips, or a community addon's zip ```sh polestar pack --help ``` ```output usage: node tools/polestar.js pack [<dir>] [options] In the repository: compiles our guides, then writes dist/Polestar-<version>.zip (Polestar, Polestar_Guides, Polestar_Nav, Polestar_Codex, the names addons Polestar_Names_<locale>, and Polestar_QuestDB / Polestar_ItemDB when built), dist/Polestar_Recorder-<version>.zip and dist/SHA256SUMS. Polestar/ in the zip also carries LICENSE and README.txt (install steps), Polestar_Recorder/ the LICENSE. The Codex must be built first (`codex build`) from release-safe inputs: pack stops on a missing Codex or a --local-extras one. Given another pack (<dir>, --pack, or run inside one): lints and builds it with our guides as context, then writes <pack>/dist/<folder>-<version>.zip holding its addon folder, the version taken from pack.json. Both are byte for byte reproducible. Without reference data (`data build`) pack stops with one error; a pack can be built without it with --no-data. options: <dir>, --pack <dir> the pack folder, holding pack.json (default: the nearest pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) --guides <dir> our guide sources (default guides/; not with a pack folder) --addons <dir> addon source folder (default addon/) --dist <dir> output folder (default dist/, <pack>/dist/ for a pack) --no-data a pack only: build it without reference data (every quest title, NPC name and place given in the guide) ``` ## polestar planner Plan routes: play a guide on the map and edit it (local page, MCP) ```sh polestar planner --help ``` ```output usage: node tools/polestar.js planner [<pack dir>...] [--port 8078] [--art <dir>] [--nav <dir>] [--open] node tools/polestar.js planner art [--continents 0,1] [--no-zones] [--force] [--offline] [--concurrency N] [--out <dir>] node tools/polestar.js planner mcp [<pack dir>...] [--port 8078] [--art <dir>] [--nav <dir>] The route planner: a local page (http://127.0.0.1:8078) that plays a guide on the real map, step by step, with the clock, the XP and the quest log, and edits the .guide files (fields, steps, dragged waypoints): every edit is written to the file at once. Our guides/ are always loaded; other packs (a folder holding pack.json, as arguments or --pack) come after them. Inspired by Nivek_Gaming (@Nivek_Gaming on X): thank you, Nivek. --port <n> port on 127.0.0.1 (default 8078; 0 picks a free one) --art <dir> the map art (default data/local/planner/art) --nav <dir> the navigation grid walks are routed on (default data/local/nav; built by node tools/polestar.js nav build; without it walks are straight lines) --data <dir> reference data (default data/forever/) --pack <dir> one more pack folder --open open the page in the browser planner art: fetch the Forever client's minimap blocks and zone maps from <tables> (cached under data/sources/casc/) and build the art the page draws into data/local/planner/art/ (never committed). --continents <c,..> only these continents (map ids, e.g. 0,1; default all) --no-zones skip the painted zone maps --force rebuild files that exist --offline use only cached downloads --concurrency <n> parallel downloads (default 8) --product <tables> product (default wow_classic_beta) --out <dir> output folder (default data/local/planner/art) planner mcp: the planner's commands as an MCP server on stdin/stdout (JSON-RPC, one message per line). It uses the planner running on --port, so an agent's edits show live in the open page, else starts one itself. ``` ## polestar play Play with the real addon in the browser (local playground) ```sh polestar play --help ``` ```output usage: node tools/polestar.js play [<dir>] [--port 8077] [--art <dir>] [--fresh] Starts a local server running the real Polestar, Polestar_Guides and the built data packs against the simulated world, and prints its URL. Click, hover, scroll, drag and type in the game screen; the side panel sets the character, moves them, plays guide goals and tweaks the look live. Given another pack (<dir>, --pack, or run inside one) that pack is linted, built into a temp folder and loaded after our guides. --port <n> port on 127.0.0.1 (default 8077; 0 picks a free one) --art <dir> local client art (default $POLESTAR_CLIENT_ART, else /tmp/polestar-art when present); served locally only --no-art draw without client art --fresh forget the character and SavedVariables (data/play/, or $POLESTAR_PLAY_DATA) <dir>, --pack <dir> the pack folder, holding pack.json (default: the nearest pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) ``` ## polestar playtest Play a pack's guides to the end for every class ```sh polestar playtest --help ``` ```output usage: node tools/polestar.js playtest [<dir>] [options] Plays a pack's guides to the end in the real addon against a simulated world (needs Lua 5.1; `doctor` checks): each guide once per class it branches on (`only`) plus one class it never names, as each race that can reach it. The pack is the one in <dir> (or --pack), else the nearest folder holding a pack.json, else our guides/. Another pack plays with our guides loaded too: a guide whose `next` names one of ours must land on it with something to do, and the guide it lands on must apply to the character (its race, class and faction). --filter plays only the guides whose file or id contains its text. One line per guide, race and class (only pairs that exist in the game): ok joe/elwynn (Human Warrior) stuck joe/elwynn (Human Paladin) at step 3 "Kobolds": goal 1 (kill "Kobold Vermin") stays active stuck joe/elwynn (Human Mage) at hand-over to forever/alliance/02-westfall: <why> stuck joe/elwynn (Human Mage) at hand-over to forever/alliance/dwarf-gnome/01-dun-morogh: no Human can follow it fail joe/elwynn (Human Warrior): no location for step 2 goal 1: accept 33 Exit code 1 when any guide is stuck or fails, nothing was played, or the pack does not compile. options: --filter <text> play only the guides whose file or id contains it --class <c> play only this class (e.g. Warrior), in every guide <dir>, --pack <dir> the pack folder (holding pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, loaded beside another pack (default guides/) --context-data <dir> reference data for the context (default data/forever/) ``` ## polestar preview Render the guide window, picker and options to docs/preview/*.svg ```sh polestar preview --help ``` ```output usage: node tools/polestar.js preview [scene ...] Runs the real Theme and UI Lua against a geometry-recording client stub with sample guides and writes SVGs to docs/preview/. Scenes: guide Guide window: a field step; a hub, one person at a time (first, then the second); the tip opened guide-picture Step pictures: a community addon's screenshot under the step's tip, scaled to the window; a picture with no tip, at most 160 high (Polestar's own textures stand in for the screenshots) skins-guide Skins: the guide window in Polestar, Halo and Hearth skins-states Skins: a hub step, transparent and the header menu, in Halo and Hearth guide-transparent Transparent mode over a bright world: at rest, and with the cursor over it guide-compact Compact mode: standard and transparent guide-states No guide open, guide complete, out-levelled banner, header menu route-choice Choose your path: an Undead after Tirisfal Glades; the guide window while the choice waits welcome The welcome, once per new character after login: Hello, Make it yours and Route style (on the account's first), Your first guide guide-professions Profession and reputation guides: chosen trainer with alternatives, skill bar, reputation bar guide-smart Smart logic: training reminder, an unavailable quest, a farm spot with alternatives guide-along Along the way: the kobolds and wolf meat of an `along` step under the steps after it; with Up next open journey The journey under the focus: walking to the Great Lift (36:48, 8.0k yd, the lift untimed); on the lift, timed; collapsed to its totals guide-group Group content: elites and an author's group size; a dungeon run said once; the guide menu's Group chip class-not-yet A Class guide opened too early: the guide window says from which level and who starts it; the guide menu's row says "From level 20" picker-class Class guides in the guide menu: the details lead with what the chain gives and why (a mount spell; a choice of rare items; a demon and its soul bag) report Report a problem (the guide window's bug button): what went wrong, the right spot to mark, the report for the Polestar Discord, or a filled-in issue on GitHub; the invite on its own (the sidebar's Discord mark) guide-ellesmere With EllesmereUI: Polestar follows its accent and font by default; every colour stays editable schemes Colour schemes on the guide window: Dusk (default), Night, Graphite, EllesmereUI; and your own ground, accent and brightness schemes-options Options > Appearance in each scheme: Dusk, Night, Graphite, and EllesmereUI installed (its scheme, follow toggles, its font offered) schemes-picker The guide menu in Dusk (default), Night, Graphite, and EllesmereUI with its purple accent options Options: Guide (Window, Arrow & routes, Automation) skins-options Skins: Options in Halo and Hearth (Guide, Window; Appearance, Windows with the Skin setting) gamepad-guide Focus mode on the guide window (Browse the guide with the gamepad): the first open goal; down a line on a hub step; up into the navigator with PlayStation buttons gamepad-options Options with a gamepad: the Gamepad page (a dropdown focused, D-pad left / right steps it), a binding row on its Key bindings tab (chips for buttons, chords and keys), and a slider with PlayStation buttons; B sits on the close button gamepad-hub The guide menu with a gamepad: the focus starts on the selected guide (X loads it, LB / RB step the sections); a dropdown's choices in the shared menu, the current one focused options-appearance Options: Appearance (Colour & type, Windows, Arrow); then a look of your own: an accent border 2px thick, no band, no shadow, your own arrow colours options-modules Options: pages the modules fill: Map, Questing, Discovery, Quality of Life options-more Options: Recorder and About, at the foot of the list options-integrations Options: Integrations: <quest-db>'s section while <quest-db> is loaded; with no supported addon, one line says so options-packs Options: Community guides: ours and a community addon on, one with problems and its report, one turned off, one too new; where suggestions come from options-search Options: a module's registered controls, search across pages, and a crowded sidebar in the game font that scrolls clear of the version skins-more Skins: the welcome, the journey and the route choice in Halo, then in Hearth skins-dungeons Skins: the dungeon journal in Halo and Hearth skins-picker Skins: the guide menu in Halo and Hearth skins-new Skins: the welcome's Route style page, Options' Community guides, the gamepad's focus and hints, and the report window, in Halo and Hearth skins-game-forever Skins: forever: the guide window (a hub step, the menu), Options (Guide, Appearance, Community guides, Gamepad), the welcome's Route style page and the report window skins-game-blizzard Skins: blizzard: the guide window (a hub step, the menu), Options (Guide, Appearance, Community guides, Gamepad), the welcome's Route style page and the report window skins-game-classic Skins: classic: the guide window (a hub step, the menu), Options (Guide, Appearance, Community guides, Gamepad), the welcome's Route style page and the report window picker-levels Guide menu: Elwynn Forest selected for a level 4 Human at 1,800 of 2,100 XP, its levels chip hovered: the XP its turn-ins and kills give, a bar from level 4 into 5, what was counted; the same in the Halo skin, the Graphite scheme and an accent of your own; the guide set to start at 6: level 6 recommended, the sums from there picker Guide menu: Home (Continue, Suggested) with the details; Leveling folders by faction and band picker-packs Guide menu: a community addon under Community guides, its guide credited to its author picker-views Guide menu: Current (the open tabs) and Recent (the last guides loaded) picker-search Guide menu: Favourites (star on), and a search with its first result selected picker-art Guide menu zone art: the Durotar starter at its first stop; The Barrens (19–24) open at step 13, on that step hub The hub: sections on the rail (Guides, Lookup, Dungeons, Rares) with Options at its foot; the sidebar holds the wordmark, the search and the section's own index on one edge lookup Lookup in the hub, over the sample Codex: "saber" with a vendor mount selected; the Winterspring Frostsaber, reputation or a limited vendor, its best source chosen; an empty search: the recent lookups lookup-retired Lookup: "frostsaber" with the retired Reins of the Frostsaber last, dimmed with its chip; its details for reference, no guide lookup-drop Lookup: Deathcharger's Reins for a level 4 character, a rare drop out of reach, saying why lookup-missing Lookup without the Codex pack: opened; a search only the Codex could answer; a guide still found picker-codex Guide search in the hub: the guides that match, then what the Codex holds (a few per kind) and a way into Lookup gear-pick The reward pick under turn-in goals: an upgrade (chevron, gain) and, with nothing better, the best of the choices quest-rewards The game's reward panel: a green arrow on each upgrade, the one to take framed in the accent; with no upgrade, the coin on the one that sells for most xp-bar The game's XP bar with the level the guide wants you to reach: the next level; four levels away; the setting under Quality of Life, Trackers quests-map Quest markers on the world map: givers, kill, item (drops, crate, vendor), object and exploration objectives, a turn-in; then a guide step highlighting its quests and dimming the rest quests-minimap Quest markers on the minimap around the player: nearby objectives, givers and the turn-in; then with the guide step highlighted travel Travel: the arrow (Arrow scale 160%) on a route into the next zone, its leg captioned ("Go to Westfall"), and the trail dots on the world map from the player to the zone crossing; then the arrow where the game gives no position (the Deeprun Tram) nav-areas Spawn regions: Teldrassil's The Balance of Nature, the arrow on the Fel Moss. On the world map every place the step's mobs and objects spawn is a region: the Grells' woods west and north of Aldrassil and a lone Grell's place in the arrow's colour, the Nightsabers', Thistle Boars' and Gnarlpine Totems' regions fainter; on the minimap the Fel Moss region around the player, cut at the rim dungeons Dungeons in the hub: Home for a level 20 Tauren (the dungeons for your level, faction filter Horde); Wailing Caverns, its Quests tab dungeons-xp Wailing Caverns: the levels its quests are worth, the chip beside the name hovered: at 19,800 of 23,200 XP into level 20 they carry the Tauren into 21; at 27 the lowest gives a tenth of its XP dungeons-bosses Wailing Caverns: the Bosses tab (kill order and the quests each serves) and the Map tab (the entrance and the quest givers near it); All dungeons with the filter on All dungeons-attune The Attunement tab: Wailing Caverns' attunement with the first quest done and the second in the log, and "Guide me through it"; the Deadmines' keys with the filter on All dungeons-small The hub at its smallest (menu scale 0.7): Wailing Caverns, Quests; without the Codex pack rares Rares in the hub: Elwynn Forest's rares by zone, Thuros Lightfingers with its signature drop, its spawns and when it was last met; the Seen list rares-toast The rare alert over the world: a rare on the minimap at its distance; a rare elite in sight; a treasure ``` ## polestar profession Build professions.json; draft a crafting guide; build or check the generated gathering guides ```sh polestar profession --help ``` ```output usage: node tools/polestar.js profession build [options] node tools/polestar.js profession draft <Profession> [options] node tools/polestar.js profession gathering build|check [options] build: writes data/forever/professions.json from the Forever client's tables (<tables> CSV, wow_classic_beta 1.60+: SkillLine, SkillLineAbility, SpellName, SpellEffect, SpellReagents, SpellTotems, SpellCastingRequirements, SpellFocusObject, ItemSparse, Item, ItemEffect, ItemXItemEffect; the newest Classic Era build fills the spells and items they lack) and data/forever/{items,npcs,objects}.json. Trainers come from a curated name list checked against npcs.json. --offline use cached tables only --build <version> <tables> Forever build (default: newest listed) --data <dir> reference data (default data/forever) --sources <dir> source cache (default data/sources) --out <file> default <data>/professions.json draft: prints (or writes) a 1-300 guide for a crafting profession (Alchemy, Blacksmithing, Enchanting, Engineering, Leatherworking, Tailoring): the cheapest sensible recipe chain by expected crafts and material cost, with trainer visits, recipes to learn, materials to buy or gather, and skill checkpoints at 75/150/225/300. --data <dir> reference data (default data/forever) --out [file] write the guide (default guides/forever/professions/<name>.guide) --quiet no plan summary on stderr gathering build: rewrites the six generated guides in guides/forever/professions (mining, herbalism, skinning, fishing, cooking, first-aid) from their specs in tools/lib/professions/gathering/specs.js and data/forever (node spawns, professions, items, npcs, objects). Run `compile` afterwards. gathering check: builds them in memory and exits 1 when a committed guide differs (writes nothing). --data <dir> reference data (default data/forever) --stdout print the guides instead of writing them (build only) ``` ## polestar qol Build the Quality of Life module data (spirit healers, flight masters, reagent vendors) ```sh polestar qol --help ``` ```output usage: node tools/polestar.js qol build [--data <dir>] [--lua <file>] --data <dir> data/forever (npcs.json, map-frames.json) --lua <file> output (default: addon/Polestar/QoL/Data.lua) ``` ## polestar questdb Build the load-on-demand quest database addon (markers, tooltips) ```sh polestar questdb --help ``` ```output usage: node tools/polestar.js questdb build [options] Builds the load-on-demand quest database addon (addon/Polestar_QuestDB) from data/forever: quests (levels, race/class masks, faction, givers, enders, prerequisites, objectives), NPCs and objects (spawn clusters per map, covering every known spawn; Era frames) and items (drop sources, objects, vendors). Prints the Lua size and an estimate of the in-game memory it costs once loaded. --data <dir> data/forever (quests, npcs, objects, items, map-frames) --out <dir> output addon folder (default: addon/Polestar_QuestDB) --radius <yd> spawn cluster radius (default 70) --droppers <n> NPC drop sources kept per item (default 8) --json print the stats as JSON ``` ## polestar readme Redraw the README's art: brand (docs/assets) and charts (docs/assets/charts) ```sh polestar readme --help ``` ```output usage: node tools/polestar.js readme brand node tools/polestar.js readme charts --draft <dir|git rev> [options] brand: rewrites docs/assets/{banner-dark,banner-light,emblem,logo,download,avatar}.svg, drawn in code from the emblem geometry and the wordmark fonts, and with rsvg-convert (librsvg) installed the CurseForge listing's PNGs in docs/curseforge/images (the avatar, the banner and the charts); without it, prints the rsvg-convert commands to run. charts re-exports its two PNGs. charts: rewrites docs/assets/charts/{levels,starts}.svg. Scores the guides under the simulator's model (as `sim compare` does) against an earlier set of them; the best route found and the consensus route are drawn when the results in --sim were searched on the world being scored. --draft <dir|rev> the earlier guides: a guides folder, or a git revision whose guides/ is used. The README's charts use v0.1.0, the first release. --draft-label <text> how the charts name them (default: "Polestar <x.y.z>" for a release tag vX.Y.Z, else "Earlier guides") --sim <dir> simulator outputs: world, params, results, consensus (default data/sim) --guides <dir> the guides to score (default guides/) ``` ## polestar record Polestar Recorder sessions: import, watch, draft guides, measure routes (report) ```sh polestar record --help ``` ```output usage: node tools/polestar.js record <subcommand> [options] import Archive and convert the recorder's SavedVariables: raw copy -> data/recordings/raw/<timestamp>-<account>.lua, one JSON per session -> data/recordings/<session>.json (a session already on disk keeps the longer event list); --anonymize for a file a player sent in: no name or realm (a hash keys the character), no raw copy watch Import again whenever the client rewrites the file (keeps sessions safe from the cold-start SavedVariables reset) draft <session|file> Write a draft guide from a session key or JSON file to <pack>/drafts/<faction>-<race>-<date>-<time>.guide: the pack is --pack, else the nearest pack.json, else our guides/; another pack's draft id starts with "<pack id>/" list List imported sessions report Measure the guides from recorded play (Polestar + Recorder): per step passes, median/p75 time, XP, XP/hr, combat share, deaths, turn-ins, travel; per guide time, levels, XP/hr; the slowest steps, steps far over the guide's median step time, and detours (far travel for little XP) options: --sv <file> SavedVariables file to use (repeatable); skips auto-detection --wtf <dir> WTF folder to search (default: the detected Forever client's, e.g. <Wine prefix>/drive_c/Program Files (x86)/World of Warcraft/_forever_/WTF; POLESTAR_WTF overrides) --out <dir|file> import/watch/list: recordings folder (default data/recordings); draft: output .guide file or folder (default <pack>/drafts) --pack <dir> draft: the pack the draft belongs to --recordings <dir> draft/report: where sessions are read (default data/recordings) --interval <ms> watch: polling interval (default 1000) --force draft: overwrite an existing draft --anonymize import: drop character names and realms (see import) --guide <text> report: only guides whose id or title contains <text> --top <n> report: length of the ranked lists (default 10) --json report: print the report as JSON ``` ## polestar regen Regenerate committed files after merging contributor PRs (compile + i18n sync + preview + media) ```sh polestar regen --help ``` ```output usage: node tools/polestar.js regen [--no-compile] [--no-i18n] [--no-preview] [--no-media] Regenerates the four sets of committed generated files that contributors do not commit themselves: compile addon/Polestar_Guides/Guides.lua from guides/ and data/forever i18n sync locale files from the addon’s English strings preview docs/preview/*.svg from the addon’s Lua (no reference data) media addon/Polestar/Media/*.tga from tools/media/ (no reference data) compile needs the reference data (data/forever); the rest do not. Pass --no-<step> to skip a step. Run this after merging contributor PRs that touch guides/ or the addon’s Lua, and before every feature release. ``` ## polestar release Release tooling: patch scope check, patch preparation, release notes ```sh polestar release --help ``` ```output usage: node tools/polestar.js release <scope|patch|notes> [args] release scope [--base <ref>] [--root <dir>] [--files <path|->] Prints each changed path a patch release may not carry, one a line, and exits 1 if there is one. A patch may change only: guides/** addon/Polestar_Guides/** tests/guides-*.test.js tools/lib/data/corrections.json CHANGELOG.md changes/** The paths are read from --files (one a line, - for stdin; `git diff --name-status` lines work too), else from `git diff --name-only <base>...HEAD` in --root, renames giving both paths. --base defaults to the newest v* tag reachable from HEAD. release patch <x.y.z> --root <dir> [--from <tag>] [--zip <file>] [--data <dir>] [--data-built] Prepares a patch release on the hotfix/ checkout at --root with that checkout's own tools: stops on paths the patch may not carry, or on a changed tools/lib/data/corrections.json (run `data build` there first, then --data-built); puts back Polestar_Codex and Polestar_QuestDB from the release zip of --from (default the newest v* tag in --root; downloaded with gh unless --zip names it); sets the version; lints and compiles; and lists the compiled guides that differ from --from, warning about those whose sources did not change. --data <dir> reference data for lint and compile (default this checkout's data/forever/, or --root's with --data-built) release notes <x.y.z> [--root <dir>] [--out <dir>] Writes the version's CHANGELOG.md section as dist/notes-<v>.md (GitHub), dist/notes-curseforge-<v>.md and dist/notes-discord-<v>.txt. Each has a placeholder for the intro, marked [[REPLACE, to replace before publishing. --root <dir> folder holding CHANGELOG.md (default the repository) --out <dir> where to write (default <root>/dist/) ``` ## polestar sim simulate and optimize leveling routes (docs/SIMULATION.md) ```sh polestar sim --help ``` ```output usage: node tools/polestar.js sim <command> [options] sim world [--faction F] [--rebuild] build/cache the world model (data/sim/world-<faction>.json) sim walks [--faction F] [--radius Y] [--workers W] route the world's walks with the walking router (data/sim/walks-<faction>.json; run, robust, compare, bench and consensus use them) sim calibrate [--fdj DIR] fit parameters to quest data and recordings sim run --faction F [--race R] [--class C] [--paths N] [--workers W] [--seed S] [--dungeons] [--jobs J] [--anneal A] [--max-paths M] [--objective time|smooth] [--param K=V ...] [--tag T] sim robust --faction F [--race R] [--class C] [--draws K] [--top N] [--objective O] robustness of the top routes sim compare --faction F [--race R] [--class C] [--guides DIR] [--pack DIR | DIR] [--to 10,20,30] [--with-optional] [--objective O] Polestar's routes vs the best found, same model sim bench --faction F [--race R] [--class C] bracket table: zones, levels, quests per 10 levels sim export --result <file> --out <dir> zone-by-zone skeleton guides + visits.json for authors sim consensus --faction F [--dungeons] [--evals N] [--objective O] one 12-60 route shared by the faction's starts (+ exports) Without --race, run/robust/compare/bench cover every start of the faction (Horde: Orc, Tauren, Undead, Skyborne; Alliance: Human, Dwarf, NightElf, Skyborne). Class defaults to none ("any": class quests excluded, class factor 1); with --class the class's quests and kill-speed prior are used, and compare/bench write their own files so the class-agnostic ones stay. options: --data <dir> reference data (default data/forever) --sim <dir> simulator outputs (default data/sim) --fdj <dir> calibrate: ForeverDungeonJournal folder (default: the installed one) --class <name> Warrior, Paladin, Hunter, Rogue, Priest, Shaman, Mage, Warlock or Druid: score for that class (run/robust/compare/bench); default none ("any") --band <levels> level width of the world's quest packages (default 5; a new width rebuilds the world) --guides <dir> compare: Polestar guides folder to score (default guides/), e.g. an old copy --pack <dir> compare: also score this pack's chain (or name the pack folder as the one argument; default: the nearest pack.json); after our chain up to its first level when it starts above 1; written to data/bench/compare-<faction>-<race>-<pack id>.json --to <levels> compare: levels to show time to (default 10,20,30,40,50,60) --with-optional compare/bench: also score the guides' optional goals (default: only what a guide requires; elite and dungeon quests stay out either way) --jobs <n> run: search jobs per round (default 32) --anneal <n> run: annealing evaluations per job (default 6000) --max-paths <n> run: hard cap on evaluated routes (default 3x --paths) --dungeons run/robust/consensus: the dungeon-inclusive family (needs data/forever/dungeons.json) --objective <o> run/robust/compare/consensus: what the search optimises (default time): time = the fastest route; smooth = fewer zone changes, returns into zones left earlier and returns to spots already worked (docs/SIMULATION.md); smooth results are their own files (horde-orc-any-smooth.json) --param <k=v> run/robust/compare/consensus: set a model parameter (params.js), after the objective's preset; repeatable (--param grindWeight=6 --param zoneReturn=0) --tag <name> run/robust/compare/consensus: a result file variant, e.g. --tag g6 writes horde-orc-any-smooth-g6.json (and robust/compare/consensus read and write it) --radius <yards> walks: route every pair of points up to this far apart (default 4000) --no-walks run/robust/compare/bench/consensus: walk the straight line × detour even when data/sim/walks-<faction>.json is there --offline never download the QuestXP table --quiet less output ``` ## polestar talents Build or check Talents/Builds.lua (talent plans) ```sh polestar talents --help ``` ```output usage: node tools/polestar.js talents build|check [options] Resolves the talent plans in talents/forever/*.json (one file per class, one pick per level, by talent name) against the Forever client's trait tables (<tables>, build 1.60.1.70450, cached under data/sources/<tables>/), replays every pick under the client's rules (one point a level from 10, tier gates, arrows; arrows need their source at full rank), and writes every class into addon/Polestar/Talents/Builds.lua. check rebuilds in memory and fails if the file differs or a plan breaks a rule. options: --plans <dir> plan sources (default talents/forever/) --out <dir> output folder (default addon/Polestar/Talents/) --sources <dir> download cache (default data/sources/) --build <ver> client build (default 1.60.1.70450) --offline use cached tables only ``` ## polestar trainers Build trainers.json and Core/ClassTrainers.lua (class trainers) ```sh polestar trainers --help ``` ```output usage: node tools/polestar.js trainers build [options] Builds data/forever/trainers.json, the class trainers `train class` picks from: every `train <npcId> only <Class>` goal under guides/, recorded trainer visits in data/recordings (by the recording character's class), and Polestar's curated list of capital and starting-town trainers, each verified by name and map against npcs.json. Without the file, compile uses the curated list alone. Also writes addon/Polestar/Core/ClassTrainers.lua: one trainer per town and class, with positions and map frames, for the class-training reminder, and every class trainer's npc id by class, for Engine.IsClassTrainer. options: --guides <dir> guide sources (default guides/) --data <dir> reference data, also the output folder (default data/forever/) --recordings <dir> normalized recordings (default data/recordings/) --out <file> output file (default <data>/trainers.json) --lua <file> Lua output (default addon/Polestar/Core/ClassTrainers.lua) ``` ## polestar travel Build the travel network (flights, boats, inns, learned paths, zone crossings), import zone crossings, test routes and draft approach chains from recordings ```sh polestar travel --help ``` ```output usage: node tools/polestar.js travel build [options] node tools/polestar.js travel route --from <map,x,y> --to <map,x,y> [options] node tools/polestar.js travel chain --to <map,x,y> [options] node tools/polestar.js travel import --<crossings> <ZoneConnections.lua> --source <text> [options] build: the flight network (Blizzard Classic Era TaxiNodes/TaxiPath/TaxiPathNode via <tables>), boats/zeppelins/tram (plus the ships WoW Forever added, from the Forever client's TaxiPathNode), inns, learned walking paths and zone crossings learned from recordings -> data/forever/travel.json, addon/Polestar/Nav/TravelData.lua and the flights' tracks in addon/Polestar/Maps/FlightPaths.lua. The shipped crossings file (tools/lib/travel/crossings.json, from "travel import") goes into TravelData.lua. With the optional local crossings file (data/local/crossings.json, validated) it also writes the local data addon addon/Polestar_Travel (installed when built, never packaged). --offline use cached <tables> tables only --build <version> Classic Era build (default: newest listed) --forever-build <v> WoW Forever build (default: newest 1.60+ listed) --data <dir> data/forever (map-frames, zones, npcs, objects) --recordings <dir> data/recordings --sources <dir> data/sources (<tables> cache) --shipped <file> the shipped crossings file (default: tools/lib/travel/crossings.json; "none" to leave it out) --grid <dir> the navigation grid (default: data/local/nav4; "none" to leave it out): a ship's end lying in the water gets a board point, the nearest dry deck within 30 yd; without a grid, none --crossings <file> the local crossings file (default: <data>/../local/crossings.json) --travel-addon <dir> Polestar_Travel output (default: addon/Polestar_Travel) --json <file> travel.json output (default: <data>/travel.json) --lua <file> TravelData.lua output (default: addon/Polestar/Nav/TravelData.lua) --flight-lua <file> FlightPaths.lua output (default: addon/Polestar/Maps/FlightPaths.lua; with --lua, FlightPaths.lua beside that file) route: run the addon's own planner (Nav/Travel.lua + TravelData.lua, plus Polestar_Travel when built) under Lua 5.1 between two Era-frame map points and print the legs. --from <map,x,y> start (uiMapID, map percent) --to <map,x,y> target --faction <name> Alliance | Horde (default Alliance) --known <ids|names> flight master node ids or names; repeatable, or separated by ";" or "," ("Sentinel Hill, Westfall" matches the full node name first) --speed <yd/s> run speed (default 7) --hearth <location> bind location, Hearthstone ready --data <dir> data/forever (map-frames, zones, travel.json) --lua <file> TravelData.lua (default: addon/Polestar/Nav/TravelData.lua) --crossings-lua <f> Polestar_Travel's Crossings.lua (default: addon/Polestar_Travel/Crossings.lua when built; "none" to skip) --json print the legs as JSON chain: a candidate approach chain (a cave, a climb) for the local crossings file, from the recorded walks that reach a target: where each walk leaves the straight line to the target, and the walked path from there simplified into nodes with radii and a first caption. Walks from several sides meet at the mouth, so the shortest chain is printed. A walk that keeps to the straight line is reported but does not stop the draft (recordings have no height: it may have followed the arrow onto the hill above a cave). Check it in game before using it. --to <map,x,y> the target (uiMapID, Era map percent) --name <text> the place ("Fargodeep Mine"): the chain's name, id and first caption --id <id> the chain's id (default: from --name, else recorded-chain-<map>-<x>-<y>) --within <yd> how far back from the target a walk is followed; shorter walks do not count (default 300) --tolerance <yd> how far the walk may stray from the line between two nodes (default 8) --session <id> draft from this session's walks only (repeatable) --reverse count each walk's way out, reversed, as a way in too --data <dir> data/forever (map-frames, zones) --recordings <dir> data/recordings --json print only the chain entry import: the shipped crossings file from <crossings>'s Classic Era zone connections (<crossings>/Data/classic/ZoneConnections.lua in github.com/IrcDirk/<crossings>-Classic, GPL-3.0): its walks between zones (two-way unless marked one way), validated, with the arrival radius given. The open borders of the file it replaces (from the navigation grid, not <crossings>) are kept. --<crossings> <file> <crossings>'s ZoneConnections.lua --source <text> where it came from (repository and commit), kept in the file --radius <yd> arrival radius of every end (default 30) --data <dir> data/forever (map-frames, zones) --out <file> output (default: tools/lib/travel/crossings.json) ``` ## polestar version Show or set the release version (package.json, guides/pack.json and addon TOCs) ```sh polestar version --help ``` ```output usage: node tools/polestar.js version [<x.y.z>] [options] Without a version, prints package.json's version and names guides/pack.json or any addon TOC whose version differs (exit 1 if one does). With one, writes it to package.json, to guides/pack.json (compile takes Polestar_Guides' version from it) and to the ## Version line of every addon/<Name>/<Name>.toc present. Data addons built later take the version from package.json. options: --root <dir> folder holding package.json (default the repository) --addons <dir> addon folder (default <root>/addon/) ``` --- # Security > How to report a security problem privately, what counts as one, and the supported versions. Page: https://polestar.guide/docs/reference/security (Polestar docs > Reference) ## Reporting a problem Report a security problem privately: on GitHub, open the repository's **Security** tab and choose **Report a vulnerability**. Please don't open a public issue or post it on Discord, so players are not exposed while it is being fixed. Say what you found, which version or commit, and how to see it happen. You get a reply in the report itself; the fix and a credit (unless you'd rather not be named) go in the changelog once it ships. ## What counts - **The addon acting against the player**: mail, trade, the auction house, the guild bank, buying or spending without the player asking; chat or addon messages sent on its own; anything that runs code it was sent. - **Community addons, guides and data**: a guide, data or locale file that gets the addon to run code, open a link or act for the player. - **The toolchain**: a command that runs code from a pack, a pull request or a downloaded file, or reads or writes outside the repository and its data folders. - **The project's automation**: the GitHub workflows, the Discord bot and its tokens. - **A fake Polestar**: a download that claims to be Polestar or one of its addons but is not from this repository's releases or its CurseForge project. A wrong step, a Lua error or a crash is a normal bug: use the issue forms or Discord (CONTRIBUTING.md). ## Supported versions The latest release, and `next` before it ships. Fixes go into a patch of the latest release when they can (docs/RELEASING.md, "Patch releases"). --- # License exception > The permission to distribute a compiled community guide or an import string under terms of your choice. Page: https://polestar.guide/docs/reference/license-exception (Polestar docs > Reference) Polestar is licensed under the GNU General Public License version 3 ([LICENSE](https://github.com/fitzforge/polestar/blob/next/LICENSE)), with this additional permission: > Additional permission under GNU GPL version 3 section 7: as a special > exception, the copyright holders of Polestar give you permission to > distribute guide packs produced by Polestar's compiler, and import strings > produced by Polestar's tools, including the parts of Polestar's reference > data that the compiler or those tools place in them, under terms of your > choice. This permission does not cover guide text copied from Polestar's > own guides, or Polestar's code. --- # Alliance leveling guide 1–60 (every race) > Every Alliance race's leveling road in Polestar, from its start zone to level 60: 4 starts, then 25 guides every Alliance race shares. Page: https://polestar.guide/guides/alliance Polestar is a free, open-source (GPL-3.0) leveling guide addon for World of Warcraft: Forever. Every guide here ships inside the addon: in game, `/polestar guides` opens the guide menu, and the guide window shows the steps with a waypoint arrow. The Alliance races start in 4 places: Elwynn Forest (Human), Dun Morogh (Dwarf and Gnome), Teldrassil (Night Elf) and Zephras Isle (Skyborne). From there every Alliance race takes the same road: 25 guides from Westfall (levels 12–17) to level 60. Which guide for a level: find the guide whose levels hold the character's level on the road below (the start guides first if the character is still in its start zone). In game, Polestar opens a guide for the character's race, level and zone at login, and `/polestar guides` lists every guide. ## Starts ### Human (levels 1–13) - [Elwynn Forest](https://polestar.guide/guides/alliance/human/01-elwynn-forest.md) (levels 1–13): 99 quests, 73 steps, hearth at Goldshire - Then [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17), where the Alliance road meets. ### Dwarf and Gnome (levels 1–13) - [Dun Morogh](https://polestar.guide/guides/alliance/dwarf-gnome/01-dun-morogh.md) (levels 1–13): 102 quests, 84 steps, hearth at Thunderbrew Distillery - Then [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17), where the Alliance road meets. ### Night Elf (levels 1–11) - [Teldrassil](https://polestar.guide/guides/alliance/nightelf/01-teldrassil.md) (levels 1–11): 79 quests, 51 steps, hearth at Dolanaar - Then [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17), where the Alliance road meets. ### Skyborne (levels 1–15) - [Zephras Isle](https://polestar.guide/guides/alliance/skyborne/01-zephras-isle.md) (levels 1–15): 108 quests, 61 steps - Then [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17), where the Alliance road meets. ## The road to 60 - [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17): 27 quests, 21 steps, hearth at Sentinel Hill - [Darkshore](https://polestar.guide/guides/alliance/03-darkshore.md) (levels 16–21): 77 quests, 43 steps, hearth at Auberdine - [Redridge Mountains](https://polestar.guide/guides/alliance/04-redridge-mountains.md) (levels 20–23): 22 quests, 20 steps, hearth at Lakeshire - [Duskwood](https://polestar.guide/guides/alliance/05-duskwood.md) (levels 22–26): 29 quests, 29 steps, hearth at Darkshire - [Ashenvale, Wetlands & Stonetalon Mountains](https://polestar.guide/guides/alliance/06-ashenvale.md) (levels 25–29): 56 quests, 66 steps, hearth at Astranaar, then Deepwater Tavern - [Thousand Needles, Duskwood & Wetlands](https://polestar.guide/guides/alliance/07-thousand-needles.md) (levels 28–31): 39 quests, 36 steps, hearth at Darkshire, then Deepwater Tavern - [Wetlands, Hillsbrad Foothills, Ironforge & Stormwind City](https://polestar.guide/guides/alliance/30-40/01-hillsbrad-foothills.md) (levels 30–33): 40 quests, 37 steps, hearth at Southshore - [Desolace](https://polestar.guide/guides/alliance/30-40/02-desolace.md) (levels 31–34): 11 quests, 22 steps, hearth at Nijel's Point - [Ashenvale & Wetlands](https://polestar.guide/guides/alliance/30-40/03-ashenvale.md) (levels 33–35): 24 quests, 34 steps, hearth at Astranaar - [Stranglethorn Vale](https://polestar.guide/guides/alliance/30-40/04-stranglethorn-vale.md) (levels 34–38): 40 quests, 36 steps, hearth at Booty Bay - [Arathi Highlands, Alterac Mountains & Swamp of Sorrows](https://polestar.guide/guides/alliance/30-40/05-arathi-highlands.md) (levels 37–40): 40 quests, 48 steps, hearth at Southshore, then Stoutlager Inn - [Badlands & Desolace](https://polestar.guide/guides/alliance/30-40/06-badlands.md) (levels 39–41): 27 quests, 39 steps, hearth at Nijel's Point - [Stranglethorn Vale, Dustwallow Marsh & Swamp of Sorrows](https://polestar.guide/guides/alliance/40-50/01-stranglethorn-vale.md) (levels 40–43): 53 quests, 52 steps, hearth at Theramore Isle, then Booty Bay, then Stormwind - [Badlands & The Hinterlands](https://polestar.guide/guides/alliance/40-50/02-badlands.md) (levels 43–44): 9 quests, 18 steps - [Feralas](https://polestar.guide/guides/alliance/40-50/03-feralas.md) (levels 43–46): 28 quests, 26 steps, hearth at Feathermoon Stronghold - [Tanaris](https://polestar.guide/guides/alliance/40-50/04-tanaris.md) (levels 45–47): 25 quests, 24 steps, hearth at Gadgetzan, then Aerie Peak - [The Hinterlands, Blasted Lands & Loch Modan](https://polestar.guide/guides/alliance/40-50/05-the-hinterlands.md) (levels 46–48): 15 quests, 20 steps, hearth at Aerie Peak, then Stoutlager Inn - [Searing Gorge](https://polestar.guide/guides/alliance/40-50/06-searing-gorge.md) (levels 47–49): 14 quests, 14 steps, hearth at Stoutlager Inn - [Un'Goro Crater & Ironforge](https://polestar.guide/guides/alliance/40-50/07-un-goro-crater.md) (levels 48–52): 34 quests, 45 steps, hearth at Stoutlager Inn, then Ironforge - [Burning Steppes, Azshara & Blasted Lands](https://polestar.guide/guides/alliance/50-60/01-burning-steppes.md) (levels 51–53): 18 quests, 38 steps, hearth at Ironforge - [Felwood](https://polestar.guide/guides/alliance/50-60/02-felwood.md) (levels 52–54): 21 quests, 20 steps, hearth at Everlook - [Winterspring & Eastern Plaguelands](https://polestar.guide/guides/alliance/50-60/03-winterspring.md) (levels 53–55): 31 quests, 32 steps, hearth at Everlook, then Light's Hope Chapel - [Western Plaguelands, Eastern Plaguelands & Feralas](https://polestar.guide/guides/alliance/50-60/04-western-plaguelands.md) (levels 54–57): 64 quests, 64 steps, hearth at Light's Hope Chapel, then Ratchet - [Silithus, Un'Goro Crater & Eastern Plaguelands](https://polestar.guide/guides/alliance/50-60/05-silithus.md) (levels 56–58): 34 quests, 27 steps, hearth at Cenarion Hold, then Ratchet - [Silithus, Felwood, Winterspring & the Plaguelands](https://polestar.guide/guides/alliance/50-60/06-silithus.md) (levels 57–60): 34 quests, 56 steps, hearth at Ratchet, then Cenarion Hold, then Stormwind Each class's talent plans, class quests and gear: https://polestar.guide/guides/class.md --- Index for language models: https://polestar.guide/llms.txt --- # Horde leveling guide 1–60 (every race) > Every Horde race's leveling road in Polestar, from its start zone to level 60: 4 starts, then 23 guides every Horde race shares. Page: https://polestar.guide/guides/horde Polestar is a free, open-source (GPL-3.0) leveling guide addon for World of Warcraft: Forever. Every guide here ships inside the addon: in game, `/polestar guides` opens the guide menu, and the guide window shows the steps with a waypoint arrow. The Horde races start in 4 places: Durotar (Orc and Troll), Mulgore (Tauren), Tirisfal Glades (Undead) and Zephras Isle (Skyborne). From there every Horde race takes the same road: 23 guides from The Barrens (levels 12–17) to level 60. Which guide for a level: find the guide whose levels hold the character's level on the road below (the start guides first if the character is still in its start zone). In game, Polestar opens a guide for the character's race, level and zone at login, and `/polestar guides` lists every guide. ## Starts ### Orc and Troll (levels 1–17) - [Durotar](https://polestar.guide/guides/horde/orc-troll/01-durotar.md) (levels 1–12): 80 quests, 67 steps, hearth at Razor Hill, then The Crossroads - [The Barrens](https://polestar.guide/guides/horde/orc-troll/02-the-barrens.md) (levels 11–17): 34 quests, 38 steps, hearth at Ratchet, then The Crossroads - Then [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17), where the Horde road meets. ### Tauren (levels 1–12) - [Mulgore](https://polestar.guide/guides/horde/tauren/01-mulgore.md) (levels 1–12): 70 quests, 59 steps, hearth at Bloodhoof Village, then Crossroads - Then [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17), where the Horde road meets. ### Undead (levels 1–13) - [Tirisfal Glades](https://polestar.guide/guides/horde/undead/01-tirisfal-glades.md) (levels 1–13): 70 quests, 70 steps, hearth at Gallows' End Tavern, then The Crossroads - Then [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17), where the Horde road meets. ### Skyborne (levels 1–15) - [Zephras Isle](https://polestar.guide/guides/horde/skyborne/01-zephras-isle.md) (levels 1–15): 111 quests, 84 steps, hearth at The Crossroads - Then [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17), where the Horde road meets. ## The road to 60 - [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17): 38 quests, 41 steps, hearth at The Crossroads - [Silverpine Forest & Orgrimmar](https://polestar.guide/guides/horde/03-silverpine-forest.md) (levels 16–20): 35 quests, 37 steps, hearth at Sepulcher - [The Barrens](https://polestar.guide/guides/horde/04-the-barrens.md) (levels 19–24): 75 quests, 76 steps, hearth at Crossroads, then Camp Taurajo - [Stonetalon Mountains & Ashenvale](https://polestar.guide/guides/horde/05-stonetalon-mountains.md) (levels 23–25): 22 quests, 28 steps, hearth at Splintertree Post, then Sun Rock Retreat, then Tarren Mill - [Hillsbrad Foothills, Undercity & The Barrens](https://polestar.guide/guides/horde/06-hillsbrad-foothills.md) (levels 24–28): 22 quests, 29 steps, hearth at Tarren Mill, then Camp Taurajo - [Ashenvale & Thousand Needles](https://polestar.guide/guides/horde/07-ashenvale.md) (levels 27–31): 47 quests, 47 steps, hearth at Splintertree Post, then Freewind Post - [Desolace & Hillsbrad Foothills](https://polestar.guide/guides/horde/30-40/01-desolace.md) (levels 30–33): 31 quests, 49 steps, hearth at Tarren Mill - [Stranglethorn Vale](https://polestar.guide/guides/horde/30-40/02-stranglethorn-vale.md) (levels 32–38): 32 quests, 44 steps, hearth at Grom'gol Base Camp, then Booty Bay - [Arathi Highlands, Badlands & The Barrens](https://polestar.guide/guides/horde/30-40/03-arathi-highlands.md) (levels 37–40): 33 quests, 53 steps, hearth at Hammerfall, then Kargath, then Ratchet - [Dustwallow Marsh & Desolace](https://polestar.guide/guides/horde/30-40/04-dustwallow-marsh.md) (levels 39–41): 25 quests, 32 steps, hearth at Ratchet, then Shadowprey Village - [Stranglethorn Vale & Swamp of Sorrows](https://polestar.guide/guides/horde/40-50/01-stranglethorn-vale.md) (levels 40–43): 31 quests, 40 steps, hearth at Grom'gol Base Camp, then Booty Bay - [Feralas & Tanaris](https://polestar.guide/guides/horde/40-50/02-feralas.md) (levels 42–44): 32 quests, 38 steps, hearth at Camp Mojache - [Feralas, Dustwallow Marsh & Swamp of Sorrows](https://polestar.guide/guides/horde/40-50/03-feralas.md) (levels 44–46): 26 quests, 31 steps, hearth at Stonard, then Camp Mojache - [Tanaris & Searing Gorge](https://polestar.guide/guides/horde/40-50/04-tanaris.md) (levels 45–48): 27 quests, 32 steps, hearth at Gadgetzan - [The Hinterlands & Blasted Lands](https://polestar.guide/guides/horde/40-50/05-the-hinterlands.md) (levels 47–50): 26 quests, 30 steps, hearth at Revantusk Village - [Azshara, Feralas & Stranglethorn Vale](https://polestar.guide/guides/horde/40-50/06-azshara.md) (levels 49–51): 35 quests, 38 steps, hearth at Camp Mojache, then Gadgetzan - [Un'Goro Crater, Eastern Plaguelands & Burning Steppes](https://polestar.guide/guides/horde/50-60/01-un-goro-crater.md) (levels 50–53): 47 quests, 56 steps, hearth at Light's Hope Chapel - [Felwood & Western Plaguelands](https://polestar.guide/guides/horde/50-60/02-felwood.md) (levels 52–54): 45 quests, 48 steps, hearth at Everlook - [Winterspring & Feralas](https://polestar.guide/guides/horde/50-60/03-winterspring.md) (levels 54–56): 31 quests, 32 steps, hearth at Everlook, then Orgrimmar - [Azshara, The Barrens & Undercity](https://polestar.guide/guides/horde/50-60/04-azshara.md) (levels 55–57): 15 quests, 21 steps - [Eastern Plaguelands, Winterspring & Tanaris](https://polestar.guide/guides/horde/50-60/05-eastern-plaguelands.md) (levels 56–58): 16 quests, 31 steps, hearth at Light's Hope Chapel, then Thunder Bluff - [Silithus, Western Plaguelands & Eastern Plaguelands](https://polestar.guide/guides/horde/50-60/06-silithus.md) (levels 57–59): 29 quests, 42 steps, hearth at Cenarion Hold - [Felwood, Moonglade & Winterspring](https://polestar.guide/guides/horde/50-60/07-felwood.md) (levels 58–60): 5 quests, 17 steps Each class's talent plans, class quests and gear: https://polestar.guide/guides/class.md --- Index for language models: https://polestar.guide/llms.txt --- # Class leveling guides for WoW: Forever > Each of the 9 classes in Polestar: who can play it, its leveling talent plans, its class quests and its gear advice. Page: https://polestar.guide/guides/class Polestar is a free, open-source (GPL-3.0) leveling guide addon for World of Warcraft: Forever. Every guide here ships inside the addon: in game, `/polestar guides` opens the guide menu, and the guide window shows the steps with a waypoint arrow. - [Warrior](https://polestar.guide/guides/class/warrior.md): Arms, Fury, Protection talent plans; Level as Arms with a two-hander (Mortal Strike, Sweeping Strikes) or Fury (Enrage, Death Wish, then Flurry and Bloodthirst with two weapons). Protection is slower alone but ready to tank any dungeon on the way. - [Paladin](https://polestar.guide/guides/class/paladin.md): Holy, Protection, Retribution talent plans; Level as Retribution (quickest solo, with a two-hander and Seal of Command) or Protection (safe group pulls, dungeon-tank ready). Holy suits raids; it can level through its melee build, more slowly, if you want to heal dungeons on the way. - [Hunter](https://polestar.guide/guides/class/hunter.md): Beast Mastery, Marksmanship, Survival talent plans; Level as Beast Mastery: your pet tanks and does much of the damage, so you rarely stop. Marksmanship hits harder from range with Careful Aim and Sniper Shot; Survival fights in melee with Predator's Edge and Lacerating Strikes. - [Rogue](https://polestar.guide/guides/class/rogue.md): Assassination, Combat, Subtlety talent plans; Level as Combat with a sword (Riposte, Blade Flurry, Adrenaline Rush) for the steadiest kills, or Assassination with daggers and poisons (Mutilate). Subtlety's Hemorrhage plan suits stealth openers and is slower solo. - [Priest](https://polestar.guide/guides/class/priest.md): Discipline, Holy, Shadow talent plans; Level as Shadow (Spirit Tap, Mind Flay, Shadowform) for the fastest kills and least drinking. Discipline levels with Smite and Penance behind a strong shield; Holy is the dungeon healer and slower alone. - [Shaman](https://polestar.guide/guides/class/shaman.md): Elemental, Enhancement, Restoration talent plans; Level as Enhancement (Flurry, Stormstrike, Maelstrom Weapon) for steady melee with few rests, or Elemental (Lightning Overload, Lava Burst) to kill from range. Restoration heals dungeons well and levels slowly alone. - [Mage](https://polestar.guide/guides/class/mage.md): Arcane, Fire, Frost talent plans; Level as Frost (the safest: slows, freezes and Ice Barrier) or Fire (more damage, with Pyroblast openers and Blast Wave). Arcane builds around Arcane Blast and Arcane Power and wants more mana between pulls. - [Warlock](https://polestar.guide/guides/class/warlock.md): Affliction, Demonology, Destruction talent plans; Level as Affliction (instant Corruption, Siphon Life, drains) or Demonology (a tougher Voidwalker, Soul Link) for the fewest deaths. Destruction hits hardest with Conflagrate and Incinerate but needs more rest. - [Druid](https://polestar.guide/guides/class/druid.md): Balance, Feral Combat, Restoration talent plans; Level as Feral Combat: Cat Form for quick kills, Bear Form for tough pulls, and no drinking. Balance kills from range with roots and Starfire; Restoration heals any dungeon and quests slowly with Wrath. --- Index for language models: https://polestar.guide/llms.txt --- # Not in this file The pages for contributors to Polestar itself, the release notes and the credits, each as Markdown: - [Overview](https://polestar.guide/docs/contributors.md) - [Contributing](https://polestar.guide/docs/contributors/contributing.md) - [Building from source](https://polestar.guide/docs/contributors/building.md) - [From source to game](https://polestar.guide/docs/contributors/source-to-game.md) - [Map and glossary](https://polestar.guide/docs/contributors/docs-map.md) - [Architecture](https://polestar.guide/docs/contributors/architecture.md) - [Core](https://polestar.guide/docs/contributors/architecture/core.md) - [Theme](https://polestar.guide/docs/contributors/architecture/theme.md) - [Nav](https://polestar.guide/docs/contributors/architecture/nav.md) - [Quests](https://polestar.guide/docs/contributors/architecture/quests.md) - [Gear](https://polestar.guide/docs/contributors/architecture/gear.md) - [Maps](https://polestar.guide/docs/contributors/architecture/maps.md) - [QoL](https://polestar.guide/docs/contributors/architecture/qol.md) - [Lookup](https://polestar.guide/docs/contributors/architecture/lookup.md) - [Dungeons](https://polestar.guide/docs/contributors/architecture/dungeons.md) - [UI](https://polestar.guide/docs/contributors/architecture/ui.md) - [Rares](https://polestar.guide/docs/contributors/architecture/rares.md) - [Talents](https://polestar.guide/docs/contributors/architecture/talents.md) - [Toolchain](https://polestar.guide/docs/contributors/architecture/toolchain.md) - [Tests](https://polestar.guide/docs/contributors/architecture/tests.md) - [The addon, file by file](https://polestar.guide/docs/contributors/addon.md) - [The toolchain](https://polestar.guide/docs/contributors/tools.md) - [The tests](https://polestar.guide/docs/contributors/tests.md) - [The suite](https://polestar.guide/docs/contributors/suite.md) - [Route simulation](https://polestar.guide/docs/contributors/simulation.md) - [Design system](https://polestar.guide/docs/contributors/design.md) - [Agent workflows](https://polestar.guide/docs/contributors/workflows.md) - [Contributing (agent)](https://polestar.guide/docs/contributors/workflows/contributing.md) - [Triaging a report](https://polestar.guide/docs/contributors/workflows/triage.md) - [Fixing a guide step](https://polestar.guide/docs/contributors/workflows/guide-fix.md) - [Releasing](https://polestar.guide/docs/contributors/releasing.md) - [The CurseForge listing](https://polestar.guide/docs/contributors/releasing/curseforge.md) - [Changelog](https://polestar.guide/docs/reference/changelog.md) - [Release notes, Polestar 0.2.6](https://polestar.guide/docs/reference/changelog/0-2-6.md) - [Release notes, Polestar 0.2.5](https://polestar.guide/docs/reference/changelog/0-2-5.md) - [Release notes, Polestar 0.2.4](https://polestar.guide/docs/reference/changelog/0-2-4.md) - [Release notes, Polestar 0.2.3](https://polestar.guide/docs/reference/changelog/0-2-3.md) - [Release notes, Polestar 0.2.2](https://polestar.guide/docs/reference/changelog/0-2-2.md) - [Release notes, Polestar 0.2.1](https://polestar.guide/docs/reference/changelog/0-2-1.md) - [Release notes, Polestar 0.2.0](https://polestar.guide/docs/reference/changelog/0-2-0.md) - [Release notes, Polestar 0.1.0](https://polestar.guide/docs/reference/changelog/0-1-0.md) - [Credits & data sources](https://polestar.guide/docs/reference/credits.md)

# Polestar: the docs in one file > Polestar is a free, open-source (GPL-3.0) leveling guide addon for World of Warcraft: Forever. This file holds its docs for players and guide authors and its reference, as of Polestar 0.2.6, followed by each faction's leveling road and the class guides. The index is https://polestar.guide/llms.txt. Each page starts with its title (a level-1 heading) and its address on polestar.guide; cite that address. Pages are separated by a line of dashes. Contents: 26 docs pages, then the Alliance road, the Horde road and the class guides. --- # Start here > Polestar is for World of Warcraft: Forever. It is a free leveling guide: install it, log in, and follow the arrow. Page: https://polestar.guide/docs/players (Polestar docs > Players) Polestar is for World of Warcraft: Forever. It is one addon for the whole game: leveling guides from 1 to 60 for every race's start, class quests, professions, reputations and collectibles, with a 3D arrow that walks real paths to your next goal. Goals tick themselves off as you play. It is free and open source. ## Install it ### CurseForge app 1. Search for **Polestar Guides** in the CurseForge app and install it. 2. Restart the game completely. A `/reload` does not load a new addon. 3. Log in. The guide window opens with a guide for your race, level and zone. ### Windows 1. Download `Polestar-.zip` from the newest release on the [Releases page](https://github.com/fitzforge/polestar/releases), under *Assets* (not "Source code"). 2. Unzip it into the game's AddOns folder, so the `Polestar` folders sit directly inside it. On the beta client: ```text title="AddOns folder" C:\Program Files (x86)\World of Warcraft\_classic_beta_\Interface\AddOns ``` From launch, `_forever_` takes the place of `_classic_beta_`. 3. Restart the game completely and log in. ### macOS 1. Download `Polestar-.zip` from the newest release on the [Releases page](https://github.com/fitzforge/polestar/releases), under *Assets*. 2. Unzip it into the game's AddOns folder, so the `Polestar` folders sit directly inside it. On the beta client: ```text title="AddOns folder" /Applications/World of Warcraft/_classic_beta_/Interface/AddOns ``` From launch, `_forever_` takes the place of `_classic_beta_`. 3. Restart the game completely and log in. ### Linux (Wine, Proton) 1. Download `Polestar-.zip` from the newest release on the [Releases page](https://github.com/fitzforge/polestar/releases), under *Assets*. 2. Unzip it into the AddOns folder inside the game's prefix, so the `Polestar` folders sit directly inside it: ```text title="AddOns folder" /drive_c/Program Files (x86)/World of Warcraft/_classic_beta_/Interface/AddOns ``` The prefix is wherever your launcher keeps it: `~/.wine`, `~/Games`, Lutris (`~/.local/share/lutris/prefixes`), Bottles, Faugus, or Steam's Proton prefixes under `~/.local/share/Steam/steamapps/compatdata`. From launch, `_forever_` takes the place of `_classic_beta_`. 3. Restart the game completely and log in. > **Tip:** > Building from a clone instead? `polestar install` finds the client in all of > these places by itself: see [Building from source](https://polestar.guide/docs/contributors/building). The full steps, with the folder for each client and what to know about updating and memory, are in [Install and first run](https://polestar.guide/docs/players/quick-start). ## Find your way round - [What Polestar is](https://polestar.guide/docs/players/what-it-is): the guides, the arrow and the hub, with screenshots from the game. - [Features](https://polestar.guide/docs/players/features): everything Polestar does, from the guide engine to gear advice, rares and the gamepad. - [Talent plans](https://polestar.guide/docs/players/talent-plans): a leveling plan for every spec, marked on the talent frame; each [class's page](https://polestar.guide/guides/class) lists its plans pick by pick. - [How the routes are made](https://polestar.guide/docs/players/how-routes-are-made): why the leveling routes are the ones they are. - [Community guides](https://polestar.guide/docs/players/community-guides): guides written by other players, installed beside Polestar, and who to ask when one goes wrong. - [Import strings](https://polestar.guide/docs/players/import-strings): a small community guide shared as one line of text. - [FAQ](https://polestar.guide/docs/players/faq): short answers to the questions players ask most. - [Using Polestar with AI assistants](https://polestar.guide/docs/players/ai-assistants): give ChatGPT, Claude or another assistant these docs, so it answers from them. > **Tip:** > Press ⌘K (or Ctrl K) on any docs page to search every > heading and every word of the docs. ## Something wrong? Click the bug in the guide window, beside Skip: say what went wrong, copy the report (it already holds the step, where you stand and the versions) and paste it on the [Polestar Discord](https://discord.gg/polestar). A wrong step in a community guide goes to that guide's author instead. --- # Install and first run > Install Polestar from the CurseForge app or a release zip, restart the game and follow the arrow. Page: https://polestar.guide/docs/players/quick-start (Polestar docs > Players) 1. **Install it with the CurseForge app** (search for [Polestar Guides](https://www.curseforge.com/wow/addons/polestar)), then skip to step 3. **Or download** `Polestar-.zip` from the newest release on the [Releases page](https://github.com/fitzforge/polestar/releases), under *Assets* (not "Source code"). 2. **Unzip it into the game's AddOns folder**, so the Polestar folders (`Polestar`, `Polestar_Guides`, `Polestar_QuestDB`, `Polestar_ItemDB`) sit directly inside it: `World of Warcraft/_classic_beta_/Interface/AddOns/` on the beta client, `_forever_` instead of `_classic_beta_` from launch. 3. **Restart the game completely** (a `/reload` does not load new addons) and log in. The guide window opens with a guide for your race, level and zone: follow the arrow, and the goals tick themselves off as you play. Good to know: - `/polestar guides` opens the hub: every guide, Lookup, Dungeons and Rares. `/polestar options` holds every setting; quest markers on the map are off until you turn them on under **Map**. - `/polestar skip` moves on for good; `/polestar next` and `prev` only look ahead or back. - **Updating:** delete the old Polestar folders, then unzip the new release the same way. - **Memory:** the arrow's walking routes (`Polestar_Nav`) load after login, never in combat: about 34 MB for the walking maps, and while a walk is being searched up to about 45 MB more for the stretch of map it crosses, released when the search ends. **Walk real paths** (Options, Arrow & routes) off never loads them. - **Optional:** `Polestar_Recorder-.zip` from the same release records your sessions to improve the routes. It does nothing until you turn it on. - **Community guides** are other people's guides for Polestar, each a separate addon from its own author: see [Community guides](https://polestar.guide/docs/players/community-guides). - Something wrong? Click the bug in the guide window, beside Skip: say what went wrong, copy the report (it already holds the step, where you stand and the versions) and paste it on the [Polestar Discord](https://discord.gg/polestar). `/polestar report` opens it too, and [issues](https://github.com/fitzforge/polestar/issues) are welcome as well. The release's `SHA256SUMS` holds the zips' checksums. --- # What Polestar is > One addon for the whole of WoW: Forever: 222 guides, a waypoint arrow that walks real paths, and the tools around them. Page: https://polestar.guide/docs/players/what-it-is (Polestar docs > Players) ## What it is Polestar is one addon for the whole of WoW: Forever. It carries 222 guides: 57 leveling guides that take both factions from 1 to 60 from every race's starting zone (Zephras Isle for the Skyborne included), 66 class guides for every class's quest chains, the twelve professions from 1 to 300, 17 reputations, 7 exploration guides, the Legacy challenges and 60 collectible guides, one per mount and per pet. Around the guides it adds a 3D waypoint arrow that walks real paths (on Polestar's walking maps, with a router that started from Shortest Path Forever's by Cillian Berragan) and a travel planner, quest markers on the map, an upgrade indicator on item tooltips, a search for where any item, mount or pet comes from, a dungeon quest journal, rare alerts and the quality-of-life helpers a long leveling session needs. Its interface and its guides read in English, German, French, Spanish (Spain and Latin America), Brazilian Portuguese, Russian, Korean and Chinese (simplified and traditional). The leveling routes are not hand-picked. A simulator models every quest Forever offers a faction, plays millions of complete 1-60 routes for each start, and keeps the one that reaches 60 soonest under its model; the guides are written from that route and scored under the same model ([How the routes are made](https://polestar.guide/docs/players/how-routes-are-made)). Other people can publish their own guides for Polestar as community addons: separate addons, made and supported by their authors ([Community guides](https://polestar.guide/docs/players/community-guides)). Each new character's first login opens a short welcome: a hello and what Polestar does; on the account's first character, quest automation, the guide at login and the color scheme, then the route style (Fastest, Balanced or Roads, with a line on what each does); then the guide Polestar suggests for that character, the Discord and community guides (`/polestar welcome` shows it again). > **Note:** > **Beta.** Every guide compiles, lints and plays to the end in a simulator > for every race and class it serves, but nothing has been play-tested on > Forever yet. Forever's new 30-60 content (Riverglades, Shen'dralas, Mount > Hyjal) is not in any data yet; the routes take it in at launch. ## A look inside Screenshots from the game: World of Warcraft: Forever (beta client) with Polestar 0.1.0 at its default settings. Click a picture for full size. *(Image: The Polestar hub on its Guides section: the section rail (Guides, Lookup, Dungeons, Rares, Options), guide categories with Leveling selected, the Horde leveling guides by level band with The Barrens (19-24) selected, and its details: a painting of the zone, levels, progress in tab 1, steps, quests, zones, the next guide and a Continue button)* **The hub.** Guides, Lookup, Dungeons and Rares on one rail, Options at its foot. Here the Horde leveling guides by level band, and the selected guide's zone, progress, quests and the guide after it. *(Image: The guide window on step 5 of 60 of The Barrens: Northwatch Hold, collect the Theramore Medal, kill Captain Fairmount and two cannoneers with a 4/10 counter, then Gilthares Firebough, 3620 XP per hour and 6 h 52 m to level)* **The guide window.** The step's goals with their counters, who comes next, XP per hour and the time to level. *(Image: The same guide window in transparent mode: no background, outlined text over the grass of the Barrens)* **Transparent mode.** Outlined text straight on the world; the controls appear under the cursor. *(Image: The 3D waypoint arrow over the sea: 34 yd, Collect Theramore Medal)* **The arrow.** Distance and the goal it leads to. *(Image: Lookup searching for Swift: 119 results across guides, mounts, items, recipes, quests, NPCs and rares, with the Swift Ram guide selected)* **Lookup.** One search over guides, mounts, items, recipes, quests, NPCs and rares, each with where it comes from. *(Image: The Dungeons section: 34 dungeons by level band on painted cards, with their levels, zone, quest count and a Your level mark)* **Dungeons.** Every dungeon by level, its quests counted for your faction, the ones for your level marked. *(Image: The Wailing Caverns page: Show on map, Guide me to the entrance and Pick up the quests buttons, and its quests with who starts and ends them and their chains)* **A dungeon's page.** Who starts and ends each quest and its chain; one button guides you round to pick them all up. *(Image: Wailing Caverns quests with their objectives and rewards: item choices with icons, experience and money)* **Objectives and rewards.** The items to choose from with their icons, the experience and the money. *(Image: The Rares section: a list of rares with their levels, and Aean Swiftriver selected with its drop, where it spawns and how far away, when it was last seen, and Mute alerts, Look up and Set waypoint buttons)* **Rares.** Every rare and treasure, its drops, where it spawns and how far, and when you last met it. *(Image: Options on the Appearance page: accent color, class color, color scheme, background color, brightness, background opacity, font set to Game font, and reduce motion)* **Options.** Every setting as one row, applied as you change it; here Appearance. Lookup, Dungeons and Rares read the Codex, a data pack that ships in the release as `Polestar_Codex` ([Lookup, Dungeons and Rares](https://polestar.guide/docs/players/features#lookup-dungeons-and-rares)). Not pictured yet: the rare alert, the upgrade marks on the quest reward panel and the quest markers on the world map. Renders of every window and state, drawn without the game, are in [docs/preview](https://github.com/fitzforge/polestar/tree/next/docs/preview). --- # Features > Everything Polestar does: the guide engine, navigation, quests and the map, gear advice, Lookup, Dungeons, Rares and more. Page: https://polestar.guide/docs/players/features (Polestar docs > Players) ## Guides and the engine - **One person at a time.** In a quest hub the window shows only who to talk to now and their quests, then "Then: *next person*" and "Person 2 of 8"; the arrow points at that person. Counters sit right after each goal ("Kill Zhevra Chargers 3/8") and a bar at the foot shows how far into the guide you are. - **Goals check themselves off** as you play: accepted and turned-in quests, kills, loot, places reached, trainers visited, skills and reputation. Your place in a guide is recomputed from your quest log, so it survives lost saved variables. - **It catches up.** With "Skip grey quests" on, a guide you open on a character who already did part of the route goes over what is done to where you are: grey quests are left out, and so are green ones behind your progress, unless a later quest needs them. A guide you are past, given to you when no guide is open or by Start guide, hands over to the next. Item, mount, reputation, profession and class guides do every step. - **A guide for where you are.** The window opens with a guide suggested for your race, class, level and location, and each guide hands over to the next one in its chain when you finish it. - **Tabs.** Up to six guides open at once (a leveling route and a profession, say); quests are auto-accepted for all of them. - **Professions** send you to the nearest trainer, vendor or inn of your own faction from where you stand, never into a city of the other faction; a goal's cycle button picks another. - **Class training reminder** every two levels (configurable): the nearest trainer of your class, unless your guide is about to take you there. - **Elite quests are optional.** Leveling routes use only quests a player can do alone; a quest that needs an elite appears as an extra marked "optional". ## Navigation - **A 3D waypoint arrow** points at the current goal, shifting from the accent to jade as you arrive, with distance and ETA. Distances read in yards, the game's unit, or in metres (Options, Arrow & routes). - **The travel planner** uses known flight paths, boats, zeppelins and your Hearthstone when they are faster. Each leg has its own caption on the arrow ("Fly to Crossroads", "Take the boat to Menethil Harbor", "Hearth to Razor Hill"). - **Trail dots** on the world map and the minimap crawl along the route between its waypoints (Map options can turn them off). - **Zone crossings.** Walks between zones go through the real tunnels, passes, bridges and gates (an Era map addon's zone connections), one waypoint at a time ("Go to Ashenvale"): from Sun Rock Retreat to Astranaar through the Talondeep Path, not over the ridge. - **`/polestar way [label]`** points the arrow anywhere on the current map. - **Go anywhere.** Shift-click the world map or the minimap and the arrow takes you there, routed like any goal; Alt-click works over map icons. Click the spot again to let it go. - **Nearby services.** `/polestar near repair` (trainer, a profession, class, weapon, reagents, vendor, innkeeper, bank, auction, flight, stable) points the arrow at the quickest one to reach; the map's tracking menu and the guide window's Nearby services button list them, the button with a page of the weapons a weapon master can teach you. Once you get there, the arrow is back on the guide. - **OpenMap.** On [OpenMap](https://www.curseforge.com/wow/addons/openmap)'s seamless world map the trail dots carry on across zone borders and show on the whole-world view too. OpenMap's menu has a "Polestar trail dots" switch. - **Other addons' waypoints** (Options, Integrations, TomTom). Without TomTom, "Let other addons set waypoints" (off by default) lets addons that set TomTom waypoints point Polestar's arrow and makes `/way` work; addons that expect TomTom's own settings may not work with it on. With TomTom, the arrow can follow TomTom's. Addon authors: `Polestar.Nav.API` (docs/ARCHITECTURE.md, "Nav API"). ## Pathing by Shortest Path Forever The arrow walks real paths: round cliffs, water and walls, through the town gate and down into the mine, not over the edge. That is the work of [Shortest Path Forever](https://github.com/cjber/shortest-path-forever) by **Cillian Berragan** ([cillian.dev](https://cillian.dev)), who baked walking maps of the continents from the game client and wrote a router that finds a route over them a couple of milliseconds at a time, so the game never stutters. It is beautiful work, and he generously said yes when we asked to use it. Polestar's travel planner still picks the flights, boats and Hearthstone; the router that started from his walks every leg between them. It keeps to roads where they are not much longer, round steep slopes, and out of the other faction's towns; when a walk must enter one (a quest inside Southshore for a Horde character), the arrow says "Hostile town: Southshore" once as the walk starts, and the walk's journey step reads the same when the route has more steps. **Route style** (Options, Guide, Arrow & routes) picks how it walks: Fastest takes the shortest way over hills and across fields, Balanced (the default) keeps to roads that aren't much longer and goes round hills, and Roads stays on roads even when they're longer. Every style keeps out of the other faction's towns. The router ships with Polestar as the `Polestar_Nav` folder. Polestar's walking router started from Shortest Path Forever v1.16.0 by Cillian Berragan, with thanks; Polestar maintains it since 2026-10-16. It runs on Polestar's own walking maps of Eastern Kingdoms, Kalimdor and Zephras Isle, made from the game's geometry in a format grown from his by a port of his map baker (GPL-3.0-or-later; what came from where is in [addon/Polestar_Nav/CREDITS.md](https://github.com/fitzforge/polestar/blob/next/addon/Polestar_Nav/CREDITS.md)). **Walk real paths** (Options, Arrow & routes) turns it off. If you like it, try his addon: [Shortest Path Forever on CurseForge](https://www.curseforge.com/wow/addons/shortest-path-forever) plans whole journeys with flights, boats, zeppelins, portals and live departure times. **Shortest Path Forever: an option.** With it installed, Polestar still guides by default. **Hand guiding to Shortest Path Forever** (Options, Integrations) hands it the route instead: each goal goes to Shortest Path Forever, whose arrow, route and journey take you there, and Polestar's own arrow, route lines, journey steps, travel button, transport alerts, map clicks and `/way` step aside, so the two never guide at once (Polestar's walking maps are not even loaded). The guide window and the map pins stay. A kill or collect area is handed over as an area, so it holds you there until the goal is done; if you clear or replace the journey, Polestar leaves it be until the guide moves on. With the option off, a journey you start in Shortest Path Forever itself still wins: Polestar steps aside the same way while it runs, and guides again when it ends. If Shortest Path Forever finds no way to a goal, or turns its journeys off, Polestar's own arrow guides you there instead. ## Quests and the map - **Quest markers**: givers, objectives and turn-ins on the world map and the minimap, with tooltip lines on the mobs and items a quest needs and quest levels in the log. Nameplate icons mark the mobs you still need, beside the health bar of EllesmereUI and other replacement nameplates too. - **Rare and treasure spawns, dungeon entrances, flight masters, docks and inns** can mark the map too. Every map icon is off by default and turns on under **Map** in the options; the arrow's target, its route and the regions the guide step's mobs and objects spawn in (shaded on the world map and the minimap) always show. - **A world map without fog of war**, with coordinates and zone level ranges. ## Gear advice - **Upgrade indicator** on item tooltips: by how much an item is an upgrade for your spec at your level, from stat weights per spec (detected from your talent points) and level band. - **On the game's reward panel** every choice that is an upgrade gets a green arrow, the one to take is framed, and a coin marks the one that sells for most. Turn-in goals name the best reward. - **In your bags** every item that is an upgrade gets the same green arrow, in the game's bags and in Baganator. ## Lookup, Dungeons and Rares - **Lookup** searches guides, items, mounts, pets, NPCs, quests, zones, dungeons and rares, and answers "how do I get that?" with the sources ranked for your character. "Guide me" opens the curated guide or builds one on the spot. Target or mouse over a player to see their mount and how to get it; Alt-click an item link for a guide. - **Dungeons**: a journal page per dungeon with every quest (where it starts and ends, its objective, chain and rewards), the bosses and the entrance. "Pick up the quests" builds a guide that collects every quest of the dungeon you can take, earlier quests first, on the shortest path from where you stand to the entrance; after the run, "Hand in the quests" guides you to where they are turned in and takes the follow-ups there. - **Rares**: rares and treasures by zone with their spawns and signature drop, and an alert when one shows up on your minimap, nameplates or target. Lookup, Dungeons and Rares read the Codex, a data pack built on your own machine from addons you have installed ([Data and licensing](https://polestar.guide/docs/reference/credits)); it is not part of the release. Without it Lookup still searches the guides, and each section says what is missing. ## Appearance and UI suites - **Colour schemes**: Dusk (the default), Night and Graphite, and EllesmereUI's own panel colour and accent while it is installed. On top of any scheme: your own accent or your class colour, background colour, opacity and brightness. Text stays legible whatever you pick: a ground too light for its text is darkened until it reads. - **Windows**: the border, its colour and thickness, the starlit header band and the shadow, each on or off; the guide window's style (standard, compact or transparent), scale, width and opacity; the menu scale; the arrow's style, scale, opacity and colours; reduced motion. Everything applies live, without a reload; right-click any setting to reset it. - **Fonts**: the game's own by default, or Inter, or EllesmereUI's. - **EllesmereUI** (Options, Integrations): Polestar follows its accent and font by default through its public skinning API, and where its Quality of Life or Friends module does the same job as a Polestar toggle, the toggle starts off. ## Quality of life Quest item, target and Hearthstone buttons; XP per hour and time to level; the level the guide wants you to reach, marked on the game's XP bar; selling greys and repairing (optionally from the guild bank first); buying what a step asks you to buy; learning new spells at class trainers; taking the best quest reward and wearing rewards that are upgrades; instant quest text, single-option gossip and faster auto-loot; hiding combat error spam; flight map and death helpers, and releasing at once in battlegrounds; setting your home at the inn the guide names when you talk to its innkeeper (off by default). Requests from other players: accept summons, resurrections and friends' or guildmates' party invitations; decline other party invitations, guild invitations and duels (friends and guild excepted). Hold **Shift** to skip auto-accept, auto-turn-in, auto-sell, training, binding or the flight helper once, or to answer a request yourself. ## With a gamepad Polestar plays with a gamepad on Forever (ported from the translated names database, @moust4ki). Open its options from the minimap button (or `/polestar gamepad` without the game's gamepad interface): their **Gamepad** page names the buttons (Xbox letters or PlayStation shapes, read off the gamepad by default), and its **Key bindings** tab binds every Polestar action: next and previous step, browse the guide, show or hide the guide window, the guide menu, the options, report a problem, and the quest item, target and Hearthstone buttons. Nothing is bound until you bind it. Press A on a row, then a button, or hold one button and press another for a combination: Polestar watches its combinations itself, keeps the second button from the game only while you hold the first, and never acts on one in a fight. With the game's gamepad interface on, LB and RB are its targeting buttons and every combination with them is the game's own: the row says so before it binds one. Tap B to cancel, hold B to bind B itself; Y unbinds. The rows take keys of the keyboard too. The guide window never takes a button away from the game. To browse it with the gamepad, bind **Browse the guide with the gamepad**: the D-pad picks a line (up from the goals: Skip, the bug, the menu and the tabs), A points the arrow there or uses the quest item on its line (not with the game's gamepad interface, whose own buttons Polestar leaves alone), X shows the line's details, LB / RB look at the previous and next step, Y minimizes the window, and B gives the gamepad back to the game. Every Polestar window you open (the guide menu with Lookup and Dungeons, the options, the welcome, the route choice, the report and copy windows, the drop-down menus) answers the gamepad while it is open: the D-pad moves the focus (an accent ring), A selects, B closes or goes back, LB / RB change tabs or pages, left / right adjust a slider or a drop-down, Y puts a setting back to its default. A window that opens by itself (the welcome on a new character, the choice of where to level next) takes no button until you press the Browse the guide button, which its bar shows. A bar under the window lists the buttons no button on screen shows; B sits on the window's close button. The gamepad goes back to the game when the window closes or a fight starts, and returns after it. Turn the bar off, or the windows' navigation altogether, on the Gamepad page. Without a gamepad plugged in, none of it shows: everything works with the mouse and keyboard as before. ## Recorder `Polestar_Recorder` is an optional companion addon that records your sessions to improve the routes. It is off until you turn it on (`/psrec on`, or Options > Recorder > Start recording) and writes nothing while off. Recordings replace the Classic Era estimates with Forever facts (quest XP, NPC and object positions, trainers, flight paths and times), feed the Codex what only play shows (rares and treasures, drops and how often they fall, dungeon entrances and bosses), and `record report` turns them into per-step timings: passes, median and p75 time, XP per hour, time in combat, deaths and travel, then the slowest steps and detours, the steps to fix first. ## Slash commands `/polestar` (or `/pole`) shows or hides the guide window; settings live in `/polestar options`, grouped by what you came to do: Guide, Appearance, Map, Questing, Discovery, Quality of Life, Integrations (settings for other addons Polestar works with, such as the community quest database, shown while they are installed), Guide packs, Gamepad, Recorder and About, with a search that finds any setting. With the game's gamepad interface on (Options, Gamepad, Enable Gamepad UI) there are no slash commands: the game blocks gamepad actions after any addon command typed in chat, until the game freezes. Polestar's minimap button (on by default then) and its key bindings open the guide and the settings instead, and Polestar keeps out of the game's own windows. ### Every slash command | Command | What it does | |---|---| | `help` | List every command | | `show`, `hide` | Show or hide the guide window | | `guides` | Open the hub on Guides | | `options [page]` | Open the settings, optionally on a page | | `next`, `prev` | Look at the next or previous step (nothing is skipped) | | `skip` | Skip the step shown, for good (the window offers Undo) | | `status` | Current guide and step | | `guide ` | Switch to a guide by id | | `tabs`, `tab `, `close` | List, switch and close guide tabs | | `path` | Choose where to level next, where a guide offers a choice of route | | `route` | Show the travel route to the current target | | `way [label]` | Point the arrow at x y on your current map (no argument clears it) | | `arrow show\|hide\|reset` | The waypoint arrow (drag it to move it) | | `reset` | Clear ticks and skips for the current guide | | `xp` | XP per hour, time to level and level splits | | `gear [item link]` | Gear advice: the weights in use, or compare an item | | `instances [clear]` | Instance limits, runs and lockouts | | `dungeons [name]` | Open Dungeons, or a dungeon's page | | `lookup [search]` | Open Lookup, optionally searching | | `mount` | Look up the mount of your target (or mouseover) and how to get it | | `rares [test]` | Open Rares, or show a sample rare alert | | `questdb` | Quest database status | | `packs` | Open Options > Community guides | | `gamepad` | Open Options > Gamepad: button names and key bindings | | `welcome` | Show the welcome again | | `where` | Print your map and position as guide lines (`zone map `, `goto x,y live`), in a box to copy | | `report` | Report a problem with the step on screen (the guide window's bug button) | | `discord` | The invite to the Polestar Discord, to copy | | `debug` | Toggle debug output | The Recorder has its own: `/psrec on | off | mark | clear` and a few more listed by `/psrec`. --- # Talent plans > Polestar's leveling talent plans for every class and spec: pick one, follow the marks on the talent frame, and get a reminder when a point waits. Page: https://polestar.guide/docs/players/talent-plans (Polestar docs > Players) Polestar has a leveling talent plan for every spec of every class in WoW: Forever: three per class, 27 in all, each an ordered list of picks from level 10 to 60 with short notes on why. A plan never spends a point for you. It shows you the next talent, and you spend it. ## Pick a plan Type `/polestar talents` to open your plan, or pick **Talents** on the hub's rail (`/polestar guides` opens the hub). Choose one of your class's three plans, or leave it on automatic: Polestar then follows the spec your gear advice uses, else the talent tree where you have spent the most points. The choice is kept for each character. ## On the talent frame With a plan chosen, the game's talent frame shows it: - **A ring** on the next talent in your plan while a point is unspent. - **Pick numbers**: where each talent comes in your plan's order (#1, #2, ...). - **A flag** on points the plan does not spend, so a misclick stands out. - **A line in each talent's tooltip**: where it comes in the plan, or that it is off the plan. When a point is waiting, a chat line names the plan's next talent. A plan is an order, not a schedule. The plans are written one point a level from 10, but Forever can hand out points sooner (a Legacy talent can grant them from level 5), so the levels in a plan's notes read "around level N", and the marks always follow the next pick whatever your level. Each plan was checked against Forever's own talent tree; if an update moves or renames a talent the plan uses, the Talents section says the plan is out of date and the frame shows no marks. ## Settings Under **Options, Questing, Talents** ([every option](https://polestar.guide/docs/reference/options#talents)): | Option | Default | What it does | |---|---|---| | Talent plans | On | Follow a talent plan for your class and spec | | Mark the talent frame | On | The ring on the next talent and the flag on points the plan does not spend | | Pick numbers | On | Each talent's place in the plan's order | | Plan in tooltips | On | The plan's line in each talent's tooltip | | Remind me of unspent points | On | The chat line naming the next talent when a point is waiting | ## Every class's plans Each class page lists its three plans pick by pick, with their notes, beside the class quests and the class steps on the leveling routes. | Class | Plans | |---|---| | [Warrior](https://polestar.guide/guides/class/warrior) | Arms, Fury, Protection | | [Paladin](https://polestar.guide/guides/class/paladin) | Holy, Protection, Retribution | | [Hunter](https://polestar.guide/guides/class/hunter) | Beast Mastery, Marksmanship, Survival | | [Rogue](https://polestar.guide/guides/class/rogue) | Assassination, Combat, Subtlety | | [Priest](https://polestar.guide/guides/class/priest) | Discipline, Holy, Shadow | | [Shaman](https://polestar.guide/guides/class/shaman) | Elemental, Enhancement, Restoration | | [Mage](https://polestar.guide/guides/class/mage) | Arcane, Fire, Frost | | [Warlock](https://polestar.guide/guides/class/warlock) | Affliction, Demonology, Destruction | | [Druid](https://polestar.guide/guides/class/druid) | Balance, Feral Combat, Restoration | ## Where the plans come from The Paladin plans are adapted from a community talent site's leveling builds. The Warrior and Rogue plans adapt that site's builds up to level 30, and the Druid and Warlock plans follow them to level 30 and are Polestar's own after. The Hunter's Beast Mastery and Marksmanship plans follow the site's builds to level 20; Survival, and the Mage, Priest and Shaman plans, are written for Polestar, with the site used only as a reference for Forever's new and changed talents. Every note is Polestar's own wording. [Credits & data sources](https://polestar.guide/docs/reference/credits) names the site. --- # How the routes are made > A simulator plays millions of complete 1-60 routes for every start and keeps the fastest; the guides are written from it. Page: https://polestar.guide/docs/players/how-routes-are-made (Polestar docs > Players) *(Diagram: How the routes are made, https://github.com/fitzforge/polestar/blob/next/docs/media/diagrams/players-how-routes-are-made.svg)* 1. **World model.** Every quest the faction can do, with its level, prerequisites, givers and enders, and the work its objectives take: kills at the mob's spawn clusters, item drops at their recorded rates, objects, escorts. Dungeon, raid, PvP and elite quests are filtered out, so a route is something one player can do alone. 2. **Search.** For each start (Orc, Tauren, Undead and Skyborne for the Horde; Human, Dwarf, Night Elf and Skyborne for the Alliance), randomised greedy construction, local search and simulated annealing evaluate millions of complete 1-60 routes, restarting until the best route stops improving or a cap on evaluated routes is reached. 3. **Route rules.** When routes are compared, grinding counts 2.5 times and every move into another zone counts 7.5 minutes, so a route takes a hub's quests, does them in one loop and moves on rather than chasing a few experience points across the map. Reported hours stay real. 4. **Consensus.** Each start keeps its own route to level 12 (the starting zone guides); from there one shared route per faction is searched, so the guides join into one chain. 5. **Guides.** The consensus route is exported as skeleton guides, one per zone visit, and the guides are written from them by hand. They drop side trips for one or two small quests behind a flight, boat, hearth or long ride; where that leaves the level short, a step names a camp to grind at (with an optional dungeon for the long ones). The finished guides are scored under the same model, next to the best route found. ## The numbers Hours to 60, solo, under the model. The routes were searched four times, independently: the first search is the one the guides were written from; each later one used another random seed, more routes and newer data. Each search is scored on its own world. The guides are scored on the world of the data this release ships with (`5eef72140b61`), beside those of the first release. The guides are scored on what they require. Their optional extras (quests started by rare drops such as the OOX beacons, the Green Hills of Stranglethorn pages, profession and bag quests, rares) are left out, because most players will not get them; the last column counts them as done, which is how these hours were published before 0.2.4 (issue [#30](https://github.com/fitzforge/polestar/issues/30)). | Start | Search 1: best / consensus | Search 2 | Search 3 | Search 4 | Guides 0.2.4 (grinding) | Guides 0.1.0 (grinding) | Guides 0.2.4 with every optional extra | |---|---:|---:|---:|---:|---:|---:|---:| | Orc | 119.4 / 120.5 | 120.7 / 117.8 | 117.7 / 116.8 | 119.6 / 117.3 | 131.1 (34.2) | 128.5 (29.7) | 122.8 | | Tauren | 120.4 / 120.2 | 119.1 / 117.4 | 118.3 / 116.5 | 117.1 / 116.8 | 130.1 (34.2) | 127.8 (29.1) | 121.9 | | Undead | 120.8 / 120.6 | 119.0 / 118.1 | 119.3 / 117.0 | 118.8 / 117.4 | 131.5 (33.8) | 128.9 (29.1) | 123.3 | | Skyborne (Horde) | 120.2 / 120.1 | 117.3 / 117.3 | 116.3 / 116.3 | 116.8 / 116.8 | 130.1 (32.8) | 128.3 (28.2) | 122.3 | | Human | 119.6 / 119.1 | 120.7 / 118.8 | 119.2 / 116.8 | 119.3 / 118.9 | 132.5 (37.0) | 132.1 (35.5) | 127.5 | | Dwarf | 119.5 / 119.5 | 120.8 / 118.8 | 117.4 / 117.3 | 119.8 / 118.8 | 133.1 (36.9) | 132.6 (35.5) | 128.2 | | Night Elf | 120.0 / 119.5 | 120.9 / 118.9 | 119.0 / 117.5 | 119.1 / 119.1 | 133.0 (37.1) | 132.6 (35.6) | 128.1 | | Skyborne (Alliance) | 121.2 / 119.6 | 118.6 / 118.6 | 118.2 / 117.3 | 119.0 / 118.4 | 133.5 (36.2) | 132.5 (34.5) | 129.0 | So a Horde character following the guides should expect about 130-132 h, an Alliance one about 132-134 h; doing the optional extras as they come can save up to about 8 h (Horde) and 5 h (Alliance). With every optional extra counted, the guides of 0.2.4 and 0.1.0 are within 0.6 h (Horde) and the Alliance guides of 0.2.4 are 0.8-1.6 h faster; counting only what each requires, 0.1.0 comes out 1.8-2.6 h faster for the Horde because the later guides marked more of their quests optional. *(Image: Chart: hours to 60 and hours of grinding per start, for what the guides require. The guides of 0.2.4 reach 60 in about 130 to 132 hours for the Horde and 132 to 134 for the Alliance; those of 0.1.0 in about 128 to 129 and 132 to 133. The guides of 0.2.4 grind about 33 to 34 hours for the Horde and 36 to 37 for the Alliance.)* *(Image: Chart: level against hours played for each faction, for what the guides require: the guides of 0.2.4 and those of 0.1.0 as curves, with a strip showing the hours the guides of 0.2.4 are ahead of (or behind) those of 0.1.0 at each level.)* The charts show only the guides: the searches' best and consensus routes were searched on earlier worlds, and a chart draws only numbers from one world. **How close to the best?** Nobody can prove a route is the best one possible, so the claim is narrower and checked: - **The searches land in the same place.** Four independent searches (3.5 to 30 million complete routes per start) find routes within 116.3-121.2 h to 60, and their consensus routes within 116.3-120.6 h. The top of the search space is flat: many different routes finish within about 2% of each other, and most searches were still finding small improvements when they reached their cap on routes, so later searches keep shaving minutes, not hours. - **The winners hold up when the model is wrong.** Re-scored under 2000 random draws of the model's parameters, the best route found stays within 1% of each draw's best in 76-100% of draws (fourth search), and no route wins every draw: "best found" names one of several near-equal routes. - **The guides trade hours for a smooth, safe run.** For what they require they take 13.3-14.1 h (Horde) and 13.6-15.1 h (Alliance) longer than the fourth search's consensus (scored on its own world). Almost all of that is grinding the guides choose: side trips for one or two small quests behind a flight, boat or hearth are left out, and quests that need a group, a rare drop or a level the route has not reached are optional or gone, so the guides grind about 33-34 h (Horde) and 36-37 h (Alliance) where the searched routes grind under 1 h and about 8 h. The Alliance mid-40s have few solo quests left once those trips are gone. - **Dungeons do not beat questing solo** under the model: searched with dungeons allowed (Orc, Tauren, Undead), no dungeon route came out ahead. > **Important:** > The hours are **model estimates in /played hours**, not measurements. No > recorded play exists yet, so time parameters such as kill time and travel > detours keep their priors, and Forever's 30-60 content is not in the data. > Comparisons between routes are what the numbers support; absolute hours > are not. Recordings from the Recorder are what will calibrate kill time > (`sim calibrate`); travel detours keep their priors even then. The whole method, every parameter and its known limitations are in [docs/SIMULATION.md](https://polestar.guide/docs/contributors/simulation). --- # Community guides > Guides written by other players: install one, find its guides, turn it on or off, and know who to ask. Page: https://polestar.guide/docs/players/community-guides (Polestar docs > Players) Guides for Polestar written by other players and published as their own addons. Install one next to Polestar and its guides show up in the guide menu, with the arrow, the map markers and everything else Polestar does. **I want to play them** Install a community addon, find its guides, turn it on or off, and know who to ask when something is wrong. **[I want to write my own](https://polestar.guide/docs/authors/community-guides)** Write guides in plain text, check them with Polestar's tools and publish them as your own addon. *(Image: The guide menu: under the Community guides heading, Joe's Routes is selected and lists four Alliance leveling guides; Westfall's details read By Joe, Joe's Routes 1.2.0, CC-BY-4.0, Written from my own play)* ## At a glance | | Polestar's own guides | Community guides | |---|---|---| | **Written by** | Polestar | the addon's author | | **Tested by Polestar** | yes | no: Polestar does not test or vouch for them | | **How you get them** | they come with Polestar | a separate addon you install yourself | | **Where they show** | the guide menu's categories (Leveling, Professions…) | the guide menu, under **Community guides** | | **Where to report a problem** | the [Polestar Discord](https://discord.gg/polestar) or GitHub | the addon's author, where they publish it | A community addon only adds guides: it never replaces Polestar's own or another community addon's. Polestar does not ship, host or recommend any; you only see one if you install it yourself. ## Install one 1. **Install Polestar first.** A community addon does nothing without it. 2. **Download the community addon** from wherever its author publishes it: CurseForge, Wago or the author's own site. Its page there should say that it needs Polestar. 3. **Install it like any addon**: with your addon app, or by unzipping it into the game's `Interface/AddOns` folder, next to the `Polestar` folders. 4. **Restart the game.** > **Tip:** > After the first install, `/reload` is enough to pick up an update. ## Find its guides Open the guide menu (`/polestar guides`). Below Polestar's own categories is the **Community guides** heading, with one entry per community addon: its title and its author. Every guide's details say who wrote it: "By <author> · <title> <version> · <license>". ## Turn one on or off **Options > Community guides** (`/polestar packs`) lists every community addon you have installed, with its author, version, license and website. *(Image: Options, Community guides: Polestar Guides and Joe's Routes switched on, Ann's Dungeons with 2 problems and its report, Kim's Quests turned off in the AddOns list, Sam's Professions not loaded)* - **The switch** on a row shows or hides its guides at once, without a reload. - **Suggest guides from** picks where the guide for your level is suggested from. It is Polestar's own guides unless you choose a community addon; Polestar's guides still fill in wherever that addon has nothing for your character. - **To remove one for good**, delete its folder or uninstall it in your addon app. ## When something is wrong Report wrong steps and other problems in a community addon to **its author**, not to Polestar. The author wrote those guides and is the one who can fix them. - When a community addon has problems, its row on the Community guides page says how many. **Show** lists them; **Copy report** copies them, with the versions, ready to send. - When it cannot run at all, its row says why (for example, turned off in the AddOns list, or made for a newer Polestar). - The row shows the author's website when they gave one. > **Warning:** > A community addon is an addon like any other, and the game runs it like > any other. Install community addons only from authors you trust, and only > from the place the author publishes them. ### Telling a community addon from Polestar's own in the AddOns list In the game's AddOns list, Polestar has one entry in the Quests category. Open it and you see Polestar's own addons and your community addons side by side. - **Polestar's own addons** are Polestar Guides and the addons that carry Polestar's data (Polestar Quest Database, Polestar Item Data, Polestar Codex), plus Polestar Recorder for guide authors. Each lists Polestar as its author. - **A community addon** built with Polestar's tools is titled "Polestar Community:" and its own name, such as "Polestar Community: Emberway Routes". Point at it and the tooltip shows its version and a line such as "Community addon for Polestar by Ashka", unless its author wrote their own. - One built before Polestar used that name reads "Polestar Pack:" until its author rebuilds it. Polestar reads both. ### Can I use several at once? Yes. Each one gets its own entry under Community guides, and you can open guides from different addons in different tabs. --- # Import strings > A small guide shared as one line of text: paste it into Import and it joins your guide menu. Page: https://polestar.guide/docs/players/import-strings (Polestar docs > Players) A small guide, such as a quest chain, an item, a mount or an errand, can come as an **import string** instead of an addon: one line of text its author shares on Discord, GitHub or a forum. Nothing to install. 1. Open **Import** at the foot of the hub's left rail, just above Options (`/polestar import`). 2. Paste the string into the box. Polestar reads it and shows what it holds before anything is saved: "Cozy Sleeping Bag · by Yendi · 14 steps · levels 30–40 · Alliance and Horde · CC-BY-4.0". 3. Press **Import**. The guide is in the guide menu under **Community guides**, in the entry **Imported**, credited to its author: "By Yendi · Imported · CC-BY-4.0". It stays imported on every character of your account. - **To update it**, paste the newer string: the button reads **Update**, and your progress stays where the guide's steps did not change. - **To remove it**, press **Delete** on its row under **Your imported guides** (twice: the second click confirms). - A string Polestar cannot read, one that is too big, or one holding a guide Polestar refuses is turned down with the reason, and nothing is saved. - Polestar never suggests an imported guide on its own: you pick it. An import string is data, never code: Polestar reads the guide out of it field by field and runs nothing in it, so it cannot do anything a guide cannot. As with a community addon, Polestar does not test or vouch for the guide; report its problems to its author. --- # Polestar Client > A small desktop app that installs Polestar's addons and community guides and keeps them up to date. Version 0.1.0, in beta. Page: https://polestar.guide/docs/players/client (Polestar docs > Players) Polestar Client is a small desktop app for Windows, macOS and Linux. It installs Polestar's addons and community guides and keeps them up to date. The current version is `0.1.0`, a beta: [download it](https://polestar.guide/docs/players/client#downloads) below, or see the overview, with screenshots, at [Polestar Client](https://polestar.guide/client). > **Note:** > **You don't need it.** Polestar works without the client. Install it from the > CurseForge app or a release zip, and download community guides as a zip, as > [Install and first run](https://polestar.guide/docs/players/quick-start) and > [Community guides](https://polestar.guide/docs/players/community-guides) describe. ## What it does - **Keeps Polestar up to date.** It installs and updates Polestar, Polestar Recorder and LibForeverData from their GitHub releases. Every download is checked against its published checksum, and your other addons are never touched. - **Community guides in one click.** On a community guide's page on polestar.guide, choose **Download guide**, then **Install with Polestar Client**. The client opens with a confirm sheet; there is no account. Its Community Guides page installs, updates and removes them. - **Automatic guide updates, if you want them.** They are off by default and take routine updates only, a day after release. A new publisher or new folders always asks first. - **Careful with your AddOns folder.** Every guide list is signature-checked, and only guide files go into AddOns. If polestar.guide pulls a guide, the client turns it off or removes it and shows you why. - **Recording, opt-in.** Choose **Start sharing** in the client and it uploads what the Polestar Recorder addon logs (quests, kills, NPC positions) to help build better routes. Character names are stripped and chat is never sent. The **What we send** page shows all of it. Recording starts with the next Polestar update. - **Looks after itself.** It updates itself with signed updates, and lives in the tray with a small window. No account, no login. It works with World of Warcraft: Forever only. ## Downloads Version `0.1.0`, from the [release on GitHub](https://github.com/fitzforge/polestar/releases/tag/client-v0.1.0), which has the release notes: | System | Download | |---|---| | Windows (x64 and Arm) | [Installer, `.msi`](https://github.com/fitzforge/polestar/releases/download/client-v0.1.0/Polestar.Client_0.1.0_x64_en-US.msi) (on Windows on Arm it runs through Windows' x64 emulation) | | macOS (Apple silicon and Intel) | [Disk image, `.dmg`](https://github.com/fitzforge/polestar/releases/download/client-v0.1.0/Polestar.Client_0.1.0_universal.dmg) | | Linux (x64) | [AppImage](https://github.com/fitzforge/polestar/releases/download/client-v0.1.0/Polestar.Client_0.1.0_amd64.AppImage) or [Debian package, `.deb`](https://github.com/fitzforge/polestar/releases/download/client-v0.1.0/Polestar.Client_0.1.0_amd64.deb) | | Linux (Arm) | [AppImage](https://github.com/fitzforge/polestar/releases/download/client-v0.1.0/Polestar.Client_0.1.0_aarch64.AppImage) or [Debian package, `.deb`](https://github.com/fitzforge/polestar/releases/download/client-v0.1.0/Polestar.Client_0.1.0_arm64.deb) | The macOS app is signed and notarized by Apple. > **Warning:** > **Windows builds aren't code-signed yet.** SmartScreen says the publisher is > unknown: choose **More info**, then **Run anyway**. --- # FAQ > Short answers to the questions players ask most, each with the page that tells the rest. Page: https://polestar.guide/docs/players/faq (Polestar docs > Players) ## Getting started ### Is Polestar free? Yes. Polestar is free and open source, under the GPL-3.0 license, and every guide comes with it. Install it from the CurseForge app or from a release on GitHub: see [Install and first run](https://polestar.guide/docs/players/quick-start). ### I installed it, but nothing shows in the game. Restart the game completely: a `/reload` does not load a newly installed addon. Check that the `Polestar` folders sit directly inside the game's `Interface/AddOns` folder, not in a folder of their own inside it. ### How do I update? In the CurseForge app, update it like any other addon. With a release zip, delete the old Polestar folders, then unzip the new release the same way you installed it. ### Which languages does it speak? Its interface and its guides read in English, German, French, Spanish (Spain and Latin America), Brazilian Portuguese, Russian, Korean and Chinese (simplified and traditional). ## Playing ### Where are all the guides and settings? `/polestar guides` opens the hub: every guide, Lookup, Dungeons and Rares. `/polestar options` holds every setting. `/polestar skip` moves on for good; `/polestar next` and `prev` only look ahead or back. ### Why are there no quest markers on my map? They are off until you turn them on, under **Map** in the options. ### How much memory does it use? The arrow's walking routes load after login, never in combat: about 34 MB for the walking maps, and while a walk is being searched up to about 45 MB more, released when the search ends. With **Walk real paths** (Options, Arrow & routes) off they never load. The details are in [Install and first run](https://polestar.guide/docs/players/quick-start). ### Has every guide been played through? Polestar is in beta. Every guide compiles, lints and plays to the end in a simulator for every race and class it serves, and the routes are found by simulation: see [How the routes are made](https://polestar.guide/docs/players/how-routes-are-made). ## Community guides ### What is a community guide? A guide for Polestar written by another player and published as its own addon. Install one beside Polestar and its guides show up in the guide menu under **Community guides**, with the arrow and everything else Polestar does. Polestar does not ship, host or recommend any: see [Community guides](https://polestar.guide/docs/players/community-guides). ### Can I use several community guides at once? Yes. Each gets its own entry under Community guides, and you can open guides from different ones in different tabs. **Options > Community guides** turns each one on or off without a reload. ### Is an import string safe? An import string is data, never code: Polestar reads the guide out of it field by field and runs nothing in it. As with any community guide, Polestar does not test or vouch for it: see [Import strings](https://polestar.guide/docs/players/import-strings). ### A community guide has a wrong step. Who do I tell? Its author, where they publish it. They wrote the guide and are the one who can fix it. Its row under **Options > Community guides** can copy a report of its problems, with the versions, ready to send. ### A community guide looks harmful, offensive or broken. What can I do? Open it on polestar.guide and use **Report this guide** under the download button (you need to be signed in). Reports go to Polestar's moderators, who can hide the guide or pull it from every player's Polestar Client. ### A community guide copies my work. How do I get it taken down? Send a copyright notice with the [copyright form](https://polestar.guide/legal/copyright/report). You don't need an account: you confirm it from your email, and a moderator reviews it. If it holds up, the guide is taken off polestar.guide and removed from players' Polestar Clients. The author is told who made the claim (your name and organization, never your contact details) and may send a counter-notice. The whole process is on [Copyright & takedowns](https://polestar.guide/legal/copyright). ## Helping out ### How do I report a wrong step in Polestar's own guides? Click the bug in the guide window, beside Skip, say what went wrong and copy the report: it already holds the step, where you stand and the versions. Paste it on the [Polestar Discord](https://discord.gg/polestar), or open an [issue](https://github.com/fitzforge/polestar/issues). ### Can I help improve the routes? Yes. `Polestar_Recorder`, a separate zip in each release, records your sessions to improve the routes; it does nothing until you turn it on. There is more you can do in [Contributing](https://polestar.guide/docs/contributors/contributing). --- # Using Polestar with AI assistants > Give ChatGPT, Claude, Copilot or a coding agent Polestar's own docs, so it answers from them instead of from memory. Page: https://polestar.guide/docs/players/ai-assistants (Polestar docs > Players) An AI assistant asked about Polestar answers from what it remembers, and it remembers little about Polestar and about WoW: Forever, whose quests differ from Classic's. Give it Polestar's docs and it answers from them instead. Every docs page and guide on polestar.guide has a plain Markdown copy made for this. ## For players - **Paste the index.** Give your assistant [polestar.guide/llms.txt](https://polestar.guide/llms.txt) with your question. It says what Polestar is, how to install it and its main commands, and links every docs page and guide. - **Paste one page.** Add `.md` to a docs page's address, as in [polestar.guide/docs/players/faq.md](https://polestar.guide/docs/players/faq.md). At the top of every docs page, **View as Markdown** opens that copy and **Copy as Markdown** copies it. - **Give it everything.** [polestar.guide/llms-full.txt](https://polestar.guide/llms-full.txt) holds the docs for players and guide authors in one file, for an assistant that reads long files or a project's knowledge files. - **Ask about a guide.** The guide pages have Markdown copies too: a faction's road from every start to 60 ([Alliance](https://polestar.guide/guides/alliance.md), [Horde](https://polestar.guide/guides/horde.md)), a class's talent plans and class quests ([Warrior](https://polestar.guide/guides/class/warrior.md)), or a zone's guide with its steps in order. Ask "which guide should my level 20 Orc play?" with the Horde road. A prompt that works: ```text title="Prompt" Read https://polestar.guide/llms.txt and the pages it links that you need. Answer from them only, and name the pages you used. My question: how do I turn on quest markers on the map? ``` An assistant can still be wrong. Check its answer on the page it names, and report a wrong step from the game (the bug in the guide window, beside Skip), not from what an assistant says. ## For guide authors - **Point a coding agent at the format.** The [authors' overview](https://polestar.guide/docs/authors.md), the [guide format](https://polestar.guide/docs/authors/guide-format.md) and the [guide format reference](https://polestar.guide/docs/reference/guide-lines.md) are what it needs to write a `.guide` file; the [command line](https://polestar.guide/docs/reference/cli.md) lists every `polestar` command. - **Work in a pack folder.** `polestar new` writes `AGENTS.md` and the polestar-guide-pack skill into the pack, so an agent started there already follows Polestar's workflow: see [Writing guides with an AI agent](https://polestar.guide/docs/authors/agent-workflow) and the handbook's [With an AI assistant](https://polestar.guide/docs/authors/handbook#with-an-ai-assistant). - **Ids are guesses until the tools agree.** An assistant's quest ids, NPC ids, place names and coordinates are guesses until `polestar find`, `lint` and `playtest` confirm them. --- # Overview > Write leveling guides in plain text, test them in the playground and publish them as your own community addon. Page: https://polestar.guide/docs/authors (Polestar docs > Guide authors) Anyone can write guides for Polestar and publish them as their own addon, with the tools Polestar uses for its own: the guide format, the compiler, `lint`, `playtest`, and in the game the guide engine, the arrow and the map markers. Hand over to any of Polestar's guides with `next`, so your guides can cover one zone or the whole climb, under a license of your choice. ## A guide is plain text Each guide is a `.guide` file: a header, then steps, each with its goals. The compiler fills in names, titles and coordinates from the reference data, so a line can be as short as `accept 783`. Try it: edit the guide, and the guide window shows the step as a player sees it. To start a community guide of your own: ```sh title="Terminal" git clone https://github.com/fitzforge/polestar.git cd polestar npm link # puts `polestar` on your PATH; no npm dependencies polestar data build # the reference data every guide command reads polestar doctor # checks the setup and prints the fix for anything missing cd .. # your community guide goes beside the clone, not inside it polestar new my-pack # asks for the id, title, author and license cd my-pack polestar dev --play # lint and build on every save, with the browser playground ``` ## Publish on polestar.guide A community guide is a folder: `pack.json` at its top and one `.guide` file per route, with pictures in `.tga` or `.blp` if it has any. You publish its source, never a built addon or Lua: the site builds the addon with Polestar's own compiler. Sign in and turn on two-step sign-in in Account settings › Sign-in & security first: publishing needs it, so a stolen password alone can't send anything to players. Then open [New community guide](https://polestar.guide/studio/new) and follow its five steps: 1. **Id and title.** The id names the addon folder (`PolestarPack_`) and starts every route's id; pack.json's `"id"` must match it. You can change it until a version has gone out to players. 2. **How you publish.** Upload here, or publish from GitHub Actions (below). An upload takes the folder or a zip of it (at most 10 MB zipped, 40 MB unpacked, 500 files). The page checks it in your browser before anything is sent, so a missing `pack.json` or a route under the wrong id shows at once. 3. **Build report.** The compiler checks every step against the game data, as `polestar lint` does, in a few seconds. Errors stop the build: fix them and upload again, with the same version number. Warnings don't. The built zip then goes to VirusTotal's malware scanners, which can take a few minutes. 4. **Listing.** A summary, a description, tags and pictures for the guide's page. 5. **Visibility.** Public, unlisted, or a draft only you and your co-authors see. You can publish while the first version still waits for a moderator: the guide goes live with your choice by itself once it is approved. Everything saves as you go, so you can leave and finish later from [Your guides](https://polestar.guide/account/guides), which shows where each guide is: in review, scanning, public, unlisted or turned down (with the moderator's reason). For a new version, raise `"version"` in pack.json and upload again from the guide's **Versions** tab, or push a tag from GitHub Actions. ### What happens to each version - **Build and checks.** A version that doesn't build never reaches anyone. - **Malware scan.** A version is published only once its scan is clean. - **Review.** A moderator looks at a guide's first version from each author, and at any later version that comes with a new owner or installs different addon folders, usually within a day. You hear the outcome in your notifications and by email. Other updates go out on their own. - **Players.** Once published, players who download it from the site get it at once; the Polestar Client's automatic updates install it 24 hours later, so you have time to pull a bad version. - **An email for every upload.** The guide's owner (and whoever uploaded it) gets a mail naming the version, who uploaded it and how. If it wasn't you or your co-authors, its **This wasn't me** link pulls the version from every player's client, revokes the token that sent it and tells the moderators. Once a version has gone out to players, deleting the guide retires its id for good: nobody can publish a guide with it again, so its players never get someone else's updates. ### If your guide is reported Players can report a guide, and rights-holders can send a copyright notice about it. A moderator looks at each one. If a copyright notice holds up, the guide is taken down: it is hidden on polestar.guide, every version is removed from players' Polestar Clients, and you and your co-authors get an email with the claim and who made it. If you believe it was a mistake, send a counter-notice from the banner on the guide's page in the studio. It is forwarded to the claimant, and unless they tell us they have gone to court, the guide can be restored after 10 to 14 business days. The removed versions stay removed, so upload a new version once it is back. A takedown that stands counts against your account, and repeated infringement can close it. Details: [Copyright & takedowns](https://polestar.guide/legal/copyright). ## Publish from GitHub Actions If your guide lives in a GitHub repository, a workflow can publish each release for you: push a tag like `v1.2.0` and it uploads the guide folder with the same checks and build as an upload in the studio. polestar.guide never reads your repository; the workflow sends the source with a token for this one guide. 1. **Make a token.** In [Your guides](https://polestar.guide/account/guides), open the guide's **Publishing** tab (or pick **Publish from GitHub Actions** when you create it) and choose **Create a token for this guide**. It is shown once. A token can only upload new versions of that one guide: it can't change the listing, touch your other guides or your account. Only an owner of the guide can make one, from a session confirmed with two-step sign-in. It expires after 90 days unless you pick another time (a year at most), and every token goes when your password is reset. Account settings › Publish tokens lists yours, with their guide, expiry and last use, and revokes them. 2. **Add it to the repository** as a secret named `POLESTAR_TOKEN`: on GitHub, **Settings → Secrets and variables → Actions → New repository secret**. 3. **Add the workflow** as `.github/workflows/polestar.yml`. The Publishing tab has it with your guide's id filled in; for a guide with the id `my-guide` it is: ```yaml title=".github/workflows/polestar.yml" # Publishes a new version of "My Guide" to polestar.guide when you push a tag like v1.2.0: # git tag -a v1.2.0 -m "What changed in this version" # git push origin v1.2.0 # The tag must match "version" in pack.json; the tag's message becomes the release notes. # Needs the repository secret POLESTAR_TOKEN: this guide's publish token, made in the studio # (Your guides > my-guide > Publishing). name: Publish to Polestar on: push: tags: ['v*'] permissions: contents: read concurrency: group: polestar-publish defaults: run: shell: bash env: POLESTAR_URL: https://polestar.guide/api/packs/my-guide/versions # The folder with pack.json at its top, from the repository's root. GUIDE_DIR: . jobs: publish: runs-on: ubuntu-latest timeout-minutes: 20 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Read the release notes from the tag run: | git fetch --no-tags --depth=1 origin "+refs/tags/$GITHUB_REF_NAME:refs/tags/$GITHUB_REF_NAME" git for-each-ref --format='%(if:equals=tag)%(objecttype)%(then)%(contents:subject)%0a%0a%(contents:body)%(end)' "refs/tags/$GITHUB_REF_NAME" | head -c 5000 > "$RUNNER_TEMP/notes.txt" - name: Zip the guide folder working-directory: ${{ env.GUIDE_DIR }} run: | zip -q -r -D "$RUNNER_TEMP/guide.zip" . \ -i 'pack.json' 'legs.json' 'retired.json' 'LICENSE*' 'README*' '*.guide' '*.tga' '*.blp' \ -x 'dist/*' 'drafts/*' 'node_modules/*' '.*' '*/.*' unzip -l "$RUNNER_TEMP/guide.zip" - name: Upload to Polestar env: POLESTAR_TOKEN: ${{ secrets.POLESTAR_TOKEN }} run: | curl --fail-with-body --silent --show-error \ -H "Authorization: Bearer $POLESTAR_TOKEN" \ -F "files=@$RUNNER_TEMP/guide.zip" \ -F "version=${GITHUB_REF_NAME#v}" \ -F "changelog=<$RUNNER_TEMP/notes.txt" \ "$POLESTAR_URL" echo - name: Wait for the build env: POLESTAR_TOKEN: ${{ secrets.POLESTAR_TOKEN }} run: | for i in $(seq 60); do build=$(curl --fail-with-body --silent --show-error --retry 6 --retry-delay 10 -H "Authorization: Bearer $POLESTAR_TOKEN" "$POLESTAR_URL/${GITHUB_REF_NAME#v}") case "$(jq -r .status <<<"$build")" in ready) echo "Built. It is published once its malware scan is clean (and a moderator has reviewed a first version)."; exit 0 ;; failed) jq . <<<"$build"; exit 1 ;; esac sleep 10 done echo "::notice::Still building after 10 minutes: see the guide's Versions tab in the studio." ``` 4. **Tag a release.** Raise `"version"` in pack.json, commit, then tag that version; the tag's message becomes the release notes: ```sh title="Terminal" git tag -a v1.2.0 -m "What changed in this version" git push origin v1.2.0 ``` - **The tag must match pack.json.** `v1.2.0` uploads only a pack.json that says `"version": "1.2.0"`; anything else is refused. - **Only the source goes up:** `pack.json`, `legs.json` and `retired.json`, `LICENSE` and `README`, every `.guide` file and `.tga` or `.blp` picture, never `dist/`, `drafts/` or hidden folders. If pack.json isn't at the top of the repository, set `GUIDE_DIR` to its folder. - **A refused upload fails the run**, with the reasons (file, line, message, hint) in its log, and so does a failed build; the run waits for the build and passes once it is ready. A version that would drop route ids players follow is refused too: upload that one from the studio, which asks you to confirm. - The workflow uses only `actions/checkout`, pinned by commit, and `curl`. An account can publish at most 30 uploads an hour. ## Where to go next | Page | What it answers | |---|---| | [Writing a community guide](https://polestar.guide/docs/authors/community-guides) | What you get, the steps from your first guide to publishing, and the checklist before you do | | [Handbook](https://polestar.guide/docs/authors/handbook) | Setup on each system, a first community guide in 15 minutes, testing, publishing and updating, every problem and its fix | | [Guide format cheatsheet](https://polestar.guide/docs/authors/cheatsheet) | Every header line, goal and condition on one page, each with a short example | | [Guide format](https://polestar.guide/docs/authors/guide-format) | The `.guide` language in full, what the compiler fills in, validation and a cookbook | | [Community guide format](https://polestar.guide/docs/authors/community-guide-format) | `pack.json`, the addon the compiler writes, the rules Polestar enforces, import strings and versioning | | [Translating](https://polestar.guide/docs/authors/translating) | The locale files, the glossary and the `i18n` commands | | [Writing guides with an AI agent](https://polestar.guide/docs/authors/agent-workflow) | The workflow an AI agent follows to write, fix and build a community guide's routes | > **Note:** > A community addon is made and supported by its author. Polestar does not > ship, host or recommend any, and players report problems in one to its > author. --- # Writing a community guide > What you get, what a pack looks like, the steps from your first guide to publishing, and the checklist before you do. Page: https://polestar.guide/docs/authors/community-guides (Polestar docs > Guide authors) ## What you get If you write leveling guides, you can use everything Polestar uses for its own: - **The guide format**: plain text `.guide` files. The compiler fills in quest titles, givers and coordinates from the reference data, so `accept 7` is a whole line. - **The checks**: `lint` checks every guide against the game's data, and `playtest` plays each one to the end in the real addon, without the game. - **In the game**: Polestar's guide engine, its waypoint arrow, its travel planner and its markers on the map. You publish the result as your own addon, under your name and a license of your choice. ## Quick start You need Node 24 or newer, and Lua 5.1 or LuaJIT for `play` and `playtest`. [PACKS.md, "Setup"](https://polestar.guide/docs/authors/handbook#setup) has the install command for each system. ```sh git clone https://github.com/fitzforge/polestar.git cd polestar npm link # puts `polestar` on your PATH polestar data build # the reference data every guide command reads polestar doctor # checks the setup and prints the fix for anything missing cd .. # your pack goes beside the clone, not inside it polestar new my-pack # asks for the id, title, author and licence cd my-pack polestar dev --play # lint and build on every save, with the browser playground ``` > **Tip:** > No Node or Lua on your machine? When your Polestar clone came from GitHub, > a pack made by `polestar new` carries a dev container: open the pack's > repository in GitHub Codespaces and everything is set up. `install` and > `dev` need the game, so use `play` and `playtest` there. ## What a pack looks like A community addon is built from a **pack**: a folder with a `pack.json` and your `.guide` files. ```text my-pack/ ├── pack.json your addon's id, title, author, version and licence ├── guides/ │ └── westfall.guide your guides, in any layout ├── LICENSE the licence you chose └── README.md for your players ``` ```json { "id": "joe-routes", "title": "Joe's Routes", "author": "Joe", "version": "1.2.0", "license": "CC-BY-4.0", "website": "https://github.com/joe/joe-routes" } ``` ```text guide joe-routes/northshire title Northshire Valley faction Alliance race Human levels 1-4 zone Elwynn Forest step Deputy Willem accept 783 turnin 783 accept 7 step Kobold camp kill 6 x10 quest 7.1 step Back to the abbey turnin 7 ``` The tools build the addon from these: the TOC, your credits, the compiled guides and the license files. Don't edit the built files: change the pack and build again. [PACK_FORMAT.md](https://polestar.guide/docs/authors/community-guide-format) describes every line of them. ## From first guide to published 1. **Start**: `polestar new my-pack` writes `pack.json`, an example guide that already passes every check, a README for your players and the `LICENSE` you chose. In a clone of the public repository it also writes a GitHub workflow that checks every push. 2. **Write**: `polestar find ` prints quest, NPC, object, item, inn and flight-point lines ready to paste. In the game, `/polestar where` prints where you stand as a guide line. 3. **Check**: `polestar lint` checks every guide against the game's data, and `polestar playtest` plays each one to the end, for each race that can reach it and each class it has steps for. 4. **Try**: `polestar play` opens the real addon in your browser with your pack loaded, and `polestar install` copies it into the game's AddOns folder (restart the game the first time). 5. **Build**: `polestar pack` writes `dist/-.zip`, byte for byte reproducible. 6. **Publish**: upload the zip as a new addon project on CurseForge, Wago or GitHub. On CurseForge and Wago, mark Polestar as a required dependency so addon apps install it too. With the template's workflow, a version tag on GitHub builds the zip and attaches it to a release. 7. **Update**: raise `version` in `pack.json`, run `polestar pack` again and upload the new zip. > **Note:** > An AI assistant can help you draft guides from your own material. > [PACKS.md, "With an AI assistant"](https://polestar.guide/docs/authors/handbook#with-an-ai-assistant) says > how, and why every id it writes needs checking. Every pack `new` writes > includes a skill for coding agents, polestar-guide-pack. ## Before you publish **The tools check these.** `lint` reports them, and `compile`, `install` and `pack` stop until they are fixed: - [ ] `pack.json` has an `id`, `title`, `author`, `version` and `license`. The id is 2 to 32 lower-case letters, digits or hyphens, and not one Polestar reserves. A title or an author name is at most 64 characters. - [ ] Every guide id starts with your pack id and a slash (`ashka-emberway/westfall`). - [ ] The addon folder is not named `Polestar` and does not start with `Polestar_`. By default it is `PolestarPack_` and your title (`PolestarPack_EmberwayRoutes`). - [ ] A `website`, when you give one, starts with `https://` or `http://`. - [ ] A `next` line hands over only to a guide that exists, is for the same faction, and that the characters of your guide can follow. `lint` also warns while `LICENSE` still holds the placeholder line `new` writes for a license it has no text for. **We ask these of you.** No tool checks them, but players need them to tell your addon apart and to reach you: - [ ] **A name of your own** that can't be mistaken for Polestar's addons. The tools put "Polestar Community:" before it in the AddOns list. Say on your addon page that it is a community addon for Polestar, and if you write your own `notes` line, keep that clear there too. - [ ] **Your name** as the author: the name players will look for. - [ ] **A version** you raise with every release. - [ ] **A website or support link** in `website`, so the Community guides page shows players where to report problems. Say the same on your addon page and in your README. - [ ] **A license of your choice.** Polestar's [LICENSE-EXCEPTION.md](https://polestar.guide/docs/reference/license-exception) lets you publish a community addon built by its compiler, including the reference data the compiler puts in it, under any terms you like. - [ ] **Your own guide text.** Don't copy text from Polestar's own guides: the license exception does not cover it. Handing over to one of Polestar's guides with `next` is fine, since that points to the guide rather than copying it. - [ ] **Support for it.** Players are told to report problems to the author, so answer them where you publish. ### How your addon shows in the AddOns list The TOC places your community addon under Polestar's entry in the Quests category, titled "Polestar Community: <your title>", with the line "Community addon for Polestar by <author>" unless you write your own `notes`. Polestar's own menus show your title as you wrote it. Community addons built before this name read "Polestar Pack:" until you rebuild them; Polestar reads both. ## Import strings A single small guide can go to players as one line of text instead of an addon: they paste it on Polestar's Import page (`/polestar import`). Use it for a quest chain, an item, a mount, an errand; a route or a set of guides is a community addon. | | Import string | Community addon | |---|---|---| | **For** | one small guide | a whole route or a set of guides | | **You run** | `polestar export ` | `polestar pack` | | **Players** | paste it on the Import page | install it, then restart the game | | **Updates** | raise the guide's `version` and share the new string: players press Update | raise `version` in `pack.json` and upload the new zip | | **Size** | one guide of at most 60 steps (and 50,000 characters) | no limit | ```sh polestar lint && polestar playtest # the same checks as for an addon polestar export guides/cozy-sleeping-bag.guide > cozy.txt ``` - The guide still lives in a pack: `export` finds the `pack.json` above the file, and the guide id starts with your pack id (`yendi/cozy-sleeping-bag`), so two authors' guides never collide. The string carries the guide and your pack's `license`; its author is the guide's `author`, else the pack's. - `export` lints the pack first and refuses a guide with errors (another guide's errors do not stop it). It prints only the string on stdout, so `> file.txt` keeps just that line. - A guide's `version` decides between Import and Update in the game: raise it when you share a new string. - A `next` or route choice may lead only to one of Polestar's guides or to a guide the player imported before; `export` names the guides to import first. Polestar refuses a string whose guide leads anywhere else. - A guide id under the id of a community addon the player has installed stays that addon's: the string is refused. - In `polestar play ` (and `polestar dev --play`), **Copy import string** beside the guide picker gives the string of the guide picked. The format of the string is in [PACK_FORMAT.md, "Import strings"](https://polestar.guide/docs/authors/community-guide-format#import-strings). Strings are covered by the same [license exception](https://polestar.guide/docs/reference/license-exception) as community addons. ## Where to go next | You want to… | Read | |---|---| | Write your first pack, step by step | [PACKS.md, "A first pack in 15 minutes"](https://polestar.guide/docs/authors/handbook#a-first-pack-in-15-minutes) | | Write guides by playing, from the simulator, by hand or with an AI assistant | [PACKS.md, "Four ways to write guides"](https://polestar.guide/docs/authors/handbook#four-ways-to-write-guides) | | Look up a guide line quickly | [GUIDE_CHEATSHEET.md](https://polestar.guide/docs/authors/cheatsheet) | | Read the whole guide format | [GUIDE_FORMAT.md](https://polestar.guide/docs/authors/guide-format) | | Fix a lint message or an in-game problem | [PACKS.md, "Lint messages"](https://polestar.guide/docs/authors/handbook#lint-messages) and ["In game: statuses and problems"](https://polestar.guide/docs/authors/handbook#in-game-statuses-and-problems) | | Update after a game patch | [PACKS.md, "Updating"](https://polestar.guide/docs/authors/handbook#updating) | | Know exactly what the tools write | [PACK_FORMAT.md](https://polestar.guide/docs/authors/community-guide-format) | Questions, or a community addon to show? Players and authors meet on the [Polestar Discord](https://discord.gg/polestar). --- # Handbook > The full handbook: setup on each system, a first pack in 15 minutes, testing, publishing, updating, and every problem with its fix. Page: https://polestar.guide/docs/authors/handbook (Polestar docs > Guide authors) 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](https://polestar.guide/docs/authors/guide-format)), 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. > **Tip:** > New here? [GUIDE_PACKS.md](https://polestar.guide/docs/players/community-guides) is the short version: what a > community addon is, the steps from `new` to publishing, and what we ask of > authors. This page is the full handbook; the exact files the tools write > are in [PACK_FORMAT.md](https://polestar.guide/docs/authors/community-guide-format). | On this page | | |---|---| | **Get going** | [Setup](https://polestar.guide/docs/authors/handbook#setup) · [A first pack in 15 minutes](https://polestar.guide/docs/authors/handbook#a-first-pack-in-15-minutes) | | **Write guides** | [By playing](https://polestar.guide/docs/authors/handbook#by-playing) · [From the simulator](https://polestar.guide/docs/authors/handbook#from-the-simulator) · [By hand](https://polestar.guide/docs/authors/handbook#by-hand) · [With an AI assistant](https://polestar.guide/docs/authors/handbook#with-an-ai-assistant) | | **Ship it** | [Testing](https://polestar.guide/docs/authors/handbook#testing) · [Publishing](https://polestar.guide/docs/authors/handbook#publishing) · [Updating](https://polestar.guide/docs/authors/handbook#updating) | | **Fix a problem** | [In game: statuses and problems](https://polestar.guide/docs/authors/handbook#in-game-statuses-and-problems) · [Lint messages](https://polestar.guide/docs/authors/handbook#lint-messages) | | **Reference** | [Where things are](https://polestar.guide/docs/authors/handbook#where-things-are) | ## Setup A pack lives in its own folder (usually its own git repository). The tools come from a clone of Polestar: ```sh git clone 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 /tools/polestar.js ` wherever this page says `polestar `. You need: | | Windows | macOS | Linux | |---|---|---|---| | Node 24 or newer (every command) | `winget install OpenJS.NodeJS.LTS`, then a new terminal | `brew install node` | your package manager, or `nvm install 24` | | Lua 5.1 or LuaJIT (`play`, `playtest`, `record import`) | `winget install DEVCOM.LuaJIT`, then a new terminal | `brew install luajit` | `sudo apt install lua5.1` (Debian, Ubuntu), `sudo pacman -S lua51` (Arch), `sudo dnf install luajit` (Fedora; or `sudo dnf install compat-lua`, then `export LUA=lua-5.1`) | | The reference data, `data/forever/` in the clone (every guide command) | `node tools/polestar.js data build` in the clone | same | same | | The game's AddOns folder (`install`, `dev`) | found automatically, or set `WOW_FOREVER_ADDONS`, or pass `--dest` | same | same (Wine, Proton, Lutris, Bottles and Faugus prefixes are searched) | `$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](https://polestar.guide/docs/reference/credits) (`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 ```sh # 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) ` 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-`: 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 ` 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 ` 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](https://polestar.guide/docs/authors/guide-format) is the language, with a cookbook of examples; [GUIDE_CHEATSHEET.md](https://polestar.guide/docs/authors/cheatsheet) 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: ```sh 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 # writes drafts/---.guide ``` Inside a pack, `record draft` writes into the pack's `drafts/` folder with a guide id under `/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 --out ` turns a simulator route into skeleton guides, one per zone visit, with a `visits.json`. Their ids are `sim///NN-zone`, which lint refuses in a pack: rename each under `/` 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: ```sh polestar find "westfall stew" ``` ```output accept 36 # Westfall Stew, level 10: Verna Furlbrow, Westfall 59.9,19.4 turnin 36 # Westfall Stew: Salma Saldean, Westfall 56.4,30.5 ``` ```sh polestar find "kobold camp cleanup" ``` ```output 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 ``` ```sh 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 ``` ```sh polestar find --kind inn # every inn, as `sethome` and `hearth` name it ``` ```output sethome "Goldshire" # Innkeeper Farley (npc 295), Elwynn Forest 43.8,65.8 ``` ```sh polestar find --kind flight --faction Alliance # every flight point, as `getfp` and `fly` name it ``` ```output getfp "Sentinel Hill" # Sentinel Hill, Westfall, Alliance: Thor (npc 523), Westfall 56.6,52.7 ``` `find` searches quests, NPCs, objects, items, inns, flight points and Polestar's guides; a number matches ids exactly. Each result is a guide line ready to paste. A quest also prints its turn-in line and its objectives, `7.1 = kill Kobold Vermin x10`: write `quest 7.1` on the goal that works it (`kill 6 x10 quest 7.1`). A guide prints its level range, who it is for (`Alliance`, `Dwarf/Gnome only`, `Alliance Paladin only`) and its own `next`. An inn prints the location `sethome` and `hearth` take (and the other names the game may report for it), a flight point the town `getfp` and `fly` take (the flight map picks the node by it; where the landing area is named differently, a `fly` goal checks off only through a later goal of its step); a text also matches their zone, and `--kind inn` or `--kind flight` without a text lists them all. `--faction`, `--race` and `--class` keep what such a character can use. `--json` prints the results as one JSON array, and `lint --format json|github` its problems, for editors, scripts and CI. Every result has `kind`, `id`, `name` and `line` (the guide line); quests always, and guides and inns when there is something to say, also `notes` (the comment lines printed under it); besides: | Kind | Fields | |---|---| | `quest` | `level`, `zone`, `x`, `y` (where it starts), `starts` and `ends` (`kind`, `id`, `name`, `zone`, `x`, `y` of the NPC, object or item), `turnin` (the turn-in line), `objectives` (`index`, `kind`: `kill`, `item`, `object` or `event`, `id`, `name`, `count`; `id` and `count` may be `null`) | | `npc` | `level`, `zone`, `x`, `y` (its first spawn) | | `object` | `zone`, `x`, `y` | | `item` | — | | `guide` | `level` (its first), `levels` (`min`, `max`), `zone`, `faction`, `races` and `classes` (`null` when the guide names none), `next` (the guide ids its `next` offers: several are a route choice) | | `inn` | `id` and `npc` (the innkeeper), `npcName`, `names` (every bind location the game may report; the first is `name`), `zone`, `map`, `x`, `y` | | `flight` | `id` (the flight point), `node` (its full name, `name` is its town), `faction` (`Alliance`, `Horde`, or `null` for both), `npc`, `npcName`, `zone`, `map`, `x`, `y` | Fields with nothing to say are left out (a quest with no starter has no `x`), except a quest's `objectives` and `notes`, which are empty lists. In game, **`/polestar where`** prints where you stand as two guide lines and puts them in a box to copy: ``` zone map 1429 goto 42.11,65.93 live ``` `live` marks the coordinates as the client's own map frame. Typed coordinates are read in the Era frame unless marked (GUIDE_FORMAT.md, `coords`), and Forever moved some zones, so keep the `live`. For any other goal, add the `@x,y live` form chat prints (`kill 299 @42.11,65.93 live`). A guide written mostly from `/polestar where` can say `coords live` in its header once instead. A pack's guide may hand over to any of Polestar's guides with `next` (GUIDE_FORMAT.md, "Handing over to our guides"). Pick one every character of your guide can follow: check its races, classes and levels with `polestar find --kind guide --race ` (and `--class ` for a class guide). Lint stops a `next` that no character of the guide can follow. ### 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](https://polestar.guide/docs/authors/guide-format) (or [GUIDE_CHEATSHEET.md](https://polestar.guide/docs/authors/cheatsheet)) 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. | Command | What it checks | |---|---| | `polestar lint` | every check `compile` makes, writing nothing; exit code 1 on errors. `--format json` prints one document on stdout and no summary: `{ "ok", "errors", "warnings", "diagnostics" }`, `ok` true without errors, `errors` and `warnings` the counts, and `diagnostics` one object per problem with `file`, `line`, `severity` (`error` or `warning`), `message` and, when there is one, `hint`. `--quiet` leaves the warnings out of the list (text, JSON and annotations alike); the JSON counts still include them. `--format github` prints workflow annotations. `--include-drafts` checks `drafts/` too. `--no-data` checks without reference data: the guides must give every quest title, NPC name and place themselves (`compile`, `dev`, and `install` and `pack` on a pack take it too; it cannot be combined with `--data`, `--context-data` or `--sim`) | | `polestar playtest [--filter text] [--class C]` | plays every guide (with `--filter`, those whose file or id contains the text) to the end in the real addon against a simulated world, once per class it branches on plus one it never names, as each race that can reach it (only race and class pairs the game has); Polestar's guides join where yours hand over. Prints per guide, race and class `ok joe/elwynn (Human Warrior)`, `stuck … at step N "title": goal M (…) stays active`, `fail …` (a problem found while playing, such as a goal with no location) or, for a hand-over that does not land on the next guide with something to do or lands on one the character cannot follow (`no Human can follow it`), a `stuck` line naming the hand-over; exit code 1 when any is stuck or fails, when nothing played, or when the pack does not compile | | `polestar play` | the playground: your guides, your row on the Community guides page and its problems, in the browser | | `polestar sim compare --faction F [--race R]` | inside a pack: scores your leveling chain beside Polestar's under the simulator's model (hours to level 10, 20 … 60); a chain starting above level 1 is scored after Polestar's own chain up to the level yours starts at, and a chain whose guides name no race is scored for every race of the faction. Needs the simulator's world (docs/SIMULATION.md) | | `polestar doctor` | the setup, and the pack's `pack.json` | 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 ```sh polestar pack # lints, builds and writes dist/-.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: " (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. - **GitHub**: with 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](https://polestar.guide/docs/reference/license-exception) 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 title> <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: | Status | The row says | Fix | |---|---|---| | `on` | the switch on, the guide count | — | | `off` | the switch off: the player hid the pack's guides | switch it on; its tabs come back | | `disabled` | "turned off in the AddOns list", with **Enable and reload** | press it, or enable the addon in the AddOns list | | `not-loaded` | "not loaded: <the client's reason>" (out of date, a dependency missing), or "not loaded" when the client gives none | out of date: rebuild with an updated clone, or tick "Load out of date AddOns"; dependency missing: install or enable the addons on the pack's `## Dependencies` line (the AddOns list names them) | | `too-new` | "needs Polestar <version> or newer", or "needs a newer Polestar" when its TOC gives no `X-Polestar-Needs` | update Polestar | | `refused` | "refused: <reason>" | one of the pack problems below | | `broken` | "broken: registered no guides" | see `no-guides` below | While any pack has problems, the page's entry in the Options sidebar carries a dot, and the row shows "<n> problems" with **Show** (the list) and **Copy report** (the pack, its version, Polestar's version, the client build and every problem, selected for copying: players can paste it into a bug report). Problems have three kinds: | Kind | Message | Fix | |---|---|---| | `pack-refused` | Pack id <id> is not valid: 2 to 32 lower-case letters, digits or hyphens, starting with a letter or digit. | fix `id` in `pack.json` and rebuild | | `pack-refused` | Pack id <id> is reserved for Polestar. — plus " 1 guide dropped." or " <n> guides dropped." when it dropped any | pick another id | | `pack-refused` | Pack id <id> is already taken by <addon>; <addon> was refused. — plus " 1 guide dropped." or " <n> guides dropped." when it dropped any | the refused pack's guides stay out, even under the holder's ids. Two installed addons claim one id: pick an id of your own (`<author>-<name>`); players remove one of the two | | `pack-refused` | The pack is missing format. / The pack is missing <field>. | rebuild with `polestar compile`; a hand-written `Pack.lua` needs every field (PACK_FORMAT.md) | | `pack-refused` | Needs Polestar <version> or newer. / Needs a newer Polestar. (no `X-Polestar-Needs` in the TOC) | the player updates Polestar | | `pack-refused` | Only Polestar's own Lookup pack may register as internal. — plus the dropped guides, as above, when its id is also reserved or taken | remove `internal` from `RegisterPack` | | `guide-refused` | Guide <id> was refused: its id must start with <prefix>. | start every guide id with `<pack id>/` | | `guide-refused` | Guide <id> was refused: it was registered before its pack. | `Pack.lua` must load first: rebuild with `polestar compile` | | `guide-refused` | Guide <id> was refused: <reason> (`missing title`, `no steps`, `step 3 has no goals`, `step 3 goal 2: unknown verb …`, `step 3 goal 2: kill needs target`, `step 3 goal 2: coordinates outside 0-100`, …). | the guide's table breaks the format: rebuild with `polestar compile`, which never writes such a table; with your own tools, PACK_FORMAT.md | | `no-guides` | Registered no guides. | the addon loaded but registered nothing, usually a Lua error in its files: turn on `/console scriptErrors 1`, `/reload`, and read the error; rebuilding with `polestar compile` fixes a damaged folder | Nothing goes to chat: every refusal happens while the packs load or in the scan at login, so the row's **Show** and **Copy report** are where to read them. Below the list, **Suggest guides from** picks where suggestions come from (Publishing, above), and **About community guides** tells players in plain words what a community addon is, with a **Read more:** link to [GUIDE_PACKS.md](https://polestar.guide/docs/players/community-guides). A pack's website and that link open the copy window, with the address selected to copy. ## 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"). | Message | Fix | |---|---| | no reference data: the folder does not exist / the folder holds none of quests.json, npcs.json, …, so no quest, NPC or place can be looked up | run `polestar data build` in the clone, or point `--data <dir>` at a built folder (and `--context-data <dir>` when our guides' data is missing too); `--no-data` checks guides that give every quest title, name and place themselves | | missing <file>.json, … (warning) | the reference data is partly built: run `polestar data build` again | | no pack.json in <dir> | create `pack.json` with `id`, `title`, `author`, `version` and `license` (or run `polestar new`) | | pack.json is not valid JSON (…) | a missing value, quote or comma; JSON allows no trailing commas or comments | | pack.json must hold one JSON object | write `{ "id": "...", "title": "...", "author": "...", "version": "...", "license": "..." }` | | missing `<key>` | add the key with your own value | | `<key>` must be a string | put the value in quotes | | `<key>` contains control characters (line breaks, tabs or other invisible characters) | keep the value on one line | | `<key>` is N characters long; at most M fit | shorten it | | pack id "<id>" is malformed: 2 to 32 lowercase letters, digits and dashes, starting with a letter or digit | pick an id like `<author>-<name>`, e.g. `joe-routes` | | pack id "<id>" is reserved for Polestar ("guides", "forever", "lookup", "draft", "polestar" are) | pick another id | | version "<v>" is malformed: one word of letters, digits, ".", "+" and "-", at most 32 characters | write a version like `1.2.0` | | website "<url>" must start with https:// or http:// | write the full address | | folder "<name>" is malformed: 1 to 64 letters, digits, "_" and "-" / folder "<name>" looks like one of Polestar's own addons | pick a folder like `PolestarPack_JoesRoutes`, or leave `folder` out | | unknown key `<key>` (ignored) (warning) | remove it; `pack.json` takes the keys in PACK_FORMAT.md | | `<key>` contains "\|", which prints literally in game (warning; the same for a guide's title, folder, pitch, pros, cons and author, step titles and tips, goal texts and notes, and names given in quotes) | drop the `\|`: Polestar shows text as written, so colour and link codes do not work | | guide id "<id>" is outside pack "<pack>": its guide ids start with <prefix> | start the id with `<pack id>/` | | `next` points to unknown guide "<id>" | a guide of your pack or one of Polestar's: list ours with `polestar find --kind guide <text>` | | `next` offers <faction> guide "<id>" after a <faction> guide | hand over to a guide of the same faction | | no <races> character can follow <id> (it is for <its races> only) | the `next` guide's `race` or `class` leaves out every character of yours: pick one for the same races (or classes) with `polestar find --kind guide <zone> --race <Race>` | | LICENSE still holds the placeholder line `polestar new` writes, not the license text (warning) | replace the line with the full text of your license | | map <id>: this pack's Era frame differs from the one Polestar's guides register; in game Polestar's wins, so coordinates on this map may be off (warning) | mark the coordinates on that map `live` or retake them with `/polestar where` | | `kill` npc <id> (<name>) is elite; … / <item> drops only from elites (<names>); … / quest <id> (<title>) is elite … (warning in packs) | Polestar's own house rule (errors in our guides): in a Leveling guide make the goal `optional` with the tip "<name> is elite: grouping up is advised." | | quest <id> (<title>) needs <Profession> <rank>, and the guide does not train it before here: characters without it never see this goal (warning, Leveling guides) | the quest giver offers it only to characters with that profession, and Polestar hides its goals from the others: make the goal `optional`, or `train <Profession>` (and `skill <Profession> <rank>` above rank 1) earlier in the guide | | sethome/hearth/getfp/fly "<location>": no inn has that bind location / no inn stands there (an inn's area or the zone it is in) / no flight point has that name / no flight point lands there (its town, an inn's area or the zone it is in); the game never reports that name, so the goal never checks off by itself (warning) | write the place as the game names it: the hint offers the closest known names (`did you mean "Grom'gol Base Camp"?`); `polestar find --kind inn` and `polestar find --kind flight` list them all. Checked against the inns and flight points of `data/forever/travel.json` (GUIDE_FORMAT.md, "Validation") | The folder rule (PACK_FORMAT.md, "TOC fields"): `compile`, `install` and `dev` write a pack folder only when it is absent, empty, or built for the same pack id (its TOC carries the "Generated by `node tools/polestar.js compile`" line); anything else is refused. (`pack` writes only the zip, and `play` builds into a fresh temporary folder, so the rule never stops them.) `compile` and `dev` print `refusing to write into <dir>: <reason>`. `install` lints and builds the pack, then checks the AddOns folder before it writes or copies anything and prints `refusing to install: <AddOns>/<folder>: <reason>`; it then writes the build into `<pack>/dist/<folder>` before copying, so the same rule there prints `install failed: refusing to write into <pack>/dist/<folder>: <reason>`. The reasons are the same everywhere: | Message | Fix | |---|---| | refusing to write into <dir>: it is not a generated community addon (no TOC with the "Generated by …" line); move it away first | a folder of the same name that Polestar did not write is in the way (in AddOns or `dist/`): move or rename it, or set `folder` in `pack.json` | | refusing to write into <dir>: it holds the community addon "<other id>", not "<id>"; set "folder" in pack.json to a folder name of your own | another pack builds into the same folder name (folder names come from titles, so two packs titled alike collide): set `folder` in `pack.json` | | refusing to write into <dir>: it is not a folder / refusing to install: <AddOns>/<folder> exists and is not a folder | a file has the pack folder's name: move or rename it, or set `folder` in `pack.json` | ## Where things are - [GUIDE_FORMAT.md](https://polestar.guide/docs/authors/guide-format): the guide language, its checks and a cookbook. - [GUIDE_CHEATSHEET.md](https://polestar.guide/docs/authors/cheatsheet): every line of the guide language on one page, with an example each. - [PACK_FORMAT.md](https://polestar.guide/docs/authors/community-guide-format): 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. --- # Guide format cheatsheet > The guide format on one page: every header line, goal and condition, with what it does and a short example. Page: https://polestar.guide/docs/authors/cheatsheet (Polestar docs > Guide authors) Every line a `.guide` file can hold, with what it does and a short example. The full rules, the checks `polestar lint` runs and worked examples are in [GUIDE_FORMAT.md](https://polestar.guide/docs/authors/guide-format); packs are in [PACKS.md](https://polestar.guide/docs/authors/handbook). `polestar find <text>` looks up the ids the examples use. A guide is a header (lines in column 0) followed by steps; the lines inside a step are indented. Words are separated by spaces, `"double quotes"` hold several words as one, and keywords ignore case. ## Header Before the first `step`. `guide`, `title`, `levels` and `zone` are required. | Header line | What it does | Example | |---|---|---| | `guide <id>` | First line: the guide's id, starting with your pack id and `/` | `guide joe-routes/goldshire` | | `title <text>` | The name players see in the guide menu | `title Goldshire to Westfall` | | `levels <min>-<max>` | The character levels the guide is for | `levels 5-10` | | `zone <Name>` | The zone the guide's coordinates are in, until a step names another | `zone Elwynn Forest` | | `zone map <uiMapID>` | The same, by map id | `zone map 1429` | | `faction <Faction>` | Only for `Alliance` or `Horde` characters | `faction Alliance` | | `race <Race>, ...` | Only for these races (see Conditions) | `race Human, Dwarf` | | `class <Class>, ...` | Only for these classes | `class Warrior, Paladin` | | `category <Category>` | The guide menu category: `Leveling` (default), `Class`, `Professions`, `Reputation`, `Legacy`, `Exploration`, `Collectibles`, `Miscellaneous` or `Dungeons` | `category Professions` | | `folder <text>` | The guide menu folder to list it under | `folder Mounts · Level 40` | | `keywords <word>, ...` | Extra words the guide menu search finds it by | `keywords wolf, meat` | | `collects <item>, ...` | Items the guide obtains; Lookup opens this guide for them | `collects 750` | | `reward item <item> ...` | What the guide's goal gives, shown with its icon in the guide menu; several items on one line are a choice of one; repeatable | `reward item 1251 2581` | | `reward spell <id> "Name"` | A spell the goal teaches (a mount, a form, a demon) | `reward spell 5784 "Summon Felsteed"` | | `reward text <words>` | A reward without an id | `reward text Shen'dralar reputation` | | `why <text>` | One short line in the guide menu: why the goal is worth doing (Class guides need it and `reward`) | `why Your own mount at 40.` | | `author <name>` | Credits a guide to someone other than the pack's author | `author Joe` | | `version <N>` | A whole number you raise when the guide changes (default 1) | `version 2` | | `coords era` / `coords live` | The map frame of the coordinates you type (default `era`; `record draft` writes `live`) | `coords live` | ## Steps and text | Line | What it does | Example | |---|---|---| | `step [title]` | Starts a step; it is done when its goals are | `step Kobold camp` | | `tip <text>` | A note for the whole step, shown in the guide window | `tip Pull one kobold at a time.` | | `image <path> [<w>x<h>]` | A picture (a `.tga` or `.blp` in the pack folder) shown under the step's tip, such as a screenshot of a cave mouth | `image media/fargodeep-mine.tga` | | `zone <Name>` / `zone map <uiMapID>` | Inside a step: the zone for coordinates from here on, also for the steps after it (after a step with `only` that sets one, name the zone again) | `zone Elwynn Forest` | | `only <condition>, ...` | Inside a step: the step is only for matching characters | `only Hunter` | | `when <predicate>` | Inside a step: the step is only for characters in that state when the route gets there (see Conditions checked during play) | `when level<6` | | `along [until <label>]` | Inside a step: the route never stops there; its goals are done along the way, listed under the next steps until done (or until the labelled step) | `along until camp` | | `label <name>` | Inside a step: names it for an `along until` before it | `label camp` | | `loop` | Inside a step: its `goto` points are the places to search, in order, for the step's kill, collect and interact goals without `@x,y` | `loop` | | `note <text>` | A line of information; never holds the player up | `note The camp is busy at night.` | | `level <N>` | Reach level N, grinding if need be | `level 2` | | `level <N>.<fraction>` / `level <N>+<XP>` | Reach a point inside level N: 12.5 is halfway through 12, 12+2500 is 2500 XP into it (to whole percent; needs Polestar 0.2.6) | `level 12.5` | | `# <text>` | A note for you and other authors; players never see it | `# check the patrol route` | | `<goal> -- <text>` | Shows the text under that goal | `accept 783 -- He stands at the abbey gate` | ## Places and travel | Line | What it does | Example | |---|---|---| | `goto <x>,<y> ["Label"]` | Walk to a spot; checked off on arrival, when a later goal of the step is done, or, ending its step, when the next step's quest work is done | `goto 47.6,35.1 "Kobold camp"` | | `r <yards>` | How close `goto` counts as arrived (default 8) | `goto 42.9,65.6 "Goldshire" r 30` | | `@<x>,<y>` | Places any goal at these coordinates instead of the data's | `talk 197 @48.9,41.6` | | `map <uiMapID>` | The map this goal's `@` coordinates are on | `kill 69 map 1429 @45,40` | | `era` / `live` | The map frame of this goal's coordinates, overriding `coords` | `goto 40,60 live` | | `explore <x>,<y> ["Area"]` | Discover the map area at these coordinates | `explore 41,65 "Goldshire"` | | `sethome "<Location>"` | Bind the hearthstone at an inn, named as the game reports it | `sethome "Goldshire"` | | `sethome nearest` | Bind at the nearest inn of the player's faction | `sethome nearest` | | `hearth "<Location>"` | Use the hearthstone; done on landing there | `hearth "Goldshire"` | | `getfp "<Flight point>"` | Learn a flight path from its flight master | `getfp "Stormwind"` | | `fly "<Town>"` | Take a flight; done on landing there | `fly "Stormwind"` | `polestar find --kind inn` and `polestar find --kind flight` list the names `sethome`, `hearth`, `getfp` and `fly` take. ## Quests | Line | What it does | Example | |---|---|---| | `accept <quest> ["Title"]` | Take a quest; the giver and title come from the data | `accept 783` | | `turnin <quest> ["Title"]` | Hand a quest in | `turnin 783` | | `lvl <N>` | On `accept`: the level the quest needs, shown beside it | `accept 7 lvl 2` | | `complete <quest> ["Title"]` | Finish every objective of a quest; give it a place (`@x,y`, or a `goto` before it) when its objectives have one, or the arrow has nowhere to point | `complete 7 @48.5,31.0` | | `npc <id>` | Which NPC gives or takes the quest, when the data knows several | `accept 5261 npc 196` | | `object <id>` / `item <id>` | The same for a quest started or ended at an object, or started by an item | `accept 9400 object 1617` | | `"<text>"` | Right after an id: the quest title, or the name of the NPC, object or item, for content missing from the data; after the modifiers: the text players see instead of the generated one | `accept 9201 "The First Step"` | | `xp <N>` / `money <amount>` | On `turnin`: what it pays (`money 1g50s`, `7s` or copper) | `turnin 9201 xp 210 money 1s` | | `choose <item> ...` / `reward <item> ...` | On `turnin`: the rewards to pick from, and the ones given outright | `turnin 5261 choose 159 2589 reward 4306` | | `direct` | On `turnin`: handed in straight from the giver's window, with no `accept` (Distracting Jarven, the cloth donations). Buy or collect what it asks for with `buy`/`collect`: the quest never enters the log, so nothing tracks objectives for it | `turnin 9300 direct` | ## Killing and collecting | Line | What it does | Example | |---|---|---| | `kill <npc>` / `kill "<Name>"` | Kill a mob; `quest Q.O` ties it to a quest objective | `kill 6 x10 quest 7.1` | | `x<N>` | How many (kills, items, purchases, crafts) | `kill "Cloth Kobold" x5 @65,75` | | `quest <quest>.<objective>` | Counts the goal by that quest objective, numbered as the quest log lists them (`quest <quest>` alone lets the data find it) | `interact 1617 quest 9400.1` | | `collect <item> ["Name"]` | Gather or loot items; without `quest`, counted in the bags | `collect 750 x8` | | `nearest` | On `collect`: the closest place mobs drop the item, by level and faction | `collect 4306 x10 nearest` | | `interact <object>` | Click a game object | `interact 2843` | | `use <item>` | Use an item | `use 1210 @47.6,35.1` | ## People, items and errands | Line | What it does | Example | |---|---|---| | `talk <npc>` | Speak to an NPC | `talk 197` | | `train class` | Visit the nearest trainer of the player's class | `train class only Warrior,Mage` | | `train <npc>` | Visit that trainer | `train 911 only Warrior,Paladin` | | `vendor nearest` / `vendor <npc>` | Sell and repair, at the closest vendor or that one | `vendor nearest` | | `buy <item> ["Name"]` | Buy an item; `nearest` picks the closest vendor selling it | `buy 159 x5 nearest` | ## Professions | Line | What it does | Example | |---|---|---| | `train <Profession> [Rank]` | Learn a profession or its next rank (`Apprentice`, `Journeyman`, `Expert`, `Artisan`) at the nearest trainer | `train Mining Journeyman` | | `skill <Profession> <N>` | Reach skill N (quote names of two words) | `skill "First Aid" 40` | | `learn <spell> ["Name"]` | Learn a recipe; from a trainer, or with `nearest` from the closest vendor of its recipe | `learn 3276` | | `craft <spell> ["Name"]` | Craft a recipe, `x<N>` times | `craft 3275 x5` | | `until <N>` | On `craft`: until the profession reaches N | `craft 3275 until 40` | ## Reputation and challenges | Line | What it does | Example | |---|---|---| | `rep <Faction> <Standing>` | Reach a standing (`Neutral` to `Exalted`) with a faction, by name or id | `rep Stormwind Friendly` | | `achieve <id> "Name"` | Complete an achievement or Legacy Challenge | `achieve 9001 "Kobold Catcher"` | | `criteria <n>` | On `achieve`: one criterion of it | `achieve 9001 "Kobold Catcher" criteria 2` | ## Conditions `race`, `class` and `only` take a comma list of names. Names in one group match any of them; the groups must all match: `only Warrior,Paladin,Dwarf` is a Dwarf who is a Warrior or a Paladin. | Line | What it does | Example | |---|---|---| | `only <condition>, ...` | After a goal: the goal is only for matching characters | `kill 299 only Hunter` | | `Warrior` `Paladin` `Hunter` `Rogue` `Priest` `Shaman` `Mage` `Warlock` `Druid` | Classes | `only Warrior,Paladin` | | `!<Class>` | Every class but this one | `only !Hunter` | | `Human` `Dwarf` `Gnome` `NightElf` `Orc` `Troll` `Tauren` `Undead` (or `Scourge`) `Skyborne` | Races; Skyborne plays on both sides | `only Dwarf,Gnome` | | `Alliance` `Horde` | Factions | `only Alliance,Mage` | ## Conditions checked during play One predicate per `when` line; a step with several needs all of them. `!` turns any of them around but `level`. Once the route has passed the step, the outcome stays. | Line | The step applies while | Example | |---|---|---| | `when level<N` (`<=`, `>`, `>=`) | the character's level compares so; N may be a point inside a level (`12.5`, `12+2500`) | `when level>=10` | | `when onquest <quest>, ...` | any of the quests is in the log | `when onquest 783` | | `when complete <quest>` | the quest is ready to turn in | `when complete 7` | | `when turnedin <quest>` | the quest is handed in | `when !turnedin 9201` | | `when available <quest>` | the quest can be taken now | `when available 9200` | | `when has <item> [xN]` | the bags hold N or more | `when !has 159 x5` | | `when zone "<Name>"` / `when subzone "<Name>"` | the player is there | `when subzone "Goldshire"` | | `when bound "<Location>"` | the hearthstone is bound there | `when !bound "Goldshire"` | ## Route choices and optional steps | Header line | What it does | Example | |---|---|---| | `next <id>, <id>, ...` | Several guides after this one: the player picks one, the first is your suggestion | `next joe-routes/westfall, joe-routes/redridge` | | `next <id> when <predicate>` | One guide per line, offered only while the predicate (as on a step's `when`) holds when this guide ends; `next` lines add up. One option left: Polestar goes on to it; none: the guide ends there | `next joe-routes/redridge when level>=15` | | `pitch <text>` | On a guide offered as a choice: one line on its card | `pitch Short walks between quests.` | | `pro <text>` / `con <text>` | One advantage or drawback per line, under the pitch | `pro Ends at a flight point` | | Line | What it does | Example | |---|---|---| | `optional` | After a goal: the step can be finished without it | `kill 299 optional` | | `group [N]` | After a goal: it needs a group (of N players, 2-40); the guide window says so. Elites, dungeon and raid quests are found from the data without it | `kill 299 group 3` | ## Handing over with `next` | Header line | What it does | Example | |---|---|---| | `next <id>` | The guide that follows when this one ends: one of yours or one of Polestar's (`polestar find --kind guide <zone>` lists them with who can follow them) | `next joe-routes/westfall` | --- # Guide format > The .guide language in full: header, steps, goals, conditions, what the compiler fills in, validation and a cookbook. Page: https://polestar.guide/docs/authors/guide-format (Polestar docs > Guide authors) Every line of the format on one page, with an example each: [GUIDE_CHEATSHEET.md](https://polestar.guide/docs/authors/cheatsheet). This page has the full rules. Guides are written as `.guide` text files in a pack (Polestar's own: `guides/`; a community pack: any folder holding a `pack.json`, see [PACKS.md](https://polestar.guide/docs/authors/handbook)) and compiled to Lua by `node tools/polestar.js compile`. The compiler fills in names, titles and coordinates from the reference data in `data/forever/`, so a line can be as short as `accept 783`. Anything you write explicitly wins over the data. Without the reference data the compiler stops with one error, unless `--no-data` says to compile guides that give every title, name and place themselves. Worked examples of every goal are in the Cookbook at the end of this page. ``` guide joe-routes/northshire title Northshire Valley faction Alliance race Human levels 1-6 zone Elwynn Forest next joe-routes/elwynn step Deputy Willem accept 783 -- He stands at the abbey gate turnin 783 accept 7 accept 33 accept 5261 npc 196 step Kobold camp tip Pull one kobold at a time until level 3. kill 6 x10 quest 7.1 collect 750 x8 quest 33.1 optional step Back to the abbey turnin 7 train only Warrior,Paladin -- Llane Beshere is inside the abbey level 4 ``` ## Lexical rules - UTF-8, one guide per file. Blank lines are ignored. - `#` starts an author comment (dropped) when it is the first non-blank character of a line or follows whitespace outside a quoted string. - ` -- ` (space, two dashes, space) starts a **player-facing note** for the goal on that line; the rest of the line is the note. - Header lines and `step` lines start in column 0. Lines inside a step are indented (any spaces or tabs). - Tokens are whitespace-separated. `"double quoted"` is one token, with `\"` and `\\` escapes. Keywords are case-insensitive; IDs are integers. ## Header Every line before the first `step`. | Key | Required | Value | |---|---|---| | `guide` | yes, first line | id: `[a-z0-9_-]+` parts joined by single `/` (none leading or trailing), unique across all guides; it starts with the pack's id and `/` (`joe-routes/elwynn`; Polestar's own guides: `forever/`) | | `title` | yes | rest of line | | `levels` | yes | `<min>-<max>` | | `zone` | yes | default zone: map name from `data/forever/zones.json`, or `map <uiMapID>` | | `faction` | no | `Alliance` or `Horde` | | `race` | no | comma list (see Conditions) | | `class` | no | comma list | | `next` | no | id of the guide that follows, or several ids separated by commas: a **route choice**. The player picks where to level next in the "Choose your path" window; the first id is the author's default. Every option must be the guide's own faction. Repeatable: each line adds its guides in order, and `next <id> when <predicate>` offers that guide only while the predicate holds at the hand-off (see "Conditional hand-offs"). | | `category` | no | default `Leveling`; others: `Class` (class quest chains, mounts and weapons; pair with a `class` header), `Professions`, `Reputation`, `Legacy`, `Exploration`, `Collectibles`, `Miscellaneous` (side chains and collections that fit no other category: the Cozy Sleeping Bag), `Dungeons` | | `folder` | no | the guide menu folder this guide is listed under, any category (e.g. `Mounts · Level 40`, `Companion pets · Vendors`). Guides sharing a folder sort by faction (yours first), then level. Without it: the category's folder (Leveling: by faction and level band). | | `keywords` | no | comma list of extra words the guide menu search matches (e.g. the colours a mount guide covers); an empty entry is an error, a repeated one a warning | | `collects` | no | comma list of item ids this guide obtains (a mount guide: every colour it sells). Compiled as `collects = { ... }`; the Lookup module opens this guide for those items instead of building one. Malformed or repeated ids are errors; an id missing from `items.json` is a warning. | | `reward` | no (a warning on a `Class` guide without it) | what the guide's goal gives, shown first in the guide menu's details with its icon and the game's tooltip. Repeatable, one entry per line: `reward item <item> ["Name"] [quality] ...` (entries as in `choose`; several on one line are a choice of one), `reward spell <spellId> "Spell name"` (a mount, a form, a demon, an ability; the name is required; the id is the spell the player ends up with, as the Forever client's `SpellName` table has it: `reward spell 691 "Summon Felhunter"`, not the quest's "Teach" spell) or `reward text <words>` (anything without an id: reputation, experience). A spell written as `reward text` shows a glyph instead of its icon and no tooltip, and tests/guides-class.test.js fails on one for the guide's class. The details list the entries given outright under "Reward", then the choices under "Choose one", each group in header order. An item's name defaults to `items.json`; an id missing there needs its name. Compiled as `reward = { { item, itemName, quality, choice }, { spell, spellName }, { text } }`. | | `why` | no (a warning on a `Class` guide without it) | one short line in the guide menu's details: why the goal is worth doing, in the author's words | | `author` | no | default: the pack's author (`pack.json`) | | `version` | no | integer, default `1` | | `coords` | no | `era` (default) or `live`: the map frame of coordinates typed in this guide (`@x,y`, `goto`, `explore`). Era-frame ones compile with `f = "e"`; on a map without Era bounds they compile live. `record draft` writes `coords live`. | | `pitch` | no | one line selling the zone, shown on its card in the route choice window (required, as a warning, when the guide is a route option) | | `pro` / `con` | no | repeatable: one advantage / disadvantage per line, shown under the pitch. Keep them short, factual and true for every race that can choose the route. | A route choice, as excerpts of two guides' headers (a pack's Tirisfal guide offering our Barrens or its own Silverpine): ``` # guides/tirisfal.guide next forever/horde/02-the-barrens, joe-routes/silverpine # guides/silverpine.guide pitch Undercity's backyard: a compact forest with the Forsaken's own story and short walks between quests. pro Ends in the Undercity, where the next guide starts: no zeppelin ride con Hunters, Shamans and Druids have no trainer here: they train next in Orgrimmar at about 22 ``` Characters arrive at a route option from any of its predecessors, so its turn-ins of earlier quests must not assume one starting zone; the engine skips a turn-in or objective for a quest the character never had (see ARCHITECTURE, "Route choice"). ## Steps ``` step [title] <directive | goal> ... ``` Step directives: | Directive | Effect | |---|---| | `zone <Name>` / `zone map <uiMapID>` | Current zone for coordinates from here on (sticky across later steps, also when its step has `only`: after a class trip, the next step everyone sees names its zone again). | | `only <cond>[,<cond>...]` | The step applies only to matching characters. | | `when <predicate>` | The step applies only while the predicate holds when the route reaches it; several `when` lines must all hold. See "Conditions checked during play". | | `along [until <label>]` | The route never stops at the step: its goals are done along the way, listed under the steps after it. See "Along the way". | | `label <name>` | Names the step, for an `along until` before it. | | `tip <text>` | Player-facing step note (compiled to `step.note`). | | `image <path> [<w>x<h>]` | A picture shown in the guide window under the step's tip, while the tip is open, scaled to the window's width (at most 160 high): a screenshot of a spot that is hard to find, such as a cave mouth. `<path>` is the file's place in the pack folder, `/` between folders (`media/fargodeep-mine.tga`), a `.tga` or `.blp` file; without the extension the `.tga`, else the `.blp`. The file ships in the pack's addon folder at that path. `<w>x<h>` is the size it is drawn at (only the ratio counts: `512x256` is twice as wide as high); without it the compiler reads the file's own. One per step; a step with no `tip` reads "Picture of this spot" above it. See "Pictures" in the Cookbook. | | `loop` | The step's `goto` points, in order, are the places to search for its kill, collect and interact goals instead of a path to walk: see "Spawn areas", Loop. | A step must contain at least one goal. ## Goals ``` <verb> <positional args> <modifiers...> [-- note] ``` | Verb | Positional | Notes | |---|---|---| | `accept` | `<questId> ["Title"]` | Title and quest giver from data; a quoted title overrides it (required if the quest is not in data). | | `turnin` | `<questId> ["Title"]` | Turn-in NPC/object from data. | | `complete` | `<questId> ["Title"]` | Finish all objectives. | | `kill` | `<npcId>` or `"Target name"` | Pair with `quest Q.O` to track a quest objective. | | `collect` | `<itemId> ["Item name"]` | Pair with `quest Q.O`; otherwise tracked by bag count `xN`. `npc <id>` names the NPC who hands the item over, for an item nothing drops and no data lists a source for (a quest report given in a gossip window): the target button then has someone to target, and the point is that NPC's spawn unless you place it. `collect <item> xN nearest` (no `quest`) compiles to farm spots: clusters of normal or rare mobs that drop the item at 2% or more, outside towns and guard posts, each with the zone's safety (`A`/`H` faction zone, `AH` contested), mob level range, items per kill and spawn count; at most 16 per continent, spread over safety and 10-level bands. The engine picks one by the player's level, faction and travel time. | | `goto` | `<x>,<y> ["Label"]` | Coordinates are mandatory here. A label that is a subzone's name as the game spells it (`"Fargodeep Mine"`, not `"Fargodeep Mine's mouth"`) gets its area ("Places by ID"); at a cave's or mine's mouth the goto then also counts as arrived once the player walks into it past the point (in that subzone and indoors). | | `talk` | `<npcId>` | | | `interact` | `<objectId>` | Click a game object. | | `use` | `<itemId> ["Item name"]` | | | `sethome` | `"Location"` or `nearest` | Inn location as the game names it (the bind location it reports), e.g. `"Goldshire"`. Without `npc` the compiler names the inn's innkeeper, so the arrow leads to them ("What the compiler fills in"); `npc <id>` picks one yourself. `sethome nearest` binds at the nearest own-faction inn when the step comes up. Lint warns about a location no inn has (`polestar find --kind inn`). Completes on every client language: binding at the inn's innkeeper, or a bind location the client names as the inn's area (see "Places by ID"). A player with "Set your home at the guide's inn" on (Quality of Life, Travel; off by default) has Polestar bind and confirm when they talk to that innkeeper (for `nearest`, any innkeeper the compiler listed for it), never at another inn. | | `hearth` | `"Location"` | Done when the zone or subzone where you land has that name: an inn's location or the zone it is in, in the client's language when the compiler finds its area ("Places by ID"). Lint warns about any other name. | | `getfp` | `"Location"` | Discover a flight path: the flight point's name (`"Stormwind, Elwynn"`) or its part before the comma (`"Stormwind"`). The compiler adds its taxi node, so it completes on every client language ("Places by ID"), and without `npc` that node's flight master, so the arrow leads to them ("What the compiler fills in"); `npc <id>` picks one yourself. Lint warns about a name no flight point has (`polestar find --kind flight`). | | `fly` | `"Location"` | Take a flight: the flight point's town (`"Stormwind"`), as the flight map picks the node by it. Done when the zone or subzone where you land has that name (in the client's language when the compiler finds its area, "Places by ID"); where the landing area is named differently (`"Stormwind City"`), the goal checks off only through a later goal of its step. Lint warns about a name that is no flight point's town, inn location or zone they are in. | | `train` | `[npcId]`, `<Profession> [Rank]`, or `class` | `train First Aid` / `train Mining Expert`: the nearest own-faction trainer of that profession and rank (`Apprentice`, `Journeyman`, `Expert`, `Artisan`; ranks taught by a book or quest point at its vendor or quest giver). Without a rank: the highest rank whose minimum skill (0/50/125/225) the last earlier `skill` (or `craft … until`) target for that profession in the guide reaches, Apprentice when there is none, and always above a rank the guide already trained. `train class`: the nearest trainer of the player's class. Resolved at runtime from the player's faction and position. | | `buy` | `<itemId> ["Item name"]` | Use `xN` for quantity. Add `nearest` to send the player to the closest own-faction vendor selling it. | | `vendor` | `[npcId]` or `nearest` | Sell junk / repair; `nearest` picks the closest own-faction vendor. | | `level` | `<N>`, `<N>.<fraction>` or `<N>+<XP>` | Reach level N (grind if needed). `level 12.5` reaches halfway through level 12 and `level 12+2500` 2500 XP into it (converted to a share of the level with the 1.12 XP table): done at level 12 with that share of the level's XP, or at any later level, and the guide window reads "Reach level 12 (50%)". The share is kept to whole percent; one that rounds to 0% or 100% is an error (write `level 12` or `level 13`), as is XP past the level's total; `level 12.0` is plain level 12. A guide that uses either form is written in pack format 4 (see "Conditions checked during play"). | | `note` | `<text...>` | Informational line; never blocks. Quotes optional. | | `skill` | `<Profession> <N>` | Reach skill rank N (`Alchemy`, `Blacksmithing`, `Enchanting`, `Engineering`, `Herbalism`, `Leatherworking`, `Mining`, `Skinning`, `Tailoring`, `Cooking`, `Fishing`, `First Aid`, quoted when multi-word). | | `learn` | `<spellId> ["Name"]` | Learn a recipe or spell (trainer or recipe item); name from `professions.json`. A trainer-taught spell points at every trainer of its rank (a smart target; `npc <id>` fixes one); `learn <spellId> nearest` for a recipe sold by vendors sends the player to the closest own-faction vendor of the recipe item. | | `craft` | `<spellId> ["Name"]` | Craft a recipe; `x<N>` crafts, or `until <N>` = until the recipe's profession reaches N. | | `rep` | `<Faction> <Standing>` | Reach a standing (`Neutral`, `Friendly`, `Honored`, `Revered`, `Exalted`) with a faction named in `factions.json`, or `rep <factionId> <Standing>`. | | `explore` | `<x>,<y> ["Area"]` | Discover the map area at those coordinates (current zone). | | `achieve` | `<achievementId> ["Name"]` | Complete an achievement / Legacy Challenge; `criteria <n>` targets one criterion. | **Quests the route leaves out.** Quest automation accepts and hands in only the `accept` and `turnin` goals of the step in play and the next two. When the game then opens a window of its own at the same NPC (the next quest of the chain, or the NPC's other quests) and none of those is a goal there, Polestar closes it (Options, Guide, Automation, "Close offers the guide skips", on by default). To keep such a follow-up in front of the player, give it an `accept` in the same step or the next two. **Smart targets.** `nearest` (and the profession/class forms of `train`) compile to a *candidate set* instead of one NPC: every matching NPC in the data with its faction. At runtime the engine keeps the candidates the character may use (faction, and race or class where it matters) and picks the cheapest by travel time from where the player stands, re-deciding on zone changes. Explicit npc ids stay fixed. Profession guides should use these forms instead of per-race branches. Sources: profession trainers from `professions.json`; class trainers from `trainers.json` (`node tools/polestar.js trainers build`: `train <npcId> only <Class>` goals in `guides/`, recorded trainer visits, and a curated list verified against `npcs.json`; without the file, the curated list); innkeepers from the `innkeeper` and `vendor nearest` from the `repair` role in `npcs.json`; `buy … nearest` from the item's `vendors`; `collect … nearest` from the item's droppers (see `collect`); `learn … nearest` from the recipe item's `vendors`; a trainer-taught `learn` from the profession rank's trainers in `professions.json`. Only factions the goal can apply to are kept, and each set keeps one candidate per town (within 250 yards), nearest to the previous goal first. Smart targets take no coordinates. Modifiers, in any order after the positional arguments: | Modifier | Meaning | |---|---| | `@x,y` or `@ x,y` | Coordinates (0–100) in the current zone. | | `map <uiMapID>` | Zone for this goal's `@` coordinates only. | | `npc <id>` / `object <id>` / `item <id>` | Explicit entity (e.g. which quest giver). | | `quest <id>` / `quest <id>.<objective>` | Quest objective link (1-based objective, numbered in the order the game's quest log lists them; `polestar find <quest id>` prints them). | | `x<N>` | Count. | | `"text"` | Display text override (for `goto`: the label). A quoted token directly after the entity id of `kill`, `talk`, `interact`, `train` or `vendor` (like `collect`/`use`/`buy`) names that entity instead, for new Forever content missing from the data. | | `r <yards>` | Arrival radius (`goto`, default 8). | | `lvl <N>` | Minimum level shown on an `accept`. | | `optional` | Never blocks the step. | | `group [N]` | Needs a group, of `N` players (2–40) when given (`kill 1234 group 3`, `accept 7583 group 5`). The guide window says "Group of 3 advised" (or "Group advised") under the goal. Overrides what the compiler derives: see "Group content". | | `only <cond>[,<cond>...]` | Goal applies only to matching characters. | | `era` / `live` | Map frame of this goal's typed coordinates, overriding `coords`. | | `choose <item> ["Name"] [quality] ...` | `turnin` only: the reward choices, shown under the turn-in and in its tooltip. Each entry is an item id, optionally its quoted name and a quality word (`poor` `common` `uncommon` `rare` `epic` `legendary` `artifact` `heirloom`); entries follow one another (`choose 6480 918 "Deviate Hide Pack" common`). Names and qualities default to `items.json`; an id missing there needs its name. Display only: a named unknown id is not a warning. | | `reward <item> ["Name"] [quality] ...` | `turnin` only: items given outright, same entries as `choose`. | | `xp <N>` | `turnin` only: the XP it pays. Shown with the rewards, and used for the route-level check when the quest has no `xp` in the data. | | `money <amount>` | `turnin` only: copper (`money 350`) or `1g50s` / `7s` / `25c` forms. | | `direct` | `turnin` only: the quest is handed in straight from the giver's window, with no `accept` (Distracting Jarven 308, the repeat cloth donations). It needs no earlier accept, and its availability, prerequisites and exclusive quests are checked as an `accept`'s are. The quest never enters the log, so it carries no objectives: get what it asks for with a plain `buy` or `collect` (without `quest`). The goal checks off on the hand-in itself and stays checked after a `/reload`, so a repeatable does not come back as undone. | ## Conditions Comma-separated names, case-insensitive: - Classes: `Warrior Paladin Hunter Rogue Priest Shaman Mage Warlock Druid`. A class may be negated with `!` (`only !Hunter`). - Races: `Human Dwarf Gnome NightElf Orc Troll Tauren Undead Skyborne` (compiled to the client's race file names, UnitRace's second return; `Undead` → `Scourge`). Skyborne plays on both sides: a guide's `faction` or an `only` faction picks the side. Unknown race names are passed through with a warning (new Forever races). - Factions: `Alliance Horde`. Classes OR together, races OR together, factions OR together; the three groups AND. `only Warrior,Paladin,Dwarf` = (Warrior or Paladin) and Dwarf. ## Conditions checked during play `only` says who a step is for; `when` says in which state. A step with `when` applies only while its predicate holds, checked on the character's live state while the step is the current one or still ahead. Several `when` lines must all hold; for "one or the other", write the step twice. ``` step Back to Gornek when onquest 788 when level<6 turnin 788 ``` | Predicate | Holds when | |---|---| | `level<N`, `level<=N`, `level>N`, `level>=N` | the character's level compares so with N (1-60); `level` takes no `!`. N may be a point inside a level as for the `level` goal: `when level<12.5` holds below level 12 and in its first half | | `onquest <quest>[,<quest>...]` | any of the quests is in the log | | `complete <quest>` | the quest is in the log, ready to turn in | | `turnedin <quest>` | the quest is handed in | | `available <quest>` | the quest can be taken now: not in the log or done, the level reached, its prerequisites done and none of the quests that close it taken or done (the compiler copies these from the data, as for an `accept`) | | `has <item> [xN]` | the bags hold N (default 1) or more | | `zone "<Name>"` | the zone text reads so (the zone as the game names it) | | `subzone "<Name>"` | the subzone text reads so | | `bound "<Location>"` | the hearthstone is bound there (a bind location, as for `sethome`) | `!` in front of any predicate but `level` turns it around: `!onquest 788` holds while the quest is not in the log, `!has 159 x5` while the bags hold fewer than five. Names can be quoted or bare. **Once the route moves past a step, its outcome stays.** Polestar stores whether the step's `when` held at that moment (once the quest log can be read after login), and reads that from then on: a "buy water" step passed because the bags were full is stored as skipped and does not come back when the water runs out, and a step that applied stays done. The player can unskip such a step like any other; it then applies whatever its `when`. Resetting the guide's progress forgets the stored outcomes. While its `when` fails, a step counts as one that does not apply: like a step for another class, it never holds the guide, and a turn-in whose only accept is in such a step goes with it. A step with `when onquest Q` (or `when complete Q`) can hand in Q with no `accept Q` before it: "hand it in if you picked it up elsewhere". A `turnin` whose quest is accepted earlier only in steps with `when` warns: characters who passed those steps never see it, so give it the same `when` or a `when onquest`. Zone, subzone and bind location names work on every client language: the compiler gives each its area ID where the data names one (see "Places by ID"), and Polestar compares the game's own name for it, then the name you wrote. ### Conditional hand-offs `next <id> when <predicate>` makes one `next` option conditional: one guide, one predicate from the table above, one line per guide (naming a guide twice is an error, so an option has one condition). `next` lines repeat, each adding its guides in order; one without `when` is always offered, and the comma form works as before. ``` guide joe-routes/durotar next joe-routes/barrens-early when level<12 next forever/horde/02-the-barrens ``` Polestar checks the condition on the character as they are when it lists the options: at the end of the guide, that decides where it goes. An option whose `when` does not hold is left out of the "Choose your path" window, the guide menu's "Next" line, `/polestar path` and a route change. With one option left Polestar goes on to it without asking; with none the guide ends there, like a guide without `next`. Nothing is stored: the condition is checked again each time. A subzone is looked up in the zone where the guide ends. A pack with a `when` anywhere (on a step or a `next` option), or a `level` goal inside a level (`level 12.5`), is written in pack format 4, which Polestar 0.2.6 and later read (docs/PACK_FORMAT.md); a pack without stays readable by older versions. ## Along the way `along` marks a step whose goals the player does on the way, without stopping the route: "kill 8 boars on your way to Goldshire and back". The route passes over the step at once. From then on its open goals are listed in the guide window under the current step, "Along the way" (up to six, with their progress; not in the compact window), until they are done. Clicking one points the arrow at it, if it has a place, until it is done. "Then:" and Up next leave along steps out. With `along until <label>`, the list ends when the route reaches the step carrying `label <label>`, done or not. The label must be on a later step of the same guide. ``` step Boars on the way along until camp kill 113 x8 quest 33.1 step Goldshire goto 42.1,65.9 "Goldshire" step Back at the camp label camp turnin 33 ``` The route goes straight from "Boars on the way" to "Goldshire", and the boar count shows under the steps until "Back at the camp". If the boars are needed before going on, hand the quest in at the labelled step, as here: the turn-in waits for the kills. Along suits goals the game counts wherever the player is: quest objectives (`kill`, `collect`, `interact`, `use` with `quest`), quests taken or handed in, bag counts (`collect`, `buy`), `level`, `skill`, `explore`. A goal Polestar checks off only on the step the route is on (`goto`, `talk`, `hearth`, `getfp`, `fly`, `vendor`, `train` but a profession's, and `kill`, `interact` or `use` without `quest`) never checks off in an along step and warns. An along step can have `only` and `when` like any step: one that does not apply when the route passes it is never listed, nor is one the player skipped. A label names one step: letters, digits, `-` and `_`, in the case written (`label Camp` is not `camp`), once per guide. A pack with `along` or `label` is written in pack format 4, like `when`. ## What the compiler fills in | Missing | Filled from | |---|---| | quest title | `quests.json` | | quest giver / turn-in target | `start` / `end` of the quest; `npc`/`object` modifiers pick one explicitly | | coordinates | the target's spawns, trying maps in order: the current zone, then maps the guide already used (most recent first), then anywhere. On the chosen map: the spawn nearest the previous goal when that goal is on the same map, else the centroid of the highest-priority candidate | | `kill` target name | `npcs.json` | | `collect` coordinates | every drop source with spawns, ranked as above (zone, used maps, nearness), then by drop chance. On the chosen map only the likely sources count (at least half the best chance there). Where elites (rank 1-3, hostile) drop the item beside normal mobs or objects, each at 1% or more, only the normal ones count, whatever the elites' chance, and a place of theirs with more elite spawns than its own within its radius (at least 70 yd) is an alternative spot: the point and the arrow lead to the normal mobs, not into the elite camp. An item only elites drop there keeps them. For a quest objective, mobs 3 or more levels above the quest (their lowest level) are left out where their higher chance would push the likely sources nearer the quest's level under that bar: those set it instead (a level 7 quest's seeds come from the level 5 Timberlings beside the giver, not the level 10 Elder Timberlings across the zone) | | `collect` source `from`, `fromAlso`, `fromId`, `fromAlsoId`, `fromKind`, `fromRank`, `fromFaction` | a `collect` (quest objectives too) whose item has one source with spawns, or one that drops it at 50% or more, and at most 8 sources at 2% or more (not cloth that drops everywhere); where normal mobs or objects and elites both drop it at 1% or more, only the normal ones are named, as the arrow leads to them (so are they where a rare tops the droppers and normal mobs drop it at 50% or more, and the sources near a quest's level where mobs 3 or more levels above it would crowd them out, as for the coordinates): the source's name, a second source of the same kind at 50% or more, their ids, `npc` or `object`, the NPC's rank (1 elite, 2 rare elite, 3 boss, 4 rare) and faction (`A`, `H`, `AH`; none for a hostile mob). The goal line names it, in the client's language by its id: "Kill Grell or Grellkin for Fel Moss" for an enemy, "Collect Oats from Sack of Oats" otherwise (nothing added for an object named as the item); with author `text` the line under it says "Kill Aean Swiftriver (rare elite)" or "From <name>"; a quest started by that item reads as one line ("Runed Scroll: kill Aean Swiftriver (rare elite)") | | `collect` source NPCs `fromNpcs` | every `collect` placed among its sources, whether the data placed the point or the author did and the data has the target there (as `spots`): the creatures its point and spawn areas belong to, the one the point itself belongs to first, then the other likely sources there (as above), at most 5. Objects are left out, as a macro can only target a creature. An item nothing drops gets the NPCs the data lists as its vendors instead, where they have spawns: those hand it over in their gossip window (the Warsong Scout's update), and nothing else would name them; a `collect` whose author named an `npc` carries that instead. The target button names them, in the client's language by their ids, before the item's own droppers, whose drop chances rank them over the whole world: for an item many creatures drop, those are mostly in other zones | | profession, recipe, trainer | `professions.json` (skill line, recipe name, created item, reagents, recipe item; a trainer-taught `learn` gets every trainer of the rank that teaches it, both factions (a smart target), unless `npc <id>` names one). Classic profession names resolve without it. | | faction | `factions.json` by name (lowest id on ties) or id | | objective index | the quest's objective whose `id` matches the npc/item, when `quest Q` has no `.O` | | count | the linked objective's count | | Era frame flag `f = "e"` | when coordinates come from Era-frame data, or were typed in an `era` guide/goal | | spawn areas `spots` | every goal placed at an NPC or object that spawns at more than one place, and hand-placed `@x,y` goals whose target the data also knows: see "Spawn areas" below | | group content `group` | elite work, dungeon and raid quests and goals on an instance map: see "Group content" below | | escort `escort` | the accept, `complete` and objective goals of an escort quest: see "Escort quests" below | | height `z` | a goal at an NPC or object: the height of that NPC's or object's spawn (`spawnz.json`), so the walk ends on its floor: see "Heights" below | | place area `area` | `sethome`, `hearth`, `fly` and `getfp` (their location) and `goto` (its label): the AreaTable area of that name, so the goal completes and reads right on every client language: see "Places by ID" below | | taxi node `node` | `getfp`: its flight point's taxi node (`travel.json`): see "Places by ID" below | | `sethome` innkeeper `npc`, `npcName` and coordinates | a `sethome "Location"` without `npc`: the innkeeper of the one inn (`travel.json`) whose bind location is that name (ignoring case) and who serves every faction the goal applies to (a neutral town's goblin serves both). None when no such inn has one: the Alliance innkeeper's inn on a goal for both factions gets none | | `getfp` flight master `npc`, `npcName` and coordinates | a `getfp "Location"` without `npc`: the flight master of the taxi node it gets (`travel.json`), the one node of that name or town serving every faction the goal applies to. None when there is no such node: Booty Bay, with one flight master per faction, on a goal for both factions gets none | | name tokens `{kind:id}`, `names` | the game's names in every text a player reads, so each shows in the client's language: see "Names in texts" below | | (a note dropped) | a goal's `--` note that only names the goal's own NPC, object, target or item (`accept 6181 -- Quartermaster Lewis`): the goal shows that name already, in the client's language | **Names in texts.** A text the player reads (the guide's `title`, `why`, `pitch`, `pros`, `cons` and `reward text`; a step's title and `tip`; a goal's `--` note and display text) names quests, NPCs, places and items in English. The compiler writes each name it can tell apart as a token, `{kind:id}`, so the addon shows the game's own name there on every client language (docs/TRANSLATING.md, "Guide texts"), and a translator writes only the words around it. It looks, longest name first and with its exact case, for: the names the step's own goals give (quests, givers and enders, targets, items, collect sources, smart-target candidates, rewards, reagents, quest objectives, spells, factions, professions), then the whole guide's, the zones of its maps and the AreaTable areas in them, then any zone and any open-world area whose name is unique, the professions and their reagents, and any NPC, object or item of the data whose name has two words or an apostrophe, then the client's spell names (the Forever `SpellName` table of the client build `meta.json` names, cached beside the data: any spell of two words or more, or with an apostrophe or colon; a one-word class or profession ability only in Class and Professions guides, or after "cast" or "your"; none another thing of the game shares, no profession rank spell, no spell owning something ("Blizzard's designers"), and no one-word spell used as a verb: taking an object or opening a sentence that goes on in lower case, "Polymorph a naga"; nor a name of a faction of the client's `Faction` table, "Burning Blade"). A place, NPC or object the game names with a leading "The" matches without it ("Molsen Farm" is the game's "The Molsen Farm"), and a zone or area ending "City" without that ("Stormwind"). An NPC of the step's or the guide's own goals also matches by its first name ("Dalinda" for Dalinda Malem) where that word has four letters or more, no other NPC of the step (or guide) shares it, no other NPC of the data starts with it ("Defias" stays words), and the word after it is not the rest of the NPC's name ("Lashtail raptors"). Other languages show the game's name there, and an English client reads the author's own words (the compiled guide's `written`). A name in its English plural ("Harvest Watchers"), in lower case ("the Jansen Stead") or inside a longer word stays words, as does a name right next to a capitalised word or before "of <Capitalised>" that would make it a longer name the data lacks ("Rot Hide" gnolls, "Young Wetlands Crocolisks", "Cleft of Shadow", "Elixirs of Shadow Power"; a possessive, a profession rank or a sentence's opening word does not count), and a one-word name the pack's texts also use as a lower-case word ("Barracks"), and two names a space apart (a name the data lacks, "Longshore Murloc Gills"). You may write a token yourself, `{npc:240}`: its kind and id must be in the data. `i18n guides stats` counts the tokens, by kind and by where the compiler found them. **Spawn areas.** Mobs, quest objects and some NPCs spawn at more than one place, and a player who finds nothing where the arrow led must be able to try the others. So a goal placed at an NPC or object gets every place its target spawns: `spots = { { x, y, r, n, alt }, ... }`, each the centre (map percent, in the goal's own `map` and frame `f`), radius in yards covering its spawns (measured through the map's Era frame, else its Forever one: Zephras Isle, Riverglades and the other maps Forever added have only that), and spawn count of one cluster of the target's spawns (for `collect`: the likely sources' spawns on that map, mobs, objects and nodes, as chosen above). Every known spawn on the goal's map lies in a spot (the reference data's evenly spread points and the ones its per-map cap left out, `more` in docs/ARCHITECTURE.md, "Reference data"). Spots with `alt = true` are the other places it spawns: the arrow never picks one on its own, but the world map marks them (fainter) and moving on by hand reaches them (the arrow button, a click on the arrow, a click on a mark). The clusters come from the quest database's clustering (`tools/lib/questdb/cluster.js`). Same map only. The goal keeps its `x`/`y` as the default point. A target with a single spawn on the map gets no `spots`. - **Places** (6 spawns or fewer: a named NPC or a quest object that appears at one of a few places, or the handful of mobs an objective needs): every place is a spot the arrow may pick, spawns within 70 yd of each other being one place, radius at least 15 yd. Places within 250 yd of their centre work as camps (below); further apart, kill, collect and interact goals search them like an area objective (`spread = true`, a walk from the goal's point). - **Camps** (90% of the spawns within 250 yd of their centre): clusters of 70 yd, widened for thinly spread mobs to twice the median spacing between neighbouring spawns (at most 250 yd); radius at least 15 yd. The arrow picks among the clusters of two or more (all of them when none has two), nearest to the goal's `x`/`y` first, at most 6; lone spawns and clusters past the 6 follow as alternatives. At runtime the waypoint is the spot nearest the player and the arrow counts the whole area as arrived. - **Area objectives** (spawns reaching further: raptors all over the northern Barrens) also get `spread = true`. Clusters as for camps; every cluster counts, lone spawns too, each at least as wide as the spacing between spawns (40-150 yd); beyond 12 the searched ones are spread evenly over the area (farthest-point picks from the cluster nearest the goal's point), ordered as a walk from the goal's point, and the rest follow as alternatives. At runtime the player searches spot by spot: the arrow says "Search here" inside a spot (never "Arrived"), moves on to the nearest spot not visited lately once the player leaves it, and the map shades every region the spots cover. - **Strays** (every goal the data places, any verb, whose target has more than 6 spawns on the map): when the spawns, linked wherever two lie within 300 yd of each other, mostly (three quarters or more) form one area, a group of one or two spawns apart from the rest is a stray: a mob or two on their own, hundreds of yards from the camps. A stray is an alternative, and a goal point at one (the spawn nearest the previous goal) moves to the nearest other spot, so the arrow leads to the area that holds the target. A sparse trail of three or more spawns is not a stray; nor is anything of a target with 6 spawns or fewer, or one spread over a zone with no area holding most of it. A stray can still be the place a step means (a named mob that drops the item too): place such a goal by hand (`@x,y`), or put it in the step at the camp. - **Hand-placed** (`@x,y`): the author's point is the spot the arrow takes, wide enough for any place of the target it stands in, and every other place the data knows follows as an alternative. Only where the data agrees: a point more than 50 yd from every spawn of an NPC to meet, or more than 250 yd from every spawn of a mob or object to kill, collect or click, places the target where the data does not (Forever moved it) and gets no `spots`. A route through gathering nodes lists every node place of the zone wherever its point lies. - **Loop** (a step with a `loop` line, for a search the data does not shape the way you want: a circuit through camps, round a lake): the step's `goto` points, in order, become the spawn areas of each of its `kill`, `collect` and `interact` goals that has no `@x,y` of its own and picks no place at runtime (`nearest`), with `spread = true`. The goal's point is the first goto, the spots are exactly the gotos (no alternatives, no spawn count `n`), each as wide as its goto's `r` (default 30 yd), and the gotos leave the step (their labels with them), so the player searches the points one after another as in an area objective. Compile-time only: the compiled step has no `loop`. It is an error when the step has fewer than two gotos, gotos on different maps or frames, an `optional` or `only` goto, or no goal to place. ``` step Kobold camps loop goto 47.6,35.1 goto 49.0,32.4 r 20 goto 52.3,26.8 kill 6 x10 quest 7.1 ``` See docs/ARCHITECTURE.md, Smart logic, "Spawn areas". **Heights.** In stacked places (the Undercity's quarters under its streets, a tower's floors) a point on the map is several places, and the walking route ends on whichever floor its engine picks. So a goal whose point stands for an NPC or object gets that entity's height, `z` (world yards), from `data/forever/spawnz.json` (the server database's spawn positions, which `data build` writes): the z of the entity's nearest spawn on the goal's instance map (its world point's, in the goal's frame), when that spawn is within 15 yards of the point. Nothing is guessed: an NPC only Forever has, or one Forever moved more than 15 yards, gets none, and without `spawnz.json` no goal gets one. These goals can get one, their point being the NPC's or object's (its spawn, or your `@x,y` at it): - `accept` and `turnin` at their NPC or object (not a quest from an item); - `talk`, `kill` (the spawn nearest the previous goal; a point at the centre of many spawns is seldom within 15 yards of one), `interact`; - `buy`, `train`, `vendor`, `sethome`, `getfp` and `learn` naming an `npc` (a `sethome` or `getfp` also with the innkeeper or flight master the compiler names). The same rule gives a height, each from its own point, to the other spawn places of such a goal (`spots`: a place within 15 yards of one of its spawns; the centre of a camp farther from each gets none) and to every candidate of a smart target (`nearest`, class and profession trainers, by the candidate's own NPC), so the walk to the place or NPC the arrow picks ends on its floor too. `goto` and `explore` (places), `collect` (a farming spot among the item's sources, also `collect … nearest`'s farm spots) and `use` never get one. `compile` prints how many got one ("heights: N of M NPC or object goals, N of M smart-target candidates and N of M spawn spots got z"). In the game the walk is searched with the height and asked again without it when that finds no route or one ending more than 30 yards above or below it. **Places by ID.** The game names places in the player's language ("Sombre-Comté" on a French client for "Darkshire") and guides name them in English, so the compiler gives a goal that names a place that place's ID, and Polestar compares IDs, or names the game gives in the same language: - `area`: on `sethome`, `hearth`, `fly` and `getfp` the area their location names, on `goto` the one its label names, from the client's AreaTable (the newest Forever build `data build` caches in `data/sources/<tables>/`): of the areas with that name (any case), the one in the goal's zone when the goal has a map, else the open world's (Eastern Kingdoms and Kalimdor, not Forever's copies of a town elsewhere). A name two areas share there gets none. In the game a `hearth` or `fly` is done when the zone or subzone text is that area's name in the client's language (`C_Map.GetAreaInfo`), a `goto` also when the player goes indoors in that subzone (a cave or mine, never a zone), and the guide window shows that name. - `node`: on `getfp`, the taxi node of its flight master (`npc`), else of the one flight point (`travel.json`) of that name or town serving every faction the goal applies to (Booty Bay has one per faction, so a goal for both gets none). In the game the goal is done once the flight map lists that node as known. - `sethome` completes by its inn: `travel build` gives every inn its area, and binding at the innkeeper the goal names (or the innkeeper of the inn its location names) completes it. A name with no single match gets nothing and the goal keeps matching by its English name, as before; the guide sources do not change. `compile` prints how many got one ("areas: N of M place goals got an area", "nodes: N of M getfp goals got a taxi node"). ## Group content Every goal that needs a group says so in the guide window, under the goal (once per card when several goals share it), and a guide with such a goal on its route (not `optional`) carries a "Group" chip in the guide menu. The compiler writes `group` on the goal, first match wins: 1. the author's `group [N]`: `{ kind = "group", size = N }` ("Group of N advised"; "Group advised" without `N`); 2. a dungeon or raid: a goal with a quest (`accept`, `turnin`, `complete`, or an objective goal with `quest`) that the simulator's solo filter counts as a dungeon or raid quest (tools/lib/sim/solo.js): the quest's area in `quests.json` lies in an instance, and its giver, its ender or one of its objectives has no open-world spawn (a breadcrumb into the instance stays an open-world quest); or a goal placed on a map drawn only on an instance: `{ kind = "dungeon" | "raid", name = "Dire Maul" }` ("Dungeon: Dire Maul", "Raid: Molten Core"); 3. elite work, the same test as the Leveling-guide elite rule (Validation): a `kill` of an npc of rank 1–3 hostile to a side the goal applies to, or a `collect` whose every located dropper is one: `{ kind = "elite", rank }` ("Elite: group advised", "Rare elite: group advised", "Boss: group advised"). The instances come from the Forever client's `Map.csv`, `AreaTable.csv` and `UiMapAssignment.csv` in the `sources` folder beside the data folder (`data/sources/<tables>/<build>/` for `data/forever`; `data build` and `codex build` cache them). Without them only `group [N]` and elite work apply. The guide's `group = true` is set when any goal that is not `optional` has `group`. ## Escort quests An escort quest's NPC walks off with whoever took the quest last and is gone until it respawns. The guide window says so under the quest's accept, `complete` and objective goals (once per card): "Escort: if the NPC is not there, wait for it to respawn". Its turn-in has no such line. The compiler writes `escort = true` on those goals (`tools/lib/dsl/escort.js`) when the quest's own words say escort: an `event` objective's text ("Escort Miran to the excavation site") or the quest's `objectiveText` ("Escort the captive fire elemental out of Dun Modr"). A quest's `escort` in `quests.json` wins, set by `tools/lib/data/corrections.json` with its source: `true` for an escort worded otherwise ("Protect Volcor until you reach the road"), `false` for a quest whose text wrongly says escort (Lost! 4492 carries the objective of the escort after it). There is no modifier: a wrong label is a data fix. ## Validation Errors fail `compile` and `lint`; warnings print. Errors: - syntax errors, unknown verbs or modifiers, malformed IDs or coordinates - duplicate guide ids; `next` pointing to an unknown guide - a `next` guide (or route option) no character of this guide can follow: of the other faction, or whose `race` or `class` leaves none of this guide's characters (no race in common, no class in common, or no race of this guide that can be one of its classes): `no Human character can follow forever/alliance/dwarf-gnome/01-dun-morogh (it is for Dwarf/Gnome only)`. A partial overlap is fine - a step with no goals - quest, npc, item or object id unknown in data **and** no explicit name/title - profession, faction or spell unknown in data **and** no quoted name; a faction not in `factions.json` also needs its id (`rep <factionId> "Name" <Standing>`); `achieve` always needs its quoted name - `rep` standing outside 1–8 / Hated–Exalted; `craft` with both `xN` and `until` - empty quoted strings (names, titles, labels, notes) - a step label used twice in a guide, an `along until` naming no label, or a label on its own step or an earlier one - `era`/`live` on a goal without typed coordinates - an `image` path that is absolute, leaves the pack folder (`..`), uses `\`, names a file other than `.tga` or `.blp`, or has a character other than letters, digits, `_`, `-` and `/`; a malformed size (`512x256`); a second `image` in a step - `choose`/`reward` without item ids, an item listed twice, a reward item missing from `items.json` without a name; malformed `money` or `xp`; a `group` size that is not a whole number from 2 to 40 - a smart target (`nearest`, `train <Profession>`, `train class`, `collect … nearest`) with no candidate in the data or with coordinates; `collect … nearest` without `xN` or with `quest`; `nearest`/`train class` with an `npc` (`train <Profession> npc <id>` keeps that trainer); an unknown profession in `train` - `turnin`/`complete`/objective goals for a quest that is never accepted earlier in this guide or in a guide that chains into it via `next`, unless the turn-in is `direct` (for a repeatable quest its giver also takes back, the hint suggests `turnin <id> direct`) - `turnin … direct` for a quest the chain accepts earlier (drop `direct`), and `complete` or an objective goal for a quest handed in `direct` - `accept` for a quest whose `races`/`classes` exclude every character the step or goal can apply to - coordinates outside 0–100 - required elite work in a `Leveling` guide (a warning in other packs; elite work may appear there only as an `optional` extra, with the tip `<Target> is elite: grouping up is advised.`): a non-`optional` `kill` of an npc of rank 1–3 (elite, rare elite, boss) hostile to a side the goal applies to (a friendly one is a talk credit), or `collect` of an item whose every located dropper is such an npc; `lint` also errors on a non-`optional` quest goal of a quest the cached simulator world (below) excludes as `elite`, unless the goal was already reported as elite Warnings: - a `when` predicate naming a quest or item the data lacks, a zone not in `zones.json`, a bind location no inn has, or a subzone that names no single area; a step whose `when level` leaves none of the guide's levels, or that asks for one predicate both ways (`onquest 7` and `!onquest 7`): no character sees it - a goal in an `along` step that Polestar checks off only on the step the route is on (see "Along the way"): it never checks off there - an `accept` whose prerequisites (`pre`, any one suffices) are none of them turned in earlier in the chain - an `accept` above the level the route plausibly reaches (when XP data exists) - an `accept` of a quest whose `excl` (exclusive) quest is accepted or turned in earlier in the chain: the game does not offer it while that quest is in the log or done - a non-`optional` `accept` never turned in later in the guide or the guides after it, checked for every route choice; when a next guide's race or class leaves out the characters still holding the quest, the warning says so (its turn-ins do not count for them) - `complete` on a quest with no objectives: the turn-in is the action; use `turnin` - a `turnin` whose quest's objectives ask for an item the world gives (a drop, an object, a vendor or a container; not one the quest or an NPC hands over) that no earlier goal in the guide or a guide chaining into it gets: a goal for the item (`collect`, `buy`), one linked to its objective (`kill … quest Q.O`), or a `complete` of the quest - a `complete` with no place (no coordinates and no `goto` earlier in its step) on a quest whose objectives have places (an npc or object with spawns, an item with a placed dropper or vendor): the arrow has nowhere to point; write a goal per objective - explicit coordinates more than 50 yards from every known spawn of the entity - ids missing from data but given explicit names/coordinates (new Forever content) - objective-capable goals with no coordinates - `quest Q.O` past the quest's objectives (the warning lists them as `7.1 = kill Kobold Vermin x10`), or an objective goal whose target is none of the quest's objectives - a `craft` before any `learn` of that spell earlier in the chain (free starter recipes excepted); `until <N>` past the recipe's grey skill - a coordinate on a map other than the step's zone that the guide never sets as a zone (catches a target resolved onto another continent) - coordinates without `map` on a zone set in a step for some characters only, when the other characters who see them are in another zone (a class trip's `zone Moonglade` holding for the rest of Darkshore) - profession, faction or spell missing from data but given a quoted name - a `goto` right before a goal that already leads to the same place: the next goal (notes skipped) is located within 200 yards of the goto point, measured to the edge of its nearest spawn area (see `goto` under "Places") - a quest item that vanishes after a while (items.json `duration`, from the Forever client's ItemSparse) carried longer than it lasts: from the goal that gets it (an `accept` whose quest hands it over, a `collect`, a `buy`) to a later `turnin` that needs it or `use` of it, timed from the latest goal that got more of it (`buy 13320 x2` serves two turn-ins, the second measured from the purchase), with the simulator's travel and kill times over the guide's goals (docs/SIMULATION.md, "Keeping the guides' fixes"): ``item 10439 (Durnan's Scalding Mornbrew) lasts 5 minutes, but the route takes about 11:29 from here to the `turnin` that spends it (line 196)``. Goals for other characters and `optional` ones are left out, so the estimate errs short - a smart target with no candidate for a faction the goal applies to (and, for `train class`, for a class that faction's allowed races can be); a `train <Profession>` whose default rank needs more skill than any earlier `skill` target - a `sethome`, `hearth`, `getfp` or `fly` location the game never reports, ignoring case: `sethome` against the inns' bind locations, `hearth` against those and the zones the inns are in, `getfp` against the flight points' names and their part before the comma (these three as the addon matches them); `fly` against the flight points' towns (the name the flight map picks the node by, even where the landing area is named differently), the inns' locations and the zones they are in. The hint names the closest known places (`did you mean "Feathermoon Stronghold"?`). Inns and flight points come from `data/forever/travel.json`; without it (or without the inns or the flight points in it) those goals are not checked - a `|` in text the player sees (`title`, `folder`, `pitch`, `pro`, `con`, `author`, step titles and tips, goal texts and notes, quoted names): it prints literally in game - another pack's Era frame for a map Polestar's guides also use, with other bounds: in game Polestar's wins, so coordinates on that map may be off - an `image` whose file the pack folder lacks (the step then shows no picture), a file whose size the compiler cannot read (not a TGA or BLP) when the line gives none, and a picture whose sides are not powers of two (256, 512, 1024), which the game may not draw - `lint` only, with a simulator world cached in `data/sim` (or `--sim <dir>`): a non-`optional` quest goal in a `Leveling` guide on a quest the solo filter excludes (dungeon, raid, pvp, rare drop, reputation, repeatable or profession; `elite` is an error, above); a `turnin … direct` is no repeatable to grind and is left out of the repeatable check These quest checks count a goal only for the characters its `only` (and the quest's own race and class masks) leaves. Most messages carry a `hint:` line saying how to fix them. ## Output `compile` writes the pack's addon folder (Polestar's: `addon/Polestar_Guides/`; another pack's: `dist/<folder>/`): the generated TOC, `Pack.lua`, `MapFrames.lua` (Era bounds for referenced maps), `Guides.lua` (one `RegisterGuide` per guide, each in its own function) and `LICENSE-DATA.txt`, plus the pack folder's `LICENSE` copied as `LICENSE.txt` when it has one, the picture file of every `image` the compiler found, at its path in the pack folder, and beside it a texts addon per language the pack's `locales/` translates (docs/TRANSLATING.md, "Guide texts"). [PACK_FORMAT.md](https://polestar.guide/docs/authors/community-guide-format) describes them. Output is deterministic: the same inputs give byte-identical files. ## Cookbook Worked examples, from guides that lint clean and play to the end. Every id here was looked up with `polestar find`; look up yours the same way. ### Quests: `accept`, `complete`, `collect`, `turnin` ``` {9} step Goldshire tip Marshal Dughan and Remy stand in front of the inn. accept 62 accept 47 step Fargodeep Mine goto 39.5,80.0 "Fargodeep Mine" complete 62 -- Walk through the mine collect 773 x10 quest 47.1 -- Gold Dust from the kobolds step Back in Goldshire turnin 62 turnin 47 ``` The compiler fills in each quest's title, giver, turn-in NPC and coordinates. `quest 47.1` ties the collect to the quest's first objective, so the guide window counts it from the quest log. `complete` finishes every objective of a quest with nothing more specific to track. ### Killing: `kill` ``` kill 299 x8 optional -- Young Wolves around the camp kill 6 x10 quest 7.1 ``` A `kill` with `quest Q.O` counts from the quest log; without it the player ticks it ("Patterns" below). Kill, collect and interact goals get spawn areas from the data, so the arrow leads to the nearest camp. `polestar find <quest id>` lists a quest's objectives as `7.1 = kill Kobold Vermin x10`: the `7.1` is the `quest 7.1` to write. ### Places: `goto`, `explore` ``` goto 39.5,80.0 "Fargodeep Mine" goto 46.0,55.0 live "Lift to the bluff" explore 39.5,80.0 "Fargodeep Mine" ``` Typed coordinates are in the Era map frame unless the guide says `coords live` or the goal says `live`. In game, `/polestar where` gives your own position as `zone map <id>` and `goto <x>,<y> live`, ready to paste, and the `@x,y live` form for any other goal. Use `goto` for travel and approach waypoints (a boat dock, a pass, a cave mouth on a long ride) and for objectives the data has no location for. Kill, drop, NPC and object goals carry their own location, so the arrow leads to them directly; lint warns on a `goto` whose next goal is located within 200 yards of it. It keeps a `goto` followed by another `goto`, by a goal without a location, an `optional` one, one for other characters (`only`) or one on another map, a kill or drop whose target spawns nowhere in the data (an instance boss placed at its entrance), and gotos in steps with `fly` or `hearth`. A `goto` counts as done on arrival, once a later goal of its step is done, or, when only other gotos, notes and goals for other characters follow it in its step, once the next step for the character is done with a quest goal of it done: a cave's mouth in a step of its own no longer sends back a player who already did the work inside. The goto still holds when that next step has no quest goal (training, a level, travel), is for some classes or races only (`only`), was skipped, or was passed only because its quests are unavailable, when the quest goal done is itself `only`, and when `optional` goals follow the goto in its own step: that is where they are done. ### Pictures: `image` ``` step Fargodeep Mine tip The mouth is easy to miss from the road: the picture shows it. image media/fargodeep-mine.tga goto 39.5,80.0 "Fargodeep Mine" ``` A screenshot helps where words and the arrow do not: a cave mouth hidden in a hillside, the right door of a building. Take it in game (Print Screen saves it in the game's `Screenshots` folder), crop it to the spot, and save it as a `.tga` at a power-of-two size such as 512x256 or 512x512 in your pack folder, for example `media/`. The guide window draws it under the step's tip as wide as the window (at most 160 high), in the ratio of the file or of `<w>x<h>` when the line gives one. Folded to one line, the tip hides it; a player who turned step tips off sees none. Lint warns when the file is not there, and `compile` copies it into the addon folder. The game may only find a picture added while it runs after a restart; `dev` rebuilds when a `.guide` file or `pack.json` is saved, so save the guide once the picture is in place. An import string carries the `image` line but not the file, so an imported guide shows no picture. ### People and things: `talk`, `interact`, `use` ``` talk 295 optional interact 176793 quest 5545.1 -- Bundles of wood lie under the trees use 5411 quest 754.1 @51.8,68.4 -- Winterhoof Cleansing Totem ``` ### Travel: `sethome`, `hearth`, `getfp`, `fly` ``` sethome "Goldshire" npc 295 -- Innkeeper Farley, inside hearth "Goldshire" getfp "Thunder Bluff" npc 2995 -- Tal, on the top of the bluff fly "Crossroads" ``` Locations are written as the game names them; `polestar find --kind inn` and `polestar find --kind flight` list the names (every inn and flight point, with coordinates). `sethome nearest` binds at the nearest inn of the player's faction instead. ### Errands: `train`, `buy`, `vendor`, `level`, `note` ``` vendor nearest buy 159 x5 nearest -- Refreshing Spring Water train class level 9 note You can train First Aid with any trainer of it in a city. ``` `nearest` and `train class` pick the trainer or vendor at runtime, by the player's faction and where they stand. ### Professions: `train`, `learn`, `craft`, `skill` ``` step First Aid train First Aid learn 3275 craft 3275 until 40 skill "First Aid" 40 ``` ### Reputation and challenges: `rep`, `achieve` ``` rep Stormwind Friendly optional achieve 6 "Level 10" optional ``` `achieve` always needs the achievement's quoted name. ### Class- and race-only steps A header `race` or `class` limits the whole guide; `only` limits one step or one goal: ``` guide joe-routes/mulgore title Bloodhoof Village faction Horde race Tauren levels 6-10 zone Mulgore step Hunters only only Hunter train class -- your next spells step Class quests note "Your class quest starts in Thunder Bluff." only Warrior,Shaman ``` A goal's `only` comes after its arguments, so a `note` with one needs its text in quotes. `only !Hunter` is every class but Hunters. Playtest plays each class a guide names, plus one it never names. ### Route choices `next` with several ids lets the player choose where to level next; the first is the default. Each option needs a `pitch`, and may have `pro` and `con` lines: ``` guide joe-routes/mulgore next joe-routes/thunder-bluff, forever/horde/02-the-barrens guide joe-routes/thunder-bluff pitch Train, shop and take the flight to the Crossroads. pro Every trainer in one city con A long ride down the lift next forever/horde/02-the-barrens ``` ### Optional extras `optional` goals never hold the step: side quests, a rare, a reputation along the way. An elite in a Leveling guide belongs here, with the tip "<Name> is elite: grouping up is advised." ``` accept 184 optional -- Only if you looted a Westfall Deed: right-click it kill 299 x8 optional ``` ### Handing over to our guides A pack's guide may end by handing over to any of Polestar's guides. Pick one its characters can follow: `polestar find --kind guide <zone>` prints each guide's level range and who it is for, and `--race`/`--class` keep only the ones such a character can follow: ```sh polestar find --kind guide westfall --race Human ``` ```output next forever/alliance/02-westfall # Westfall (12-17), Alliance # its next: forever/alliance/03-darkshore next forever/collectibles/pets/chicken-egg # Chicken Egg (1-60), Alliance … (the other collectible guides set in Westfall follow) ``` A guide for Humans cannot hand over to the Dwarf and Gnome guide (`… # Dun Morogh (1-13), Dwarf/Gnome only`): lint stops it. Start the next guide near the level yours ends at, and put its id in `next`: ``` next forever/alliance/02-westfall ``` Lint and playtest load Polestar's guides beside yours, so the handover is checked and played: a hand-over that does not land on our guide with something to do, or lands on one that does not apply to the character (`no Human can follow it`), is reported as stuck at the hand-over. An option with `when` that does not hold when the played guide ends is no hand-over; with none offered the guide ends there. Turn-ins in our guide of quests your guide accepted count too. ### With an AI assistant An assistant can draft guides from your own notes and routes; [PACKS.md](https://polestar.guide/docs/authors/handbook) ("With an AI assistant") explains how, and the ground rule: its ids and coordinates are guesses until `find`, lint and playtest confirm them. ### Patterns **Several objectives at once.** The goals of one step are open together: each counts as soon as it is done, in any order, and the step ends when every goal that holds it is done. The arrow leads to the first open one (click a row to aim at another). Put objectives the player works in the same area in one step: ``` step Kobolds and wolves kill 6 x10 quest 7.1 -- Kobold Vermin collect 750 x8 quest 33.1 -- Tough Wolf Meat, from the wolves ``` **An optional side chain.** Mark every goal of the side quest `optional`: it never holds a step, the player may dismiss it, and lint does not ask for its turn-in. Keep it in steps that also have a goal that holds them: a step of `optional` goals only is done at once, and the guide moves past it. ``` step Deputy Willem turnin 783 accept 7 accept 5261 optional -- a short errand to Eagan Peltskinner step Kobolds kill 6 x10 quest 7.1 turnin 5261 optional -- Eagan stands by the path ``` The turn-in, objectives and `complete` goals of a quest whose accepts in the guide are all `optional` apply only while the quest is in the log or handed in. A player who never took it doesn't see them. So a side quest's turn-in can have a step of its own, written without `optional`: the step holds and leads the arrow to the ender for a player who took the quest, and the guide passes it for everyone else. ``` step Murlocs collect 780 quest 46 collect 247826 x1 optional -- Croaky's Head: Croaky accept 91740 optional step Ridgepoint Tower turnin 91740 -- only for players who took it ``` **Leveling up before moving on.** `level <N>` holds its step until the character reaches level N. End a guide with it when the next guide's zone needs a level the route may not reach by itself: ``` {2} step Ready for Westfall level 12 ``` **A bare `kill <npc>`** (no `quest`) is a check-off: Polestar does not count the kills, so the player ticks the goal in the guide window, and until they do it holds the step, unless it is `optional`. Tie a kill that serves a quest to the objective with `quest Q.O` so the quest log counts it. --- # Community guide format > The contract between a community guide and Polestar: pack.json, the addon the compiler writes, the rules, import strings, versioning. Page: https://polestar.guide/docs/authors/community-guide-format (Polestar docs > Guide authors) The contract between a community addon and Polestar, for anyone building tools of their own. Authors who use Polestar's tools never write any of this by hand: they write `pack.json` and `.guide` files ([GUIDE_FORMAT.md](https://polestar.guide/docs/authors/guide-format)) and `polestar compile` writes the rest. The handbook is [PACKS.md](https://polestar.guide/docs/authors/handbook). > **Tip:** > Building a tool that generates guides? The simplest path is to write a > pack (`pack.json` and `.guide` files) and let `polestar lint`, > `polestar playtest` and `polestar pack` check and build it. Write the > addon described below yourself only when that is not an option. **On this page:** [`pack.json`](https://polestar.guide/docs/authors/community-guide-format#packjson) · [The addon](https://polestar.guide/docs/authors/community-guide-format#the-addon) · [TOC fields](https://polestar.guide/docs/authors/community-guide-format#toc-fields) · [Rules Polestar enforces](https://polestar.guide/docs/authors/community-guide-format#rules-polestar-enforces) · [Format 3](https://polestar.guide/docs/authors/community-guide-format#format-3) · [Format 4](https://polestar.guide/docs/authors/community-guide-format#format-4) · [Import strings](https://polestar.guide/docs/authors/community-guide-format#import-strings) · [Versioning](https://polestar.guide/docs/authors/community-guide-format#versioning) A community addon is an addon for World of Warcraft: Forever that depends on Polestar and registers guides with it. It is built from a pack: a folder with a `pack.json` and `.guide` files. In the format, every such addon is a pack; Polestar's own guides are a pack too (`Polestar_Guides`, pack id `guides`). ## `pack.json` The pack's manifest, in the root of the pack's folder. Every tool works on the pack folder given as its one argument (`polestar lint ../joe-routes`) or with `--pack <dir>`, else on the nearest `pack.json` in the current folder or a parent. ```json { "id": "joe-routes", "title": "Joe's Routes", "author": "Joe", "version": "1.2.0", "license": "CC-BY-4.0", "website": "https://github.com/joe/joe-routes", "source": "Written from my own play", "folder": "PolestarPack_JoesRoutes" } ``` | Key | Required | Value | |---|---|---| | `id` | yes | the pack id: `^[a-z0-9][a-z0-9-]{1,31}$` (2 to 32 lower-case letters, digits and hyphens, starting with a letter or digit), not reserved (below) | | `title` | yes | shown to players; at most 64 characters | | `author` | yes | shown to players; at most 64 characters | | `version` | yes | one word of letters, digits, `.`, `+` and `-`, starting with a letter or digit, at most 32 characters (`1.2.0`) | | `license` | yes | the license of the pack's guides, as an SPDX id where one exists (`CC-BY-4.0`, `CC0-1.0`, `MIT`, `GPL-3.0-only`); at most 64 characters | | `website` | no | `https://` or `http://` address; at most 200 characters | | `source` | no | where the guides come from, in the author's words; at most 200 characters | | `notes` | no | one line for the AddOns list, shown when the player points at the pack there; at most 200 characters (default "Community addon for Polestar by <author>") | | `folder` | no | the addon's folder name: 1 to 64 letters, digits, `_` and `-`, not `Polestar` and not starting with `Polestar_` (in any case); default `PolestarPack_` and the title in CamelCase (`Joe's Routes` → `PolestarPack_JoesRoutes`), or the id when the title has no letters or digits | Every value is a string on one line. A missing required field, or a value that breaks these rules, is a lint error; an unknown key is a warning; a `|` in a displayed value is a warning (it prints literally in game). The pack folder holds `pack.json`, the `.guide` files in any layout, `drafts/` (Recorder drafts, compiled only with `--include-drafts`), `dist/` (build output) and the picture files its `image` lines name (`.tga` or `.blp`, at any path inside the folder, such as `media/`). The compiler reads every `.guide` file under the folder except in `dist/`, `drafts/`, `node_modules/` and folders whose name starts with a dot. ## The addon `polestar compile` writes `dist/<folder>/` (ours: `addon/Polestar_Guides/`): ``` PolestarPack_JoesRoutes/ PolestarPack_JoesRoutes.toc Pack.lua Polestar.RegisterPack({ ... }) MapFrames.lua Polestar.RegisterMapFrames({ ... }, "joe-routes") Guides.lua one Polestar.RegisterGuide({ ... }) per guide LICENSE-DATA.txt the reference data sources the guides draw on LICENSE.txt the pack folder's LICENSE, copied as is (only when it has one) media/cave.tga each picture an `image` line names, at its path in the pack folder PolestarPack_JoesRoutes_deDE/ one texts addon per language the pack translates PolestarPack_JoesRoutes_deDE.toc Texts.lua Polestar.RegisterGuideTexts("deDE", "joe-routes", { ... }) LICENSE.txt as above ``` **Texts addons.** A pack whose `locales/<locale>/` folder holds translations (docs/TRANSLATING.md, "Guide texts") gets, beside its folder, one load-on-demand addon per language, `<folder>_<locale>`. Polestar loads the client's own once the pack's files are in, and no other: a German client never reads the French texts. Its TOC carries `## LoadOnDemand: 1`, `## Dependencies: Polestar`, `## X-Polestar-Texts: <pack id>` and `## X-Polestar-Locale: <locale>` with the generated-folder marker, and `Texts.lua` makes one call: ```lua Polestar.RegisterGuideTexts("deDE", "joe-routes", { pack = { ["Joe's Routes"] = "Joes Routen" }, -- the pack's title and notes, its guides' folders guides = { ["joe-routes/elwynn"] = { ["{npc:240} stands outside the inn."] = "{npc:240} steht vor dem Gasthaus." } }, }) ``` Each table maps a text's English, name tokens and all, to its translation; a text without one shows in English. `compile`, `install` and `dev` write and replace a texts addon folder by the same rule as the pack folder (its marker and `X-Polestar-Texts`), and remove the one of a language the pack no longer translates; `pack` puts each into the zip as a folder of its own. The file set is fixed: a new guide changes `Guides.lua`, never the file list, so `/reload` shows every change and only a pack's first install needs a restart of the game (`LICENSE.txt` is a text file the game never loads); so does the first texts addon of a language, below. Each guide's table is built inside its own function in `Guides.lua`, so Lua 5.1's constant limit applies per guide. ### TOC fields ``` ## Interface: 16001 ## Title: Polestar Community: Joe's Routes ## Notes: Community addon for Polestar by Joe ## Author: Joe ## Version: 1.2.0 ## Category: Quests ## Group: Polestar ## Dependencies: Polestar ## X-Polestar-Pack: joe-routes ## X-Polestar-Format: 3 ## X-Polestar-Needs: 0.2.5 ## X-License: CC-BY-4.0 ## X-Website: https://github.com/joe/joe-routes # Generated by `node tools/polestar.js compile` from pack.json and the .guide files. Do not edit: rebuild with that command. Pack.lua MapFrames.lua Guides.lua ``` | Field | Value | |---|---| | `Interface` | copied from `addon/Polestar/Polestar.toc` at build time | | `Title` | "Polestar Community: " and `pack.json` `title` (the title alone when it already starts so), so the AddOns list reads the addon as a community addon. Community addons built before this prefix carry "Polestar Pack: " until rebuilt; Polestar recognises both. Polestar's own menus show the title without it. Polestar's own pack (`guides`) gets no prefix | | `Author`, `Version` | from `pack.json` | | `Notes` | `pack.json` `notes`, else "Community addon for Polestar by <author>" | | `Category` | `Quests`, Polestar's category in the AddOns list | | `Group` | `Polestar`: the AddOns list shows the pack under Polestar's own entry, beside Polestar's own addons. Not written for Polestar's own pack | | `Dependencies` | `Polestar`: the client loads Polestar first | | `X-Polestar-Pack` | the pack id. Polestar lists every addon carrying it on the Community guides page, loaded or not | | `X-Polestar-Format` | the pack format (below) | | `X-Polestar-Needs` | the first Polestar version that reads that format, so an older Polestar can say which version the pack needs | | `X-License` | `pack.json` `license` | | `X-Website` | `pack.json` `website`, only when given | The comment line is the **generated-folder marker**, and with `X-Polestar-Pack` it makes the folder rule: `compile` (its output folder), `install` (`dist/<folder>/` and the folder in AddOns, where a symlink is replaced without the check) and `dev` (the folder in AddOns) write a pack folder only when it is absent, empty, or carrying the generated marker and no other pack's id. Anything else is refused: a folder without the marker as "not a generated community addon", one generated for another pack as holding that pack, with the hint to set `folder` in `pack.json`. `pack` builds a community addon's zip in memory, and `play` writes into a new temporary folder, so neither touches an existing pack folder. ## Rules Polestar enforces `Core/Guides.lua` applies these at registration; lint reports the same ones before a pack is built (`tests/packs-parity.test.js` holds the two together). 1. **Ids.** Pack ids match `^[a-z0-9][a-z0-9-]{1,31}$`; `guides`, `forever`, `lookup`, `draft`, `polestar` and `imported` are reserved. Every guide id starts with `<pack id>/`, except in Polestar's own packs: `guides` (the addon `Polestar_Guides`) owns `forever/` and `draft/`, Polestar's internal `lookup` pack owns `lookup/`, and `imported` (the guides pasted as import strings, below) owns every `<author>/` that is a valid pack id nobody reserves. 2. **No overrides.** A guide id outside its pack's prefix is refused. A pack may register one of its own ids again, which replaces that guide. An id a guide of another pack already holds is refused too ("Guide <id> was refused: <pack> already holds that id."): only an imported guide can share a prefix with a pack. 3. **Clashes.** A pack whose id is already registered is refused whole, and the problem names both addons; a pack with a reserved id is refused whole with "Pack id <id> is reserved for Polestar.". Either way the guides and map frames its files register for that id while it loads are dropped, never given to the holder, and the dropped guides are counted in the problem. A pack with a malformed id, no `format` or a required field missing is refused too ("Pack id <id> is not valid: …", "The pack is missing <field>."), and its guides are dropped without a problem each. A guide registered before its pack is refused (listed once the pack registers); one for a pack that never registers is ignored, since there is no row to list it on. 4. **Map frames.** A pack may add Era map frames for maps Polestar's lack; for a map both cover, Polestar's win whatever the load order (lint warns when the bounds differ). Frames for a pack that is not registered, or was refused, are dropped. 5. **Format.** A pack declaring a format Polestar does not read is refused whole, with the status `too-new` and "Needs Polestar <X-Polestar-Needs> or newer." ("Needs a newer Polestar." when its TOC has no `X-Polestar-Needs`). An unknown verb or a malformed field inside a known format refuses only that guide. 6. **Visible problems.** Every refusal is recorded against its pack with a kind: `pack-refused` (the pack), `guide-refused` (one guide, with its id), `no-guides` (the addon loaded but registered no guides, usually a Lua error in its files). The Community guides page shows them. 7. **Text prints literally.** Every string a pack registers is escaped once, at registration (`|` doubled), so colour and link codes do not work. A guide's ids (`id`, `pack`, `next`, `nextChoices`) are left as written. 8. **Missing guides keep their place.** Saved tabs of a guide whose pack is missing or switched off reopen in their old place when it comes back. 9. **Packs on disk.** At login Polestar lists every addon whose TOC carries `X-Polestar-Pack`, loaded or not, with a status. A registered pack is `on`, `off` (switched off on the Community guides page), `refused`, `too-new` (a newer format) or `broken` (registered no guides). One that never registered is, in this order of precedence, `too-new`, `disabled` (turned off in the AddOns list), `not-loaded` (the client did not load it: out of date, a dependency missing) or `broken`. Only guides of packs that are on are shown, searched and suggested. Suggestions come from Polestar's guides unless the player picks a pack under **Suggest guides from** on the Community guides page; only packs with Leveling guides are offered there, and Polestar's guides fill in where the chosen pack has nothing for the character. ## Format 3 The format the compiler writes for a pack whose guides have no `when` (on a step or a `next` option), `along` or `label`, and whose `level` goals have no `frac` (format 4, below). Format 2 is format 1 with the two `group` keys (a guide's and a goal's) and a guide's `reward` and `why`, marked "format 2" below; Polestar 0.2.4 and later read it. Format 3 is format 2 with **name tokens** in the texts and a guide's `names`, marked "format 3" below; Polestar 0.2.5 and later read it. A format 1 or 2 pack is the same without them and keeps loading. **Name tokens** (format 3). The game's names inside the texts a player reads (a guide's `title`, `why`, `pitch`, `pros`, `cons` and reward `text`; a step's `title` and `note`; a goal's `note` and `text`) are written `{kind:id}`: `{npc:240}`, `{object:68}`, `{item:1528}`, `{quest:176}`, `{zone:1429}` (a uiMapID), `{area:87}` (an AreaTable ID), `{spell:5487}`, `{faction:72}`, `{skill:182}` (a profession's skill line). Polestar shows each as the game names it in the client's language (Polestar.Names, the client's map and area names, the profession's translation), else as the guide's `names` give it, so an English client reads the text as its author wrote it (a text that spells a name otherwise, "Dendrite" for Dendrite Starblaze, is in the guide's `written` with the author's words). The compiler writes the tokens (GUIDE_FORMAT.md, "Names in texts"); an older Polestar would show them as written, hence the format. ## Format 4 Format 3 with a step's **`when`**: the conditions checked during play (GUIDE_FORMAT.md, "Conditions checked during play"), a step's **`along`** and **`label`** (GUIDE_FORMAT.md, "Along the way"), a `level` goal's **`frac`**: a point inside the level, and a guide's **`nextWhen`**: conditional hand-offs (GUIDE_FORMAT.md, "Conditional hand-offs"). Polestar 0.2.6 and later read it. The compiler writes a pack in format 4 only when its guides use one of them; any other pack stays in format 3, so the Polestar it needs does not change. An older Polestar would show every conditional step to every character, stop the route at every along step, count `level 12.5` done at level 12 and offer every `next` option (it ignores keys it does not know), hence the format. `when` is a list of predicates, each a table with its kind `k`, `neg = true` to turn it around, and the kind's keys; a step applies while all of them hold: | `k` | Keys | Holds when | |---|---|---| | `"level"` | `op` (`"<"`, `"<="`, `">"`, `">="`), `n`; optional `frac` (0 < frac < 1) | the character's level compares so with `n`; with `frac`, the level plus the share of it done (XP / XPMax) compares so with `n + frac` | | `"onquest"` | `q`: a list of quest ids | any of them is in the log | | `"complete"` | `q` | the quest is in the log, ready to turn in | | `"turnedin"` | `q` | the quest is handed in | | `"available"` | `q`; optional `minLevel`, `pre`, `preAll`, `closedBy` (as on an `accept`) | the quest is not in the log or done, the level is reached, one of `pre` and every one of `preAll` is done, and none of `closedBy` is in the log or done | | `"has"` | `item`; optional `n` (default 1) | the bags hold `n` or more | | `"zone"`, `"subzone"` | `name`; optional `area` | the zone (subzone) text reads as the area's name in the client's language, or as `name` | | `"bound"` | `name`; optional `area` | the bind location reads so | ```lua { title = "Back to Gornek", when = { { k = "onquest", q = { 788 } }, { k = "level", op = "<", n = 6 } }, goals = { ... } } ``` A `when` that is not a non-empty list, or a predicate of another kind or without its keys, refuses the guide. Once the route has moved past a step, Polestar stores whether its `when` held (per character, guide and step) and reads that from then on. `label` is a string, the step's name, unique in the guide. `along` is `true`, or the `label` of a later step: the route passes over the step, and its open goals are listed under the steps after it until they are done or the route reaches that labelled step. ```lua { title = "Boars on the way", along = "camp", goals = { ... } }, { title = "Goldshire", goals = { ... } }, { title = "Back at the camp", label = "camp", goals = { ... } }, ``` A `label` that is not a string or names a second step, or an `along` that is neither `true` nor the label of a later step, refuses the guide ("step N: bad label", "step N: duplicate label <name>", "step N: bad along"). `frac` on a `level` goal (format 4) is the share of the level's XP the goal asks for, a number with 0 < frac < 1: `{ t = "level", level = 12, frac = 0.5 }` is done at level 12 with XP / XPMax >= 0.5, or at any later level. A goal's `frac` outside that refuses the guide ("bad frac"); a `level` predicate's, "bad when". `nextWhen` maps a `next` option to its predicates, the same tables as a step's `when`: `{ ["joe-routes/barrens-early"] = { { k = "level", op = "<", n = 12 } } }`. Every key must be one of `nextChoices`, which the compiler writes whenever `nextWhen` is there, even for one option. Polestar offers an option only while its predicates hold, checked on the character's live state each time it lists the options; with one option offered it goes on to it without asking, with none the guide ends there. Nothing is stored. A `nextWhen` that is not a table, a key that is not in `nextChoices` or a malformed predicate list refuses the guide. ### `RegisterPack(meta)` ```lua local ADDON = ... Polestar.RegisterPack({ addon = ADDON, id = "joe-routes", format = 3, title = "Joe's Routes", author = "Joe", version = "1.2.0", license = "CC-BY-4.0", website = "https://github.com/joe/joe-routes", source = "Written from my own play", }) ``` | Field | Required | Value | |---|---|---| | `addon` | yes | the addon's folder name (the file's first vararg) | | `id` | yes | the pack id (rule 1) | | `format` | yes | `3` (`1` or `2` for a pack of that format) | | `title`, `author`, `version`, `license` | yes | non-empty strings | | `website`, `source`, `notes` | no | strings | Returns `ok, err`. Call it once, in the first file the TOC loads, before any guide. ### `RegisterGuide(def)` One table per guide; returns `ok, err`. ```lua Polestar.RegisterGuide({ id = "joe-routes/elwynn", pack = "joe-routes", title = "Elwynn Forest", faction = "Alliance", minLevel = 5, maxLevel = 10, category = "Leveling", zone = 1429, zoneName = "Elwynn Forest", next = "forever/alliance/02-westfall", author = "Joe", version = 1, steps = { { title = "Goldshire", goals = { { t = "accept", quest = 62, title = "The Fargodeep Mine", npc = 240, npcName = "Marshal Dughan", minLevel = 4, qlvl = 7, map = 1429, x = 42.11, y = 65.93, f = "e" }, } }, }, }) ``` Guide keys (the compiler writes them in this order): | Key | Required | Value | |---|---|---| | `id` | yes | the guide id, under the pack's prefix | | `pack` | yes | the registered pack id | | `title` | yes | string | | `faction` | no | `"Alliance"` or `"Horde"`; absent: either | | `races` | no | list of race file names (`"Human"`, `"Scourge"`, `"NightElf"`, …); absent: any | | `classes` | no | list of class file names (`"WARRIOR"`, …); absent: any | | `minLevel`, `maxLevel` | no | numbers | | `category` | no | `"Leveling"` (default), `"Class"`, `"Professions"`, `"Reputation"`, `"Legacy"`, `"Exploration"`, `"Collectibles"`, `"Miscellaneous"`, `"Dungeons"`; the compiler passes another name through with a warning | | `folder` | no | the guide menu folder | | `keywords` | no | list of extra search words | | `collects` | no | list of item ids the guide obtains | | `reward` | no | format 2: what the guide's goal gives, shown first in the guide menu's details, in order: `{ item = 20536, itemName = "Soul Harvester", quality = 3, choice = true }` (an item; `choice` when one of several to choose from; the name shows in the client's quality colour when the item is cached, else the compiled `quality`'s), `{ spell = 23161, spellName = "Summon Dreadsteed" }` or `{ text = "Shen'dralar reputation" }`; an entry with none of `item`, `spell` or `text` refuses the guide | | `why` | no | format 2: one line on why the goal is worth doing, shown under the reward | | `zone`, `zoneName` | no | the default zone's uiMapID and name | | `next` | no | the id of the guide that follows: one of the pack's or one of Polestar's | | `nextChoices` | no | list of guide ids offered as a route choice (the first is the default); with `nextWhen`, every option, even one | | `nextWhen` | no | format 4: `{ [<guide id>] = { <predicate>, ... } }`, an option of `nextChoices` offered only while its predicates hold (Format 4, above) | | `pitch` | no | one line for the route choice card | | `pros`, `cons` | no | lists of short lines under the pitch | | `author` | no | string; the compiler writes the pack's author when the guide names none | | `version` | no | number | | `group` | no | `true` (format 2): a goal of the guide's route that is not `optional` needs a group; the guide menu shows a "Group" chip | | `names` | no | format 3: `{ ["npc:240"] = "Marshal Dughan", ... }`, the English of every name token the guide's texts hold (a token it lacks is shown as written) | | `written` | no | format 3: `{ ["Back to {npc:3649}"] = "Back to Dendrite", ... }`, a text whose names its tokens' English in `names` would spell otherwise, with the author's words an English client reads | | `steps` | yes | list of steps, at least one | Step keys: `title` (optional), `note` (optional, player-facing), `image` (optional: `{ file = "media\\cave", w = 512, h = 256 }`, the step's picture: `file` its path in the pack's addon folder without the extension, `\` between folders, `w` and `h` its size in pixels; Polestar shows it under the step's tip, and an imported guide, which has no addon folder, shows none), `only` (optional: `{ classes = { ... }, races = { ... }, factions = { ... } }`, AND across keys, OR within; Polestar also reads an entry `"!X"` as "not X", but the compiler writes positive lists only), `when` (optional, format 4: the step's conditions checked during play, below) and `goals` (at least one). Goal keys common to every verb: `t` (the verb), `text` (display text), `note`, `optional` (`true`: never blocks the step), `only` (as on a step), `map`, `x`, `y` (0 to 100, together), `z` (optional, with them: the height of the NPC or object the point stands for, below), `f` (`"e"`: the Era map frame; absent: the live frame), `r` (arrival radius in yards), `spots` (every place the goal's target spawns, below; with `map`), `group` (format 2: the goal needs a group, below). | Verb `t` | Required | Optional | |---|---|---| | `accept` | `quest`, `title` | `npc`/`npcName`, `object`/`objName`, `item`/`itemName`, `minLevel`, `qlvl`, `pre`, `preAll`, `closedBy`, `preTitles` | | `turnin` | `quest`, `title` | `npc`/`npcName`, `object`/`objName`, `rewards = { choices = { { item, itemName, quality } }, items = { ... }, xp, money }`, `direct` | | `complete` | `quest`, `title` | — | | `kill` | `target` | `title`, `npc`, `count`, `quest`, `oi`, `spread` | | `collect` | `item`, `itemName` | `title`, `count`, `quest`, `oi`, `spread`, `from`, `fromAlso`, `fromId`, `fromAlsoId`, `fromKind`, `fromRank`, `fromFaction`, `fromNpcs`, `npc`, `npcName`, `candidates` | | `goto` | `map`, `x`, `y` | `text`, `r`, `area` | | `talk` | `npc`, `npcName` | — | | `interact` | `object`, `objName` | `title`, `quest`, `oi`, `spread` | | `use` | `item`, `itemName` | `title`, `quest`, `oi` | | `sethome` | `location`, or `candidates` | `npc`, `npcName`, `area` | | `hearth` | `location` | `area` | | `getfp` | `location` | `npc`, `npcName`, `node`, `area` | | `fly` | `location` | `area` | | `train` | — | `npc`, `npcName`, `class`, `skill`, `skillLine`, `rank`, `rankMax`, `candidates` | | `buy` | `item`, `itemName` | `count`, `npc`, `npcName`, `candidates` | | `vendor` | — | `npc`, `npcName`, `candidates` | | `level` | `level` | `frac` (format 4) | | `note` | `text` | — | | `skill` | `skill`, `level` | `skillLine` | | `learn` | `spell`, `spellName` | `skillLine`, `npc`/`npcName`, `item`/`itemName`, `candidates` | | `craft` | `spell`, `spellName` | `item`/`itemName`, `count`, `untilSkill`, `skillLine`, `reagents = { { item, itemName, count } }` | | `rep` | `faction`, `factionName`, `standing` (1 to 8) | — | | `explore` | `map`, `x`, `y` | `text` | | `achieve` | `achievement`, `achievementName` | `criteria` | The fields: | Field | Value | |---|---| | `quest`, `npc`, `object`, `item`, `spell`, `faction`, `achievement` | numeric ids | | `title`, `npcName`, `objName`, `itemName`, `spellName`, `factionName`, `achievementName`, `target` | names | | `count` | number to collect, kill or buy; on `craft`, the number of items to make | | `oi` | 1-based quest objective index (`C_QuestLog.GetQuestObjectives`) | | `minLevel` | the level an `accept` needs; `qlvl` the quest's level (number or string) | | `pre` | prerequisite quest ids, any one suffices; `preAll` every one needed | | `closedBy` | quest ids that close this one once taken or done | | `preTitles` | `{ [questId] = title }` for the quests those name | | `profLine`, `profName`, `profRank` | on any goal of a quest only characters with a profession can take: its skill line id, name and the rank it needs; the goal is hidden from characters without it | | `location` | an inn, flight point or zone name as the game shows it | | `class` | `true` on `train`: the nearest trainer of the player's class | | `skill` | a profession name; `skillLine` its skill line id | | `rank`, `rankMax` | on `train`: the profession rank (1 Apprentice to 4 Artisan; Polestar also reads a rank name or a skill cap) and its skill cap (written by the compiler, not read by Polestar) | | `level` | on `level`: the level to reach; on `skill`: the skill to reach | | `frac` | on `level` (format 4): the share of the level's XP to reach, 0 < frac < 1 (above) | | `untilSkill` | on `craft`: craft until the profession reaches this skill | | `reagents` | `{ { item, itemName, count } }` | | `standing` | 1 Hated to 8 Exalted | | `criteria` | an achievement's criterion index | | `z` | the height (world z, yards) of the NPC or object the goal's `x`,`y` stands for, so the walking route ends on its floor (an Undercity quarter rather than the street above it). Polestar 0.2.4 and later pass it to the walking engine while the arrow leads to that point, and ask again without it when the route found with it fails or ends more than 30 yards above or below it. A spot (`spots`) and a smart target's candidate (`candidates`) may carry their own `z`, which Polestar 0.2.5 and later pass the same way when the arrow leads there (#180). The compiler fills it in (GUIDE_FORMAT.md, "Heights"); a hand-written pack may leave it out. Older Polestar ignores it, so it does not change the format | | `area` | the AreaTable area ID (`C_Map.GetAreaInfo`) of the place a `sethome`, `hearth`, `fly` or `getfp` location or a `goto` label names. Polestar 0.2.5 and later complete a `hearth` or `fly` when the zone or subzone text is that area's name in the client's language, accept a `sethome` bind location that reads so, count a `goto` arrived when the player goes indoors in that subzone (a cave or mine past its mouth; never for a zone), and show that name in place of the English one. The compiler fills it in (GUIDE_FORMAT.md, "Places by ID"); without it the goal matches by its English name. Older Polestar ignores it, so it does not change the format | | `node` | on `getfp`: the taxi node ID (`C_TaxiMap` `nodeID`) of its flight point. Polestar 0.2.5 and later count the goal done once the flight map lists that node as known, instead of comparing names. Filled in like `area`; older Polestar ignores it | | `spots` | spawn places `{ { x, y, z, r, n, alt } }`: centre in the goal's map and frame, its height (optional, see `z`), radius in yards, spawn count; `alt = true` for another place the target spawns, which the arrow takes only when the player moves on to it (the world map marks it) | | `spread` | `true` with `spots`: an area objective, searched spot by spot | | `from`, `fromAlso`, `fromKind`, `fromRank`, `fromFaction` | a `collect`'s main source: name, a second source of the same kind dropping it at 50% or more, `"npc"` or `"object"`, rank (1 elite, 2 rare elite, 3 boss, 4 rare), faction `"A"`, `"H"` or `"AH"` | | `fromId`, `fromAlsoId` | the ids of `from` and `fromAlso` (of kind `fromKind`): Polestar names them in the client's language (`Polestar.Names`), keeping `from`/`fromAlso` where it has no name; older Polestar ignores them | | `npc`, `npcName` | a `collect` whose guide names the NPC who hands the item over (`npc <id>`), for an item nothing drops: the target button targets them first. The farm spot a `collect … nearest` goal settles on carries the same pair | | `fromNpcs` | a `collect`'s source creatures where the goal stands: `{ { npc, npcName } }`, the one its point belongs to first, then the other likely sources there, at most 5 (GUIDE_FORMAT.md, "What the compiler fills in"). Newer Polestar gives them to the target button, named in the client's language by their ids, before the item's own droppers from the quest database, whose drop chances rank them over the whole world. Older Polestar ignores them, so it does not change the format | | `candidates` | smart targets: `{ { npc, npcName, map, x, y, z, f, faction, races, classes, lvl, rate, spawns } }` (`z` optional, see `z`); Polestar picks the nearest usable one at runtime | | `rewards` | `{ choices = { { item, itemName, quality } }, items = { ... }, xp, money }` (money in copper) | | `direct` | `true` on a `turnin`: the quest is handed in straight from the giver's window and never enters the quest log, so the goal needs no `accept` before it and carries no objectives. Polestar counts it done on the hand-in itself and stores that, so a repeatable stays done after a reload | | `escort` | `true` on the accept, `complete` and objective goals of an escort quest: the guide window says under the goal that the NPC may have to respawn (GUIDE_FORMAT.md, "Escort quests"). Older Polestar ignores it | | `group` | format 2: the goal needs a group, shown under it in the guide window: `{ kind = "elite", rank = 1 }` (rank 1 elite, 2 rare elite, 3 boss: "Elite: group advised"), `{ kind = "dungeon", name = "Dire Maul" }` ("Dungeon: Dire Maul"), `{ kind = "raid", name = "Molten Core" }` ("Raid: Molten Core"), `{ kind = "group", size = 3 }` ("Group of 3 advised"; without `size`, "Group advised"). The compiler derives it or takes the author's `group [N]` (GUIDE_FORMAT.md, "Group content"); Polestar shows nothing for a kind it does not know | Polestar 0.1.0 reads every verb above; 0.2.4 and later read the `group` keys; 0.2.4 and later read `z`; 0.2.5 and later read `area`, `node` and `direct`. ARCHITECTURE.md ("Guide data") describes when the Engine counts each goal done. ### `RegisterMapFrames(frames, packId)` ```lua Polestar.RegisterMapFrames({ era = { [1429] = { c = 0, left = 1535.417, right = -1935.417, top = -7939.583, bottom = -10254.166 }, }, }, "joe-routes") ``` The Era world bounds of every map the pack's guides place a goal or a candidate on, where the reference data has them: `c` the continent, `left`/`right` world Y, `top`/`bottom` world X. For a map Polestar already covers, Polestar's bounds win (rule 4). Call it after `RegisterPack`: the frames of a pack that is not registered are dropped. ## Import strings One compiled guide as one line of text, for a player to paste on Polestar's Import page instead of installing an addon (GUIDE_PACKS.md, "Import strings"). `polestar export <file.guide>` writes it (`tools/lib/pack/importstring.js`); `addon/Polestar/Core/Import.lua` reads it. ```text !PS1!<checksum>!<body> ``` | Part | Value | |---|---| | `!PS1!` | the string format, version 1. A later format gets another number; Polestar refuses one it does not know with "This import string needs a newer Polestar." | | `<checksum>` | the Adler-32 of the payload (the JSON below, as UTF-8 bytes), 8 hex digits | | `<body>` | the payload, compressed with zlib (RFC 1950) and written in base64 (`A`–`Z`, `a`–`z`, `0`–`9`, `+`, `/`, `=` padding) | Whitespace anywhere in a pasted string is dropped first (a chat window may wrap it). The payload is JSON: ```json { "format": 3, "license": "CC-BY-4.0", "guide": { "id": "yendi/cozy-sleeping-bag", "title": "Cozy Sleeping Bag", "...": "...", "steps": [ ... ] }, "frames": { "1429": { "c": 0, "left": 1535.417, "right": -1935.417, "top": -7939.583, "bottom": -10254.166 } } } ``` | Key | Required | Value | |---|---|---| | `format` | yes | the guide data's format (above): 4 when a step has `when`, else 3; Polestar refuses a format it does not read | | `license` | yes | the license of the guide, from the pack's `pack.json` | | `guide` | yes | one guide exactly as `RegisterGuide(def)` takes it, without `pack`: the keys above, numbers rounded as `Guides.lua` writes them, `preTitles` with the quest ids as the object's keys | | `frames` | no | `RegisterMapFrames`'s `era` table for the maps its goals use, by uiMapID. Polestar takes a frame only for a map the guide's goals or their smart targets stand on, and only where no one (Polestar, a community addon, an earlier import) has registered one | Polestar reads it as data only. The client's own decoders (`C_EncodingUtil.DecodeBase64` and `DecompressString`, the ones the walking maps use) unpack it; Polestar parses the JSON itself (objects, arrays, strings, numbers, `true`, `false`; no `null`, nested 12 deep at most) and builds the guide field by field from the keys this page lists, each with its type. A key it does not know refuses the string, naming the key ("This import string holds a field Polestar does not read (guide.steps[3].goals[1].onLoad)."). Nothing in a string is ever run: the reader never hands its text to `loadstring` or anything like it. Then the guide meets the rules above, as a community addon's would, plus: - at most 50,000 characters in the string, 256 KB of payload, 60 steps, and 4,096 bytes in any one text or key (a longer one is refused, naming it, before any text is filled in; `export` refuses it too); - its id is `<author>/<name>`, under no reserved id and no id of a community addon the player has installed (registered or only listed); - `next` and every `nextChoices` entry name one of Polestar's guides (`forever/`, `draft/`) or a guide already imported; - `Guides.Validate` passes (the message is the Community guides page's: "Guide <id> was refused: <reason>."). A refused string saves nothing. An accepted one is kept account-wide in `PolestarDB.imports[<guide id>]` as its payload, and registered at every login through the same checks under the reserved pack `imported`. A guide's `version` (a number) against the stored one's decides Import, Update (higher) or nothing (equal or lower). Imported guides are listed in the guide menu as **Imported** under Community guides, credited "By <author> · Imported · <license>", never on the Community guides page, and never suggested. ## Versioning - The format number changes when a verb, a field or a field's meaning is added or changed. Polestar ignores keys it does not know; an unknown verb refuses the guide. - Polestar keeps reading every format it has shipped, so a published pack keeps working when Polestar updates. - The compiler writes the first Polestar version that reads the pack's format into the TOC as `X-Polestar-Needs`. Format 1 is read by Polestar 0.1.0 and later, format 2 (the `group`, `reward` and `why` keys) by 0.2.4 and later, format 3 (name tokens) by 0.2.5 and later, format 4 (a step's `when`, `along` and `label`, a `level` goal's `frac`, a guide's `nextWhen`) by 0.2.6 and later. - A pack in a format this Polestar does not read registers nothing; the Community guides page shows it as `too-new` with "Needs Polestar <version> or newer." (rule 5). --- # Translating > The languages and their status, the locale file, formats, the glossary, the i18n commands, and adding or reviewing a language. Page: https://polestar.guide/docs/authors/translating (Polestar docs > Guide authors) Polestar follows the game's language: a German client reads Polestar's interface in German, and any text without a translation in English. The translation tools are adapted from the translated names database (@moust4ki), GPL-3.0. ## Languages `node tools/polestar.js i18n status` lists every language with how much of it is translated (`--markdown` prints the table for the README and release notes). The list, with each language's status and translators, is `tools/lib/i18n/locales.js`. - **reviewed**: written or checked by a native speaker. The tools never fill or rewrite its translations. German (`deDE`, thecodingcortex), Latin American Spanish (`esMX`, CDVolvik), French (`frFR`, Yendi). - **ai**: made by a machine. On that client, Options > About says so and links to the Discord. Spanish of Spain (`esES`), Korean (`koKR`), Brazilian Portuguese (`ptBR`), Russian (`ruRU`), Chinese (`zhCN`, `zhTW`). Spain's and Latin America's clients use different words for game terms (mazmorra, calabozo), so `esES` and `esMX` are separate files. English clients (`enUS`, `enGB`) read the English text. ## The file Each language has one file, `addon/Polestar/Locales/<locale>.lua`, and one for the optional Recorder's few chat lines, `addon/Polestar_Recorder/Locales/<locale>.lua`, written the same way: ```lua -- German (deDE). ... local _, ns = ... if not (GetLocale and GetLocale() == "deDE") then return end local L = ns.L -- Core/Commands.lua L["Toggle guide window"] = "Guide-Fenster ein-/ausblenden" -- L["Next step"] = "" ``` - The key, between `L[` and `]`, is the exact English text the code shows. Leave it byte for byte as it is; translate the right-hand side only. - A line starting `-- L[` is not translated yet and shows in English. To translate it, remove the `-- ` and write the translation between the quotes. - Lines are grouped under the file that first uses them (`-- Core/Commands.lua`), so you can see where a text appears. Your own comment lines and group headers stay as you wrote them. - A key `"context: text"` (`"boss: Chest"`) is one meaning of a word: translate the text after the colon, in that meaning. - The block at the end, `-- No longer in the code (its English changed or it went away): reuse or delete.`, keeps your translations of texts the code no longer has, commented out. When the English of a text changed, its new key is in the file as a `-- L[...] = ""` line: copy your old translation there, adapt it, and delete the old line. ## Formats Keep every `%s`, `%d`, `%.1f` of the key, of the same kind, in the same order. If the sentence needs another order, number them all: `"%2$s niveau %1$d"`. Keep `|4singular:plural;` (translate both forms), `|cAARRGGBB…|r` colours and `|T…|t` textures. In a text with a `%s` or `%d`, write a percent sign `%%`. ## Game terms and the glossary Where the game names something itself, Polestar shows the game's word and there is nothing to translate: reputation standings, item qualities, the Alliance and the Horde, gear slots, the Dungeon Journal. For the rest, use the game's vocabulary. `tools/lib/i18n/glossary/<locale>.json` holds about forty terms (quest, step, flight master, hearthstone, dungeon…) with the word chosen for that language: the game client's own word first, then the reviewed translators' choice. `i18n check` warns where the translation of a text holding one of those terms does not use the glossary's word. A warning is a question, not an error: fix the line, or keep your wording where it reads better. ```json "flight master": { "term": "Flugmeister", "client": "MINIMAP_TRACKING_FLIGHTMASTER" } ``` `term` is the word; `match` (optional) lists the forms that count, compared without case or accents anywhere in the translation (`["annehm", "angenommen"]`); `client` names the game's string the word comes from; `note` is any remark. The English terms are `TERMS` in `tools/lib/i18n/glossary.js`. The game's strings (Blizzard's GlobalStrings) are not in the repository: download them for your language from `https://<tables>/db2/GlobalStrings/csv?build=<build>&locale=<locale>` into `data/sources/<tables>/` (ignored by git) when you need them. ## Commands - `node tools/polestar.js i18n sync [<locale>...]` adds every text the code gained to the file, commented out at the end of its file's group, and moves translations of texts the code lost to the block at the end. It never changes a line that holds a translation. A language named that has no file gets one, loaded from `addon/Polestar/Core/Core.xml` (a new Recorder file goes in `Polestar_Recorder.toc` by hand). Without a locale it updates every existing file. It covers Polestar and the Recorder; `--addon Polestar_Recorder` (or `Polestar`) limits it, and `status`, `keys` and `import` to that one (Polestar's by default). - `node tools/polestar.js i18n check [<locale>...]` lists each language's translated and missing counts and fails on a file Lua cannot load, a stale key (a translated text the code no longer has, outside the end block), a key set twice, or a translation whose formats differ from the English. Missing translations are fine. CI runs it (`npm run i18n:check`), and `npm test` runs the same checks (`tests/i18n.test.js`). - `node tools/polestar.js i18n status` prints the table of languages. - `node tools/polestar.js i18n keys` lists every key with the files and lines that use it. - `node tools/polestar.js i18n import <locale> <file.lua>...` merges translations written elsewhere: a file that returns `{ ["English"] = "translation" }`, sets `L["English"] = "..."`, or calls `ns.AddTranslations` (the translated names database's layout). It fills only texts not translated yet, refuses a broken format, and puts texts the code lacks in the end block. - `node tools/polestar.js i18n fit [<locale>[=<file>]...]` lays out every preview scene and every Options page in English and each language, and lists the translated text the window would cut with an ellipsis or let cross its edge (`deDE=my-deDE.lua` checks a file of your own). Write your translation as long as it needs to be: the layout makes room (labels and descriptions wrap, controls size to their text), and a text this still lists is a layout bug to report, not yours to shorten. `--slack 1.15` measures about as wide as the game's own font. - `node tools/polestar.js i18n leaks [<locale>...]` runs the addon in each language and lists the English it leaves on screen, grouped by where it came from ("English left on screen" below). `--scene guide,options` runs only those scenes, `--guide <id>,...` puts other guides in the guide window, `--json` prints one document, `--update-baseline` rewrites the baseline (below). ## For developers Write every player-facing text as a literal `L["..."]` (or `ns.LC("context", "text")`) where it is used, so `i18n keys` finds it. After adding, changing or removing texts, run `node tools/polestar.js i18n sync` and commit the locale files with the change: a stale key fails `npm test`. A text looked up through a variable (`L[category]`) must be listed in `DATA_KEYS` in `tools/lib/i18n/keys.js` (the Dungeons attunement notes are read from `tools/lib/codex/attunements.json` there); a generator writes its prose as literal keys (`talents build`: the plan notes in `Talents/Builds.lua`). Data that names a game thing carries its id, never its English name alone, so the display can ask `Polestar.Names` for it. A game term the client names (`ITEM_QUALITY3_DESC`, `FACTION_HORDE`…) is read from the client, not put in `L`, and its English value goes in `tests/lua/wow_stub.lua`. Tests that need a translated client fake a language Polestar does not ship: `fakeLocale('itIT', { ... })` (`tests/helpers/locale.js`). ## English left on screen `node tools/polestar.js i18n leaks` checks that nothing English reaches the screen on a client in another language, so a new feature cannot add English unnoticed. It runs the addon on the client stub (`tests/lua`) in each language with the shipped translations, names addon and guide texts, and has the client answer in "its language": every name the client itself gives (quest titles, item, zone, map, area, spell, faction, class and race names, the player's name) comes back as a placeholder holding no word. Scenes then drive the windows: the guide window step by step with every tooltip, all guides (both with every step shown, whatever class, race or faction it is for), the welcome, the picker, Options, Lookup, Dungeons, Rares, talents, the journey planner, Polestar's tooltip lines, every slash command, the world map and alerts, and the Recorder. Every text the addons put up is recorded (font strings and buttons, tooltips, chat, popups, menus) with its scene and the line that set it. A word of three or more Latin letters is English left on screen unless it is the language's own or `tools/lib/i18n/leaks-allow.json` allows it: - **The language's own words.** Russian, Korean and Chinese have none in Latin letters. German, Spanish, French and Portuguese learn the words of their real translations (interface strings and guide texts), after cutting what is the same in every language (products, slash commands and their arguments, tokens, formats): a translation that equals its English, or copies most of it, teaches nothing. - **Names the client gave.** Every name `Polestar.Names` returned in the run is the client's, in whole and by its words. - **The allow list**: product and people's names (Polestar, Discord, TomTom, the font credits...), terms every client shows in English (XP, PvP, Shift, Ctrl+C), patterns for links, files, versions, slash commands with their documented arguments (`slashArguments` and every registered command; the prose after one is checked), guide ids and format directives, and per language the names and words it writes as English does (Uldaman; German Navigation). What a scene types (a search, a command's arguments) does not count where a text repeats it. Each finding names its source: - **interface string not translated**: a key the language's file leaves empty (`i18n sync`, then translate it); - **guide text not translated**: a guide text its texts file leaves empty (`i18n guides sync`); - **name missing from the names pack**: `Polestar.Names` was asked and had no name, so the guide's English showed (`i18n names`); - **English name, Polestar.Names not asked**: the code shows a name from a guide or the data without asking `Polestar.Names` for it by its id; - **English a translation keeps**: the words are ones a translation of the language writes as in English (a Forever-only place such as Hyjal Summit); - **English in the code**: a literal or a data text that does not go through `L`. `tools/lib/i18n/leaks-baseline.json` lists, per language, what cannot be fixed in Polestar yet, each with a reason and the scenes it shows in: names as `"kind:id"` (`no-source`: no source of `i18n names` has it, mostly Forever's own NPCs, objects and items, which the client shows once the player has seen them; `same-as-english`: every source names it as in English, which `i18n names` records in `data/local/names-same-as-english.json` for the baseline), and texts as `"text:<the text>"` whose English a translation keeps (`kept-english`). A text whose only English is such is no finding. It fails (exit 1) on any finding, on a scene that stops with an error, and on a baseline entry that no longer shows in English in scenes that all ran (so the file only shrinks: remove the entry, or run with `--update-baseline`, which also adds the names and kept texts a new guide leaves in English, and never takes English from the code or an untranslated string or guide text). `npm test` runs a part of it (`tests/i18n-leaks.test.js`: Russian and Simplified Chinese; the guide window on three guides, Options, the picker, and Lookup, Dungeons and Rares where the Codex and quest database are built), and plants English to show the check finds it: an interface string "translated" as its English, English the code writes out, dropped guide texts (a paladin's among them) and prose after a slash command. Every scene needs the Codex and the quest database built (`codex build`, `questdb build`): without them the addon is an incomplete install with its own warnings, so the scenes skip, as on CI; run `i18n leaks` before a pull request that changes what the addon shows. A text that is right to show in Latin letters goes on the allow list with the reason in its group, never to make a finding go away. Developer output stays English on purpose: the guide lines `/polestar where` prints and the details block of a bug report, both read by maintainers, are on the allow list. ## Game names Names of quests, NPCs, objects, items, instances, dungeon encounters, factions and flight points are not translated by hand: they are the game's own. A client in another language reads them from the client where it has them (quest titles, item names) and from Polestar's names addon of its language, `Polestar_Names_<locale>`, loaded only on that client. A name no source has stays English. The client is the truth: a name it shows in play (an NPC targeted, moused over or talked to, a quest-giving object opened) is kept, per language, and shown from then on. docs/ARCHITECTURE.md, "Names", has the details. - `node tools/polestar.js i18n names [<locale>...]` rebuilds the addons. Per id the first source with a name wins: the client's own tables in that language (the game-table export), the Forever web database in that language (what is cached under `data/sources/<web-db>/names`), the community names database (cloned into `data/sources/<names-db>` at the commit pinned in `tools/lib/i18n/names.js`, every file checked against its sha256) and the Era quest database's `db/<locale>` (the clone `data build` uses). It keeps only the ids the compiled guides, the quest database (`questdb build`, or `--questdb <dir>`), the Codex's data (`codex build`, or `--codex <dir>`) and the travel data name. A name equal to the English one is not stored (a later source's translation wins), nor is one marking unused content (`[PH]`, `(DNT)`...). The client tables come from the newest build that has them all in English and every language; without one the build stops (`--no-tables` leaves them out on purpose). The web database names are read from the cache in `data/sources/<web-db>/names/`, and without it that source is empty. `--offline` reads only the caches, `--no-<quest-db>` leaves the community names database out. It prints, per language, how many ids of each kind have no name. Commit the folders it writes. - A wrong name is fixed at its source: in the client (it changes there), in the community names database (tell Yendi, then move the pin to his new commit and rebuild) or, for one only the Era quest database has, in the Era quest database. - To move the pin, read what changed in Ding's `Ding/DB/`, then set the commit, version and sha256s of `DING` in `tools/lib/i18n/names.js`; a file that differs from its pin stops the build. - A new language needs its the web database path (`LOCALE_PATHS` in `tools/lib/codex/<web-db>.js`, for the cache and the packs' credit), a the community names database file and `DING` pin if Ding has it, its AddOns-list text (`tools/lib/i18n/toc.js`) and the folder's entry in the release list (`tools/lib/dsl/project.js` takes every locale of `locales.js`). ## The AddOns list The game's AddOns list shows each addon's title and notes in the client's language from its TOC's `## Title-<locale>` and `## Notes-<locale>`. Every Polestar addon's are written once in `tools/lib/i18n/toc.js` (Polestar and Codex stay as they are); the generated TOCs take them from there, the hand-written ones (Polestar, Polestar_Nav, Polestar_ItemDB, Polestar_Recorder) carry the same lines, and `tests/i18n-toc.test.js` checks that every TOC under `addon/` has all nine and that they match. ## Guide texts A guide's own words (its title, why and route-choice lines, each step's title and tip, each goal's note and label) are translated per pack, in the pack's `locales/` folder: `guides/locales/<locale>/` for Polestar's own, one file per guide at the guide's path (`forever/alliance/02-westfall.lua`), plus `_pack.lua` for the pack's own texts (its title and notes, its guides' menu folders). A file returns the English of each text with its translation: ```lua return { -- Step 1: Sentinel Hill -- {npc:234} Gryan Stoutmantle · {npc:821} Captain Danuvin ["{npc:234} and {npc:821} stand at the top of the stone tower."] = "{npc:234} und {npc:821} stehen oben auf dem Steinturm.", ["Fill the vial at the well"] = "", } ``` - **Names are not translated.** The compiler writes the game's names inside a text as tokens, `{npc:234}` (kinds: npc, object, item, quest, zone, area, spell, faction, skill), and the game shows each in the client's language. The comment above the line lists them with their English. Keep every token of the English, as many times, wherever the sentence needs it; add none. A text that is only names (a step titled after its NPC) has no line. - A token marked `(no name in this language: may be words)` is an object no source names in your language (a district's sign, a tavern): the game would show it in English. Write its name in your words instead; `i18n guides check` accepts the translation without that token. - A name the text uses in the English plural stays words ("Harvest Watchers"): the comment `-- plural, as words: Harvest Watchers = {npc:115} Harvest Watcher` gives its NPC. Translate the plural yourself from the game's singular name (Polestar_Names_<locale>, `i18n names`), or, where the game has no name for it in your language, write the singular's token in the translation: `"Bandidos ({npc:251918})"`, `"{npc:251918} ×8"`. A token of that line is allowed though the English has none. - `""` is not translated yet: the English shows. Keep the key byte for byte. - Keep the line breaks (`\n`) of the English. - `-- No longer in the guide (its English changed or it went away)` heads the translations whose English the guide lost, commented out; `i18n guides check` names the new English of a changed one where it can tell. Copy the translation to the new line, adapt it, and delete the old one. - The files are written whole by sync: comments you add are rewritten. The compiler puts each language's translations into the pack's texts addon for it, `<pack folder>_<locale>` (`Polestar_Guides_deDE`), which only that client loads, on demand (docs/PACK_FORMAT.md, "Texts addons"). Commit the locale files and the texts addons `compile` writes. - `node tools/polestar.js i18n guides sync [<locale>...]` writes every guide's file and `_pack.lua` for each language named (without one: each the pack has a folder for): every text in reading order, the translations kept, the lost ones moved to the end. `--pack <dir>` names another pack. - `node tools/polestar.js i18n guides check [<locale>...]` fails on a file Lua cannot load, a translation that leaves out or adds a token or a line break, a stale translation, or a file no guide has. `lint` and `compile` warn about the same, and leave a broken translation out (the English shows). - `node tools/polestar.js i18n guides stats` sizes the work: the texts that need words, with their words and characters, in all and per guide folder, and how many names the compiler made tokens. ## Adding a language Add it to `LOCALES` in `tools/lib/i18n/locales.js` with its status and translators (and to `ns.AI_LOCALES` in `addon/Polestar/Core/Init.lua` when its status is `ai`), then run `node tools/polestar.js i18n sync <locale>`. ## Reviewing an AI-made language Play with it, correct what reads wrong, and open a pull request that also sets its `status` to `"reviewed"` with your name in `translators` (`tools/lib/i18n/locales.js`) and removes it from `ns.AI_LOCALES` (`addon/Polestar/Core/Init.lua`). --- # Writing guides with an AI agent > The polestar-guide-pack skill: the ground rules and workflow an AI agent follows to write, fix and build a pack's guides. Page: https://polestar.guide/docs/authors/agent-workflow (Polestar docs > Guide authors) A community addon is built from a pack: a folder with a `pack.json` and `.guide` text files. Polestar's tools check the guides against the game's data, play them to the end without the game, and build the addon. The `polestar` command comes from a Polestar clone (`npm link` in it); without it, run `node <polestar clone>/tools/polestar.js <command>` instead. Run every command from the pack's folder. The guide format, every line of it: [references/guide-format.md](https://github.com/fitzforge/polestar/blob/next/skills/polestar-guide-pack/references/guide-format.md). Read it before writing a guide. ## Ground rules - **An id or a coordinate is a guess until `find`, `lint` and `playtest` confirm it.** Look up every quest, NPC, object and item id, every inn and flight point name and every guide id with `polestar find` before you write it. Never write one from memory: ids in this game differ from other versions of it. When `find` has no match, say so to the author instead of inventing a value. - **Leave out what the data fills in.** `accept 7` is enough: the compiler adds the title, the quest giver and the coordinates. Type coordinates only for `goto` and `explore`, or for a place the data does not know. - **Routes a player can do alone.** A leveling guide never requires an elite, a dungeon or a group quest: lint stops required elite work. Group content goes in as an `optional` goal with the tip `<Name> is elite: grouping up is advised.` - **The author's own material only.** Write from the author's notes, routes they played (`polestar record`) or guides they wrote. Never copy text, step lists or routes from guides you did not write, Polestar's own guides included: hand over to them with `next` instead. - **Pack naming.** `pack.json`'s `title` is the pack's own name (`Joe's Routes`), one that cannot be taken for Polestar's own addons. The build titles the addon "Polestar Community: Joe's Routes" and groups it under Polestar in the game's AddOns list; the addon page should say the same: a community addon for Polestar, by its author. Every guide id starts with the pack id and a slash (`joe-routes/westfall`). ## Workflow 1. **Start the pack** (skip when `pack.json` exists). The folder must be empty or missing: ```sh polestar new joe-routes --id joe-routes --title "Joe's Routes" --author Joe --yes cd joe-routes ``` It writes `pack.json`, `guides/example.guide` (a guide that lints and plays: replace it), README, LICENSE and editor and CI files. `polestar doctor` checks Node, Lua and the reference data when a command fails for want of them. 2. **Look up every id and place**, as JSON: ```sh polestar find "Kobold Camp Cleanup" --kind quest --json # the quest, its giver, turn-in and objectives polestar find 7 --kind quest --json # a quest by id polestar find "Kobold Vermin" --kind npc --json # an NPC or mob polestar find --kind inn --faction Alliance # names sethome and hearth take polestar find --kind flight --faction Alliance # names getfp and fly take polestar find westfall --kind guide --race Human # Polestar guides to hand over to with next ``` A number matches every kind with that id (`find 783` prints quest 783, NPC 783 and item 783): add `--kind`. Each result's `line` is a guide line ready to paste. A quest's `objectives` list each objective's `index` (the `n` of `quest <id>.<n>`, numbered as the quest log lists them) and the `id` of the mob, item or object it needs: use that id in the `kill`, `collect` or `interact`, not one found by name (a name search for "Mottled Boar" also returns Dire and Elder Mottled Boars). 3. **Write the guide** in `guides/<name>.guide` with the ids found. Keep a step to one place or one batch of work. A step is done when every goal in it that is not `optional` is. 4. **Lint until it reports no errors and no warnings:** ```sh polestar lint --format json ``` Each diagnostic has `file`, `line`, `severity`, `message` and often a `hint` saying how to fix it. `"ok": true` only means no errors: a wrong objective number (`quest 788.2` for a quest with one objective) is a warning, and playtest still passes. Fix every warning too, or tell the author why one stays (new Forever content the data does not know yet). Aim for `"errors": 0, "warnings": 0`; run lint again after every change. 5. **Playtest until every guide plays to the end:** ```sh polestar playtest polestar playtest --filter westfall --class Mage # one guide, one class ``` Every line must read `ok`. A `stuck ... at step N` line names the goal the simulated character could not finish: a wrong id, an objective number, a goal for a quest it never got, a place it cannot reach. Fix it and run lint and playtest again. 6. **Try it and build it.** `polestar play` opens the real addon in a browser with the pack loaded; `polestar install` copies the pack into the game, and `polestar dev` rebuilds it there on every save. When lint and playtest pass: ```sh polestar pack # writes dist/<folder>-<version>.zip ``` Raise `version` in `pack.json` for each release. **One small guide** (a quest chain, an item, a mount, an errand; at most 60 steps) can go out as an import string instead, a line players paste on Polestar's Import page (`/polestar import`) with nothing to install: ```sh polestar export guides/cozy-sleeping-bag.guide > cozy.txt ``` `export` lints the pack first and refuses a guide with errors; the string carries the guide and the pack's `license`. Raise the guide's own `version` header with each new string: it decides Import or Update in the game. A `next` must lead to one of Polestar's guides or to a guide the player imports first. A route or a set of guides stays a community addon (`polestar pack`). ## Example A short guide, every id from `polestar find`, that lints clean and plays to the end (write your pack id in place of `joe-routes`): ``` guide joe-routes/northshire title Northshire Valley faction Alliance race Human levels 1-4 zone Elwynn Forest step Deputy Willem accept 783 -- He stands at the abbey gate turnin 783 accept 7 step Kobold camp tip Pull one kobold at a time. kill 6 x10 quest 7.1 step Back to the abbey turnin 7 ``` `quest 7.1` ties the kills to the quest's first objective, so the guide window counts them from the quest log. A `kill` without it is a check-off the player ticks by hand. ## When something is unclear - `polestar help <command>` lists every option of a command. - Polestar's docs in the clone: `docs/GUIDE_PACKS.md` (what a pack is and how to publish one), `docs/GUIDE_FORMAT.md` (the full format and every lint check), `docs/GUIDE_CHEATSHEET.md` (every line on one page), `docs/PACKS.md` (the pack handbook, with every lint message and its fix) and `docs/PACK_FORMAT.md` (pack.json and the built addon). --- # Slash commands > Every /polestar command and its help line, from the addon’s command registry. Page: https://polestar.guide/docs/reference/commands (Polestar docs > Reference) Polestar's slash commands, as the addon registers them, with the help line `/polestar help` prints for each. `/pole` works wherever `/polestar` does, and `/polestar` on its own shows or hides the guide window. With the gamepad interface on, the game's chat box cannot run addon commands safely, so Polestar registers none: the key bindings and the minimap button open everything instead. ## /polestar | Command | What it does | Defined in | |---|---|---| | `/polestar` | Show or hide the guide window | | | `/polestar help` | List every command in chat | | | `/polestar import` | Open the Import page; import clear / import delete <id>: remove imports | [Core/Import.lua:648](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Import.lua#L648) | | `/polestar show` | Show the guide window | [Core/Commands.lua:46](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L46) | | `/polestar hide` | Hide the guide window | [Core/Commands.lua:47](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L47) | | `/polestar guides` | Choose a guide | [Core/Commands.lua:48](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L48) | | `/polestar options` | Open settings | [Core/Commands.lua:49](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L49) | | `/polestar debug` | Toggle debug output | [Core/Commands.lua:50](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L50) | | `/polestar next` | Look at the next step (skips nothing) | [Core/Commands.lua:55](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L55) | | `/polestar prev` | Look at the step before | [Core/Commands.lua:59](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L59) | | `/polestar skip` | Skip the step shown, for good (the window offers the undo) | [Core/Commands.lua:63](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L63) | | `/polestar reset` | Clear ticks and skips for the current guide | [Core/Commands.lua:67](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L67) | | `/polestar guide` | Switch to a guide by id | [Core/Commands.lua:73](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L73) | | `/polestar status` | Show the current guide and step | [Core/Commands.lua:90](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L90) | | `/polestar tabs` | List the open guide tabs | [Core/Commands.lua:113](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L113) | | `/polestar tab` | Switch to guide tab <n> | [Core/Commands.lua:127](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L127) | | `/polestar close` | Close the current guide tab | [Core/Commands.lua:137](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L137) | | `/polestar path` | Choose (or change) where to level next | [Core/Commands.lua:146](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L146) | | `/polestar welcome` | Show the welcome again | [Core/Commands.lua:152](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L152) | | `/polestar where` | Print your map and position as guide lines | [Core/Commands.lua:159](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L159) | | `/polestar report` | Report a problem with the step on screen | [Core/Commands.lua:170](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L170) | | `/polestar discord` | The invite to the Polestar Discord | [Core/Commands.lua:171](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L171) | | `/polestar packs` | Open the Community guides page | [Core/Commands.lua:173](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L173) | | `/polestar gamepad` | Open the Gamepad page: button names and bindings | [Core/Commands.lua:174](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Core/Commands.lua#L174) | | `/polestar arrow` | Waypoint arrow: show, hide, reset | [Nav/Nav.lua:556](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Nav.lua#L556) | | `/polestar way` | Point the arrow at x y on your current map (no argument clears it) | [Nav/Nav.lua:585](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Nav.lua#L585) | | `/polestar route` | Show the travel route to the current target | [Nav/Travel.lua:2216](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Travel.lua#L2216) | | `/polestar near` | Point the arrow at the nearest trainer, class trainer, repair, reagents, vendor, innkeeper, bank, auction house, flight or stable master | [Nav/Nearby.lua:445](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Nearby.lua#L445) | | `/polestar skipleg` | Skip the travel route's current leg (a Hearthstone, teleport, flight, ride or portal: plan the rest without it; a walk or lift: mark it done) | [Nav/Prompts.lua:383](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Prompts.lua#L383) | | `/polestar questdb` | Quest database status | [Quests/Options.lua:83](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Quests/Options.lua#L83) | | `/polestar gear` | Gear advice: weights in use, or compare an item link | [Gear/Gear.lua:785](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Gear/Gear.lua#L785) | | `/polestar instances` | Instance limits, runs and lockouts (instances clear: forget them) | [Maps/Instances.lua:435](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Maps/Instances.lua#L435) | | `/polestar xp` | XP per hour, time to level and level splits | [QoL/XP.lua:351](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/QoL/XP.lua#L351) | | `/polestar mount` | Look up your target's mount | [Lookup/Spotter.lua:252](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Lookup/Spotter.lua#L252) | | `/polestar lookup` | Search guides, items, mounts, NPCs and quests | [Lookup/Spotter.lua:253](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Lookup/Spotter.lua#L253) | | `/polestar dungeons` | Dungeon quests, bosses and entrances | [Dungeons/Dungeons.lua:389](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Dungeons/Dungeons.lua#L389) | | `/polestar rares` | rares [test]: open Rares, or show a sample alert | [Rares/Rares.lua:514](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Rares/Rares.lua#L514) | | `/polestar talents` | Open your talent plan | [Talents/Talents.lua:426](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Talents/Talents.lua#L426) | ## Other commands | Command | What it does | Defined in | |---|---|---| | `/way <x> <y> [label]` | Points the arrow at a spot, for addons and players used to `/way`. Claimed only while "Let other addons set waypoints" (Options, Integrations) is on and no other addon owns `/way` | [Nav/Journey.lua](https://github.com/fitzforge/polestar/blob/next/addon/Polestar/Nav/Journey.lua) | | `/psrec <command>` (or `/polestarrec`) | The Recorder, for guide authors: `status`, `on`, `off`, `mark`, `maps`, `talents`, `legacy`, `factions`, `skills`, `clear`. On its own it prints the status | [Polestar_Recorder/Commands.lua](https://github.com/fitzforge/polestar/blob/next/addon/Polestar_Recorder/Commands.lua) | --- # Options > Every setting in the options window, page by page, with its default and what it does. Page: https://polestar.guide/docs/reference/options (Polestar docs > Reference) Every setting in Polestar's options window (`/polestar options`), page by page, with its default and what it does, read from the addon's own options registry. A page opens directly with `/polestar options <page>`. Filter below by name, key or any word of its description. ## Guide Opens with `/polestar options guide` The guide window, the arrow and its routes, and what Polestar does for you. ### Window #### What it shows | Setting | Default | What it does | |---|---|---| | **Show the window** `ui.shown` | On | Also /polestar, or the key binding. (Switch) | | **Compact mode** `ui.compact` | Off | Only the header and the current step's goals. (Switch) | | **Step tips** `ui.showNotes` | On | The author's tip under the goals, one line until clicked. (Switch) | | **Expand step tips** `ui.notesOpen` | On | Start each step with its tip in full instead of one line. (Switch) | | **Upcoming steps** `ui.upcoming` | 0 | How many steps the Up next list holds; 0 turns it off. (Slider (0 to 6)) | | **Expand Up next** `ui.upcomingOpen` | Off | Start with the upcoming steps listed instead of collapsed. (Switch) | #### Combat | Setting | Default | What it does | |---|---|---| | **In combat** `ui.combat` | Keep visible | What the window does while you fight. Choices: Keep visible, Fade out, Hide. (Choice) | #### Dungeons | Setting | Default | What it does | |---|---|---| | **In dungeons** `ui.instance` | Keep visible | What the window does in dungeons and raids. /polestar or the key binding opens it there until you leave. Choices: Keep visible, Hide. (Choice) | #### Position | Setting | Default | What it does | |---|---|---| | **Lock window** `ui.locked` | Off | Prevents moving and resizing. (Switch) | | **Lock arrow and buttons** `ui.lockHud` | Off | Stops stray drags on the arrow, the action buttons and the flight and instance timers. Shift-drag still moves them. (Switch) | | **Grow upward** `ui.growUp` | Off | Keep the bottom edge in place, so longer steps extend the window up. (Switch) | | **Bar at the bottom** `ui.barsBottom` | Off | With Grow upward, put the tabs and the step bar at the bottom edge, next to where the window is pinned. (Switch) | | **Reset position** | — | Put the guide window back in its corner. (Action) | ### Arrow & routes #### Arrow | Setting | Default | What it does | |---|---|---| | **Show arrow** `nav.arrow` | On | Points to the current goal. Its look and colours are under Appearance, Arrow. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Arrival time** `nav.arrowEta` | On | Estimated time under the distance. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Distances** `nav.distanceUnit` | Yards (the game's unit) | How the arrow, map tooltips, rares and the death helper show distances. Choices: Yards (the game's unit), Metres. (Choice) | | **Arrival sound** `nav.arrivalSound` | On | A soft chime when you reach a waypoint. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Reset arrow position** | — | Back to the top of the screen. Drag the arrow to move it. Greyed out while Shortest Path Forever guides: it does this itself. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Action) | #### Routes | Setting | Default | What it does | |---|---|---| | **Plan travel routes** `nav.travel` | On | Flights, boats and your hearthstone when they are faster. Off: the arrow points straight at the goal. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Walk real paths** `nav.navRouting` | On | The arrow follows paths on the ground around cliffs, water and walls, on Polestar's walking maps, with Shortest Path Forever's router by Cillian Berragan. Off: it points straight at each stop. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Route lines** `nav.routeLines` | On | The way to the goal on the world map and the minimap: dots where you walk, lines where you fly, sail or ride, the legs after this one fainter. Drawn as Shortest Path Forever by Cillian Berragan draws them. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Class teleports** `nav.teleports` | On | Routes may start with a Teleport spell you know (a mage's city teleports, a druid's Moonglade) when it is faster. A city teleport needs a Rune of Teleportation in your bags. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Share boat times** `nav.shareTransit` | Off | Riding a boat, zeppelin, tram or lift times it; your guild and group get those times and you get theirs, so the arrow can say when the next one leaves. (Switch) | | **Shift-click a map to go there** `nav.mapPlan` | On | Shift-click the world map or minimap and the arrow takes you there; Alt-click works over map icons. Click the spot again to clear it. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Route style** `nav.routeStyle` | Balanced | Fastest: the shortest walk, over hills and across fields. Balanced: roads that aren't much longer, and round hills. Roads: stays on roads even when they're longer; the safest way, not the quickest. Greyed out while Shortest Path Forever guides: it does this itself. Choices: Fastest, Balanced, Roads. (Choice) | | **Nearby services in map menus** `nav.nearbyMenu` | On | The world map's and minimap's tracking menus find the nearest trainer, vendor, inn, bank and more (/polestar near). (Switch) | | **Nearby services button** `nav.nearbyButton` | On | A button in the guide window's header, left of the menu, finds the nearest vendor, repair, inn, flight master or trainer and points the arrow there. (Switch) | | **Show the journey** `nav.journeySteps` | On | The route's steps in the guide window with a time for each, counting down: walks, lifts, boats and flights. Click the current step to skip it. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | #### Other waypoints | Setting | Default | What it does | |---|---|---| | **Blizzard waypoint** `nav.blizzardWaypoint` | Off | Also set the game's own map pin and tracking. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Mirror to TomTom** `nav.tomtom` | On | Adds the target as a TomTom waypoint when TomTom is loaded. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Use TomTom's arrow** `nav.useTomTomArrow` | Off | Hides Polestar's arrow in favour of TomTom's. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | #### Along the route | Setting | Default | What it does | |---|---|---| | **Travel button** `nav.castPrompt` | On | When the route says to hearth or teleport, a button under the arrow casts it. Right-click the arrow to skip a leg. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Transport alerts** `nav.alerts` | On | Before your boat, zeppelin or tram comes in: 30 seconds ahead at the dock, 20 before the next stop on board. Never for lifts or in combat. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Show a banner** `nav.alertBanner` | On | A small card near the top of the screen with a countdown. Click it to dismiss. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Play the transport's sound** `nav.alertSound` | On | The ship's bell, the zeppelin's horn or the tram, on the Master channel so you hear it with the game in the background. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Flash the taskbar icon** `nav.alertFlash` | On | The game's icon flashes while the game is in the background. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Show a sample alert** | — | See the banner and hear the boat's bell. (Action) | ### Automation #### Quests | Setting | Default | What it does | |---|---|---| | **Accept guide quests** `behavior.autoAccept` | On | Only quests in the next steps of your open guides. Hold Shift to skip. (Switch) | | **Turn in guide quests** `behavior.autoTurnin` | On | Never picks between rewards. Hold Shift to skip. (Switch) | | **Close offers the guide skips** `behavior.closeSkipped` | On | After Polestar accepts or turns in a quest, closes the quest window the NPC opens next when the guide skips its quests. Hold Shift to keep it open. (Switch) | | **Warn about missable quests** `behavior.warnClosing` | Off | Before you take a quest that closes another for good, says which in chat and leaves the accept to you. (Switch) | | **Skip grey quests** `behavior.skipGrey` | Off | Leaves out grey quests and their turn-ins, unless a later quest needs them first. (Switch) | #### Guides | Setting | Default | What it does | |---|---|---| | **Pick a guide for me** `behavior.autoSelectGuide` | On | Opens the suggested guide when no tab is open. (Switch) | | **Continue to the next guide** `behavior.autoNextGuide` | On | Loads the follow-up guide in the same tab when one finishes. (Switch) | | **Where to level next** `behavior.routeChoice` | Let me choose | Where a guide offers more than one zone to continue in (/polestar path). Choices: Let me choose, Take the recommended zone. (Choice) | | **Trainer reminders** `behavior.trainReminder` | Every 2 levels | A note in the guide window, with the nearest trainer of your class, when new skills are waiting. Choices: Every 2 levels, Every level, Off. (Choice) | | **Reset guide progress** | — | Manual check-offs and skips, current guide. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Action) | ## Appearance Opens with `/polestar options appearance` Colours, type, window frames and the arrow. Everything repaints as you change it; right-click a setting to reset it. ### Colour & type #### Accent | Setting | Default | What it does | |---|---|---| | **Accent colour** `ui.accent` | false | Click to pick your own, right-click to go back to the scheme's. (Colour) | | **Class colour** `ui.classAccent` | Off | The accent follows your class: warlock purple, shaman blue, druid orange. Picking your own accent turns this off. (Switch) | #### Background | Setting | Default | What it does | |---|---|---| | **Colour scheme** `ui.scheme` | Dusk | How deep the night runs. Dusk is the default, Night the darkest, Graphite a neutral grey; EllesmereUI takes its panel colour and accent. Choices: Dusk, Night, Graphite. (Choice) | | **Background colour** `ui.bgColor` | false | The ground of every Polestar window. Right-click to go back to the scheme's. Text always stays legible: a colour too light for it is darkened. (Colour) | | **Brightness** `ui.brightness` | 0 | Lifts or lowers every background together. Right-click to reset. (Slider (-1 to 1)) | | **Background opacity** `ui.bgOpacity` | 0.94 | The background opacity of every Polestar window: how much of the world shows through. Right-click to reset. (Slider (0 to 1)) | #### Type & motion | Setting | Default | What it does | |---|---|---| | **Font** `ui.font` | The skin's font | The skin's font (the default: the game's own, Fira Sans in Halo), the game's, Inter, Fira Sans, or EllesmereUI's. Choices: The skin's font, Game font, Inter, Fira Sans. (Choice) | | **Reduce motion** `ui.reduceMotion` | Off | No sliding or popping; fades stay short. (Switch) | ### Windows #### Frame | Setting | Default | What it does | |---|---|---| | **Skin** `ui.skin` | Polestar | Polestar's own look (the default), Halo (no frame, a soft dark veil, Fira Sans), Hearth (warm game colours), or the game's own art: WoW Forever, Blizzard and Classic. Style, compact mode and the colours you pick work in each. Choices: Polestar, Halo, Hearth, Blizzard, Classic. (Choice) | | **Window border** `ui.border` | On | The line around every Polestar window. (Switch) | | **Border colour** `ui.borderColor` | false | Click to pick your own, right-click to go back to the scheme's hairline. (Colour) | | **Accent border** `ui.borderAccent` | Off | The border takes your accent colour. Picking your own border colour turns this off. (Switch) | | **Border thickness** `ui.borderSize` | 1 | In screen pixels; a thicker border grows outward. Right-click to reset. (Slider (1 to 4)) | | **Starlit band** `ui.band` | On | The night sky with its stars across the top of every window. Off: the plain background. (Switch) | | **Window shadow** `ui.shadow` | On | The soft shadow under every window. (Switch) | #### Guide window | Setting | Default | What it does | |---|---|---| | **Style** `ui.style` | Standard | Transparent drops every background and border; text is outlined and the controls appear when you hover the window. Choices: Standard, Transparent. (Choice) | | **Window scale** `ui.scale` | 1 | (Slider (0.6 to 1.6)) | | **Width** `ui.width` | 340 | (Slider (260 to 560)) | | **Window opacity** `ui.opacity` | 1 | The whole guide window, text included. The background's own opacity is under Colour & type. (Slider (0.3 to 1)) | #### Menus | Setting | Default | What it does | |---|---|---| | **Menu scale** `ui.menuScale` | 1 | The guide menu and this window; applies when you let go. Right-click to reset. (Slider (0.7 to 1.4)) | ### Arrow #### Arrow | Setting | Default | What it does | |---|---|---| | **Arrow style** `nav.arrowStyle` | The skin's arrow | Greyed out while Shortest Path Forever guides: it does this itself. Choices: The skin's arrow, 3D, Flat, Halo, Hearth. (Choice) | | **Arrow scale** `nav.arrowScale` | 1 | Greyed out while Shortest Path Forever guides: it does this itself. (Slider (0.5 to 2)) | | **Arrow opacity** `nav.arrowAlpha` | 1 | Greyed out while Shortest Path Forever guides: it does this itself. (Slider (0.2 to 1)) | #### Colours | Setting | Default | What it does | |---|---|---| | **Arrow colour** `nav.arrowColor` | false | The arrow on its way; the target's pin on the maps and the route's stops wear it too. Right-click to go back to the accent. (Colour) | | **Arrival colour** `nav.arrowNearColor` | false | The arrow as it closes on the target, and the ring when you arrive. Right-click to go back to jade. (Colour) | ## Map Opens with `/polestar options map` What Polestar draws on the world map and the minimap. Quest, rare and travel icons start off. ### Guide & quests #### Guide | Setting | Default | What it does | |---|---|---| | **Guide pins on the world map** `nav.worldPins` | On | The arrow's target, the stops of its travel route, the step's other goals, the areas their mobs and objects spawn in, and the route lines. (Switch) | | **Guide pin on the minimap** `nav.minimapPins` | On | The arrow's target, the areas it spawns in, and the route line. (Switch) | | **Trail dots along the travel route** `nav.trailDots` | On | Moving dots from you to the target on the world map and the minimap, along the travel route, while route lines are off. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Minimap button** `maps.minimapButton` | Off | A Polestar button on the edge of the minimap. Click to show or hide the guide, right-click for settings, drag to move it. (Switch) | #### Quest markers | Setting | Default | What it does | |---|---|---| | **Available quests** `qol.availableQuests` | Off | Mark quest givers with quests you can accept now. (Switch) | | **Quests above your level** `qol.questLevelWindow` | Your level | Mark quests up to this many levels above yours. (Slider (Your level to Your level)) | | **Low-level quests** `qol.lowLevelQuests` | Off | Also mark grey quests that are far below your level. (Switch) | | **World map objectives** `qol.mapObjectives` | Off | Mark mob areas, item sources and objects for quests in your log. (Switch) | | **Objective areas** `qol.objectiveAreas` | Off | Shade the area each group of mobs or objects spreads over on the world map. (Switch) | | **Turn-ins** `qol.turnInMarkers` | Off | Mark who to return to once a quest is ready. (Switch) | | **Minimap markers** `qol.minimapObjectives` | Off | Show the same quest markers on the minimap. (Switch) | | **Highlight step quests** `qol.guideHighlight` | On | Enlarge and light up the markers of the quests in your guide's current step. (Switch) | | **Dim other quests** `qol.guideDim` | Off | While a guide runs, fade every quest marker that is not part of its current step. (Switch) | ### Rares & travel #### Rares and treasures | Setting | Default | What it does | |---|---|---| | **Rares on the world map** `rares.worldRares` | Off | Every known spawn point. Click one to see it in Rares; Shift-click for a waypoint. (Switch) | | **Treasures on the world map** `rares.worldTreasures` | Off | Every known treasure spot. (Switch) | | **Rares on the minimap** `rares.minimapRares` | Off | Loads the Codex at login. (Switch) | | **Treasures on the minimap** `rares.minimapTreasures` | Off | Loads the Codex at login. (Switch) | | **Hide rares below your level** `rares.hideGrey` | Off | Rares too low to give experience leave the map. (Switch) | #### Dungeons and travel | Setting | Default | What it does | |---|---|---| | **Dungeon entrances** `maps.dungeonPins` | Off | Marks each dungeon entrance with its level range. Click to open the dungeon's guide, or to set a waypoint when there is none; Shift-click always sets a waypoint. Needs the Codex pack. (Switch) | | **Flight masters** `maps.taxiPins` | Off | Your faction's and neutral flight masters: green when known, amber when not yet discovered. The tooltip lists destinations and flight times. (Switch) | | **Boats and zeppelins** `maps.dockPins` | Off | Docks, zeppelin towers and the Deeprun Tram, with where they go. (Switch) | | **Inns** `maps.innPins` | Off | Innkeepers; the one your Hearthstone is bound to is marked. (Switch) | | **Travel icons on the minimap** `maps.travelMinimap` | Off | Shows the flight masters, docks and inns turned on here on the minimap as well. (Switch) | ### Zones #### Zones | Setting | Default | What it does | |---|---|---| | **Unexplored areas** `maps.reveal` | Revealed and tinted | Shows the parts of each zone you have not explored yet, so the whole map is there before you visit. Tinted keeps them apart from where you have been. Choices: Hidden, Revealed, Revealed and tinted. (Choice) | | **Zone level ranges** `maps.zoneLevels` | On | Shows each zone's level range on the continent and zone maps, coloured by difficulty for your level. (Switch) | #### Coordinates | Setting | Default | What it does | |---|---|---| | **Coordinates** `maps.coords` | On | Shows your position and the cursor's position under the world map. (Switch) | | **Coordinates on the minimap** `maps.minimapCoords` | Off | A small readout of your position at the bottom of the minimap. (Switch) | ## Questing Opens with `/polestar options questing` Quest information, rewards and gear advice, and the quest buttons. ### Quests #### Quest database | Setting | Default | What it does | |---|---|---| | **Quest database** `qol.questDB` | On | Quest, NPC and item data for markers and tooltips, loaded when one of them is on (about 5 MB of memory). (Switch) | #### Tooltips and quest log | Setting | Default | What it does | |---|---|---| | **Quest tooltips** `qol.questTooltips` | On | Name the quests a mob, item or object is for, with your progress. (Switch) | | **Nameplate icons** `qol.nameplateIcons` | Off | Show a quest icon and your progress, like 3/10, on nameplates of mobs you still need. (Switch) | | **Quest levels** `qol.questLevels` | On | Show quest levels, like [12], wherever the game lists quests without them. (Switch) | #### Faster questing | Setting | Default | What it does | |---|---|---| | **Instant quest text** `qol.instantQuestText` | On | Shows quest text at once instead of fading it in (Forever's own option). (Switch) | | **Skip single-option gossip** `qol.skipGossip` | On | Picks the only option of NPCs without quests. Hold Shift to read it. (Switch) | | **Faster auto-loot** `qol.fastLoot` | On | Takes the whole corpse at once when auto-loot is on. (Switch) | | **Hide combat errors** `qol.hideErrors` | Off | Hides "Not enough rage", "Out of range" and cooldown messages. Other errors still show. (Switch) | #### Party | Setting | Default | What it does | |---|---|---| | **Share my quest progress with my party** `party.share` | Off | Party members who run Polestar see your counts under their quest goals. Nothing goes to chat. (Switch) | | **Show my party's progress in the guide** `party.show` | Off | Their counts under your quest goals, and who lacks a quest you took. (Switch) | ### Rewards & gear #### Quest rewards | Setting | Default | What it does | |---|---|---| | **Mark quest rewards** `qol.rewardHighlight` | On | On the reward choices, a green arrow marks each upgrade for your spec (with Gear advice on), a thin frame in your accent colour the one to take, and a coin the one that sells for most. (Switch) | | **Take the best reward** `qol.rewardAutoPick` | Off | Chooses that reward for you when you complete the quest. Hold Shift to choose yourself. (Switch) | | **Wear reward upgrades** `qol.rewardEquip` | Off | Puts on what a turn-in gives when it is an upgrade for your spec (with Gear advice on), once it reaches your bags and you are out of combat. Hold Shift at the turn-in to skip. (Switch) | #### Gear advice | Setting | Default | What it does | |---|---|---| | **Gear advice** `gear.enabled` | On | Score items for your class and talents and point out upgrades. (Switch) | | **Stat weights** `gear.spec.PALADIN` | Automatic (talents) | Which levelling weights score your items. Automatic follows the talent tree with the most points. Choices: Automatic (talents), Holy (healer), Protection (tank), Retribution. (Choice) | | **Tooltip comparison** `gear.tooltip` | On | Show on item tooltips how much better or worse an item is than what you wear. (Switch) | | **Upgrade arrows in bags** `gear.bagArrows` | On | A green arrow on each item in your bags that is an upgrade for your spec, in the game's bags and in Baganator. (Switch) | | **Reward pick in the guide** `gear.rewards` | On | Under a turn-in step, name the reward to take: an upgrade with its gain, else the best one you can use. The marks on the game's reward panel are under Quest rewards. (Switch) | | **Reward pick on tooltips** `gear.pickTooltip` | On | On a quest reward's tooltip, say whether it is the upgrade to take. (Switch) | #### Comparison | Setting | Default | What it does | |---|---|---| | **Upgrade threshold** `gear.minUpgrade` | 1.0% | Smaller gains than this are not called upgrades. (Slider (0.0% to 10.0%)) | | **Pair with bag items** `gear.useBags` | On | Against a worn two-hander, weigh a one-hander together with the best off-hand piece in your bags. (Switch) | ### Talents #### Talent plan | Setting | Default | What it does | |---|---|---| | **Talent plans** `talents.enabled` | On | Follow a talent plan for your class and spec (/pole talents). (Switch) | | **Mark the talent frame** `talents.overlay` | On | A ring on the next talent in your plan and a flag on points the plan does not spend. (Switch) | | **Pick numbers** `talents.badges` | On | Where each talent comes in your plan's order (#1, #2, ...). (Switch) | | **Plan in tooltips** `talents.tooltip` | On | A line in each talent's tooltip: where it comes in the plan, or that it is off the plan. (Switch) | | **Remind me of unspent points** `talents.reminder` | On | A chat line naming the plan's next talent when a point is waiting. (Switch) | ### Buttons #### Action buttons | Setting | Default | What it does | |---|---|---| | **Quest item button** `qol.itemButton` | On | A button for the current step's quest item, with count, cooldown and range. Bind it under Key Bindings > AddOns. (Switch) | | **Target button** `qol.targetButton` | On | Targets the current step's mobs by name; each click moves to the next name. Bindable. (Switch) | | **Rare button** `qol.rareButton` | On | Shows a button that targets a rare Polestar spotted nearby, until it dies or is out of sight. Bindable. (Switch) | | **Hearthstone button** `qol.hearthButton` | On | Shows your Hearthstone while the guide says to hearth. Bindable. (Switch) | | **Mark what they target** `qol.markTarget` | Off | The target button and the step key put a raid icon on the mob and the NPC they target; out of combat, a press that finds neither clears your target. Your party sees the icons; in a raid only the leader and assistants can set them. (Switch) | | **Icon on mobs** `qol.markMob` | \|TInterface\TargetingFrame\UI-RaidTargetingIcon_8:0\|t 8 | A new one each press skips the NPCs' icon and leaves a mob that has one as it is. Choices: \|TInterface\TargetingFrame\UI-RaidTargetingIcon_1:0\|t 1, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_2:0\|t 2, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_3:0\|t 3, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_4:0\|t 4, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_5:0\|t 5, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_6:0\|t 6, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_7:0\|t 7, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_8:0\|t 8, A new one each press. (Choice) | | **Icon on NPCs** `qol.markNpc` | \|TInterface\TargetingFrame\UI-RaidTargetingIcon_1:0\|t 1 | A new one each press, so the last few NPCs keep theirs. Every press counts, even one that marks nothing. Choices: \|TInterface\TargetingFrame\UI-RaidTargetingIcon_1:0\|t 1, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_2:0\|t 2, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_3:0\|t 3, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_4:0\|t 4, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_5:0\|t 5, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_6:0\|t 6, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_7:0\|t 7, \|TInterface\TargetingFrame\UI-RaidTargetingIcon_8:0\|t 8, A new one each press. (Choice) | | **Button size** `qol.buttonScale` | 1 | Scale of the quest item, Hearthstone, target and rare buttons. Drag one to move them all. (Slider (0.6 to 1.6)) | | **Target name position** `qol.buttonTextSide` | Right | Where the target's name shows around the target button: right, left, above or below. Choices: Right, Left, Above, Below. (Choice) | | **Reset button positions** | — | Put the buttons back in their default spot. (Action) | ## Discovery Opens with `/polestar options discovery` Lookup, the dungeon journal and rares: finding things in the world. ### Lookup #### How to get anything | Setting | Default | What it does | |---|---|---| | **Lookup** `lookup.enabled` | On | Search every item, mount, pet, NPC and quest, and see where it comes from (/pole lookup). (Switch) | | **Sources on item tooltips** `lookup.tooltip` | On | The best one or two places to get an item, ranked for this character. (Switch) | | **Alt-click an item for a guide** `lookup.altClick` | On | Alt-click an item link, bag item or loot to open a guide that gets it. (Switch) | | **Spot other players' mounts** `lookup.mounts` | On | Name the mount of a player you target or point at, and where it comes from (/pole mount). (Switch) | ### Dungeons #### Dungeon Journal | Setting | Default | What it does | |---|---|---| | **Dungeons** `dungeons.enabled` | On | A page per dungeon and raid: every quest with where to get it, its chain and rewards, the bosses and the entrance. (Switch) | ### Rares #### When a rare shows up | Setting | Default | What it does | |---|---|---| | **Rares** `rares.enabled` | On | Watch for rare NPCs and treasures and keep when you last met them (/pole rares). Their map pins are under Map, off by default. (Switch) | | **Alert for rares** `rares.alerts` | On | A card with its name, level and distance, and a waypoint to it. (Switch) | | **Alert for treasures** `rares.treasureAlerts` | On | Treasures the client marks on the minimap. (Switch) | | **Once per rare every** `rares.cooldown` | 10 | The same rare stays quiet this long after an alert. (Slider (1 to 60)) | | **Alert stays for** `rares.toastSeconds` | 20 | Hovering the alert holds it. (Slider (5 to 60)) | | **Alert during combat** `rares.combatAlerts` | Off | Off: an alert waits for the fight to end, if the rare was seen in the last minute. (Switch) | | **Play a sound** `rares.sound` | On | One sound with each alert. (Switch) | | **Sound** `rares.soundKit` | Raid warning | Played through the Master channel. Choices: Raid warning, Ready check, Boss whisper. (Choice) | | **Show a sample alert** | — | See where the alert sits; drag it to move it. (Action) | #### How rares are noticed | Setting | Default | What it does | |---|---|---| | **Minimap markers** `rares.vignettes` | On | Rares and treasures the client marks on the minimap (vignettes), with their exact distance. (Switch) | | **Nameplates** `rares.nameplates` | On | A rare's nameplate coming into view. Needs enemy nameplates on. (Switch) | | **Your target** `rares.target` | On | Targeting a rare. (Switch) | | **Under the cursor** `rares.mouseover` | On | Pointing at a rare in the world. (Switch) | #### History | Setting | Default | What it does | |---|---|---| | **Forget rares met on this realm** | — | Clears the Seen list, alert cooldowns and the glow on recently seen pins. (Action) | ## Quality of Life Opens with `/polestar options qualityoflife` Small conveniences: travel, invitations, merchants and trackers. ### Travel #### Flight masters | Setting | Default | What it does | |---|---|---| | **Open the flight map** `qol.flightAutoOpen` | On | Talking to a flight master opens the map directly. Hold Shift for the gossip. (Switch) | | **Mark the route's destination** `qol.flightHighlight` | On | Marks where the travel route flies next on the flight map. You still choose the flight. (Switch) | #### Hearthstone | Setting | Default | What it does | |---|---|---| | **Set your home at the guide's inn** `qol.autoBind` | Off | When the step sets your home and you talk to its innkeeper, binds your Hearthstone there. Never at another inn. Hold Shift to skip. (Switch) | #### Flight timer | Setting | Default | What it does | |---|---|---| | **Flight timer** `maps.flightTimer` | On | While flying, shows the destination and the time left. Learns each route's real duration for this character; drag to move. (Switch) | | **Forget learned flight times** | — | Clears this character's recorded flight durations; estimates are used until they are flown again. (Action) | #### Death | Setting | Default | What it does | |---|---|---| | **Corpse or Spirit Healer** `qol.deathHelper` | On | As a ghost, points the arrow at the faster way back: your corpse or the nearest Spirit Healer. (Switch) | | **Release in battlegrounds** `qol.autoReleasePvP` | Off | Releases your spirit at once when you die in a battleground, unless you can resurrect yourself or someone offers to. Hold Shift to stay. (Switch) | ### Social #### Requests | Setting | Default | What it does | |---|---|---| | **Accept summons** `qol.acceptSummon` | Off | Takes a summon at once, unless you are in combat. Hold Shift to decide yourself. (Switch) | | **Accept resurrections** `qol.acceptResurrect` | Off | Takes a resurrection as soon as it can, unless the caster is in combat. Never in Hardcore. Hold Shift to decide yourself. (Switch) | | **Join friends' parties** `qol.acceptPartyFriends` | Off | Accepts party invitations from friends, Battle.net friends and your guild, unless joining would leave a queue. Hold Shift to decide yourself. (Switch) | #### Blocking | Setting | Default | What it does | |---|---|---| | **Decline other party invitations** `qol.declinePartyStrangers` | Off | Declines party invitations from anyone who is not a friend or in your guild. (Switch) | | **Decline guild invitations** `qol.declineGuildInvites` | Off | Declines guild invitations, except from friends. (Switch) | | **Decline duels** `qol.declineDuels` | Off | Declines duel requests, except from friends and your guild. (Switch) | ### Vendors #### Merchants | Setting | Default | What it does | |---|---|---| | **Sell grey items** `qol.sellJunk` | On | Sells Poor-quality items when a merchant opens and prints the total. Never sells anything else. (Switch) | | **Repair** `qol.autoRepair` | On | Repairs all gear at merchants who can, when you can afford it. Hold Shift to skip. (Switch) | | **Guild bank first** `qol.repairGuild` | Off | When your guild rank may, the guild bank pays for repairs and your money covers the rest. (Switch) | | **Buy for the guide** `qol.buyGoals` | Off | When the step asks you to buy something and the merchant sells it, buys what you still need after selling and repairing. Optional buys and anything over 50g are left to you. Hold Shift to skip. (Switch) | #### Trainers | Setting | Default | What it does | |---|---|---| | **Learn new spells** `qol.trainAll` | Off | Learns every spell a class trainer offers that you can afford, and prints the total. Profession trainers are left alone. Hold Shift to skip. (Switch) | ### Trackers #### Experience | Setting | Default | What it does | |---|---|---| | **XP tracker** `qol.xpTracker` | On | XP per hour, time, kills and quests to level, and level splits (/pole xp). (Switch) | | **Guide level on the XP bar** `qol.xpTargetMark` | On | A mark at the end of the game's XP bar with the level the guide wants you to reach before it moves on, and how many levels away that is when it is more than one. (Switch) | | **Reset session** | — | Start this session's XP per hour from zero. (Action) | #### Instances | Setting | Default | What it does | |---|---|---| | **Track instances** `maps.instances` | On | Records dungeon and raid entries, time and experience per run. /pole instances lists them. (Switch) | | **Compact display** `maps.instanceDisplay` | Off | Shows the hourly instance count and the current run while it matters; drag to move. (Switch) | #### Instance limits | Setting | Default | What it does | |---|---|---| | **Instances per hour** `maps.perHour` | 5 | Classic allows 5 new instances per hour per account. Forever may differ; adjust if it does. (Slider (1 to 10)) | | **Instances per day** `maps.perDay` | 30 | Classic Era allows 30 new instances per 24 hours per account; 0 ignores the daily cap. Forever may differ. (Slider (0 to 60)) | | **Clear instance history** | — | Forgets recorded entries and runs (the server's own limit is not affected). (Action) | ## Integrations Opens with `/polestar options integrations` Settings for other addons Polestar works with, shown when they are installed. ### EllesmereUI | Setting | Default | What it does | |---|---|---| | **Match EllesmereUI accent** `ui.matchAccent` | On | Follow EllesmereUI's accent, live. Picking your own accent turns this off. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Switch) | | **Match EllesmereUI font** `ui.matchFont` | Off | Follow EllesmereUI's font, live. Choosing another font turns this off. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Switch) | ### TomTom | Setting | Default | What it does | |---|---|---| | **Let other addons set waypoints** `nav.answerTomTom` | Off | Without TomTom installed, waypoints other addons set through TomTom, and /way, point Polestar's arrow. Addons that expect TomTom's own settings may not work with it on. Greyed out while Shortest Path Forever guides: it does this itself. (Switch) | | **Follow TomTom's arrow** `nav.followTomTom` | Off | With TomTom installed, the arrow goes wherever TomTom's arrow points, routed like any goal. (Switch) | ### Shortest Path Forever | Setting | Default | What it does | |---|---|---| | **Hand guiding to Shortest Path Forever** `nav.spfHandoff` | Off | Shortest Path Forever's arrow, route and journey take you to each goal. Polestar's arrow, route lines, journey steps, travel button, transport alerts, map clicks and /way step aside; the guide window and map pins stay. Off: Polestar guides, and steps aside only while a journey you started in Shortest Path Forever runs. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Switch) | ### The community quest database | Setting | Default | What it does | |---|---|---| | **Show planned turn-ins in the community quest database** `routePlan.<quest-db>` | Off | Completed quests in the community quest database's tracker show their Polestar turn-in step. Earlier, skipped and unplanned hand-ins are flagged. Shown only when it applies (the addon it works with is installed, or a setting it depends on is on). (Switch) | ## Community guides Opens with `/polestar options guidepacks` Guides made by other players: switch them on or off, and choose where suggestions come from. This page is drawn by its own code: it shows status and actions rather than settings. ## Gamepad Opens with `/polestar options gamepad` Play Polestar with a gamepad: its windows, its buttons and your bindings. The bindings take keys too. ### Navigation #### Your gamepad | Setting | Default | What it does | |---|---|---| | **Button names** `gamepad.glyphs` | Automatic | The names and shapes Polestar shows for your gamepad's buttons. Automatic reads them off the gamepad. Choices: Automatic, Xbox (A, B, X, Y), PlayStation (shapes). (Choice) | | **Navigate Polestar's windows** `gamepad.navigate` | On | While a Polestar window is open, the D-pad moves through it, A selects, B closes, LB and RB change tabs, Y restores a default. Out of combat; the game gets every button back when the window closes. (Switch) | | **Button hints** `gamepad.hints` | On | A bar under the window says what each button does, and B sits on the close button. (Switch) | | **Use with the keyboard and mouse** `gamepad.withMouse` | Off | Off, Polestar uses the gamepad only with the game's gamepad interface (Options, Gamepad, Enable Gamepad UI). On, also with the keyboard and mouse interface, while the gamepad is turned on in the game's options and plugged in. (Switch) | ### Key bindings #### The guide | Setting | Default | What it does | |---|---|---| | **Next step** | — | (Key binding) | | **Previous step** | — | (Key binding) | | **Browse the guide with the gamepad** | — | The guide window holds the gamepad until B: the D-pad picks a line, A points the arrow there or uses the item, X shows its details, LB and RB change steps, Y minimizes the window. A window that opened by itself, such as a route choice, waits for this button before it takes the gamepad. (Key binding) | | **Toggle guide window** | — | (Key binding) | #### Windows | Setting | Default | What it does | |---|---|---| | **Open the guide menu** | — | (Key binding) | | **Open Polestar options** | — | (Key binding) | | **Report a problem** | — | (Key binding) | #### Quest buttons | Setting | Default | What it does | |---|---|---| | **Use quest item** | — | (Key binding) | | **Target quest mob** | — | (Key binding) | | **Target rare** | — | (Key binding) | | **Use Hearthstone** | — | (Key binding) | | **Use the step button** | — | Step action: NPC, quest item, mob or Hearthstone (Key binding) | | **Use the travel button** | — | Use the route's Hearthstone or teleport (Key binding) | ## Recorder Opens with `/polestar options recorder` The data recorder for guide authors. This page is drawn by its own code: it shows status and actions rather than settings. ## About Opens with `/polestar options about` Why Polestar exists, its commands and its credits. This page is drawn by its own code: it shows status and actions rather than settings. ## Settings without a control Defaults the addon keeps that no row above shows: window positions, remembered choices and values other settings derive from. Reset page in the options window clears a page; these reset with them. ### 26 saved settings | Key | Default | |---|---| | `behavior.suggestFrom` | `"guides"` | | `gear.spec.DRUID` | `"auto"` | | `gear.spec.HUNTER` | `"auto"` | | `gear.spec.MAGE` | `"auto"` | | `gear.spec.PRIEST` | `"auto"` | | `gear.spec.ROGUE` | `"auto"` | | `gear.spec.SHAMAN` | `"auto"` | | `gear.spec.WARLOCK` | `"auto"` | | `gear.spec.WARRIOR` | `"auto"` | | `maps.minimapButtonAngle` | `225` | | `maps.timerPos` | `false` | | `maps.trackerPos` | `false` | | `nav.journeyOpen` | `true` | | `nav.lineStyle` | `"dots"` | | `nav.openmapDots` | `true` | | `nav.sparkleColor` | `"gold"` | | `nav.sparkleDensity` | `5` | | `nav.sparkleFlow` | `0.5` | | `nav.sparkleIntensity` | `0.75` | | `nav.sparkleLater` | `false` | | `nav.sparkleMax` | `140` | | `nav.sparkleSize` | `14` | | `nav.sparkleSubtlety` | `0.35` | | `rares.ignored` | `false` | | `rares.toastPoint` | `false` | | `ui.pickerFaction` | `"auto"` | --- # Key bindings > Every key binding and gamepad action, and which take a chord. Page: https://polestar.guide/docs/reference/bindings (Polestar docs > Reference) Polestar's key bindings, under **Polestar** in the game's Key Bindings (AddOns), in the order the Gamepad page of Polestar's options lists them. Every action takes a key; the ones marked below also take a gamepad chord (two buttons at once) on that page. The buttons are secure clicks the game runs itself, so they take a key or a single gamepad button but not a chord. | Action | Group | Gamepad chord | Binding | |---|---|---|---| | **Next step** | Guide | Yes | `POLESTAR_NEXT` | | **Previous step** | Guide | Yes | `POLESTAR_PREV` | | **Browse the guide with the gamepad** | Guide | Yes | `POLESTAR_FOCUS` | | **Toggle guide window** | Guide | Yes | `POLESTAR_TOGGLE` | | **Open the guide menu** | Windows | Yes | `POLESTAR_MENU` | | **Open Polestar options** | Windows | Yes | `POLESTAR_OPTIONS` | | **Report a problem** | Windows | Yes | `POLESTAR_REPORT` | | **Use quest item** | Buttons | No | `CLICK PolestarQuestItemButton:LeftButton` | | **Target quest mob** | Buttons | No | `CLICK PolestarTargetButton:LeftButton` | | **Target rare** | Buttons | No | `CLICK PolestarRareButton:LeftButton` | | **Use Hearthstone** | Buttons | No | `CLICK PolestarHearthButton:LeftButton` | | **Use the step button** | Buttons | No | `CLICK PolestarStepButton:LeftButton` | | **Use the travel button** | Buttons | No | `CLICK PolestarTravelButton:LeftButton` | ## Gamepad defaults The gamepad settings as they start, before any change on the Gamepad page: | Setting | Default | |---|---| | `gamepad.glyphs` | `"auto"` | | `gamepad.hints` | `true` | | `gamepad.navigate` | `true` | | `gamepad.withMouse` | `false` | --- # Guide format reference > Every header line, step line and goal the guide compiler takes, with the modifiers each accepts. Page: https://polestar.guide/docs/reference/guide-lines (Polestar docs > Reference) Every line the guide compiler takes, read from its own tables (`tools/lib/dsl/parse.js`): the header lines, the lines inside a step, and each goal with the modifiers it accepts. The words and examples are the cheatsheet's; the [full rules](https://polestar.guide/docs/authors/guide-format) are in the guide format. Try them here: edit the guide on the left and the guide window on the right follows. ## Header lines In column 0, before the first `step`: `guide`, `title`, `levels`, `zone`, `faction`, `race`, `class`, `next`, `category`, `folder`, `keywords`, `collects`, `reward`, `why`, `author`, `version`, `coords`, `pitch`, `pro`, `con`. | Line | What it does | Example | |---|---|---| | `guide <id>` | First line: the guide's id, starting with your pack id and `/` | `guide joe-routes/goldshire` | | `title <text>` | The name players see in the guide menu | `title Goldshire to Westfall` | | `levels <min>-<max>` | The character levels the guide is for | `levels 5-10` | | `zone <Name>` | The zone the guide's coordinates are in, until a step names another | `zone Elwynn Forest` | | `zone map <uiMapID>` | The same, by map id | `zone map 1429` | | `zone <Name>` / `zone map <uiMapID>` | Inside a step: the zone for coordinates from here on, also for the steps after it (after a step with `only` that sets one, name the zone again) | `zone Elwynn Forest` | | `faction <Faction>` | Only for `Alliance` or `Horde` characters | `faction Alliance` | | `race <Race>, ...` | Only for these races (see Conditions) | `race Human, Dwarf` | | `class <Class>, ...` | Only for these classes | `class Warrior, Paladin` | | `next <id>, <id>, ...` | Several guides after this one: the player picks one, the first is your suggestion | `next joe-routes/westfall, joe-routes/redridge` | | `next <id> when <predicate>` | One guide per line, offered only while the predicate (as on a step's `when`) holds when this guide ends; `next` lines add up. One option left: Polestar goes on to it; none: the guide ends there | `next joe-routes/redridge when level>=15` | | `next <id>` | The guide that follows when this one ends: one of yours or one of Polestar's (`polestar find --kind guide <zone>` lists them with who can follow them) | `next joe-routes/westfall` | | `category <Category>` | The guide menu category: `Leveling` (default), `Class`, `Professions`, `Reputation`, `Legacy`, `Exploration`, `Collectibles`, `Miscellaneous` or `Dungeons` | `category Professions` | | `folder <text>` | The guide menu folder to list it under | `folder Mounts · Level 40` | | `keywords <word>, ...` | Extra words the guide menu search finds it by | `keywords wolf, meat` | | `collects <item>, ...` | Items the guide obtains; Lookup opens this guide for them | `collects 750` | | `reward item <item> ...` | What the guide's goal gives, shown with its icon in the guide menu; several items on one line are a choice of one; repeatable | `reward item 1251 2581` | | `reward spell <id> "Name"` | A spell the goal teaches (a mount, a form, a demon) | `reward spell 5784 "Summon Felsteed"` | | `reward text <words>` | A reward without an id | `reward text Shen'dralar reputation` | | `choose <item> ...` / `reward <item> ...` | On `turnin`: the rewards to pick from, and the ones given outright | `turnin 5261 choose 159 2589 reward 4306` | | `why <text>` | One short line in the guide menu: why the goal is worth doing (Class guides need it and `reward`) | `why Your own mount at 40.` | | `author <name>` | Credits a guide to someone other than the pack's author | `author Joe` | | `version <N>` | A whole number you raise when the guide changes (default 1) | `version 2` | | `coords era` / `coords live` | The map frame of the coordinates you type (default `era`; `record draft` writes `live`) | `coords live` | | `pitch <text>` | On a guide offered as a choice: one line on its card | `pitch Short walks between quests.` | | `pro <text>` / `con <text>` | One advantage or drawback per line, under the pitch | `pro Ends at a flight point` | ## Step lines Indented inside a step, beside its goals: `zone`, `only`, `tip`, `image`, `when`, `label`, `along`, `loop`. | Line | What it does | Example | |---|---|---| | `zone <Name>` | The zone the guide's coordinates are in, until a step names another | `zone Elwynn Forest` | | `zone map <uiMapID>` | The same, by map id | `zone map 1429` | | `zone <Name>` / `zone map <uiMapID>` | Inside a step: the zone for coordinates from here on, also for the steps after it (after a step with `only` that sets one, name the zone again) | `zone Elwynn Forest` | | `only <condition>, ...` | Inside a step: the step is only for matching characters | `only Hunter` | | `only <condition>, ...` | After a goal: the goal is only for matching characters | `kill 299 only Hunter` | | `tip <text>` | A note for the whole step, shown in the guide window | `tip Pull one kobold at a time.` | | `image <path> [<w>x<h>]` | A picture (a `.tga` or `.blp` in the pack folder) shown under the step's tip, such as a screenshot of a cave mouth | `image media/fargodeep-mine.tga` | | `when <predicate>` | Inside a step: the step is only for characters in that state when the route gets there (see Conditions checked during play) | `when level<6` | | `when level<N` (`<=`, `>`, `>=`) | the character's level compares so; N may be a point inside a level (`12.5`, `12+2500`) | `when level>=10` | | `when onquest <quest>, ...` | any of the quests is in the log | `when onquest 783` | | `when complete <quest>` | the quest is ready to turn in | `when complete 7` | | `when turnedin <quest>` | the quest is handed in | `when !turnedin 9201` | | `when available <quest>` | the quest can be taken now | `when available 9200` | | `when has <item> [xN]` | the bags hold N or more | `when !has 159 x5` | | `when zone "<Name>"` / `when subzone "<Name>"` | the player is there | `when subzone "Goldshire"` | | `when bound "<Location>"` | the hearthstone is bound there | `when !bound "Goldshire"` | | `label <name>` | Inside a step: names it for an `along until` before it | `label camp` | | `along [until <label>]` | Inside a step: the route never stops there; its goals are done along the way, listed under the next steps until done (or until the labelled step) | `along until camp` | | `loop` | Inside a step: its `goto` points are the places to search, in order, for the step's kill, collect and interact goals without `@x,y` | `loop` | ## Goals 24 verbs, each a line inside a step: [`accept`](https://polestar.guide/docs/reference/guide-lines#accept) [`turnin`](https://polestar.guide/docs/reference/guide-lines#turnin) [`complete`](https://polestar.guide/docs/reference/guide-lines#complete) [`kill`](https://polestar.guide/docs/reference/guide-lines#kill) [`collect`](https://polestar.guide/docs/reference/guide-lines#collect) [`goto`](https://polestar.guide/docs/reference/guide-lines#goto) [`talk`](https://polestar.guide/docs/reference/guide-lines#talk) [`interact`](https://polestar.guide/docs/reference/guide-lines#interact) [`use`](https://polestar.guide/docs/reference/guide-lines#use) [`sethome`](https://polestar.guide/docs/reference/guide-lines#sethome) [`hearth`](https://polestar.guide/docs/reference/guide-lines#hearth) [`getfp`](https://polestar.guide/docs/reference/guide-lines#getfp) [`fly`](https://polestar.guide/docs/reference/guide-lines#fly) [`train`](https://polestar.guide/docs/reference/guide-lines#train) [`buy`](https://polestar.guide/docs/reference/guide-lines#buy) [`vendor`](https://polestar.guide/docs/reference/guide-lines#vendor) [`level`](https://polestar.guide/docs/reference/guide-lines#level) [`note`](https://polestar.guide/docs/reference/guide-lines#note) [`skill`](https://polestar.guide/docs/reference/guide-lines#skill) [`learn`](https://polestar.guide/docs/reference/guide-lines#learn) [`craft`](https://polestar.guide/docs/reference/guide-lines#craft) [`rep`](https://polestar.guide/docs/reference/guide-lines#rep) [`explore`](https://polestar.guide/docs/reference/guide-lines#explore) [`achieve`](https://polestar.guide/docs/reference/guide-lines#achieve). ### accept | Line | What it does | Example | |---|---|---| | `accept <quest> ["Title"]` | Take a quest; the giver and title come from the data | `accept 783` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `object` `item` `lvl` ### turnin | Line | What it does | Example | |---|---|---| | `turnin <quest> ["Title"]` | Hand a quest in | `turnin 783` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `object` `reward` `choose` `xp <N>` `money <amount>` `direct` ### complete | Line | What it does | Example | |---|---|---| | `complete <quest> ["Title"]` | Finish every objective of a quest; give it a place (`@x,y`, or a `goto` before it) when its objectives have one, or the arrow has nowhere to point | `complete 7 @48.5,31.0` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` ### kill | Line | What it does | Example | |---|---|---| | `kill <npc>` / `kill "<Name>"` | Kill a mob; `quest Q.O` ties it to a quest objective | `kill 6 x10 quest 7.1` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `quest` `xN` ### collect | Line | What it does | Example | |---|---|---| | `collect <item> ["Name"]` | Gather or loot items; without `quest`, counted in the bags | `collect 750 x8` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `quest` `xN` `nearest` ### goto | Line | What it does | Example | |---|---|---| | `goto <x>,<y> ["Label"]` | Walk to a spot; checked off on arrival, when a later goal of the step is done, or, ending its step, when the next step's quest work is done | `goto 47.6,35.1 "Kobold camp"` | Takes `"text"` `optional` `only` `group [N]` `map` `r` `era/live` ### talk | Line | What it does | Example | |---|---|---| | `talk <npc>` | Speak to an NPC | `talk 197` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` ### interact | Line | What it does | Example | |---|---|---| | `interact <object>` | Click a game object | `interact 2843` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `quest` ### use | Line | What it does | Example | |---|---|---| | `use <item>` | Use an item | `use 1210 @47.6,35.1` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `quest` ### sethome | Line | What it does | Example | |---|---|---| | `sethome "<Location>"` | Bind the hearthstone at an inn, named as the game reports it | `sethome "Goldshire"` | | `sethome nearest` | Bind at the nearest inn of the player's faction | `sethome nearest` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` ### hearth | Line | What it does | Example | |---|---|---| | `hearth "<Location>"` | Use the hearthstone; done on landing there | `hearth "Goldshire"` | Takes `"text"` `optional` `only` `group [N]` ### getfp | Line | What it does | Example | |---|---|---| | `getfp "<Flight point>"` | Learn a flight path from its flight master | `getfp "Stormwind"` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` ### fly | Line | What it does | Example | |---|---|---| | `fly "<Town>"` | Take a flight; done on landing there | `fly "Stormwind"` | Takes `"text"` `optional` `only` `group [N]` ### train | Line | What it does | Example | |---|---|---| | `train class` | Visit the nearest trainer of the player's class | `train class only Warrior,Mage` | | `train <npc>` | Visit that trainer | `train 911 only Warrior,Paladin` | | `train <Profession> [Rank]` | Learn a profession or its next rank (`Apprentice`, `Journeyman`, `Expert`, `Artisan`) at the nearest trainer | `train Mining Journeyman` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` ### buy | Line | What it does | Example | |---|---|---| | `buy <item> ["Name"]` | Buy an item; `nearest` picks the closest vendor selling it | `buy 159 x5 nearest` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `xN` `nearest` ### vendor | Line | What it does | Example | |---|---|---| | `vendor nearest` / `vendor <npc>` | Sell and repair, at the closest vendor or that one | `vendor nearest` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` ### level | Line | What it does | Example | |---|---|---| | `level <N>` | Reach level N, grinding if need be | `level 2` | | `level <N>.<fraction>` / `level <N>+<XP>` | Reach a point inside level N: 12.5 is halfway through 12, 12+2500 is 2500 XP into it (to whole percent; needs Polestar 0.2.6) | `level 12.5` | Takes `"text"` `optional` `only` `group [N]` ### note | Line | What it does | Example | |---|---|---| | `note <text>` | A line of information; never holds the player up | `note The camp is busy at night.` | Takes `optional` `only` `@x,y` `map` `r` `era/live` ### skill | Line | What it does | Example | |---|---|---| | `skill <Profession> <N>` | Reach skill N (quote names of two words) | `skill "First Aid" 40` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` ### learn | Line | What it does | Example | |---|---|---| | `learn <spell> ["Name"]` | Learn a recipe; from a trainer, or with `nearest` from the closest vendor of its recipe | `learn 3276` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `npc` `item` `nearest` ### craft | Line | What it does | Example | |---|---|---| | `craft <spell> ["Name"]` | Craft a recipe, `x<N>` times | `craft 3275 x5` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `xN` `until <N>` ### rep | Line | What it does | Example | |---|---|---| | `rep <Faction> <Standing>` | Reach a standing (`Neutral` to `Exalted`) with a faction, by name or id | `rep Stormwind Friendly` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` ### explore | Line | What it does | Example | |---|---|---| | `explore <x>,<y> ["Area"]` | Discover the map area at these coordinates | `explore 41,65 "Goldshire"` | Takes `"text"` `optional` `only` `group [N]` `map` `r` `era/live` ### achieve | Line | What it does | Example | |---|---|---| | `achieve <id> "Name"` | Complete an achievement or Legacy Challenge | `achieve 9001 "Kobold Catcher"` | Takes `"text"` `optional` `only` `group [N]` `@x,y` `map` `r` `era/live` `criteria <n>` --- # Command line > Every polestar command of the toolchain, with its usage as the command prints it. Page: https://polestar.guide/docs/reference/cli (Polestar docs > Reference) Polestar's command line, the toolchain for guides, data and releases. Run a command as `node tools/polestar.js <command>` from a clone, or as `polestar <command>` after `npm link`. `--help` after any command prints its usage and runs nothing. Each entry below is that usage, as the command prints it. | Command | What it does | |---|---| | [`changelog`](https://polestar.guide/docs/reference/cli#polestar-changelog) | Changelog fragments in changes/: add, check, show, and build into CHANGELOG.md | | [`codex`](https://polestar.guide/docs/reference/cli#polestar-codex) | Build Lookup's Codex (data/forever/codex + the Polestar_Codex pack) | | [`compile`](https://polestar.guide/docs/reference/cli#polestar-compile) | Compile a pack into its community addon folder | | [`data`](https://polestar.guide/docs/reference/cli#polestar-data) | Build reference data (data/forever/*.json) from the Era quest database, the community quest database, Blizzard map tables and recordings | | [`dev`](https://polestar.guide/docs/reference/cli#polestar-dev) | Rebuild a pack into the game on every save | | [`doctor`](https://polestar.guide/docs/reference/cli#polestar-doctor) | Check Node, Lua, the reference data, the AddOns folder and pack.json | | [`draft`](https://polestar.guide/docs/reference/cli#polestar-draft) | Generate a first-draft leveling route (.guide) from the reference data | | [`dungeons`](https://polestar.guide/docs/reference/cli#polestar-dungeons) | Import DungeonJournal: dungeon data (data/forever/dungeons.json) | | [`exploration`](https://polestar.guide/docs/reference/cli#polestar-exploration) | Build or check the generated exploration guides | | [`export`](https://polestar.guide/docs/reference/cli#polestar-export) | Print the import string of one guide | | [`find`](https://polestar.guide/docs/reference/cli#polestar-find) | Look up quests, NPCs, objects, items, inns, flight points and guides as guide lines | | [`gear`](https://polestar.guide/docs/reference/cli#polestar-gear) | Build the upgrade-advice data (Forever item stats, reward choices, stat weights) from installed addons and sims | | [`i18n`](https://polestar.guide/docs/reference/cli#polestar-i18n) | interface translations (status, check, sync, keys, import, fit, leaks), guide texts (guides) and the names addons (names) | | [`install`](https://polestar.guide/docs/reference/cli#polestar-install) | Install the addons into the Forever client | | [`itemdb`](https://polestar.guide/docs/reference/cli#polestar-itemdb) | Build the Polestar_ItemDB data addon (item stats) from client tables | | [`lint`](https://polestar.guide/docs/reference/cli#polestar-lint) | Check .guide files without writing output | | [`maps`](https://polestar.guide/docs/reference/cli#polestar-maps) | Build world map data (zone level ranges, zone art overlays) | | [`media`](https://polestar.guide/docs/reference/cli#polestar-media) | Regenerate the addon textures (tools/media/*.js -> addon/Polestar/Media) | | [`nav`](https://polestar.guide/docs/reference/cli#polestar-nav) | Terrain navigation from the client geometry (build the grid, route between map points) and Polestar's walking router with its maps (Polestar_Nav) | | [`new`](https://polestar.guide/docs/reference/cli#polestar-new) | Start a pack in a new folder from the template | | [`pack`](https://polestar.guide/docs/reference/cli#polestar-pack) | Build the release zips, or a community addon's zip | | [`planner`](https://polestar.guide/docs/reference/cli#polestar-planner) | Plan routes: play a guide on the map and edit it (local page, MCP) | | [`play`](https://polestar.guide/docs/reference/cli#polestar-play) | Play with the real addon in the browser (local playground) | | [`playtest`](https://polestar.guide/docs/reference/cli#polestar-playtest) | Play a pack's guides to the end for every class | | [`preview`](https://polestar.guide/docs/reference/cli#polestar-preview) | Render the guide window, picker and options to docs/preview/*.svg | | [`profession`](https://polestar.guide/docs/reference/cli#polestar-profession) | Build professions.json; draft a crafting guide; build or check the generated gathering guides | | [`qol`](https://polestar.guide/docs/reference/cli#polestar-qol) | Build the Quality of Life module data (spirit healers, flight masters, reagent vendors) | | [`questdb`](https://polestar.guide/docs/reference/cli#polestar-questdb) | Build the load-on-demand quest database addon (markers, tooltips) | | [`readme`](https://polestar.guide/docs/reference/cli#polestar-readme) | Redraw the README's art: brand (docs/assets) and charts (docs/assets/charts) | | [`record`](https://polestar.guide/docs/reference/cli#polestar-record) | Polestar Recorder sessions: import, watch, draft guides, measure routes (report) | | [`regen`](https://polestar.guide/docs/reference/cli#polestar-regen) | Regenerate committed files after merging contributor PRs (compile + i18n sync + preview + media) | | [`release`](https://polestar.guide/docs/reference/cli#polestar-release) | Release tooling: patch scope check, patch preparation, release notes | | [`sim`](https://polestar.guide/docs/reference/cli#polestar-sim) | simulate and optimize leveling routes (docs/SIMULATION.md) | | [`talents`](https://polestar.guide/docs/reference/cli#polestar-talents) | Build or check Talents/Builds.lua (talent plans) | | [`trainers`](https://polestar.guide/docs/reference/cli#polestar-trainers) | Build trainers.json and Core/ClassTrainers.lua (class trainers) | | [`travel`](https://polestar.guide/docs/reference/cli#polestar-travel) | Build the travel network (flights, boats, inns, learned paths, zone crossings), import zone crossings, test routes and draft approach chains from recordings | | [`version`](https://polestar.guide/docs/reference/cli#polestar-version) | Show or set the release version (package.json, guides/pack.json and addon TOCs) | ## polestar changelog Changelog fragments in changes/: add, check, show, and build into CHANGELOG.md ```sh polestar changelog --help ``` ```output usage: node tools/polestar.js changelog <add|check|show|build> [options] Each change's changelog entry is its own file, changes/<slug>.md: front matter naming its section, then the entry as CHANGELOG.md writes it, a markdown list item wrapped at 78 columns (changes/README.md). add <players|authors|contributors> write a fragment for that section ("For players", "For guide authors", "For contributors"). The entry is --text or stdin; plain text becomes one list item, wrapped. The file is named --name, else the entry's first words; an existing file is never overwritten. check every fragment has a known section and an entry starting "- ", and CHANGELOG.md has no ## Unreleased section; names each fault, exit 1 show print the entries the next release gathers, as a ## Unreleased section; writes nothing build <version> add ## <version> (<date>) to CHANGELOG.md above the newest release, with each section that has entries, in order, and the entries by file name; then delete the fragments. Refuses when CHANGELOG.md has that version already, when there are no fragments or when one is faulty options: --root <dir> the checkout to work on (default the repository) --name <slug> add: the fragment's file name, without .md --text <entry> add: the entry (default stdin) --date <date> build: the release date, YYYY-MM-DD (default today, UTC) ``` ## polestar codex Build Lookup's Codex (data/forever/codex + the Polestar_Codex pack) ```sh polestar codex --help ``` ```output usage: node tools/polestar.js codex build [options] node tools/polestar.js codex parity [--ours <dir>] [--against <dir>] node tools/polestar.js codex attune [--addons <dir>] [--ours <dir>] Builds Lookup's Codex: every item, mount, pet, recipe, NPC, rare, quest, zone, dungeon and treasure, with where each item comes from, and the Dungeons journal. Release-safe inputs only: the data/forever/*.json tables (<era-db>, <quest-db> facts, recordings, corrections), the Forever client's tables (the newest 1.60+ build <tables> lists, cached under data/sources/<tables>/; meta.json records it), the installed <leveling-bis> (MIT) and Polestar's own guides. Writes data/forever/codex/*.json and the load-on-demand pack addon/Polestar_Codex with its LICENSE-DATA.txt; `pack` ships that folder in the release zip. --addons <dir> the Forever client's Interface/AddOns (default: detected) --build <version> <tables> Forever build (default: newest listed) --offline use cached client tables only (the newest cached build holding every table the Codex reads) --out <dir> JSON output (default data/forever/codex; with --local-extras data/local/codex-extras) --pack <dir> pack output (default addon/Polestar_Codex; with --local-extras data/local/codex-extras/Polestar_Codex) --local-extras also merge the installed <loot-db> (GPL-2.0), <rares-db> (All Rights Reserved) and data/forever/dungeons.json (DungeonJournal, no licence). For this machine only: the pack's meta says local and `pack` refuses to ship it. A release build also reads the <web-db> Forever facts cached in data/sources/<web-db>/codex/ (tools/lib/codex/<web-db>.js), when present. A release build compares itself with the last --local-extras build (when data/local/codex-extras exists), entity by entity, writes data/local/codex-parity.json and .md and records the match per kind in its meta (`parity`). `codex parity` reruns that comparison on two built folders (default ours data/forever/codex, against data/local/codex-extras). `codex attune` compares the built Dungeons journal (--ours, default data/forever/codex) with the installed Attune addon (no licence: read on this machine only, never in a build): each dungeon's quests per side and every journal quest's rewards, written to data/local/dungeon-quests-audit.md (and .json), and the attunement chains to data/local/attunements-audit.md. --ours <dir> parity: the release build (default data/forever/codex) --against <dir> parity: the internal build (default data/local/codex-extras) ``` ## polestar compile Compile a pack into its community addon folder ```sh polestar compile --help ``` ```output usage: node tools/polestar.js compile [<dir>] [options] Compiles a pack's .guide files (docs/GUIDE_FORMAT.md) into its community addon folder, as its pack.json describes it: the generated TOC, Pack.lua, MapFrames.lua, Guides.lua and LICENSE-DATA.txt, plus the pack's LICENSE file as LICENSE.txt when it has one. The pack is the one in <dir> (or --pack), else the nearest folder holding a pack.json (this one or a parent), else our guides/. Another pack is checked with our guides as context and written to <pack>/dist/<folder>/; ours to addon/Polestar_Guides/. Nothing is written when there are errors, nor without reference data (`data build`): compile then stops with one error before reading any guide, unless --no-data says to compile without it. options: <dir>, --pack <dir> the pack folder (holding pack.json) --guides <dir> our pack's guide sources in another folder (default guides/) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context for another pack (default guides/) --context-data <dir> reference data for the context (default data/forever/) --no-data compile without reference data: every quest title, NPC name and place must be given in the guide --out <dir> pack folder (default addon/<folder>/ for ours, <pack>/dist/<folder>/ for another pack) --include-drafts also compile the pack's drafts/** --format <f> diagnostics as text (default), json (one document on stdout, no summary) or github (workflow annotations) --quiet print errors only ``` ## polestar data Build reference data (data/forever/*.json) from the Era quest database, the community quest database, Blizzard map tables and recordings ```sh polestar data --help ``` ```output usage: node tools/polestar.js data build [options] Builds data/forever/*.json (quests, npcs, objects, items, zones, map-frames, factions, meta) from <era-db> (MIT), <quest-db>'s Forever store (installed with <quest-db> for the Forever client; read locally, facts only ship), Blizzard Classic Era and Forever client tables (<tables> CSV) and data/recordings/*.json. Precedence: recordings > <quest-db>-forever > <era-db>. Also spawnz.json: every NPC and object spawn's height on Eastern Kingdoms and Kalimdor from <server-db> <server-db> (GPL-3.0, facts), which the compiler gives goals at an NPC or object; with --offline and no cached dump it is left out with a warning. The same dump's quest_template gives the objective counts <quest-db> and <era-db> lack (left null without it, with a warning). Downloads are cached under data/sources/. options: --offline use cached sources only (no git, no HTTP) --<era-db> <dir> use this <era-db> checkout as is (default: cache clone) --<quest-db> <dir> <quest-db> folder (or the AddOns folder holding it) (default: auto-detected in the Forever client, as `install` finds it) --no-<quest-db> build without <quest-db> --build <version> <tables> Classic Era build (default: newest listed) --forever-build <v> <tables> Forever build (default: newest 1.60+ wow_classic_beta) --no-forever skip the Forever client tables (zones and frames from Era only) --no-web-xp skip quest XP lookups on <talents-site> / <changes-site> for quests <quest-db> has no XP for (results cached in data/sources/webxp/) --no-<web-db> skip <web-db> Forever's change notes (XP, levels) and its XP for quests still without any (the zone lists cached in data/sources/<web-db>/, when present) --recordings <dir> recordings folder (default: data/recordings) --out <dir> output folder (default: data/forever) --sources <dir> source cache folder (default: data/sources) --cap <n> max spawn points per entity per map (default 24) --built-at <iso> timestamp for meta.json (default: now, or SOURCE_DATE_EPOCH) ``` ## polestar dev Rebuild a pack into the game on every save ```sh polestar dev --help ``` ```output usage: node tools/polestar.js dev [<dir>] [options] On a pack (<dir>, --pack, or run inside one): watches pack.json and the pack's .guide files. On every save it lints, printing the diagnostics, and without errors compiles the pack into <AddOns>/<folder>, then reloads the playground when --play started one. In game, /reload shows the change; a pack's first build needs one restart of the game. A folder in AddOns is replaced only when it is empty or a generated build of the same pack. Ctrl-C stops. Without reference data (`data build`) dev stops at once with one error, unless --no-data says to build without it. options: --dest <dir> the Interface/AddOns folder (default: the one install finds) --no-game do not write into AddOns (lint, and the playground) --play also start the playground with the pack loaded (client art and SavedVariables folder as play finds them) --port <n> the playground's port (default 8077; 0 picks a free one) --no-data build without reference data: every quest title, NPC name and place must be given in the guide <dir>, --pack <dir> the pack folder, holding pack.json (default: the nearest pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) ``` ## polestar doctor Check Node, Lua, the reference data, the AddOns folder and pack.json ```sh polestar doctor --help ``` ```output usage: node tools/polestar.js doctor [<dir> | --pack <dir>] Checks what the Polestar tools need, one line per check (`ok` or `fix`, with the fix for Windows, macOS and Linux): node Node 24 or newer (every command) lua a Lua 5.1 interpreter: lua5.1, LuaJIT, or a `lua` that is 5.1 (play, playtest and record import; $LUA picks one) data the reference data, data/forever/ (every guide command) addons the game's AddOns folder: $WOW_FOREVER_ADDONS, else the client install finds (install and dev; or pass them --dest) pack.json inside a pack (or given its folder), the pack's manifest Exit code 1 when the Node or reference-data check fails, else 0. ``` ## polestar draft Generate a first-draft leveling route (.guide) from the reference data ```sh polestar draft --help ``` ```output usage: node tools/polestar.js draft --faction <Alliance|Horde> --race <Race> --zone <name> [--zone <name>...] --levels <min>-<max> [options] Generates an efficient first-draft route (docs/GUIDE_FORMAT.md) from the reference data: hub-style accepts and turn-ins, objective areas ordered by nearest neighbour + 2-opt over world distances, level gating by estimated XP. options: --class <Class> route for one class; otherwise class quests get "only <Class>" --start-quest <id> begin at this quest's giver --start <x,y> begin at these coordinates in the first zone --id <guide id> default forever/<faction>/<race>/<zones>-<min>-<max> --title <text> default "<zones> <min>-<max>" --next <guide id> header "next" --done <ids|file.guide> quests already turned in (comma list, or the turnins of a guide); repeatable --trainer <Class>:<npc> a class trainer the data does not mark; repeatable --keep-breadcrumbs end with optional accepts of breadcrumbs leading out of the area --data <dir> reference data (default data/forever) --out <file> write the guide here (default stdout) --quiet no summary on stderr Races: Human Dwarf Gnome NightElf Orc Troll Tauren Undead Skyborne; a new race takes its bit as <Name>:<bit> (e.g. Newrace:512). ``` ## polestar dungeons Import DungeonJournal: dungeon data (data/forever/dungeons.json) ```sh polestar dungeons --help ``` ```output usage: node tools/polestar.js dungeons build [options] Reads the installed DungeonJournal addon (ForeverDungeonJournal) and writes data/forever/dungeons.json: dungeons with levels, entrance and bosses, quests with chains, XP, money, rewards, shareability and where they start and end (docs/ARCHITECTURE.md). The Dungeons section of the hub reads it through the Codex (`codex build`). DungeonJournal publishes no licence: the output is gitignored and stays local. --source <dir> the ForeverDungeonJournal folder (default: WOW_FOREVER_ADDONS, else the Forever clients `install` detects) --data <dir> reference data (default data/forever) --json print the report as JSON ``` ## polestar exploration Build or check the generated exploration guides ```sh polestar exploration --help ``` ```output usage: node tools/polestar.js exploration build [options] node tools/polestar.js exploration check [options] build: rewrites guides/forever/exploration/*.guide, one guide per continent and level range plus Zephras Isle, from the Forever client's map tables (<tables> CSV, cached in <sources>/<tables>), data/forever (zones, map frames, flight masters from travel.json) and the zone order in tools/lib/exploration/spec.js. Run `compile` afterwards. check: builds the same guides in memory and exits 1 when a committed guide differs (writes nothing). --offline use cached tables only --build <version> <tables> build (default: newest listed) --data <dir> reference data (default data/forever) --sources <dir> source cache (default data/sources) --stdout print the guides instead of writing them (build only) ``` ## polestar export Print the import string of one guide ```sh polestar export --help ``` ```output usage: node tools/polestar.js export <file.guide> [options] Prints the import string of the one guide in <file.guide>: a line of text a player pastes into Polestar's Import page (/polestar import) to get the guide without installing anything (docs/GUIDE_PACKS.md, "Import strings"). The guide belongs to a community pack: the nearest folder above the file holding a pack.json, whose id is the guide id's prefix and whose license the string carries. The pack is linted first, with our guides as context, and a guide with errors is refused. A string holds one guide of at most 60 steps and 50000 characters; anything bigger, or a set of guides, is a community addon (`polestar pack`). The string goes to stdout, everything else to stderr, so `polestar export my.guide > my.txt` keeps only the string. options: --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) --quiet print errors only ``` ## polestar find Look up quests, NPCs, objects, items, inns, flight points and guides as guide lines ```sh polestar find --help ``` ```output usage: node tools/polestar.js find <text> [options] Searches the reference data (quests, NPCs, objects, items, inns and flight points) and our guides. A number matches ids exactly; other text matches names (and a guide's id and zone, an inn's or flight point's zone), ignoring case. Each result prints as a guide line ready to paste, with what it is in a comment. A quest also prints its turn-in line and its objectives (the `quest <id>.<n>` of an objective goal); a guide prints who it is for and the guide its own `next` offers; an inn prints the name `sethome` and `hearth` take, a flight point the one `getfp` and `fly` take: 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 sethome "Goldshire" # Innkeeper Farley (npc 295), Elwynn Forest 43.8,65.8 getfp "Sentinel Hill" # Sentinel Hill, Westfall, Alliance: Thor (npc 523), Westfall 56.6,52.7 next forever/alliance/02-westfall # Westfall (12-17), Alliance # its next: forever/alliance/03-darkshore `find --kind inn` and `find --kind flight` without a text list them all. Exit code 1 when nothing matches. options: --kind <k> only quest, npc, object, item, inn, flight, guide --faction <f> only what Alliance or Horde can use (quests by race, NPCs and inns by who they are friendly to, flight points by their side, guides by faction) --race <r> only what this race can use (Human, Orc, Dwarf, NightElf, Undead, Tauren, Gnome, Troll, Skyborne): quests by race, NPCs, inns and flight points by side, guides by faction and race --class <c> only what this class can use: quests and guides by class --limit <n> at most n results (default 20; a full list of inns or flight points: all) --json print the results as a JSON array: every result has kind, id, name and line; quests level, zone, x, y, starts, ends, turnin and objectives; guides levels, zone, faction, races, classes and next; inns (id: the innkeeper) names, npc, npcName, zone, map, x, y; flight points node (the full name), faction, npc, npcName, zone, map, x, y --data <dir> reference data (default data/forever/) --guides <dir> our guides (default guides/) ``` ## polestar gear Build the upgrade-advice data (Forever item stats, reward choices, stat weights) from installed addons and sims ```sh polestar gear --help ``` ```output usage: node tools/polestar.js gear build [--addons <dir>] node tools/polestar.js gear fetch build: the data behind Polestar's upgrade advice: addon/Polestar_ItemDB/Forever.lua <leveling-bis> (MIT): Forever item stats over the Era table, and quest reward choices addon/Polestar/Gear/SpecData.lua stat weight bands per spec and level (Polestar's weights blended with <gear-sim>, MIT), racial traits Reads the installed <leveling-bis> and the <gear-sim> cache under data/sources/<gear-sim> (no network). Run `itemdb build` first. fetch: refresh the <gear-sim> cache (pinned commits). --addons <dir> the client's Interface/AddOns (default: detected) ``` ## polestar i18n interface translations (status, check, sync, keys, import, fit, leaks), guide texts (guides) and the names addons (names) ```sh polestar i18n --help ``` ```output usage: node tools/polestar.js i18n <status|check|sync|keys|import|fit|leaks|names|guides> [options] Polestar's interface translations (docs/TRANSLATING.md): one file per locale, addon/Polestar/Locales/<locale>.lua, and the same for the Recorder, addon/Polestar_Recorder/Locales/<locale>.lua. Locales: deDE, esES, esMX, frFR, koKR, ptBR, ruRU, zhCN, zhTW. check and sync read both addons; status, keys and import read Polestar's unless --addon names the other. i18n status per locale: its language, status (reviewed or ai), translators, and how many keys it translates. --markdown prints a table for the README and release notes. i18n check [<locale>...] fails (exit 1) on a file Lua cannot load, a stale key (one the code no longer has), a key set twice, or a translation whose %s/%d/%1$s, |4one:many; or |c/|r/|T escapes differ from the English. Warns where a translation leaves out its glossary's word (tools/lib/i18n/glossary). Missing translations are fine: the English shows. i18n sync [<locale>...] adds the keys the code gained to each file as -- L["English"] = "" lines under their file's group, and moves translations of keys it lost to a commented block at the end. Never rewrites a translation. A locale named that has no file gets one, loaded from Core/Core.xml (the Recorder's TOC lists its own). i18n keys every interface key with where it is used. i18n import <locale> <file.lua>... merges translations written apart (a file that returns { ["English"] = "translation" }, sets L["English"], or calls ns.AddTranslations) into the locale's file: only into keys not translated yet; a broken format is refused; keys the code lacks go to the commented block at the end. i18n fit [<locale>[=<file>]...] lays out every preview scene and every Options page and tab in English and in each locale (or those named; <file> stands in for the shipped file, such as a pull request's), in the game font and in Inter, and lists the text the window cuts with an ellipsis, cuts after its last line or lets cross its edge. Text cut the same way in English (a long guide or item name) is left out. Fails (exit 1) when a locale has any. CJK is measured 1em wide. i18n leaks [<locale>...] runs the addon on the client stub in each locale (or those named) with its shipped translations, names pack and guide texts, the client's own names as placeholders, through every scene (or those --scene names), and lists the English left on screen: a Latin word of 3+ letters in a text, tooltip, chat line or menu that none of the locale's own texts uses and tools/lib/i18n/leaks-allow.json does not allow, grouped by where it came from (an untranslated interface string or guide text, a name missing from the names pack, a name Polestar.Names was not asked for, English in the code). Fails (exit 1) on any, or on a scene that errors. Scenes (--scene; default all): guide, guides, welcome, picker, options, lookup, dungeons, rares, talents, journey, tooltips, slash, more, recorder. i18n names [<locale>...] builds the names addons addon/Polestar_Names_<locale>: the names of quests, NPCs, objects, items, instances, encounters, factions and flight points (and the objectives of dungeon event quests) in each language. Per id, the first source with a name wins: the Forever client's tables (<tables>, &locale=), <web-db>'s Forever database in that language (list pages and tooltips, read only from what is already cached in data/sources/<web-db>/names), <names-db> (pinned commit and sha256s, cloned into data/sources/<names-db>), then <era-db>'s db/<locale>. Only the ids the compiled guides, the quest database, the Codex's data and the travel data name. A language left without names loses its folder. i18n guides sync [<locale>...] writes a pack's texts in other languages (docs/TRANSLATING.md, "Guide texts"): <pack>/locales/<locale>/<guide path>.lua per guide and _pack.lua for the pack's own texts, each with every text that needs words, the game's names as {kind:id} tokens, "" while not translated. Keeps every translation; one whose English the guide lost moves to a commented block at the end. Without a locale: every language the pack has a folder for. i18n guides check [<locale>...] fails (exit 1) on a texts file Lua cannot load, a translation that leaves out or adds a name token or a line break, a stale translation (its English changed or went away: the new English is named when it can be told) or a file no guide has. Missing translations are fine. i18n guides stats the texts to translate: unique texts, words and characters (tokens left out), in all and by guide folder; the names the compiler made tokens, by kind and source; the notes dropped for naming only their goal. options: --json status, check, keys, names, fit, leaks, guides: one JSON document on stdout --scene <a,b> leaks: only these scenes --guide <id,...> leaks: the guides the guide scene shows (default a few) --jobs <n> leaks: runs at a time (default one per core) --update-baseline leaks: write tools/lib/i18n/leaks-baseline.json: add the names no source has that the runs showed in English, drop the entries that no longer show --slack <n> fit: measure every glyph n times wider (1.15: about the client's own font) --pack <dir> guides: the pack (default our guides/) --data <dir> guides: the reference data (default data/forever) --markdown status: a Markdown table --no-<quest-db> names: leave <names-db> out (its base data is <quest-db>'s) --no-tables names: leave the client tables out (otherwise a missing table stops the build) --offline names: no downloads; the cached clones and tables --build <version> names: this Forever client build (default the newest <tables> lists) --sources <dir> names: the client-table and <web-db> cache (default data/sources) --ding <dir> names: this <names-db> checkout (default data/sources/<names-db>) --<era-db> <dir> names: this <era-db> checkout (default data/sources/<era-db>) --guides <file> names: the compiled guides (default addon/Polestar_Guides/Guides.lua) --questdb <dir> names: the built quest database (default addon/Polestar_QuestDB) --codex <dir> names: the Codex's data (default data/forever/codex) --travel <file> names: the travel data (default addon/Polestar/Nav/TravelData.lua) --chokepoints <file> names: the walking map's chokepoints, for the lifts' objects (default addon/Polestar_Nav/Nav/Chokepoints.lua) --out <dir> names: where the addon folders go (default addon/) --addon <name> status, check, sync, keys, import: Polestar or Polestar_Recorder only ``` ## polestar install Install the addons into the Forever client ```sh polestar install --help ``` ```output usage: node tools/polestar.js install [<dir>] [options] Installs addon/Polestar, addon/Polestar_Guides and addon/Polestar_Nav, plus the data addons Polestar_QuestDB, Polestar_ItemDB, Polestar_Codex and the names addons Polestar_Names_<locale> when they have been built (and with --recorder, addon/Polestar_Recorder) into World of Warcraft: Forever's AddOns folder. Given another pack (<dir>, --pack, or run inside one) it lints and builds that pack into <pack>/dist/<folder>/ instead and installs that folder; an existing <AddOns>/<folder> is replaced only when it is empty or a generated build of the same pack (its TOC's X-Polestar-Pack names this pack's id). Without reference data (`data build`) it stops with one error, unless --no-data says to build without it. Destination, first match wins: --dest <dir> the Interface/AddOns folder to install into $WOW_FOREVER_ADDONS same, from the environment auto-detect Wine/Proton/Faugus/Lutris/Bottles prefixes under your home folder, and native installs (C:\Program Files (x86)\World of Warcraft on Windows, /Applications/World of Warcraft on macOS); a "_forever_" or "_classic_beta_" client folder whose .flavor.info names Forever (wow_forever*) or the classic beta options: --link symlink the folders instead of copying (edit, then /reload) --recorder also install Polestar_Recorder --dry-run print what would happen, change nothing --addons <dir> source folder holding the addons (default addon/) --no-data a pack only: build it without reference data (every quest title, NPC name and place given in the guide) <dir>, --pack <dir> the pack folder, holding pack.json (default: the nearest pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) ``` ## polestar itemdb Build the Polestar_ItemDB data addon (item stats) from client tables ```sh polestar itemdb --help ``` ```output usage: node tools/polestar.js itemdb build [options] Writes the load-on-demand data addon addon/Polestar_ItemDB (Items.lua + TOC): stats of every equippable Classic Era item (item level, required level, inventory type, armor, weapon damage and speed, primary stats and the equip bonuses Polestar.Gear scores), from Blizzard client tables (<tables> CSV: ItemSparse, Item, ItemEffect, SpellEffect). Size budget: 1024 KiB. --offline use cached tables only --build <version> <tables> Classic Era build (default: newest listed) --sources <dir> source cache (default data/sources) --out <dir> default addon/Polestar_ItemDB ``` ## polestar lint Check .guide files without writing output ```sh polestar lint --help ``` ```output usage: node tools/polestar.js lint [<dir>] [options] Runs every compile check (syntax, data lookups, cross-guide validation) on a pack without writing anything: the pack in <dir> (or --pack), else the nearest folder holding a pack.json (this one or a parent), else our guides/. Exit code 1 on errors. Another pack is checked with our guides as context (its `next` and turn-ins see our chains; their own diagnostics are not shown). When the simulator has cached a world (`sim`), also warns on leveling goals its solo filter excludes. Without reference data (`data build`) lint stops with one error before reading any guide, unless --no-data says to check without it. options: <dir>, --pack <dir> the pack folder (holding pack.json) --guides <dir> our pack's guide sources in another folder (default guides/) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context for another pack (default guides/) --context-data <dir> reference data for the context (default data/forever/) --no-data check without reference data: every quest title, NPC name and place must be given in the guide --sim <dir> simulator cache with world-<faction>.json (default data/sim/, used only with the default --data) --include-drafts also check the pack's drafts/** --format <f> text (default), json (one document on stdout, no summary) or github (workflow annotations) --quiet print errors only ``` ## polestar maps Build world map data (zone level ranges, zone art overlays) ```sh polestar maps --help ``` ```output usage: node tools/polestar.js maps <build|overlays> [options] build: zone level ranges for the world map (hostile creature levels per zone, spawn-weighted P10..P90; heuristic in tools/lib/maps/zonelevels.js) -> addon/Polestar/Maps/ZoneLevels.lua. --data <dir> data/forever (npcs.json, zones.json) --lua <file> output (default: addon/Polestar/Maps/ZoneLevels.lua) overlays: every world map overlay of every zone map (the explored-area paintings), from the client's DB2 tables via <tables>, so the zone art shows a map without fog of war -> addon/Polestar/UI/ZoneArtOverlays.lua. --build <ver> client build (default: 1.60.1.70338, the Forever client) --sources <dir> source cache folder (default: data/sources) --offline use cached tables only --lua <file> output (default: addon/Polestar/UI/ZoneArtOverlays.lua) ``` ## polestar media Regenerate the addon textures (tools/media/*.js -> addon/Polestar/Media) ```sh polestar media --help ``` ```output usage: node tools/polestar.js media [generator ...] Runs every generator in tools/media/ (or only the named ones) against addon/Polestar and lists the files written. ``` ## polestar nav Terrain navigation from the client geometry (build the grid, route between map points) and Polestar's walking router with its maps (Polestar_Nav) ```sh polestar nav --help ``` ```output usage: node tools/polestar.js nav build [--continents 0,1] [--force] [--offline] [--workers N] [--out <dir>] [--product ] node tools/polestar.js nav path <map> <x>,<y> <map> <x>,<y> [--class C] [--level N] [--frame era|forever] [--json] [--dir <dir>] node tools/polestar.js nav aids [--out <file>] [--lua <file>] [--report] [--continents 0,1] [--workers N] [--reference <file>] [--dir <dir>] node tools/polestar.js nav pack [--cells N] [--date <YYYY-MM-DD>] [--dir <grid dir>] [--layers <dir>] [--out <dir>] | nav pack --check [--out <dir>] node tools/polestar.js nav check [--out <dir>] node tools/polestar.js nav eval [--nav <Polestar_Nav dir>] [--baseline <dir or eval .json>] [--routes <file>] [--sweep] [--style fastest|balanced|roads] [--out <file.json>] node tools/polestar.js nav layers roads [--c 0|1] [--allowlist] [--offline] [--product ] node tools/polestar.js nav layers hubs [--dir <grid dir>] [--offline] build the navigation grid of every continent map-frames.json names (or --continents): client geometry per ADT tile through the CASC cache (data/sources/casc), walkable surfaces, links, regions and the abstract graph, in worker threads, written to data/local/nav (--out). A tile already built is kept unless --force; --offline only reads cached client files. path a route between two map points: <map> a uiMapID, <x>,<y> percent on it (the Era frame unless --frame forever). Prints yards, seconds by class, falls and the simplified points (map percent of the first map); --json prints the whole result. --class (e.g. Druid) and --level (default 10) choose the movement profile. aids the arrow's aids from the grid (--dir, default data/local/nav; tools/lib/nav/aids.js): zone crossings, open borders and approach chains in the crossings schema, validated, written to aids.json in the grid's folder (--out: another file). --lua writes them as a Crossings.lua for a local test (never into addon/Polestar_Travel); to build a test copy of the data addon: node tools/polestar.js travel build --offline --crossings data/local/nav/aids.json --travel-addon <test folder> --json <test folder>/travel.json --lua <test folder>/TravelData.lua Pockets are tested in --workers threads (default: up to 6). --report also plans every consecutive pair of located goals in our guides with the addon's planner without and with the aids and writes aids-report.json and aids-report.md next to --out, comparing with the reference crossings file (--reference, default data/local/crossings.json; read only). pack Polestar's walking maps of maps 0 (Eastern Kingdoms), 1 (Kalimdor) and 2991 (Zephras Isle) from the grid (--dir, default data/local/nav; it needs grid version 4: nav build --out data/local/nav4, then --dir data/local/nav4) and the ground layers (--layers, default data/local/nav-layers: roads and hubs, from nav layers), in maps format 2: a ground class per surface (road, gentle or steep slope, indoor, indoor city, Alliance and Horde hubs) and every graph edge priced per faction (tools/lib/nav/pack.js, grown from a port of Shortest Path Forever's (Cillian Berragan) gen_nav.py and pack_nav.py), with Chokepoints.lua (lifts, bridges, gates, tunnels, cave and building mouths, passes; tools/lib/nav/chokepoints.js), into addon/Polestar_Nav (--out): Nav/Nav<map>*.lua, Nav/Chokepoints.lua, PACK.json (grid build, cells, date, sizes, sha256 of every file) and Nav/Nav.xml. --cells cuts each ADT tile into N x N cells (default 128, 4.17 yd); --date dates the generated headers (default today; the same grid, layers, cells and date give the same bytes). --check only compares the folder with PACK.json. check the walking maps match PACK.json and Nav/Nav.xml lists them. eval the walking router run standalone (LuaJIT, else Lua 5.1; a folder without its own Routing takes the repository's) on a folder's maps (--nav, default addon/Polestar_Nav): the route corpus (--routes, default tools/lib/nav/eval/routes.json) with each route's metrics (yards, seconds, the share of the drawn line our grid at data/local/nav3 cannot walk, off-road share, yards in hostile hubs, steepest climb, indoor yards on data/local/nav4's indoor surfaces outside the capitals, yards per zone, swumYards: yards over water; a layer not built yet reads n/a) and expectations; a route with a level (the character's) is priced with zone danger as the addon prices it (x3 at 4+ levels above; more than 10 above x20; the start's and goal's zones exempt; tools/lib/maps/zonelevels.js), and a route's own danger ({ "<uiMapID>": multiplier }) is laid over it; --sweep also searches, per zone with located guide goals and per side, from the zone's flight master (else its first goal) to every goal. --baseline runs the same on another folder (or reads an earlier --out report) and judges the acceptance checks A1-A8; exit 1 when one fails. --style prices every search in a route style (fastest, balanced or roads; default balanced), the baseline's too. --out writes the whole report. layers the ground layers under data/local/nav-layers. roads: per grid column, the share of the ground the client paints with a road texture (tools/lib/nav/layers/roads.js), from each tile's tex0 ADT (its texture layers and alpha maps) and the reviewed allowlist tools/lib/nav/layers/road-textures.json, texture names from the wowdev community listfile (downloaded once to data/sources/listfile; build time only), for maps 0 and 1 (--c: one of them), into roads/<c>/<col>_<row>.bin. --allowlist instead rewrites the allowlist from every texture both maps' tiles use (never with --c): one whose tileset path names a road, path, cobble, street or trail; one naming dirt, footprint, brick or gravel, or listed under reviewed, when its shape is a road's (most of its weight in long, narrow, elongated strips); with every measure (review it). hubs: each faction's towns and outposts (tools/lib/nav/layers/hubs.js): its guards and service NPCs (quest givers, vendors, trainers, flight masters, innkeepers, bankers, repairers) from the <server-db> <server-db> spawns and creature templates, judged by the client's FactionTemplate table, clustered, named by the AreaTable area under them (the grid's area ids, --dir, default data/local/nav4), into hubs.json. ``` ## polestar new Start a pack in a new folder from the template ```sh polestar new --help ``` ```output usage: node tools/polestar.js new [dir] [options] Starts a pack in [dir] (default: the current folder), which must be empty or missing (run it before `git init`: a folder holding .git is not empty): pack.json, an example guide, README.md, LICENSE, .gitignore, VS Code tasks, AGENTS.md / CLAUDE.md for AI assistants, the polestar-guide-pack skill (skills/ in this clone) in .agents/skills/ and .claude/skills/, and a GitHub workflow and a dev container that install Polestar from this clone's origin remote. The origin must be an http(s) or SSH URL; it is written as https, without a user name, password, query or fragment. With no origin, or any other kind, those two are left out. Asks for each value not given, unless --yes accepts the defaults; without a terminal to ask in, it writes nothing and exits 1 unless --yes or all four values are given. options: --id <id> pack id, e.g. joe-routes (default: from the folder name) --title <text> pack title (default: from the id) --author <name> author (default: git config user.name) --license <spdx> licence, e.g. CC-BY-4.0, CC0-1.0, MIT, GPL-3.0-only (default CC-BY-4.0) --yes accept the defaults for every value not given ``` ## polestar pack Build the release zips, or a community addon's zip ```sh polestar pack --help ``` ```output usage: node tools/polestar.js pack [<dir>] [options] In the repository: compiles our guides, then writes dist/Polestar-<version>.zip (Polestar, Polestar_Guides, Polestar_Nav, Polestar_Codex, the names addons Polestar_Names_<locale>, and Polestar_QuestDB / Polestar_ItemDB when built), dist/Polestar_Recorder-<version>.zip and dist/SHA256SUMS. Polestar/ in the zip also carries LICENSE and README.txt (install steps), Polestar_Recorder/ the LICENSE. The Codex must be built first (`codex build`) from release-safe inputs: pack stops on a missing Codex or a --local-extras one. Given another pack (<dir>, --pack, or run inside one): lints and builds it with our guides as context, then writes <pack>/dist/<folder>-<version>.zip holding its addon folder, the version taken from pack.json. Both are byte for byte reproducible. Without reference data (`data build`) pack stops with one error; a pack can be built without it with --no-data. options: <dir>, --pack <dir> the pack folder, holding pack.json (default: the nearest pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) --guides <dir> our guide sources (default guides/; not with a pack folder) --addons <dir> addon source folder (default addon/) --dist <dir> output folder (default dist/, <pack>/dist/ for a pack) --no-data a pack only: build it without reference data (every quest title, NPC name and place given in the guide) ``` ## polestar planner Plan routes: play a guide on the map and edit it (local page, MCP) ```sh polestar planner --help ``` ```output usage: node tools/polestar.js planner [<pack dir>...] [--port 8078] [--art <dir>] [--nav <dir>] [--open] node tools/polestar.js planner art [--continents 0,1] [--no-zones] [--force] [--offline] [--concurrency N] [--out <dir>] node tools/polestar.js planner mcp [<pack dir>...] [--port 8078] [--art <dir>] [--nav <dir>] The route planner: a local page (http://127.0.0.1:8078) that plays a guide on the real map, step by step, with the clock, the XP and the quest log, and edits the .guide files (fields, steps, dragged waypoints): every edit is written to the file at once. Our guides/ are always loaded; other packs (a folder holding pack.json, as arguments or --pack) come after them. Inspired by Nivek_Gaming (@Nivek_Gaming on X): thank you, Nivek. --port <n> port on 127.0.0.1 (default 8078; 0 picks a free one) --art <dir> the map art (default data/local/planner/art) --nav <dir> the navigation grid walks are routed on (default data/local/nav; built by node tools/polestar.js nav build; without it walks are straight lines) --data <dir> reference data (default data/forever/) --pack <dir> one more pack folder --open open the page in the browser planner art: fetch the Forever client's minimap blocks and zone maps from <tables> (cached under data/sources/casc/) and build the art the page draws into data/local/planner/art/ (never committed). --continents <c,..> only these continents (map ids, e.g. 0,1; default all) --no-zones skip the painted zone maps --force rebuild files that exist --offline use only cached downloads --concurrency <n> parallel downloads (default 8) --product <tables> product (default wow_classic_beta) --out <dir> output folder (default data/local/planner/art) planner mcp: the planner's commands as an MCP server on stdin/stdout (JSON-RPC, one message per line). It uses the planner running on --port, so an agent's edits show live in the open page, else starts one itself. ``` ## polestar play Play with the real addon in the browser (local playground) ```sh polestar play --help ``` ```output usage: node tools/polestar.js play [<dir>] [--port 8077] [--art <dir>] [--fresh] Starts a local server running the real Polestar, Polestar_Guides and the built data packs against the simulated world, and prints its URL. Click, hover, scroll, drag and type in the game screen; the side panel sets the character, moves them, plays guide goals and tweaks the look live. Given another pack (<dir>, --pack, or run inside one) that pack is linted, built into a temp folder and loaded after our guides. --port <n> port on 127.0.0.1 (default 8077; 0 picks a free one) --art <dir> local client art (default $POLESTAR_CLIENT_ART, else /tmp/polestar-art when present); served locally only --no-art draw without client art --fresh forget the character and SavedVariables (data/play/, or $POLESTAR_PLAY_DATA) <dir>, --pack <dir> the pack folder, holding pack.json (default: the nearest pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, read as context (default guides/) --context-data <dir> reference data for the context (default data/forever/) ``` ## polestar playtest Play a pack's guides to the end for every class ```sh polestar playtest --help ``` ```output usage: node tools/polestar.js playtest [<dir>] [options] Plays a pack's guides to the end in the real addon against a simulated world (needs Lua 5.1; `doctor` checks): each guide once per class it branches on (`only`) plus one class it never names, as each race that can reach it. The pack is the one in <dir> (or --pack), else the nearest folder holding a pack.json, else our guides/. Another pack plays with our guides loaded too: a guide whose `next` names one of ours must land on it with something to do, and the guide it lands on must apply to the character (its race, class and faction). --filter plays only the guides whose file or id contains its text. One line per guide, race and class (only pairs that exist in the game): ok joe/elwynn (Human Warrior) stuck joe/elwynn (Human Paladin) at step 3 "Kobolds": goal 1 (kill "Kobold Vermin") stays active stuck joe/elwynn (Human Mage) at hand-over to forever/alliance/02-westfall: <why> stuck joe/elwynn (Human Mage) at hand-over to forever/alliance/dwarf-gnome/01-dun-morogh: no Human can follow it fail joe/elwynn (Human Warrior): no location for step 2 goal 1: accept 33 Exit code 1 when any guide is stuck or fails, nothing was played, or the pack does not compile. options: --filter <text> play only the guides whose file or id contains it --class <c> play only this class (e.g. Warrior), in every guide <dir>, --pack <dir> the pack folder (holding pack.json) --data <dir> reference data (default data/forever/) --context <dir> our guides, loaded beside another pack (default guides/) --context-data <dir> reference data for the context (default data/forever/) ``` ## polestar preview Render the guide window, picker and options to docs/preview/*.svg ```sh polestar preview --help ``` ```output usage: node tools/polestar.js preview [scene ...] Runs the real Theme and UI Lua against a geometry-recording client stub with sample guides and writes SVGs to docs/preview/. Scenes: guide Guide window: a field step; a hub, one person at a time (first, then the second); the tip opened guide-picture Step pictures: a community addon's screenshot under the step's tip, scaled to the window; a picture with no tip, at most 160 high (Polestar's own textures stand in for the screenshots) skins-guide Skins: the guide window in Polestar, Halo and Hearth skins-states Skins: a hub step, transparent and the header menu, in Halo and Hearth guide-transparent Transparent mode over a bright world: at rest, and with the cursor over it guide-compact Compact mode: standard and transparent guide-states No guide open, guide complete, out-levelled banner, header menu route-choice Choose your path: an Undead after Tirisfal Glades; the guide window while the choice waits welcome The welcome, once per new character after login: Hello, Make it yours and Route style (on the account's first), Your first guide guide-professions Profession and reputation guides: chosen trainer with alternatives, skill bar, reputation bar guide-smart Smart logic: training reminder, an unavailable quest, a farm spot with alternatives guide-along Along the way: the kobolds and wolf meat of an `along` step under the steps after it; with Up next open journey The journey under the focus: walking to the Great Lift (36:48, 8.0k yd, the lift untimed); on the lift, timed; collapsed to its totals guide-group Group content: elites and an author's group size; a dungeon run said once; the guide menu's Group chip class-not-yet A Class guide opened too early: the guide window says from which level and who starts it; the guide menu's row says "From level 20" picker-class Class guides in the guide menu: the details lead with what the chain gives and why (a mount spell; a choice of rare items; a demon and its soul bag) report Report a problem (the guide window's bug button): what went wrong, the right spot to mark, the report for the Polestar Discord, or a filled-in issue on GitHub; the invite on its own (the sidebar's Discord mark) guide-ellesmere With EllesmereUI: Polestar follows its accent and font by default; every colour stays editable schemes Colour schemes on the guide window: Dusk (default), Night, Graphite, EllesmereUI; and your own ground, accent and brightness schemes-options Options > Appearance in each scheme: Dusk, Night, Graphite, and EllesmereUI installed (its scheme, follow toggles, its font offered) schemes-picker The guide menu in Dusk (default), Night, Graphite, and EllesmereUI with its purple accent options Options: Guide (Window, Arrow & routes, Automation) skins-options Skins: Options in Halo and Hearth (Guide, Window; Appearance, Windows with the Skin setting) gamepad-guide Focus mode on the guide window (Browse the guide with the gamepad): the first open goal; down a line on a hub step; up into the navigator with PlayStation buttons gamepad-options Options with a gamepad: the Gamepad page (a dropdown focused, D-pad left / right steps it), a binding row on its Key bindings tab (chips for buttons, chords and keys), and a slider with PlayStation buttons; B sits on the close button gamepad-hub The guide menu with a gamepad: the focus starts on the selected guide (X loads it, LB / RB step the sections); a dropdown's choices in the shared menu, the current one focused options-appearance Options: Appearance (Colour & type, Windows, Arrow); then a look of your own: an accent border 2px thick, no band, no shadow, your own arrow colours options-modules Options: pages the modules fill: Map, Questing, Discovery, Quality of Life options-more Options: Recorder and About, at the foot of the list options-integrations Options: Integrations: <quest-db>'s section while <quest-db> is loaded; with no supported addon, one line says so options-packs Options: Community guides: ours and a community addon on, one with problems and its report, one turned off, one too new; where suggestions come from options-search Options: a module's registered controls, search across pages, and a crowded sidebar in the game font that scrolls clear of the version skins-more Skins: the welcome, the journey and the route choice in Halo, then in Hearth skins-dungeons Skins: the dungeon journal in Halo and Hearth skins-picker Skins: the guide menu in Halo and Hearth skins-new Skins: the welcome's Route style page, Options' Community guides, the gamepad's focus and hints, and the report window, in Halo and Hearth skins-game-forever Skins: forever: the guide window (a hub step, the menu), Options (Guide, Appearance, Community guides, Gamepad), the welcome's Route style page and the report window skins-game-blizzard Skins: blizzard: the guide window (a hub step, the menu), Options (Guide, Appearance, Community guides, Gamepad), the welcome's Route style page and the report window skins-game-classic Skins: classic: the guide window (a hub step, the menu), Options (Guide, Appearance, Community guides, Gamepad), the welcome's Route style page and the report window picker-levels Guide menu: Elwynn Forest selected for a level 4 Human at 1,800 of 2,100 XP, its levels chip hovered: the XP its turn-ins and kills give, a bar from level 4 into 5, what was counted; the same in the Halo skin, the Graphite scheme and an accent of your own; the guide set to start at 6: level 6 recommended, the sums from there picker Guide menu: Home (Continue, Suggested) with the details; Leveling folders by faction and band picker-packs Guide menu: a community addon under Community guides, its guide credited to its author picker-views Guide menu: Current (the open tabs) and Recent (the last guides loaded) picker-search Guide menu: Favourites (star on), and a search with its first result selected picker-art Guide menu zone art: the Durotar starter at its first stop; The Barrens (19–24) open at step 13, on that step hub The hub: sections on the rail (Guides, Lookup, Dungeons, Rares) with Options at its foot; the sidebar holds the wordmark, the search and the section's own index on one edge lookup Lookup in the hub, over the sample Codex: "saber" with a vendor mount selected; the Winterspring Frostsaber, reputation or a limited vendor, its best source chosen; an empty search: the recent lookups lookup-retired Lookup: "frostsaber" with the retired Reins of the Frostsaber last, dimmed with its chip; its details for reference, no guide lookup-drop Lookup: Deathcharger's Reins for a level 4 character, a rare drop out of reach, saying why lookup-missing Lookup without the Codex pack: opened; a search only the Codex could answer; a guide still found picker-codex Guide search in the hub: the guides that match, then what the Codex holds (a few per kind) and a way into Lookup gear-pick The reward pick under turn-in goals: an upgrade (chevron, gain) and, with nothing better, the best of the choices quest-rewards The game's reward panel: a green arrow on each upgrade, the one to take framed in the accent; with no upgrade, the coin on the one that sells for most xp-bar The game's XP bar with the level the guide wants you to reach: the next level; four levels away; the setting under Quality of Life, Trackers quests-map Quest markers on the world map: givers, kill, item (drops, crate, vendor), object and exploration objectives, a turn-in; then a guide step highlighting its quests and dimming the rest quests-minimap Quest markers on the minimap around the player: nearby objectives, givers and the turn-in; then with the guide step highlighted travel Travel: the arrow (Arrow scale 160%) on a route into the next zone, its leg captioned ("Go to Westfall"), and the trail dots on the world map from the player to the zone crossing; then the arrow where the game gives no position (the Deeprun Tram) nav-areas Spawn regions: Teldrassil's The Balance of Nature, the arrow on the Fel Moss. On the world map every place the step's mobs and objects spawn is a region: the Grells' woods west and north of Aldrassil and a lone Grell's place in the arrow's colour, the Nightsabers', Thistle Boars' and Gnarlpine Totems' regions fainter; on the minimap the Fel Moss region around the player, cut at the rim dungeons Dungeons in the hub: Home for a level 20 Tauren (the dungeons for your level, faction filter Horde); Wailing Caverns, its Quests tab dungeons-xp Wailing Caverns: the levels its quests are worth, the chip beside the name hovered: at 19,800 of 23,200 XP into level 20 they carry the Tauren into 21; at 27 the lowest gives a tenth of its XP dungeons-bosses Wailing Caverns: the Bosses tab (kill order and the quests each serves) and the Map tab (the entrance and the quest givers near it); All dungeons with the filter on All dungeons-attune The Attunement tab: Wailing Caverns' attunement with the first quest done and the second in the log, and "Guide me through it"; the Deadmines' keys with the filter on All dungeons-small The hub at its smallest (menu scale 0.7): Wailing Caverns, Quests; without the Codex pack rares Rares in the hub: Elwynn Forest's rares by zone, Thuros Lightfingers with its signature drop, its spawns and when it was last met; the Seen list rares-toast The rare alert over the world: a rare on the minimap at its distance; a rare elite in sight; a treasure ``` ## polestar profession Build professions.json; draft a crafting guide; build or check the generated gathering guides ```sh polestar profession --help ``` ```output usage: node tools/polestar.js profession build [options] node tools/polestar.js profession draft <Profession> [options] node tools/polestar.js profession gathering build|check [options] build: writes data/forever/professions.json from the Forever client's tables (<tables> CSV, wow_classic_beta 1.60+: SkillLine, SkillLineAbility, SpellName, SpellEffect, SpellReagents, SpellTotems, SpellCastingRequirements, SpellFocusObject, ItemSparse, Item, ItemEffect, ItemXItemEffect; the newest Classic Era build fills the spells and items they lack) and data/forever/{items,npcs,objects}.json. Trainers come from a curated name list checked against npcs.json. --offline use cached tables only --build <version> <tables> Forever build (default: newest listed) --data <dir> reference data (default data/forever) --sources <dir> source cache (default data/sources) --out <file> default <data>/professions.json draft: prints (or writes) a 1-300 guide for a crafting profession (Alchemy, Blacksmithing, Enchanting, Engineering, Leatherworking, Tailoring): the cheapest sensible recipe chain by expected crafts and material cost, with trainer visits, recipes to learn, materials to buy or gather, and skill checkpoints at 75/150/225/300. --data <dir> reference data (default data/forever) --out [file] write the guide (default guides/forever/professions/<name>.guide) --quiet no plan summary on stderr gathering build: rewrites the six generated guides in guides/forever/professions (mining, herbalism, skinning, fishing, cooking, first-aid) from their specs in tools/lib/professions/gathering/specs.js and data/forever (node spawns, professions, items, npcs, objects). Run `compile` afterwards. gathering check: builds them in memory and exits 1 when a committed guide differs (writes nothing). --data <dir> reference data (default data/forever) --stdout print the guides instead of writing them (build only) ``` ## polestar qol Build the Quality of Life module data (spirit healers, flight masters, reagent vendors) ```sh polestar qol --help ``` ```output usage: node tools/polestar.js qol build [--data <dir>] [--lua <file>] --data <dir> data/forever (npcs.json, map-frames.json) --lua <file> output (default: addon/Polestar/QoL/Data.lua) ``` ## polestar questdb Build the load-on-demand quest database addon (markers, tooltips) ```sh polestar questdb --help ``` ```output usage: node tools/polestar.js questdb build [options] Builds the load-on-demand quest database addon (addon/Polestar_QuestDB) from data/forever: quests (levels, race/class masks, faction, givers, enders, prerequisites, objectives), NPCs and objects (spawn clusters per map, covering every known spawn; Era frames) and items (drop sources, objects, vendors). Prints the Lua size and an estimate of the in-game memory it costs once loaded. --data <dir> data/forever (quests, npcs, objects, items, map-frames) --out <dir> output addon folder (default: addon/Polestar_QuestDB) --radius <yd> spawn cluster radius (default 70) --droppers <n> NPC drop sources kept per item (default 8) --json print the stats as JSON ``` ## polestar readme Redraw the README's art: brand (docs/assets) and charts (docs/assets/charts) ```sh polestar readme --help ``` ```output usage: node tools/polestar.js readme brand node tools/polestar.js readme charts --draft <dir|git rev> [options] brand: rewrites docs/assets/{banner-dark,banner-light,emblem,logo,download,avatar}.svg, drawn in code from the emblem geometry and the wordmark fonts, and with rsvg-convert (librsvg) installed the CurseForge listing's PNGs in docs/curseforge/images (the avatar, the banner and the charts); without it, prints the rsvg-convert commands to run. charts re-exports its two PNGs. charts: rewrites docs/assets/charts/{levels,starts}.svg. Scores the guides under the simulator's model (as `sim compare` does) against an earlier set of them; the best route found and the consensus route are drawn when the results in --sim were searched on the world being scored. --draft <dir|rev> the earlier guides: a guides folder, or a git revision whose guides/ is used. The README's charts use v0.1.0, the first release. --draft-label <text> how the charts name them (default: "Polestar <x.y.z>" for a release tag vX.Y.Z, else "Earlier guides") --sim <dir> simulator outputs: world, params, results, consensus (default data/sim) --guides <dir> the guides to score (default guides/) ``` ## polestar record Polestar Recorder sessions: import, watch, draft guides, measure routes (report) ```sh polestar record --help ``` ```output usage: node tools/polestar.js record <subcommand> [options] import Archive and convert the recorder's SavedVariables: raw copy -> data/recordings/raw/<timestamp>-<account>.lua, one JSON per session -> data/recordings/<session>.json (a session already on disk keeps the longer event list); --anonymize for a file a player sent in: no name or realm (a hash keys the character), no raw copy watch Import again whenever the client rewrites the file (keeps sessions safe from the cold-start SavedVariables reset) draft <session|file> Write a draft guide from a session key or JSON file to <pack>/drafts/<faction>-<race>-<date>-<time>.guide: the pack is --pack, else the nearest pack.json, else our guides/; another pack's draft id starts with "<pack id>/" list List imported sessions report Measure the guides from recorded play (Polestar + Recorder): per step passes, median/p75 time, XP, XP/hr, combat share, deaths, turn-ins, travel; per guide time, levels, XP/hr; the slowest steps, steps far over the guide's median step time, and detours (far travel for little XP) options: --sv <file> SavedVariables file to use (repeatable); skips auto-detection --wtf <dir> WTF folder to search (default: the detected Forever client's, e.g. <Wine prefix>/drive_c/Program Files (x86)/World of Warcraft/_forever_/WTF; POLESTAR_WTF overrides) --out <dir|file> import/watch/list: recordings folder (default data/recordings); draft: output .guide file or folder (default <pack>/drafts) --pack <dir> draft: the pack the draft belongs to --recordings <dir> draft/report: where sessions are read (default data/recordings) --interval <ms> watch: polling interval (default 1000) --force draft: overwrite an existing draft --anonymize import: drop character names and realms (see import) --guide <text> report: only guides whose id or title contains <text> --top <n> report: length of the ranked lists (default 10) --json report: print the report as JSON ``` ## polestar regen Regenerate committed files after merging contributor PRs (compile + i18n sync + preview + media) ```sh polestar regen --help ``` ```output usage: node tools/polestar.js regen [--no-compile] [--no-i18n] [--no-preview] [--no-media] Regenerates the four sets of committed generated files that contributors do not commit themselves: compile addon/Polestar_Guides/Guides.lua from guides/ and data/forever i18n sync locale files from the addon’s English strings preview docs/preview/*.svg from the addon’s Lua (no reference data) media addon/Polestar/Media/*.tga from tools/media/ (no reference data) compile needs the reference data (data/forever); the rest do not. Pass --no-<step> to skip a step. Run this after merging contributor PRs that touch guides/ or the addon’s Lua, and before every feature release. ``` ## polestar release Release tooling: patch scope check, patch preparation, release notes ```sh polestar release --help ``` ```output usage: node tools/polestar.js release <scope|patch|notes> [args] release scope [--base <ref>] [--root <dir>] [--files <path|->] Prints each changed path a patch release may not carry, one a line, and exits 1 if there is one. A patch may change only: guides/** addon/Polestar_Guides/** tests/guides-*.test.js tools/lib/data/corrections.json CHANGELOG.md changes/** The paths are read from --files (one a line, - for stdin; `git diff --name-status` lines work too), else from `git diff --name-only <base>...HEAD` in --root, renames giving both paths. --base defaults to the newest v* tag reachable from HEAD. release patch <x.y.z> --root <dir> [--from <tag>] [--zip <file>] [--data <dir>] [--data-built] Prepares a patch release on the hotfix/ checkout at --root with that checkout's own tools: stops on paths the patch may not carry, or on a changed tools/lib/data/corrections.json (run `data build` there first, then --data-built); puts back Polestar_Codex and Polestar_QuestDB from the release zip of --from (default the newest v* tag in --root; downloaded with gh unless --zip names it); sets the version; lints and compiles; and lists the compiled guides that differ from --from, warning about those whose sources did not change. --data <dir> reference data for lint and compile (default this checkout's data/forever/, or --root's with --data-built) release notes <x.y.z> [--root <dir>] [--out <dir>] Writes the version's CHANGELOG.md section as dist/notes-<v>.md (GitHub), dist/notes-curseforge-<v>.md and dist/notes-discord-<v>.txt. Each has a placeholder for the intro, marked [[REPLACE, to replace before publishing. --root <dir> folder holding CHANGELOG.md (default the repository) --out <dir> where to write (default <root>/dist/) ``` ## polestar sim simulate and optimize leveling routes (docs/SIMULATION.md) ```sh polestar sim --help ``` ```output usage: node tools/polestar.js sim <command> [options] sim world [--faction F] [--rebuild] build/cache the world model (data/sim/world-<faction>.json) sim walks [--faction F] [--radius Y] [--workers W] route the world's walks with the walking router (data/sim/walks-<faction>.json; run, robust, compare, bench and consensus use them) sim calibrate [--fdj DIR] fit parameters to quest data and recordings sim run --faction F [--race R] [--class C] [--paths N] [--workers W] [--seed S] [--dungeons] [--jobs J] [--anneal A] [--max-paths M] [--objective time|smooth] [--param K=V ...] [--tag T] sim robust --faction F [--race R] [--class C] [--draws K] [--top N] [--objective O] robustness of the top routes sim compare --faction F [--race R] [--class C] [--guides DIR] [--pack DIR | DIR] [--to 10,20,30] [--with-optional] [--objective O] Polestar's routes vs the best found, same model sim bench --faction F [--race R] [--class C] bracket table: zones, levels, quests per 10 levels sim export --result <file> --out <dir> zone-by-zone skeleton guides + visits.json for authors sim consensus --faction F [--dungeons] [--evals N] [--objective O] one 12-60 route shared by the faction's starts (+ exports) Without --race, run/robust/compare/bench cover every start of the faction (Horde: Orc, Tauren, Undead, Skyborne; Alliance: Human, Dwarf, NightElf, Skyborne). Class defaults to none ("any": class quests excluded, class factor 1); with --class the class's quests and kill-speed prior are used, and compare/bench write their own files so the class-agnostic ones stay. options: --data <dir> reference data (default data/forever) --sim <dir> simulator outputs (default data/sim) --fdj <dir> calibrate: ForeverDungeonJournal folder (default: the installed one) --class <name> Warrior, Paladin, Hunter, Rogue, Priest, Shaman, Mage, Warlock or Druid: score for that class (run/robust/compare/bench); default none ("any") --band <levels> level width of the world's quest packages (default 5; a new width rebuilds the world) --guides <dir> compare: Polestar guides folder to score (default guides/), e.g. an old copy --pack <dir> compare: also score this pack's chain (or name the pack folder as the one argument; default: the nearest pack.json); after our chain up to its first level when it starts above 1; written to data/bench/compare-<faction>-<race>-<pack id>.json --to <levels> compare: levels to show time to (default 10,20,30,40,50,60) --with-optional compare/bench: also score the guides' optional goals (default: only what a guide requires; elite and dungeon quests stay out either way) --jobs <n> run: search jobs per round (default 32) --anneal <n> run: annealing evaluations per job (default 6000) --max-paths <n> run: hard cap on evaluated routes (default 3x --paths) --dungeons run/robust/consensus: the dungeon-inclusive family (needs data/forever/dungeons.json) --objective <o> run/robust/compare/consensus: what the search optimises (default time): time = the fastest route; smooth = fewer zone changes, returns into zones left earlier and returns to spots already worked (docs/SIMULATION.md); smooth results are their own files (horde-orc-any-smooth.json) --param <k=v> run/robust/compare/consensus: set a model parameter (params.js), after the objective's preset; repeatable (--param grindWeight=6 --param zoneReturn=0) --tag <name> run/robust/compare/consensus: a result file variant, e.g. --tag g6 writes horde-orc-any-smooth-g6.json (and robust/compare/consensus read and write it) --radius <yards> walks: route every pair of points up to this far apart (default 4000) --no-walks run/robust/compare/bench/consensus: walk the straight line × detour even when data/sim/walks-<faction>.json is there --offline never download the QuestXP table --quiet less output ``` ## polestar talents Build or check Talents/Builds.lua (talent plans) ```sh polestar talents --help ``` ```output usage: node tools/polestar.js talents build|check [options] Resolves the talent plans in talents/forever/*.json (one file per class, one pick per level, by talent name) against the Forever client's trait tables (<tables>, build 1.60.1.70450, cached under data/sources/<tables>/), replays every pick under the client's rules (one point a level from 10, tier gates, arrows; arrows need their source at full rank), and writes every class into addon/Polestar/Talents/Builds.lua. check rebuilds in memory and fails if the file differs or a plan breaks a rule. options: --plans <dir> plan sources (default talents/forever/) --out <dir> output folder (default addon/Polestar/Talents/) --sources <dir> download cache (default data/sources/) --build <ver> client build (default 1.60.1.70450) --offline use cached tables only ``` ## polestar trainers Build trainers.json and Core/ClassTrainers.lua (class trainers) ```sh polestar trainers --help ``` ```output usage: node tools/polestar.js trainers build [options] Builds data/forever/trainers.json, the class trainers `train class` picks from: every `train <npcId> only <Class>` goal under guides/, recorded trainer visits in data/recordings (by the recording character's class), and Polestar's curated list of capital and starting-town trainers, each verified by name and map against npcs.json. Without the file, compile uses the curated list alone. Also writes addon/Polestar/Core/ClassTrainers.lua: one trainer per town and class, with positions and map frames, for the class-training reminder, and every class trainer's npc id by class, for Engine.IsClassTrainer. options: --guides <dir> guide sources (default guides/) --data <dir> reference data, also the output folder (default data/forever/) --recordings <dir> normalized recordings (default data/recordings/) --out <file> output file (default <data>/trainers.json) --lua <file> Lua output (default addon/Polestar/Core/ClassTrainers.lua) ``` ## polestar travel Build the travel network (flights, boats, inns, learned paths, zone crossings), import zone crossings, test routes and draft approach chains from recordings ```sh polestar travel --help ``` ```output usage: node tools/polestar.js travel build [options] node tools/polestar.js travel route --from <map,x,y> --to <map,x,y> [options] node tools/polestar.js travel chain --to <map,x,y> [options] node tools/polestar.js travel import --<crossings> <ZoneConnections.lua> --source <text> [options] build: the flight network (Blizzard Classic Era TaxiNodes/TaxiPath/TaxiPathNode via <tables>), boats/zeppelins/tram (plus the ships WoW Forever added, from the Forever client's TaxiPathNode), inns, learned walking paths and zone crossings learned from recordings -> data/forever/travel.json, addon/Polestar/Nav/TravelData.lua and the flights' tracks in addon/Polestar/Maps/FlightPaths.lua. The shipped crossings file (tools/lib/travel/crossings.json, from "travel import") goes into TravelData.lua. With the optional local crossings file (data/local/crossings.json, validated) it also writes the local data addon addon/Polestar_Travel (installed when built, never packaged). --offline use cached <tables> tables only --build <version> Classic Era build (default: newest listed) --forever-build <v> WoW Forever build (default: newest 1.60+ listed) --data <dir> data/forever (map-frames, zones, npcs, objects) --recordings <dir> data/recordings --sources <dir> data/sources (<tables> cache) --shipped <file> the shipped crossings file (default: tools/lib/travel/crossings.json; "none" to leave it out) --grid <dir> the navigation grid (default: data/local/nav4; "none" to leave it out): a ship's end lying in the water gets a board point, the nearest dry deck within 30 yd; without a grid, none --crossings <file> the local crossings file (default: <data>/../local/crossings.json) --travel-addon <dir> Polestar_Travel output (default: addon/Polestar_Travel) --json <file> travel.json output (default: <data>/travel.json) --lua <file> TravelData.lua output (default: addon/Polestar/Nav/TravelData.lua) --flight-lua <file> FlightPaths.lua output (default: addon/Polestar/Maps/FlightPaths.lua; with --lua, FlightPaths.lua beside that file) route: run the addon's own planner (Nav/Travel.lua + TravelData.lua, plus Polestar_Travel when built) under Lua 5.1 between two Era-frame map points and print the legs. --from <map,x,y> start (uiMapID, map percent) --to <map,x,y> target --faction <name> Alliance | Horde (default Alliance) --known <ids|names> flight master node ids or names; repeatable, or separated by ";" or "," ("Sentinel Hill, Westfall" matches the full node name first) --speed <yd/s> run speed (default 7) --hearth <location> bind location, Hearthstone ready --data <dir> data/forever (map-frames, zones, travel.json) --lua <file> TravelData.lua (default: addon/Polestar/Nav/TravelData.lua) --crossings-lua <f> Polestar_Travel's Crossings.lua (default: addon/Polestar_Travel/Crossings.lua when built; "none" to skip) --json print the legs as JSON chain: a candidate approach chain (a cave, a climb) for the local crossings file, from the recorded walks that reach a target: where each walk leaves the straight line to the target, and the walked path from there simplified into nodes with radii and a first caption. Walks from several sides meet at the mouth, so the shortest chain is printed. A walk that keeps to the straight line is reported but does not stop the draft (recordings have no height: it may have followed the arrow onto the hill above a cave). Check it in game before using it. --to <map,x,y> the target (uiMapID, Era map percent) --name <text> the place ("Fargodeep Mine"): the chain's name, id and first caption --id <id> the chain's id (default: from --name, else recorded-chain-<map>-<x>-<y>) --within <yd> how far back from the target a walk is followed; shorter walks do not count (default 300) --tolerance <yd> how far the walk may stray from the line between two nodes (default 8) --session <id> draft from this session's walks only (repeatable) --reverse count each walk's way out, reversed, as a way in too --data <dir> data/forever (map-frames, zones) --recordings <dir> data/recordings --json print only the chain entry import: the shipped crossings file from <crossings>'s Classic Era zone connections (<crossings>/Data/classic/ZoneConnections.lua in github.com/IrcDirk/<crossings>-Classic, GPL-3.0): its walks between zones (two-way unless marked one way), validated, with the arrival radius given. The open borders of the file it replaces (from the navigation grid, not <crossings>) are kept. --<crossings> <file> <crossings>'s ZoneConnections.lua --source <text> where it came from (repository and commit), kept in the file --radius <yd> arrival radius of every end (default 30) --data <dir> data/forever (map-frames, zones) --out <file> output (default: tools/lib/travel/crossings.json) ``` ## polestar version Show or set the release version (package.json, guides/pack.json and addon TOCs) ```sh polestar version --help ``` ```output usage: node tools/polestar.js version [<x.y.z>] [options] Without a version, prints package.json's version and names guides/pack.json or any addon TOC whose version differs (exit 1 if one does). With one, writes it to package.json, to guides/pack.json (compile takes Polestar_Guides' version from it) and to the ## Version line of every addon/<Name>/<Name>.toc present. Data addons built later take the version from package.json. options: --root <dir> folder holding package.json (default the repository) --addons <dir> addon folder (default <root>/addon/) ``` --- # Security > How to report a security problem privately, what counts as one, and the supported versions. Page: https://polestar.guide/docs/reference/security (Polestar docs > Reference) ## Reporting a problem Report a security problem privately: on GitHub, open the repository's **Security** tab and choose **Report a vulnerability**. Please don't open a public issue or post it on Discord, so players are not exposed while it is being fixed. Say what you found, which version or commit, and how to see it happen. You get a reply in the report itself; the fix and a credit (unless you'd rather not be named) go in the changelog once it ships. ## What counts - **The addon acting against the player**: mail, trade, the auction house, the guild bank, buying or spending without the player asking; chat or addon messages sent on its own; anything that runs code it was sent. - **Community addons, guides and data**: a guide, data or locale file that gets the addon to run code, open a link or act for the player. - **The toolchain**: a command that runs code from a pack, a pull request or a downloaded file, or reads or writes outside the repository and its data folders. - **The project's automation**: the GitHub workflows, the Discord bot and its tokens. - **A fake Polestar**: a download that claims to be Polestar or one of its addons but is not from this repository's releases or its CurseForge project. A wrong step, a Lua error or a crash is a normal bug: use the issue forms or Discord (CONTRIBUTING.md). ## Supported versions The latest release, and `next` before it ships. Fixes go into a patch of the latest release when they can (docs/RELEASING.md, "Patch releases"). --- # License exception > The permission to distribute a compiled community guide or an import string under terms of your choice. Page: https://polestar.guide/docs/reference/license-exception (Polestar docs > Reference) Polestar is licensed under the GNU General Public License version 3 ([LICENSE](https://github.com/fitzforge/polestar/blob/next/LICENSE)), with this additional permission: > Additional permission under GNU GPL version 3 section 7: as a special > exception, the copyright holders of Polestar give you permission to > distribute guide packs produced by Polestar's compiler, and import strings > produced by Polestar's tools, including the parts of Polestar's reference > data that the compiler or those tools place in them, under terms of your > choice. This permission does not cover guide text copied from Polestar's > own guides, or Polestar's code. --- # Alliance leveling guide 1–60 (every race) > Every Alliance race's leveling road in Polestar, from its start zone to level 60: 4 starts, then 25 guides every Alliance race shares. Page: https://polestar.guide/guides/alliance Polestar is a free, open-source (GPL-3.0) leveling guide addon for World of Warcraft: Forever. Every guide here ships inside the addon: in game, `/polestar guides` opens the guide menu, and the guide window shows the steps with a waypoint arrow. The Alliance races start in 4 places: Elwynn Forest (Human), Dun Morogh (Dwarf and Gnome), Teldrassil (Night Elf) and Zephras Isle (Skyborne). From there every Alliance race takes the same road: 25 guides from Westfall (levels 12–17) to level 60. Which guide for a level: find the guide whose levels hold the character's level on the road below (the start guides first if the character is still in its start zone). In game, Polestar opens a guide for the character's race, level and zone at login, and `/polestar guides` lists every guide. ## Starts ### Human (levels 1–13) - [Elwynn Forest](https://polestar.guide/guides/alliance/human/01-elwynn-forest.md) (levels 1–13): 99 quests, 73 steps, hearth at Goldshire - Then [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17), where the Alliance road meets. ### Dwarf and Gnome (levels 1–13) - [Dun Morogh](https://polestar.guide/guides/alliance/dwarf-gnome/01-dun-morogh.md) (levels 1–13): 102 quests, 84 steps, hearth at Thunderbrew Distillery - Then [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17), where the Alliance road meets. ### Night Elf (levels 1–11) - [Teldrassil](https://polestar.guide/guides/alliance/nightelf/01-teldrassil.md) (levels 1–11): 79 quests, 51 steps, hearth at Dolanaar - Then [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17), where the Alliance road meets. ### Skyborne (levels 1–15) - [Zephras Isle](https://polestar.guide/guides/alliance/skyborne/01-zephras-isle.md) (levels 1–15): 108 quests, 61 steps - Then [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17), where the Alliance road meets. ## The road to 60 - [Westfall](https://polestar.guide/guides/alliance/02-westfall.md) (levels 12–17): 27 quests, 21 steps, hearth at Sentinel Hill - [Darkshore](https://polestar.guide/guides/alliance/03-darkshore.md) (levels 16–21): 77 quests, 43 steps, hearth at Auberdine - [Redridge Mountains](https://polestar.guide/guides/alliance/04-redridge-mountains.md) (levels 20–23): 22 quests, 20 steps, hearth at Lakeshire - [Duskwood](https://polestar.guide/guides/alliance/05-duskwood.md) (levels 22–26): 29 quests, 29 steps, hearth at Darkshire - [Ashenvale, Wetlands & Stonetalon Mountains](https://polestar.guide/guides/alliance/06-ashenvale.md) (levels 25–29): 56 quests, 66 steps, hearth at Astranaar, then Deepwater Tavern - [Thousand Needles, Duskwood & Wetlands](https://polestar.guide/guides/alliance/07-thousand-needles.md) (levels 28–31): 39 quests, 36 steps, hearth at Darkshire, then Deepwater Tavern - [Wetlands, Hillsbrad Foothills, Ironforge & Stormwind City](https://polestar.guide/guides/alliance/30-40/01-hillsbrad-foothills.md) (levels 30–33): 40 quests, 37 steps, hearth at Southshore - [Desolace](https://polestar.guide/guides/alliance/30-40/02-desolace.md) (levels 31–34): 11 quests, 22 steps, hearth at Nijel's Point - [Ashenvale & Wetlands](https://polestar.guide/guides/alliance/30-40/03-ashenvale.md) (levels 33–35): 24 quests, 34 steps, hearth at Astranaar - [Stranglethorn Vale](https://polestar.guide/guides/alliance/30-40/04-stranglethorn-vale.md) (levels 34–38): 40 quests, 36 steps, hearth at Booty Bay - [Arathi Highlands, Alterac Mountains & Swamp of Sorrows](https://polestar.guide/guides/alliance/30-40/05-arathi-highlands.md) (levels 37–40): 40 quests, 48 steps, hearth at Southshore, then Stoutlager Inn - [Badlands & Desolace](https://polestar.guide/guides/alliance/30-40/06-badlands.md) (levels 39–41): 27 quests, 39 steps, hearth at Nijel's Point - [Stranglethorn Vale, Dustwallow Marsh & Swamp of Sorrows](https://polestar.guide/guides/alliance/40-50/01-stranglethorn-vale.md) (levels 40–43): 53 quests, 52 steps, hearth at Theramore Isle, then Booty Bay, then Stormwind - [Badlands & The Hinterlands](https://polestar.guide/guides/alliance/40-50/02-badlands.md) (levels 43–44): 9 quests, 18 steps - [Feralas](https://polestar.guide/guides/alliance/40-50/03-feralas.md) (levels 43–46): 28 quests, 26 steps, hearth at Feathermoon Stronghold - [Tanaris](https://polestar.guide/guides/alliance/40-50/04-tanaris.md) (levels 45–47): 25 quests, 24 steps, hearth at Gadgetzan, then Aerie Peak - [The Hinterlands, Blasted Lands & Loch Modan](https://polestar.guide/guides/alliance/40-50/05-the-hinterlands.md) (levels 46–48): 15 quests, 20 steps, hearth at Aerie Peak, then Stoutlager Inn - [Searing Gorge](https://polestar.guide/guides/alliance/40-50/06-searing-gorge.md) (levels 47–49): 14 quests, 14 steps, hearth at Stoutlager Inn - [Un'Goro Crater & Ironforge](https://polestar.guide/guides/alliance/40-50/07-un-goro-crater.md) (levels 48–52): 34 quests, 45 steps, hearth at Stoutlager Inn, then Ironforge - [Burning Steppes, Azshara & Blasted Lands](https://polestar.guide/guides/alliance/50-60/01-burning-steppes.md) (levels 51–53): 18 quests, 38 steps, hearth at Ironforge - [Felwood](https://polestar.guide/guides/alliance/50-60/02-felwood.md) (levels 52–54): 21 quests, 20 steps, hearth at Everlook - [Winterspring & Eastern Plaguelands](https://polestar.guide/guides/alliance/50-60/03-winterspring.md) (levels 53–55): 31 quests, 32 steps, hearth at Everlook, then Light's Hope Chapel - [Western Plaguelands, Eastern Plaguelands & Feralas](https://polestar.guide/guides/alliance/50-60/04-western-plaguelands.md) (levels 54–57): 64 quests, 64 steps, hearth at Light's Hope Chapel, then Ratchet - [Silithus, Un'Goro Crater & Eastern Plaguelands](https://polestar.guide/guides/alliance/50-60/05-silithus.md) (levels 56–58): 34 quests, 27 steps, hearth at Cenarion Hold, then Ratchet - [Silithus, Felwood, Winterspring & the Plaguelands](https://polestar.guide/guides/alliance/50-60/06-silithus.md) (levels 57–60): 34 quests, 56 steps, hearth at Ratchet, then Cenarion Hold, then Stormwind Each class's talent plans, class quests and gear: https://polestar.guide/guides/class.md --- Index for language models: https://polestar.guide/llms.txt --- # Horde leveling guide 1–60 (every race) > Every Horde race's leveling road in Polestar, from its start zone to level 60: 4 starts, then 23 guides every Horde race shares. Page: https://polestar.guide/guides/horde Polestar is a free, open-source (GPL-3.0) leveling guide addon for World of Warcraft: Forever. Every guide here ships inside the addon: in game, `/polestar guides` opens the guide menu, and the guide window shows the steps with a waypoint arrow. The Horde races start in 4 places: Durotar (Orc and Troll), Mulgore (Tauren), Tirisfal Glades (Undead) and Zephras Isle (Skyborne). From there every Horde race takes the same road: 23 guides from The Barrens (levels 12–17) to level 60. Which guide for a level: find the guide whose levels hold the character's level on the road below (the start guides first if the character is still in its start zone). In game, Polestar opens a guide for the character's race, level and zone at login, and `/polestar guides` lists every guide. ## Starts ### Orc and Troll (levels 1–17) - [Durotar](https://polestar.guide/guides/horde/orc-troll/01-durotar.md) (levels 1–12): 80 quests, 67 steps, hearth at Razor Hill, then The Crossroads - [The Barrens](https://polestar.guide/guides/horde/orc-troll/02-the-barrens.md) (levels 11–17): 34 quests, 38 steps, hearth at Ratchet, then The Crossroads - Then [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17), where the Horde road meets. ### Tauren (levels 1–12) - [Mulgore](https://polestar.guide/guides/horde/tauren/01-mulgore.md) (levels 1–12): 70 quests, 59 steps, hearth at Bloodhoof Village, then Crossroads - Then [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17), where the Horde road meets. ### Undead (levels 1–13) - [Tirisfal Glades](https://polestar.guide/guides/horde/undead/01-tirisfal-glades.md) (levels 1–13): 70 quests, 70 steps, hearth at Gallows' End Tavern, then The Crossroads - Then [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17), where the Horde road meets. ### Skyborne (levels 1–15) - [Zephras Isle](https://polestar.guide/guides/horde/skyborne/01-zephras-isle.md) (levels 1–15): 111 quests, 84 steps, hearth at The Crossroads - Then [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17), where the Horde road meets. ## The road to 60 - [The Barrens](https://polestar.guide/guides/horde/02-the-barrens.md) (levels 12–17): 38 quests, 41 steps, hearth at The Crossroads - [Silverpine Forest & Orgrimmar](https://polestar.guide/guides/horde/03-silverpine-forest.md) (levels 16–20): 35 quests, 37 steps, hearth at Sepulcher - [The Barrens](https://polestar.guide/guides/horde/04-the-barrens.md) (levels 19–24): 75 quests, 76 steps, hearth at Crossroads, then Camp Taurajo - [Stonetalon Mountains & Ashenvale](https://polestar.guide/guides/horde/05-stonetalon-mountains.md) (levels 23–25): 22 quests, 28 steps, hearth at Splintertree Post, then Sun Rock Retreat, then Tarren Mill - [Hillsbrad Foothills, Undercity & The Barrens](https://polestar.guide/guides/horde/06-hillsbrad-foothills.md) (levels 24–28): 22 quests, 29 steps, hearth at Tarren Mill, then Camp Taurajo - [Ashenvale & Thousand Needles](https://polestar.guide/guides/horde/07-ashenvale.md) (levels 27–31): 47 quests, 47 steps, hearth at Splintertree Post, then Freewind Post - [Desolace & Hillsbrad Foothills](https://polestar.guide/guides/horde/30-40/01-desolace.md) (levels 30–33): 31 quests, 49 steps, hearth at Tarren Mill - [Stranglethorn Vale](https://polestar.guide/guides/horde/30-40/02-stranglethorn-vale.md) (levels 32–38): 32 quests, 44 steps, hearth at Grom'gol Base Camp, then Booty Bay - [Arathi Highlands, Badlands & The Barrens](https://polestar.guide/guides/horde/30-40/03-arathi-highlands.md) (levels 37–40): 33 quests, 53 steps, hearth at Hammerfall, then Kargath, then Ratchet - [Dustwallow Marsh & Desolace](https://polestar.guide/guides/horde/30-40/04-dustwallow-marsh.md) (levels 39–41): 25 quests, 32 steps, hearth at Ratchet, then Shadowprey Village - [Stranglethorn Vale & Swamp of Sorrows](https://polestar.guide/guides/horde/40-50/01-stranglethorn-vale.md) (levels 40–43): 31 quests, 40 steps, hearth at Grom'gol Base Camp, then Booty Bay - [Feralas & Tanaris](https://polestar.guide/guides/horde/40-50/02-feralas.md) (levels 42–44): 32 quests, 38 steps, hearth at Camp Mojache - [Feralas, Dustwallow Marsh & Swamp of Sorrows](https://polestar.guide/guides/horde/40-50/03-feralas.md) (levels 44–46): 26 quests, 31 steps, hearth at Stonard, then Camp Mojache - [Tanaris & Searing Gorge](https://polestar.guide/guides/horde/40-50/04-tanaris.md) (levels 45–48): 27 quests, 32 steps, hearth at Gadgetzan - [The Hinterlands & Blasted Lands](https://polestar.guide/guides/horde/40-50/05-the-hinterlands.md) (levels 47–50): 26 quests, 30 steps, hearth at Revantusk Village - [Azshara, Feralas & Stranglethorn Vale](https://polestar.guide/guides/horde/40-50/06-azshara.md) (levels 49–51): 35 quests, 38 steps, hearth at Camp Mojache, then Gadgetzan - [Un'Goro Crater, Eastern Plaguelands & Burning Steppes](https://polestar.guide/guides/horde/50-60/01-un-goro-crater.md) (levels 50–53): 47 quests, 56 steps, hearth at Light's Hope Chapel - [Felwood & Western Plaguelands](https://polestar.guide/guides/horde/50-60/02-felwood.md) (levels 52–54): 45 quests, 48 steps, hearth at Everlook - [Winterspring & Feralas](https://polestar.guide/guides/horde/50-60/03-winterspring.md) (levels 54–56): 31 quests, 32 steps, hearth at Everlook, then Orgrimmar - [Azshara, The Barrens & Undercity](https://polestar.guide/guides/horde/50-60/04-azshara.md) (levels 55–57): 15 quests, 21 steps - [Eastern Plaguelands, Winterspring & Tanaris](https://polestar.guide/guides/horde/50-60/05-eastern-plaguelands.md) (levels 56–58): 16 quests, 31 steps, hearth at Light's Hope Chapel, then Thunder Bluff - [Silithus, Western Plaguelands & Eastern Plaguelands](https://polestar.guide/guides/horde/50-60/06-silithus.md) (levels 57–59): 29 quests, 42 steps, hearth at Cenarion Hold - [Felwood, Moonglade & Winterspring](https://polestar.guide/guides/horde/50-60/07-felwood.md) (levels 58–60): 5 quests, 17 steps Each class's talent plans, class quests and gear: https://polestar.guide/guides/class.md --- Index for language models: https://polestar.guide/llms.txt --- # Class leveling guides for WoW: Forever > Each of the 9 classes in Polestar: who can play it, its leveling talent plans, its class quests and its gear advice. Page: https://polestar.guide/guides/class Polestar is a free, open-source (GPL-3.0) leveling guide addon for World of Warcraft: Forever. Every guide here ships inside the addon: in game, `/polestar guides` opens the guide menu, and the guide window shows the steps with a waypoint arrow. - [Warrior](https://polestar.guide/guides/class/warrior.md): Arms, Fury, Protection talent plans; Level as Arms with a two-hander (Mortal Strike, Sweeping Strikes) or Fury (Enrage, Death Wish, then Flurry and Bloodthirst with two weapons). Protection is slower alone but ready to tank any dungeon on the way. - [Paladin](https://polestar.guide/guides/class/paladin.md): Holy, Protection, Retribution talent plans; Level as Retribution (quickest solo, with a two-hander and Seal of Command) or Protection (safe group pulls, dungeon-tank ready). Holy suits raids; it can level through its melee build, more slowly, if you want to heal dungeons on the way. - [Hunter](https://polestar.guide/guides/class/hunter.md): Beast Mastery, Marksmanship, Survival talent plans; Level as Beast Mastery: your pet tanks and does much of the damage, so you rarely stop. Marksmanship hits harder from range with Careful Aim and Sniper Shot; Survival fights in melee with Predator's Edge and Lacerating Strikes. - [Rogue](https://polestar.guide/guides/class/rogue.md): Assassination, Combat, Subtlety talent plans; Level as Combat with a sword (Riposte, Blade Flurry, Adrenaline Rush) for the steadiest kills, or Assassination with daggers and poisons (Mutilate). Subtlety's Hemorrhage plan suits stealth openers and is slower solo. - [Priest](https://polestar.guide/guides/class/priest.md): Discipline, Holy, Shadow talent plans; Level as Shadow (Spirit Tap, Mind Flay, Shadowform) for the fastest kills and least drinking. Discipline levels with Smite and Penance behind a strong shield; Holy is the dungeon healer and slower alone. - [Shaman](https://polestar.guide/guides/class/shaman.md): Elemental, Enhancement, Restoration talent plans; Level as Enhancement (Flurry, Stormstrike, Maelstrom Weapon) for steady melee with few rests, or Elemental (Lightning Overload, Lava Burst) to kill from range. Restoration heals dungeons well and levels slowly alone. - [Mage](https://polestar.guide/guides/class/mage.md): Arcane, Fire, Frost talent plans; Level as Frost (the safest: slows, freezes and Ice Barrier) or Fire (more damage, with Pyroblast openers and Blast Wave). Arcane builds around Arcane Blast and Arcane Power and wants more mana between pulls. - [Warlock](https://polestar.guide/guides/class/warlock.md): Affliction, Demonology, Destruction talent plans; Level as Affliction (instant Corruption, Siphon Life, drains) or Demonology (a tougher Voidwalker, Soul Link) for the fewest deaths. Destruction hits hardest with Conflagrate and Incinerate but needs more rest. - [Druid](https://polestar.guide/guides/class/druid.md): Balance, Feral Combat, Restoration talent plans; Level as Feral Combat: Cat Form for quick kills, Bear Form for tough pulls, and no drinking. Balance kills from range with roots and Starfire; Restoration heals any dungeon and quests slowly with Wrath. --- Index for language models: https://polestar.guide/llms.txt --- # Not in this file The pages for contributors to Polestar itself, the release notes and the credits, each as Markdown: - [Overview](https://polestar.guide/docs/contributors.md) - [Contributing](https://polestar.guide/docs/contributors/contributing.md) - [Building from source](https://polestar.guide/docs/contributors/building.md) - [From source to game](https://polestar.guide/docs/contributors/source-to-game.md) - [Map and glossary](https://polestar.guide/docs/contributors/docs-map.md) - [Architecture](https://polestar.guide/docs/contributors/architecture.md) - [Core](https://polestar.guide/docs/contributors/architecture/core.md) - [Theme](https://polestar.guide/docs/contributors/architecture/theme.md) - [Nav](https://polestar.guide/docs/contributors/architecture/nav.md) - [Quests](https://polestar.guide/docs/contributors/architecture/quests.md) - [Gear](https://polestar.guide/docs/contributors/architecture/gear.md) - [Maps](https://polestar.guide/docs/contributors/architecture/maps.md) - [QoL](https://polestar.guide/docs/contributors/architecture/qol.md) - [Lookup](https://polestar.guide/docs/contributors/architecture/lookup.md) - [Dungeons](https://polestar.guide/docs/contributors/architecture/dungeons.md) - [UI](https://polestar.guide/docs/contributors/architecture/ui.md) - [Rares](https://polestar.guide/docs/contributors/architecture/rares.md) - [Talents](https://polestar.guide/docs/contributors/architecture/talents.md) - [Toolchain](https://polestar.guide/docs/contributors/architecture/toolchain.md) - [Tests](https://polestar.guide/docs/contributors/architecture/tests.md) - [The addon, file by file](https://polestar.guide/docs/contributors/addon.md) - [The toolchain](https://polestar.guide/docs/contributors/tools.md) - [The tests](https://polestar.guide/docs/contributors/tests.md) - [The suite](https://polestar.guide/docs/contributors/suite.md) - [Route simulation](https://polestar.guide/docs/contributors/simulation.md) - [Design system](https://polestar.guide/docs/contributors/design.md) - [Agent workflows](https://polestar.guide/docs/contributors/workflows.md) - [Contributing (agent)](https://polestar.guide/docs/contributors/workflows/contributing.md) - [Triaging a report](https://polestar.guide/docs/contributors/workflows/triage.md) - [Fixing a guide step](https://polestar.guide/docs/contributors/workflows/guide-fix.md) - [Releasing](https://polestar.guide/docs/contributors/releasing.md) - [The CurseForge listing](https://polestar.guide/docs/contributors/releasing/curseforge.md) - [Changelog](https://polestar.guide/docs/reference/changelog.md) - [Release notes, Polestar 0.2.6](https://polestar.guide/docs/reference/changelog/0-2-6.md) - [Release notes, Polestar 0.2.5](https://polestar.guide/docs/reference/changelog/0-2-5.md) - [Release notes, Polestar 0.2.4](https://polestar.guide/docs/reference/changelog/0-2-4.md) - [Release notes, Polestar 0.2.3](https://polestar.guide/docs/reference/changelog/0-2-3.md) - [Release notes, Polestar 0.2.2](https://polestar.guide/docs/reference/changelog/0-2-2.md) - [Release notes, Polestar 0.2.1](https://polestar.guide/docs/reference/changelog/0-2-1.md) - [Release notes, Polestar 0.2.0](https://polestar.guide/docs/reference/changelog/0-2-0.md) - [Release notes, Polestar 0.1.0](https://polestar.guide/docs/reference/changelog/0-1-0.md) - [Credits & data sources](https://polestar.guide/docs/reference/credits.md)