Guide format

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").

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:

! 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.

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

  In this exampleKobold Vermin6Kobold Camp Cleanup7

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").

• 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.

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:

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.