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

> **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: &lt;your title&gt;", with the line
"Community addon for Polestar by &lt;author&gt;" 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 <file.guide>` | `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 <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"](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).

---

Next page: [Handbook](https://polestar.guide/docs/authors/handbook.md) · Every docs page: https://polestar.guide/llms.txt · All docs in one file: https://polestar.guide/llms-full.txt