From 7ba0c961a195c803237c87a45c6098f274be41ab Mon Sep 17 00:00:00 2001 From: Brandon Cook Date: Sat, 6 Jun 2026 18:09:14 +1000 Subject: [PATCH 1/2] docs: add get-started guide + embedding docs package Add docs/get-started.md, an author-facing getting-started guide written terminal-first (hard-wrapped at <=76 columns, no HTML/images/wide tables) so it renders cleanly in an 80x24 SSH TUI: quickstart with shellcade-kit new/check/play, publishing to the public games catalog, and linking GitHub over SSH. Add the docs package that embeds it as docs.GetStarted for the arcade's "Add your own game" screen, plus a minor changeset. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/get-started-doc.md | 10 +++++ docs/docs.go | 17 +++++++++ docs/get-started.md | 70 +++++++++++++++++++++++++++++++++++ 3 files changed, 97 insertions(+) create mode 100644 .changeset/get-started-doc.md create mode 100644 docs/docs.go create mode 100644 docs/get-started.md diff --git a/.changeset/get-started-doc.md b/.changeset/get-started-doc.md new file mode 100644 index 0000000..f5d4d59 --- /dev/null +++ b/.changeset/get-started-doc.md @@ -0,0 +1,10 @@ +--- +"kit": minor +--- + +docs: export the getting-started guide via the new `docs` package. A new +author-facing `docs/get-started.md` (terminal-first, hard-wrapped at <=76 +columns) covers the quickstart (`shellcade-kit new` / `check` / `play`), +publishing to the public games catalog, and linking GitHub over SSH. The +new `docs` package embeds it as `docs.GetStarted` so the shellcade arcade +can render it directly in its "Add your own game" screen. diff --git a/docs/docs.go b/docs/docs.go new file mode 100644 index 0000000..6a95298 --- /dev/null +++ b/docs/docs.go @@ -0,0 +1,17 @@ +// Package docs embeds the author-facing getting-started guide so the +// shellcade arcade can render it directly in its "Add your own game" +// screen — a glamour-rendered Markdown pane inside an 80x24 SSH TUI. +// +// Because of that 80x24 budget, get-started.md is authored terminal-first: +// prose is hard-wrapped at <=76 columns and avoids HTML, images, and wide +// tables. Keep it that way when editing — anything wider clips or wraps +// badly in the pager. +package docs + +import _ "embed" + +// GetStarted is the rendered-ready Markdown of the author getting-started +// guide (get-started.md), embedded at build time. +// +//go:embed get-started.md +var GetStarted string diff --git a/docs/get-started.md b/docs/get-started.md new file mode 100644 index 0000000..7fef586 --- /dev/null +++ b/docs/get-started.md @@ -0,0 +1,70 @@ +# Get started with shellcade + +A shellcade game is a small WebAssembly plugin that draws to a fixed +80x24 terminal canvas. You write it in Go (or Rust) against this kit, +test it locally with no wasm and no network, compile it to wasm, and +submit the artifact — the arcade hosts it sandboxed and reachable over +SSH at shellcade.com. + +## Quickstart + +Grab the one author tool, `shellcade-kit` (scaffold, verify, play), from +this repo's Releases: + + https://github.com/shellcade/kit/releases + +(macOS may quarantine the download: +`xattr -d com.apple.quarantine shellcade-kit` clears it.) + +Scaffold a game and play it in your terminal — the inner loop is a plain +Go program (debugger, prints, sub-second builds), no wasm required: + + shellcade-kit new mygame + cd mygame && go mod tidy && go run . + +Edit `main.go`, run `go run .` again, and you are iterating. When you +want the real artifact, build the wasm and check it against the same +gate the arcade runs, then play that artifact on the production engine: + + shellcade-kit check game.wasm + shellcade-kit play game.wasm + +`check` passing locally is the arcade's acceptance bar — same code, same +verdict. Multiplayer testing is hot-seat: pass `--seats N` to join N +players to one room and Ctrl-T to switch the seat your keyboard drives. + +Prefer Rust? `shellcade-kit new --rust mygame` scaffolds the same game +shape on the Rust SDK; the mental model carries over one for one. + +## Publish your game + +Games live in the public catalog at github.com/shellcade/games. To ship: + +1. Build your wasm and confirm `shellcade-kit check game.wasm` is green. +2. Open a pull request that adds your game to the catalog. +3. When the PR is merged it cuts a release of your game. +4. An operator reviews the release and takes it live in the arcade. + +Every game in the catalog is conformance-green, so the check gate is the +bar both for your PR and for going live. Read a complete, published game +to learn the patterns before you submit. + +## Link your GitHub + +Link your GitHub account so the games you publish are attributed to you +in the arcade. Connect over SSH: + + ssh shellcade.com + +Then open the User menu and choose Link GitHub, and follow the prompt. +Once linked, games you author show up under your name. + +## Where to go next + +- GUIDE.md — the full authoring guide: the event-to-frame model, time + via OnWake, input and controls, leaderboards, durable per-player KV, + multiplayer rendering, and smoke scripts. +- ABI.md — the normative contract: the wasm ABI, host functions, and + the packed payload encodings the kit compiles against. +- github.com/shellcade/games — the public catalog of published games to + read and learn from. From dc9c7d5bfb4c059d7b9a9f139ab9d48847b7f88f Mon Sep 17 00:00:00 2001 From: Brandon Cook Date: Sat, 6 Jun 2026 18:18:50 +1000 Subject: [PATCH 2/2] docs: brew-first install, manual download in a glamour-safe expand MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lead the Quickstart with `brew install shellcade/tap/shellcade-kit` for macOS (the documented cask), and move the manual Releases download into a
expand for Linux/Windows/no-brew. The HTML tag lines sit alone between blank lines, so GitHub collapses the block while glamour (the shellcade TUI renderer) drops the raw tags and still renders the inner markdown inline — terminal users lose nothing. The quarantine note moves with the manual path (the brew cask strips quarantine itself). Lines stay <=76 cols. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/get-started.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/get-started.md b/docs/get-started.md index 7fef586..cce4c9b 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -8,13 +8,23 @@ SSH at shellcade.com. ## Quickstart -Grab the one author tool, `shellcade-kit` (scaffold, verify, play), from -this repo's Releases: +Install the one author tool, `shellcade-kit` (scaffold, verify, play). +On macOS, use Homebrew: + + brew install shellcade/tap/shellcade-kit + +
+Manual download (Linux / Windows / no brew) + +Grab a build for your platform from this repo's Releases: https://github.com/shellcade/kit/releases -(macOS may quarantine the download: -`xattr -d com.apple.quarantine shellcade-kit` clears it.) +(macOS downloads may be quarantined: +`xattr -d com.apple.quarantine shellcade-kit` clears it. The brew cask +strips this for you.) + +
Scaffold a game and play it in your terminal — the inner loop is a plain Go program (debugger, prints, sub-second builds), no wasm required: