@fzgame/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Fanzeal
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,314 @@
-# Temporary Holding Version
+# Develop an FZ game
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This guide covers creating a game project and running it on your machine. You do not need GameHub, MinIO, or a published build for day-to-day work. `fzgame dev` serves the game, the editor, and a mock runtime that `@fzgame/kit` talks to.
+
+## Install
+
+Node.js 20 or later.
+
+```bash
+npm i -g @fzgame/cli
+fzgame --version
+```
+
+The published package carries the click-counter example, so `fzgame init` works without a checkout.
+
+### From this monorepo
+
+```bash
+pnpm install
+pnpm --filter @fzgame/kit build
+pnpm --filter @fzgame/cli build
+node packages/fzgame-cli/dist/cli.cjs --help
+```
+
+Below, `fzgame` means the global `fzgame` command or `node packages/fzgame-cli/dist/cli.cjs` from the repo root. `fzgame --help` lists the five commands: `init`, `build`, `publish`, `dev`, and `runner`.
+
+## Init a project
+
+A game root is a folder with `fzgame.json` plus three directories:
+
+```
+my-game/
+  fzgame.json
+  game/          # player iframe (required: game/index.html)
+  editor/        # instance config UI (required: editor/index.html)
+  handler/       # backend artifact uploaded to S3 (required: handler/index.js)
+```
+
+### Scaffold the example
+
+Fastest path. Click Counter is a complete local game.
+
+```bash
+fzgame init my-game
+cd my-game
+fzgame dev
+```
+
+`init` refuses a directory that already has files; pass `--force` to write into one. An existing `.gitignore` is kept.
+
+Then edit `my-game/fzgame.json` (`info.name`, `info.slug`, `info.version`) and the files under `game/`, `editor/`, and `handler/`.
+
+### Create the layout yourself
+
+```bash
+mkdir -p my-game/game my-game/editor my-game/handler
+```
+
+`my-game/fzgame.json`:
+
+```json
+{
+  "info": {
+    "name": "My Game",
+    "slug": "my-game",
+    "version": 1,
+    "image": "",
+    "description": "",
+    "author": "",
+    "git_url": ""
+  },
+  "entry": {
+    "game": "game/index.html",
+    "editor": "editor/index.html",
+    "handler": "handler/index.js"
+  },
+  "formSchema": {
+    "type": "object",
+    "properties": {}
+  },
+  "resultSchema": {
+    "type": "object",
+    "properties": {}
+  },
+  "snapshotSchema": {
+    "type": "object",
+    "properties": {}
+  },
+  "gameDataSchema": {
+    "type": "object",
+    "properties": {}
+  }
+}
+```
+
+Five parts of `fzgame.json`:
+
+1. `info` — catalog identity: `name` (min 2 chars), `slug` (kebab-case), `version` (positive integer, default `1`), optional `image`, `description`, `author`, `git_url` (http(s))
+2. `formSchema` — JSON Schema for the create/edit form (instance config). Optional `formUiSchema` for JSON Forms / RJSF widgets
+3. `resultSchema` — JSON Schema for the payload `finish` / the handler returns; stored on the play session `result`
+4. `snapshotSchema` — JSON Schema for mid-play state (`kit.setState` → `metadata.snapshot`)
+5. `gameDataSchema` — JSON Schema for persistent instance/content data
+
+`entry` is optional; the paths above are the defaults. Legacy flat `name` / `slug` / `version` / `configSchema` still parse (`configSchema` is an alias for `formSchema`). `kit.config()` reads `formSchema` property defaults, then instance overrides.
+
+`my-game/game/index.html` (loads the kit, opens a play session, starts the lifecycle):
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>My Game</title>
+  </head>
+  <body>
+    <p id="status">Loading…</p>
+    <script type="module">
+      const params = new URLSearchParams(location.search)
+      const kitUrl = params.get('kit') || './vendor/kit.js'
+      const { createKit } = await import(kitUrl)
+
+      const kit = createKit()
+      await kit.load()
+      await kit.connect()
+      await kit.emit('ready')
+      await kit.emit('start')
+
+      document.getElementById('status').textContent = kit.snapshot.status
+    </script>
+  </body>
+</html>
+```
+
+`my-game/editor/index.html` (saves config to the host via `postMessage`):
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>My Game editor</title>
+  </head>
+  <body>
+    <form id="form">
+      <button type="submit">Save</button>
+    </form>
+    <script type="module">
+      const form = document.getElementById('form')
+      window.addEventListener('message', (event) => {
+        if (event.data?.source !== 'fzgame-host' || event.data?.type !== 'init') return
+        // apply event.data.config onto the form
+      })
+      parent.postMessage({ source: 'fzgame-editor', type: 'ready' }, '*')
+      form.addEventListener('submit', (event) => {
+        event.preventDefault()
+        parent.postMessage({ source: 'fzgame-editor', type: 'save', config: {} }, '*')
+      })
+    </script>
+  </body>
+</html>
+```
+
+`my-game/handler/index.js`:
+
+```js
+export default {
+  async fetch() {
+    return new Response(JSON.stringify({ ok: true }), {
+      headers: { 'content-type': 'application/json' },
+    })
+  },
+}
+```
+
+## Start local development
+
+From the game root:
+
+```bash
+fzgame dev
+```
+
+Or from anywhere:
+
+```bash
+fzgame dev --cwd my-game
+```
+
+`dev` serves the game, the editor, and a mock runtime, and needs no GameHub instance. From a monorepo checkout without a global install, `node packages/fzgame-cli/dist/cli.cjs dev --cwd my-game`.
+
+Options:
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--cwd <dir>` | current directory | Game root (must contain `fzgame.json`) |
+| `-p, --port <port>` | `3400` | Dev server port |
+| `--host <host>` | `127.0.0.1` | Bind address. `0.0.0.0` exposes the mock runtime on the LAN; it has no authentication, so the default keeps it on this machine |
+
+Open [http://127.0.0.1:3400](http://127.0.0.1:3400) for the launcher, or attach the portal studio while `fzgame dev` is running:
+
+[http://localhost:3000/game-editor/sandbox](http://localhost:3000/game-editor/sandbox)
+
+The sandbox shows play on the left and the editor on the right. The game URL includes a `config` query JSON so the kit can load instance config. Device size, a resizable event console, and kit events (`load`, `connect`, `emit`, `snapshot`) plus editor saves live on the same page. A different origin is `?origin=http://127.0.0.1:3400`.
+
+The launcher links to:
+
+- **Open game** — `/game/index.html` with `gameInstanceId`, `playerToken`, `apiUrl`, and `kit` already in the query string
+- **Open editor** — `/editor/index.html` with the same `apiUrl` / `kit`
+
+Reload the browser after you edit HTML, JS, or CSS. The server reads files from disk on each request.
+
+### What the dev server provides
+
+- Static files from the game root (`/game`, `/editor`, `/handler`)
+- `@fzgame/kit` at `/@fzgame/kit.js`
+- Mock GameHub runtime at `/games/runtime` (in-memory sessions, no database)
+- `/health` for the portal sandbox (CORS is open so the studio can watch the origin)
+
+The game page is launched as:
+
+```
+/game/index.html?gameInstanceId=dev-instance&playerToken=dev-player&apiUrl=http://127.0.0.1:3400&kit=/@fzgame/kit.js
+```
+
+`createKit()` reads `apiUrl`, `gameInstanceId`, and `playerToken` from that query string.
+
+Sandbox and editor preview use `?preview=true&gameSetting={...}` instead. That skips play-session calls and applies the JSON as `kit.config()`.
+
+If `/@fzgame/kit.js` returns 404, the kit is missing its build output: reinstall the CLI, or in a monorepo run `pnpm --filter @fzgame/kit build`.
+
+## Talk to GameHub from the game
+
+```js
+import { createKit } from '/@fzgame/kit.js' // in `fzgame dev`; use `./vendor/kit.js` after publish
+
+const kit = createKit()
+await kit.load()       // GET  /games/runtime/instances/:gameInstanceId
+await kit.connect()    // POST /games/runtime/sessions  { gameInstanceId, playerToken }
+await kit.emit('ready')
+await kit.emit('start')
+await kit.setState({ score: 1 })           // local snapshot + PUT .../snapshot
+await kit.emit('score', { score: 1 })
+await kit.emit('finish', { score: 1, result: { score: 1 } })
+
+kit.config()           // formSchema defaults merged with instance overrides
+kit.snapshot           // { status, score, result, state }
+```
+
+Lifecycle:
+
+```
+CREATED → READY → PLAYING ⇄ PAUSED → FINISHED
+                    ↘ abort / expire
+```
+
+Emit `ready`, `start`, `pause`, `finish`, `abort`, `score`, or `snapshot`. `finish` and `score` accept `{ score, result }`.
+
+On a published GameHub instance the host still passes `apiUrl`, `gameInstanceId`, and `playerToken`. `playerToken` is the player's `identity` or id (the player must already exist).
+
+## Editor host protocol
+
+The portal and BO load `editor/index.html` in an iframe.
+
+- Host → editor: `{ source: 'fzgame-host', type: 'init', config, configSchema, gameInstanceId }` (`configSchema` is the unwrapped `formSchema`)
+- Editor → host: `{ source: 'fzgame-editor', type: 'ready' }`
+- Editor → host: `{ source: 'fzgame-editor', type: 'save', config }`
+
+In local `fzgame dev` there is no parent to persist config. Use the editor page to check the UI; save is wired when the same HTML is opened from the portal instance editor.
+
+## Next: pack and publish
+
+When the game runs locally:
+
+```bash
+fzgame build --cwd my-game
+fzgame publish --cwd my-game --api http://localhost:3020 --token <session>
+```
+
+Every flag falls back to an environment variable, and `fzgame` reads a `.env` file from the current directory before it parses arguments. Values already exported in the shell win over the file.
+
+| Variable | Used by | Meaning |
+| --- | --- | --- |
+| `FZGAME_API` | `publish`, `runner start` | GameHub API (default `http://localhost:3020`) |
+| `FZGAME_SERVER` | `runner start` | Alias for `FZGAME_API` |
+| `FZGAME_TOKEN` | `publish` | Session token, same as `--token` |
+| `FZGAME_SPACE_ID` | `publish` | Space id, publishes a space-private game |
+| `FZGAME_RUNNER_KEY` | `runner start` | Runner key from the BO receipt |
+| `FZGAME_RUNNER_PASS` | `runner start` | Runner pass from the BO receipt |
+
+## CI runner
+
+BO **Runners → Generate runner** opens the runner page with a one-time pass and CLI / Docker start commands. Start the worker with `--server` pointing at the GameHub API:
+
+```bash
+fzgame runner start --server http://localhost:3020 --key fzr_... --pass ...
+```
+
+From this repo:
+
+```bash
+node packages/fzgame-cli/dist/cli.cjs runner start --server http://localhost:3020 --key fzr_... --pass ...
+```
+
+Docker (after generating the receipt):
+
+```bash
+docker compose run --rm runner --server http://host.docker.internal:3020 --key fzr_... --pass ...
+```
+
+Or set `FZGAME_RUNNER_KEY` and `FZGAME_RUNNER_PASS` and `docker compose up -d runner`. The runner claims queued git deploys, then fetch → build → optional test → publish preview.
+
+`build` writes `my-game/dist/<slug>-v<version>.zip`. `publish` uploads that zip to `/games/publishing` (add `--space <id>` for a space-private game). The zip is validated, then `game/`, `editor/`, and `handler/` are stored on MinIO/S3.
+
+Publishing needs the GameHub API and a logged-in session token. It is not required for local development.