@onceworlds/cli 0.9.5 → 0.10.0

package/README.md

@@ -83,15 +83,28 @@ from the running game and commit them under `store/`. `onceworlds doctor` says w
 
 ## Commands
 
-- `onceworlds new [folder]` starts a game: a blank engine project (`--space 3d` for 3D) with nothing that decides the game, only
-  the wiring: a `game.config.js` with a camera and an empty action map, a test that plays it through a reloaded host and a dropped
-  player, an `onceworlds.json` for your game (`--name`, `--slug`, `--description`; the folder's name by default), the engine guide
-  as `AGENTS.md` and `CLAUDE.md`, and a `DESIGN.md` to fill in first (the hook and signature mechanic, an originality pass, the first
-  minute, the art direction, the feel, the UI and a pre-build check). `--kit <name>` starts from a kit instead: a complete game of
-  one kind (`--list` shows them), a reference for its plumbing (rooms, netcode, Flow, bots, tests) whose idea, look and screens are
-  never yours. A kit adds its own notes as `KIT.md` and its fingerprints as `.onceworlds/kit.json`, so `check` can note what is
-  still the kit's. `--template party` or `starter` starts a small game on the SDK alone.
-- `onceworlds check [dir]` is what to run before a deploy: doctor's findings and, for an engine game, the game's own tests
+- `onceworlds new [folder]` starts a game on the web platform and the SDK: `index.html`, `game.js` on the stack you pick
+  (`--stack canvas`, the default with no library, `three`, `pixi` or `phaser`, loaded from a CDN by an import map), `rules.js`
+  with tests that run in Node (`npm test`: `node --test`, nothing to install), an `onceworlds.json` for your game (`--name`,
+  `--slug`, `--description`; the folder's name by default), the platform guide as `AGENTS.md` and `CLAUDE.md`, a `DESIGN.md` to
+  fill in first (the hook and signature mechanic, an originality pass, the first minute, playing together, the art direction, the
+  feel, the UI, the stack and a pre-build check), a `.gitignore` and the deploy workflow. Each starting point is tiny on purpose:
+  the platform wired in (a room joined as the page loads, you and everyone in your server, the keys and the phone's thumbstick, a
+  title with one Play button) and nothing that decides the game. `--engine` makes a blank project on the Onceworlds engine
+  instead, an optional library (`--space 3d` for 3D), with the engine guide as its `AGENTS.md`. `--kit <name>` starts from an
+  engine kit: a complete game of one kind (`--list` shows them), a reference for its plumbing (rooms, netcode, Flow, bots, tests)
+  whose idea, look and screens are never yours; it adds its own notes as `KIT.md` and its fingerprints as `.onceworlds/kit.json`,
+  so `check` can note what is still the kit's. `--template party` or `starter` starts from a complete game on the SDK, and
+  `--template <name>` from a scene project of Onceworlds Build.
+- `onceworlds check [dir]` is what to run before a deploy, for any game (canvas, three.js, PixiJS, Phaser, the DOM, the engine):
+  doctor's findings, plus the hosts the platform's CSP won't let the game reach, WebSockets of its own, text too small for a phone,
+  a second countdown under the platform's lobby, shared state written from `Math.random()` or the device's clock, and a `DESIGN.md`
+  silent on originality and the first minute. Then it plays the game on the local platform (`serve`'s) in headless Chrome: it loads
+  with no errors, draws, joins a room (pressing Play as a player does), starts its match from the platform's lobby, answers input,
+  takes a second player, survives its host reloading and then leaving, fits a phone (nothing of its text under the platform's menu or
+  touch controls, text big enough, no sideways scrolling), and keeps its own work per frame and its memory in hand: one ✓, ! or ✗
+  line each, with the fix. A ✗ exits with an error (`--strict`: a ! too); `--quick` skips the browser. For an engine game it also
+  runs the game's own tests
   (`npm test`) and simulated matches played with no browser, with a reloaded host, a dropped player, the host changing (also while
   paused), a late joiner and garbage messages. A failing test or a match with errors exits with an error. The game's config is
   read from `game.config.js` (or `src/game.config.js`, or `--config <file>`): `export const config = {...}`, and `export const actions`
@@ -113,11 +126,16 @@ from the running game and commit them under `store/`. `onceworlds doctor` says w
   Then commit, push, and import the repo at https://onceworlds.com/create?new=github.
 - `onceworlds deploy [dir]` uploads only the files that changed and publishes the game
   (the workflow runs it). It lists every file it skipped because Onceworlds can't serve it. A game's tests never go up: `*.test.js`, `vitest.config.*` and the `test/` folder at the top of the game.
-- `onceworlds serve [dir]` plays the game in your own browser on this computer, offline and with no login: it serves the folder
-  (onceworlds.json's `dir`) with the import map the platform adds for the engine (the installed package's files, else the hosted
-  copy of the engine this CLI ships with). With no platform around it the engine's stand-in is the platform: you alone in a room
-  of your own, the lobby's Start button (engine 1.3.2 on; older ones start a match with `?autoplay`), saves in memory, and
-  `--bots 3` (the default) bots beside you in a game whose roster gives bots a body. `--port` picks the port (default 8788).
+- `onceworlds serve [dir]` plays any game in your own browser on this computer, offline and with no login, on a local platform
+  at http://127.0.0.1:8788/ (`--port`): the platform's play page (its bridge, room connection, lobby, touch controls and the
+  corner the menu takes), its rooms (matchmaking, private servers with `&server=<code>`, the host role, held seats, state, private
+  values, ready, the countdown and the match, as onceworlds.com runs them) and the real SDK with its helpers
+  (`/__onceworlds/v1/match.js`, `host.js`, `bots.js`), under the platform's CSP. Saves, badges, leaderboards and game data
+  (`"data"`) are kept in memory while it runs. Each browser is a player, and `?player=2` to `9` are more in the same one. A game
+  with a build script is built first and its `dir` served. Ranked ratings, parties into matchmaking, `onceworlds.fetch` and chat
+  moderation need onceworlds.com. An engine game uses the installed engine (else the hosted copy this CLI ships with) and also gets
+  its page on its own, the engine's stand-in for the platform, with `--bots 3` (the default) bots; any other game gets `?bots=N`
+  passed on.
 - `onceworlds dev [dir]` deploys to a local Onceworlds platform (for platform development)
   and redeploys on every save. `--players 3` also prints links for players 2 and 3 (`?player=N`): on a
   local platform each is another player, so one person can fill a lobby.
@@ -141,9 +159,13 @@ from the running game and commit them under `store/`. `onceworlds doctor` says w
   (tycoon, survival, racing, platformer, shooter, party, rpg, idle, sandbox, chase-ai, inventory, shop, dialogue, day-night), and
   `onceworlds guide [topic]` the engine guide's topics or any heading of the guide or the reference. They read the index of the
   engine installed in the game's `node_modules` (its own version), else the platform's.
-- `onceworlds shot [dir]` saves a picture of the game to look at: the first player's screen a few seconds into a simulated match
-  with bots (`--at 20`), the title screen (`--phase title`) or the lobby (`--phase lobby`), or a poster (`--poster cover`), at
-  `--size 1280x720` by default. A 2D game is drawn with no browser, from the frame the engine draws, with its text in the fonts
+- `onceworlds shot [dir]` saves a picture of any game to look at: a moment of play (`--at 20`), the title screen (`--phase
+  title`) or the lobby (`--phase lobby`), or a poster (`--poster cover`), at `--size 1280x720` by default (`--size all` makes one
+  each of 390x844, 844x390, 1280x720 and 1920x1080). A game off the engine is played on the local platform in Chrome: the title
+  as it loads, the lobby once it joins (a Play button pressed when it waits on one), or play after the platform's Start (more local
+  players join when its match needs them), moving about, with the platform's menu (and on a phone its touch controls) over it as
+  players see it; the caption names errors, files the CSP refused, fonts that never loaded, symbols and text too small. A poster is
+  the game's own `?poster=` page when it says `data-ready`. An engine game in 2D is drawn with no browser, from the frame the engine draws, with its text in the fonts
   the game's files name (its own font files, or Google Fonts, downloaded once and kept) and Sora for the rest; the caption says
   which it couldn't have, and that the HTML overlay (`ui.overlay`) needs `--browser`. A 3D game (or `--browser`) is drawn by
   Chrome, Chromium or Edge from a local copy of the game. `--out` picks the file (default `store/shot.png`). `--story` plays the
@@ -153,7 +175,10 @@ from the running game and commit them under `store/`. `onceworlds doctor` says w
 
 Running `onceworlds mcp` gives an AI tool the same as tools: `api_lookup`, `recipe`, `read_guide`, `search_assets` (the engine's
 asset library), `check`, `screenshot` (the picture comes back to the model), `serve` (an address for the user to play it at),
-`new_game`, `deploy_preview`, `playtest` and `game_status`.
+`new_game`, `deploy_preview`, `playtest` (`local: true` for the folder on the local platform) and `game_status`.
+
+- `onceworlds playtest [dir]` plays the game as several guests in headless Chrome (join, a match, reloads, drops, the host leaving,
+  a late arrival, a phone): your latest draft, or `--local` the folder on the local platform, with no login.
 
 Games talk to the platform through the injected `window.onceworlds` SDK. The
 starter template's `AGENTS.md` documents it for AI coding tools.