Community guide format

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) and polestar compile writes the rest. The handbook is PACKS.md.

On this page: pack.json · The addon · TOC fields · Rules Polestar enforces · Format 3 · Format 4 · Import strings · 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.

{
	"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"
}

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:

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

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:

{ title = "Back to Gornek", when = { { k = "onquest", q = { 788 } }, { k = "level", op = "<", n = 6 } }, goals = { ... } }

{ title = "Boars on the way", along = "camp", goals = { ... } },
{ title = "Goldshire", goals = { ... } },
{ title = "Back at the camp", label = "camp", goals = { ... } },

RegisterPack(meta)#

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",
})

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.

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" },
		} },
	},
})

RegisterMapFrames(frames, packId)#

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.

!PS1!<checksum>!<body>

{ "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 } } }

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