Writing a community guide

What you get#

If you write leveling guides, you can use everything Polestar uses for its own:

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" has the install command for each system.

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

What a pack looks like#

A community addon is built from a pack: a folder with a pack.json and your .guide files.

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

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

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 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 <text> 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/<folder>-<version>.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.

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.

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.

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 <pack> (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". Strings are covered by the same license exception as community addons.

Where to go next#

Questions, or a community addon to show? Players and authors meet on the Polestar Discord (opens in a new tab).