Overview

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:

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 and follow its five steps:

1. Id and title. The id names the addon folder (PolestarPack_<id>) 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, 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#

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.

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, 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:

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

git tag -a v1.2.0 -m "What changed in this version"
git push origin v1.2.0

Where to go next#