@onceworlds/cli 0.2.0 → 0.3.0

package/README.md

@@ -6,12 +6,17 @@ players) with no server code.
 
 ## Deploy from GitHub Actions
 
-Add `.github/workflows/deploy.yml` to your game's repo:
+Deploys run from GitHub Actions: GitHub vouches for the repo, so there are no API
+keys. The easiest setup is to import the repo at https://onceworlds.com/dashboard/new,
+which adds `onceworlds.json` and `.github/workflows/onceworlds.yml` for you (that
+workflow also builds with npm, pnpm, yarn or bun when there's a build script). By
+hand, the minimum is:
 
 ```yaml
 name: Deploy to Onceworlds
 on:
   push:
+    branches: ['**']
 permissions:
   contents: read
   id-token: write # proves which repo is deploying; no API keys needed
@@ -26,17 +31,16 @@ jobs:
       - run: npx --yes @onceworlds/cli@latest deploy
 ```
 
-Pushes to `main` go live at `onceworlds.com/play/<slug>`; other branches get a
-preview URL in the job log. Sign in at https://onceworlds.com with the GitHub
-account that owns the repo (or any member of its organization) before the first
-deploy.
+Pushes to the production branch (`main` unless you change it in the dashboard or
+`onceworlds.json`) go live at `onceworlds.com/play/<slug>`; other branches get a
+preview URL in the job log. Log in to https://onceworlds.com with a GitHub
+account that has write access to the repo before the first deploy. Install the
+Onceworlds GitHub App on that repo to use the dashboard and open the game while
+private. If a deploy fails, the dashboard shows why.
 
-New games start private: only the repo's owner (or its organization's members)
-can play them. When it's ready to share, open the game in the dashboard and click
-"Make public" in the Settings tab.
-
-You can also skip the setup: import the repo at https://onceworlds.com/dashboard/new,
-which adds `onceworlds.json` and this workflow for you.
+New games start private: only accounts with write access to the repo can play
+them. To share one, open it in the dashboard and pick Unlisted (anyone
+with the link) or Public (also listed on Onceworlds).
 
 ## Project file
 
@@ -44,30 +48,45 @@ which adds `onceworlds.json` and this workflow for you.
 
 ```json
 {
-  "slug": "star-party",
-  "name": "Star Party",
-  "description": "Grab stars with everyone online.",
+  "slug": "kart-rush",
+  "name": "Kart Rush",
+  "description": "Race friends around twisty tracks.",
   "dir": ".",
-  "genre": "Party",
+  "genre": "Racing",
   "icon": "store/icon.png",
   "thumbnails": ["store/thumb-1.png", "store/thumb-2.png"],
-  "badges": [{ "id": "first-star", "name": "First Star", "description": "Grab a star." }]
+  "badges": [{ "id": "first-win", "name": "Top Step", "description": "Win a race." }]
 }
 ```
 
 `dir` is the folder to publish (for example `dist` after a build); it must contain
-`index.html`. `productionBranch` (default `main`) picks the branch that goes live.
+`index.html`. `productionBranch` (default `main`) picks the branch that goes live;
+the dashboard can change it too, and the file wins again only when this value changes.
 
-The rest fills in the game page: `genre`, a square `icon` (at least 128×128),
+`controls` (`[{ "keys": ["W", "A", "S", "D"], "action": "Move" }]`, up to 12) and `help` (up to 400
+characters) fill "How to play" in the platform menu. The rest fills in the game page: `genre`, a square `icon` (at least 128×128),
 16:9 `thumbnails` (at least 480 wide; the first is the cover) and `badges` (`id`,
 `name`, `description` and an optional square `icon`). Images are PNG, JPEG, WebP
 or GIF up to 5 MB, with paths relative to `onceworlds.json`. Live deploys apply
 these fields only when they change, so edits made in the dashboard last until then.
 
+Make the art before the first deploy: players see the icon and thumbnails before the game, and a game
+without them gets a plain colored placeholder. The icon is a simple, wordless 512×512 square; the thumbnails
+are three to five 1280×720 pictures of the game being played, the best one first (it is the cover). Capture them
+from the running game and commit them under `store/`. `onceworlds doctor` says which fields are missing.
+
 ## Commands
 
-- `onceworlds deploy [dir]` uploads only the files that changed and publishes the game.
-- `onceworlds dev [dir]` deploys to a local Onceworlds platform and redeploys on every save.
+- `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.
+- `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.
+- `onceworlds doctor [dir]` looks through the game's files for what games often ship with: no viewport
+  tag, text fields under 16px (Safari zooms the page when one is focused), `confirm()` and other dialogs
+  (blocked in the game frame), localStorage (gone on reload), and, for games with rooms, `Date.now()` for
+  shared time and no use of the platform's lobby. It only suggests: nothing in it stops a deploy
+  (`--strict` exits with an error on likely bugs, for CI).
 
 Games talk to the platform through the injected `window.onceworlds` SDK. The
 starter template's `AGENTS.md` documents it for AI coding tools.

package/dist/cli.js

@@ -8,21 +8,212 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 
+// src/doctor.ts
+var ROOM_MAX_PLAYERS = 30;
+var MINIFIED_LINE = 400;
+var lineOf = (text, index) => text.slice(0, index).split("\n").length;
+function looksMinified(text) {
+  const lines = text.split("\n");
+  return text.length > 2e4 && text.length / lines.length > MINIFIED_LINE;
+}
+function cssIn(file) {
+  if (/\.css$/i.test(file.path)) return [{ css: file.text, offset: 0 }];
+  if (!/\.html?$/i.test(file.path)) return [];
+  const blocks = [];
+  for (const match of file.text.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) blocks.push({ css: match[1], offset: (match.index ?? 0) + match[0].indexOf(match[1]) });
+  return blocks;
+}
+function smallFields(file) {
+  const found = [];
+  for (const { css, offset } of cssIn(file)) {
+    for (const rule of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+      const selector = rule[1];
+      if (!/(^|[\s,>+~(])(input|textarea|select)\b/i.test(selector) && !/\.[\w-]*(input|field|textbox)\b/i.test(selector)) continue;
+      if (/type\s*=\s*["']?(range|checkbox|radio|color|button|submit|file)/i.test(selector)) continue;
+      const size = /(?:^|[;\s])font-size\s*:\s*(\d+(?:\.\d+)?)px/i.exec(rule[2]) ?? /(?:^|[;\s])font\s*:\s*[^;]*?\b(\d+(?:\.\d+)?)px/i.exec(rule[2]);
+      if (!size || Number(size[1]) >= 16) continue;
+      const at = offset + (rule.index ?? 0) + rule[0].indexOf(size[0]);
+      found.push({
+        file: file.path,
+        line: lineOf(file.text, at),
+        level: "warn",
+        id: "field-size",
+        message: `A text field at ${size[1]}px: Safari on iPhone and iPad zooms the whole page when it's focused. Use at least 16px.`
+      });
+    }
+  }
+  return found;
+}
+var LINE_RULES = [
+  {
+    id: "dialogs",
+    level: "warn",
+    test: /(?<![\w$])(?:window\s*\.\s*)?(alert|confirm|prompt)\s*\(/,
+    // `confirm() {` (a method), `function prompt(`, `.confirm(` on some object of the game's own.
+    except: /(?<![\w$])(alert|confirm|prompt)\s*\([^()]*\)\s*\{|function\s+(alert|confirm|prompt)\b|(?<!window)\.\s*(alert|confirm|prompt)\s*\(/,
+    message: "alert(), confirm() and prompt() are blocked in the game frame (confirm() answers false at once). Draw your own message or dialog."
+  },
+  {
+    id: "fullscreen",
+    level: "note",
+    test: /\.(webkitR|r)equestFullscreen\s*\(/,
+    message: "Use onceworlds.ui.requestFullscreen(): the platform keeps its menu and chat available in fullscreen, and handles iPhone."
+  },
+  {
+    id: "storage",
+    level: "note",
+    test: /\b(localStorage|sessionStorage)\b|document\.cookie/,
+    message: "localStorage, sessionStorage and cookies are kept in memory in the game frame and are gone on reload (fine for caches and a fallback outside the platform). Use onceworlds.save.set/get for progress and settings that should stay."
+  }
+];
+function checkListing(config, file = "onceworlds.json") {
+  const found = [];
+  const note = (id, message) => found.push({ file, line: 1, level: "note", id, message });
+  const filled = (value) => typeof value === "string" && value.trim() !== "";
+  if (!filled(config.icon)) {
+    note("listing-icon", `No "icon": the game's card shows a plain colored placeholder. Add a square image (512\xD7512, simple, no words), like "icon": "store/icon.png".`);
+  }
+  if (!Array.isArray(config.thumbnails) || config.thumbnails.length === 0) {
+    note("listing-thumbnails", 'No "thumbnails": the game page and its card have no cover. Add three or more 16:9 pictures (1280\xD7720) of the game being played; the first is the cover.');
+  }
+  if (!filled(config.genre)) note("listing-genre", `No "genre": players can't find the game under a Discover genre. Pick one of the genres in AGENTS.md.`);
+  const noControls = !Array.isArray(config.controls) || config.controls.length === 0;
+  if (noControls && !filled(config.help)) {
+    note("listing-help", `No "controls" or "help": the menu's How to play is empty. List every key or button the game uses and a line on how to win.`);
+  }
+  return found;
+}
+function checkGame(files) {
+  const found = [];
+  const code = files.filter((f) => /\.(html?|m?js|css)$/i.test(f.path));
+  const index = code.find((f) => f.path === "index.html");
+  if (index && !/<meta[^>]+name\s*=\s*["']viewport["']/i.test(index.text)) {
+    found.push({
+      file: index.path,
+      line: 1,
+      level: "warn",
+      id: "viewport",
+      message: 'No viewport meta tag: phones show the page zoomed out. Add <meta name="viewport" content="width=device-width, initial-scale=1">.'
+    });
+  }
+  for (const file of code) {
+    found.push(...smallFields(file));
+    if (looksMinified(file.text) || /\.css$/i.test(file.path)) continue;
+    const lines = file.text.split("\n");
+    for (const rule of LINE_RULES) {
+      const first = lines.findIndex((line) => !/^\s*(\/\/|\*|\/\*)/.test(line) && rule.test.test(line) && !rule.except?.test(line));
+      if (first !== -1) found.push({ file: file.path, line: first + 1, level: rule.level, id: rule.id, message: rule.message });
+    }
+  }
+  const all = code.map((f) => f.text).join("\n");
+  if (/\brooms\s*\.\s*join\s*\(/.test(all)) {
+    const host = code.find((f) => /\brooms\s*\.\s*join\s*\(/.test(f.text));
+    const at = lineOf(host.text, host.text.search(/\brooms\s*\.\s*join\s*\(/));
+    if (!/\b(lobby\s*:|startMatch|matchstart|setReady|minPlayers)/.test(all)) {
+      found.push({
+        file: host.path,
+        line: at,
+        level: "note",
+        id: "matches",
+        message: `This joins a room but doesn't use the platform's lobby or match lifecycle. That's right for a world people drop in and out of; a game with rounds gets ready-up, a countdown, spectators and pausing from rooms.join({ lobby: 'card' }) (see AGENTS.md, "Matches").`
+      });
+    }
+    if (/\bDate\s*\.\s*now\s*\(/.test(all) && !/\bonceworlds\s*\.\s*now\s*\(|\bow\s*\.\s*now\s*\(|\bmatchNow\s*\(/.test(all)) {
+      found.push({
+        file: host.path,
+        line: at,
+        level: "note",
+        id: "clock",
+        message: "Time from Date.now() differs between players' devices. Use onceworlds.now() for anything players share, and room.matchNow() for a match's deadlines."
+      });
+    }
+  }
+  const size = /\bmaxPlayers\s*:\s*(\d+)\b/g;
+  for (const file of code) {
+    for (const match of file.text.matchAll(size)) {
+      if (Number(match[1]) <= ROOM_MAX_PLAYERS) continue;
+      found.push({
+        file: file.path,
+        line: lineOf(file.text, match.index ?? 0),
+        level: "note",
+        id: "room-size",
+        message: `A room seats at most ${ROOM_MAX_PLAYERS} players: maxPlayers: ${match[1]} gives ${ROOM_MAX_PLAYERS}. The bigger the room, the less each player may send (room.budget), so a full room stays smooth.`
+      });
+      break;
+    }
+  }
+  const keyboardKeys = /\b(ArrowLeft|ArrowRight|ArrowUp|ArrowDown|KeyW|KeyA|KeyS|KeyD)\b|\.key\s*={2,3}\s*['"](?:w|a|s|d|ArrowLeft|ArrowRight|ArrowUp|ArrowDown)['"]|case\s+['"](?:w|a|s|d|ArrowLeft|ArrowRight|ArrowUp|ArrowDown)['"]|keys\s*\.\s*has\s*\(\s*['"](?:w|a|s|d|arrowleft|arrowright|arrowup|arrowdown)['"]/;
+  const keyboard = keyboardKeys.test(all);
+  if (keyboard && !/\bcontrols\s*\??\.\s*(?:set|stick|touch|pressed)\b|\b(?:set|sync)Controls\s*\(/i.test(all)) {
+    const touchable = /\b(pointerdown|touchstart|mousedown|click)\b/.test(all);
+    const file = code.find((f) => keyboardKeys.test(f.text));
+    found.push({
+      file: file.path,
+      line: lineOf(file.text, file.text.search(keyboardKeys)),
+      level: touchable ? "note" : "warn",
+      id: "touch-controls",
+      message: touchable ? "Steered by keys, with no on-screen controls: phones show none. Ask for the platform's with onceworlds.controls.set({ stick: 'wasd' }) (see AGENTS.md, phones and tablets)." : "Steered by keys, and nothing responds to touch: on a phone the game can't be played. Ask for the platform's on-screen controls with onceworlds.controls.set({ stick: 'wasd', buttons: [...] })."
+    });
+  }
+  if (/\bdevicePixelRatio\b/.test(all) && !/\bsettings\s*\.\s*pixelRatio\b/.test(all)) {
+    const file = code.find((f) => /\bdevicePixelRatio\b/.test(f.text));
+    found.push({
+      file: file.path,
+      line: lineOf(file.text, file.text.search(/\bdevicePixelRatio\b/)),
+      level: "note",
+      id: "pixel-ratio",
+      message: "Size canvases with onceworlds.settings.pixelRatio(2): it caps the resolution and follows the player's Graphics setting, so tablets and older phones keep their frame rate."
+    });
+  }
+  return found.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+
 // ../protocol/src/index.ts
 var OIDC_AUDIENCE = "onceworlds";
 var LIMITS = {
   roomMaxPlayersDefault: 16,
-  roomMaxPlayersCap: 50,
+  /**
+   * The most players a room seats. A room is one Durable Object that copies every update a player sends to everyone else, so
+   * what it costs grows with the square of its players: 30 is where a room stays well inside what one object serves.
+   */
+  roomMaxPlayersCap: 30,
   teamsMax: 8,
   messageBytes: 16 * 1024,
   presenceBytes: 1024,
   stateKeyLength: 64,
   stateValueBytes: 16 * 1024,
   stateKeys: 256,
+  /** Private values (room.setPrivate): keys per player, one value, and all of a player's together. */
+  privateKeys: 16,
+  privateValueBytes: 4 * 1024,
+  privateBytesPerPlayer: 8 * 1024,
+  /** The most messages a second one player may send a room (a room with more players gives each less: see roomBudget). */
   messagesPerSecond: 60,
-  /** Bytes one player may send to a room per second, on average (bursts up to 4x). */
+  messagesPerSecondMin: 10,
+  /** Bytes one player may send to a room per second, on average (bursts up to 4x): the most, in a small room. */
   roomBytesPerSecond: 128 * 1024,
+  roomBytesPerSecondMin: 16 * 1024,
+  /** The most presence updates a second one player may send. */
   presenceHz: 20,
+  presenceHzMin: 5,
+  /**
+   * What a room takes in from all its players together each second, presence included (a Durable Object serves about 1000
+   * requests a second, and each update is then sent on to everyone else), and the bytes. Each player's share is this divided
+   * by the room's capacity, up to the per-player maximums above: rooms of up to 11 players get all of them.
+   */
+  roomMessagesPerSecond: 900,
+  roomBytesPerSecondTotal: 2 * 1024 * 1024,
+  /** A match's countdown before play begins, unless the room is set up otherwise (rooms.join({ countdown })). */
+  matchCountdownMs: 3e3,
+  matchCountdownMaxMs: 1e4,
+  /** A public lobby where half the players are ready waits this long for the rest before starting without them. */
+  matchIdleMs: 45e3,
+  /** A match that has waited this long for its players (paused, too few connected) is over. */
+  matchAbandonMs: 12e4,
+  /** A player who hasn't touched the game (pointer, keys, touch, gamepad) this long is idle (room.on('idle')). */
+  idleAfterMs: 3e4,
+  /** A running match whose connected players have all been idle this long is over: nobody is playing. */
+  idleAbandonMs: 5 * 6e4,
   chatLength: 200,
   chatIntervalMs: 750,
   chatHistory: 50,
@@ -34,37 +225,128 @@ var LIMITS = {
   guestSaveBytesPerGame: 128 * 1024,
   deployFiles: 2e3,
   deployFileBytes: 25 * 1024 * 1024,
+  /** HTML files (.html, .htm) get the SDK injected as they're served (streamed: only the first bytes are read for it), so they're held to less than other files. */
+  deployHtmlBytes: 10 * 1024 * 1024,
+  /** Characters in a deployed file's path. */
+  deployPathLength: 200,
   deployTotalBytes: 100 * 1024 * 1024,
   envVars: 50,
   envValueBytes: 4 * 1024,
+  /** All of a game's public variables together, as injected into its pages. */
+  envTotalBytes: 16 * 1024,
+  /** Proxied request bodies: routes that take a file (audio to transcribe, an image to edit, model inputs on Replicate and fal). */
   proxyRequestBytes: 1024 * 1024,
+  /** Proxied JSON bodies for text, embeddings and image generation. */
+  proxyTextRequestBytes: 256 * 1024,
+  /** Proxied text-to-speech bodies (priced per character). */
+  proxySpeechRequestBytes: 16 * 1024,
   proxyResponseBytes: 10 * 1024 * 1024,
+  /** Output tokens per proxied text call: a request asking for more is lowered to this, one that doesn't say gets it. */
+  proxyMaxOutputTokens: 4096,
   proxyCallsPerDay: 2e3,
+  proxyCallsPerDayMax: 1e5,
+  proxyCallsPerPlayerPerDay: 100,
+  proxyCallsPerNetworkPerDay: 1e3,
+  proxyMediaCallsPerDay: 100,
+  proxyMediaCallsPerDayMax: 1e4,
+  proxyMediaCallsPerPlayerPerDay: 20,
+  proxyMediaCallsPerNetworkPerDay: 25,
+  /**
+   * Daily units: each proxied call's estimated tokens (request bytes / 3 plus its output
+   * cap) times its model's weight. Per game (the creator can set up to the max), per
+   * signed-in player, per guest, and per guests' network.
+   */
+  proxyUnitsPerDay: 2e6,
+  proxyUnitsPerDayMax: 1e8,
+  proxyUnitsPerPlayerPerDay: 25e4,
+  proxyUnitsPerGuestPerDay: 1e5,
+  proxyUnitsPerNetworkPerDay: 5e5,
   errorReportsPerPage: 10,
   gameNameLength: 60,
   gameDescriptionLength: 1e3,
   galleryItems: 10,
   mediaImageBytes: 5 * 1024 * 1024,
   mediaVideoBytes: 30 * 1024 * 1024,
+  /** GIFs are served as they are (never resized), so they're small: at most this many bytes and pixels a side. */
+  mediaGifBytes: 1024 * 1024,
+  mediaGifSide: 512,
+  /** Media an account uploads in the dashboard (or a repo owner's deploys add to game pages) in any 24 hours. */
+  mediaUploadsPerDay: 200,
+  mediaBytesPerDay: 500 * 1024 * 1024,
   badgesPerGame: 100,
+  /** The menu's "How to play": up to this many controls (each with a few keys and a short action), and a few lines of help. */
+  controlHints: 12,
+  controlHintKeys: 4,
+  controlKeyLength: 12,
+  controlActionLength: 40,
+  helpLength: 400,
   badgeNameLength: 50,
   badgeDescriptionLength: 200,
   leaderboardsPerGame: 25,
   leaderboardTop: 100,
   gamesPerOwner: 50,
+  /** New games per creator in any rolling 24-hour period. Redeploys do not count. */
+  gamesCreatedPerCreatorPerDay: 3,
   deploysPerOwnerPerDay: 100,
+  /** Finished versions retained per game, including its live version. */
+  deploymentsKeptPerGame: 10,
   deployBytesPerOwnerPerDay: 2 * 1024 * 1024 * 1024,
+  /** Files listed by all of a repo owner's deploys in any 24 hours (each is a record to keep and clean up). */
+  deployEntriesPerOwnerPerDay: 1e5,
   bioLength: 500,
   friendsMax: 200,
+  /** Requests one player has sent that are still waiting. */
   friendRequestsMax: 100,
+  /** Requests waiting for one player: more wait until they answer some. */
+  friendRequestsIncomingMax: 50,
+  /** New friend requests an account sends in 24 hours (asking again after cancelling counts again)... */
+  friendRequestsPerDay: 20,
+  /** ...and all accounts under a week old on one network (IPv4 address, or IPv6 /48) together: a bot farm's accounts share one, a school's established ones are not counted. */
+  friendRequestsPerNetworkPerDay: 120,
+  /** Friend requests that reach a player's devices (push) in a day, at most one every 10 minutes. */
+  friendRequestPushesPerDay: 5,
   passwordMinLength: 8,
-  passwordMaxLength: 72
+  passwordMaxLength: 72,
+  /** Account creation attempts, with or without email, per network (IP, or IPv6 /64) in 24 hours. */
+  signupsPerNetworkPerDay: 100,
+  /** The same per wide network (an IPv6 /48); an IPv4 address with a proof of work may go on to this too. */
+  signupsPerWidePerDay: 300,
+  /** New guest players per network per day (each one can hold saves). */
+  guestsPerNetworkPerDay: 300,
+  /** The same per wide network (an IPv6 /48); an IPv4 address with a proof of work may go on to this too. */
+  guestsPerWidePerDay: 1500,
+  /** Visits a game gets per network (IPv4 address, or IPv6 /48) per day: a script can't pump the count. */
+  visitsPerNetworkPerDay: 10,
+  /** Seconds of visible play before a play counts as a visit. */
+  visitSeconds: 10,
+  /** Distinct errors kept per deploy of a game (more are counted by nobody). */
+  errorsPerDeployment: 100,
+  /** On-screen controls: buttons beside the thumbstick, and their labels. */
+  controlButtons: 4,
+  controlLabelLength: 12,
+  /** Friends in one party, the leader included. */
+  partySize: 6,
+  partyChatHistory: 50,
+  /** Messages outside games: saved chats between friends. */
+  messageLength: 500,
+  messagesPerPage: 50,
+  groupChatMembers: 20,
+  groupChatNameLength: 40,
+  conversationsListed: 50,
+  notificationsListed: 50,
+  /** Friends one game invite can go to. */
+  invitesPerRequest: 10,
+  /** How long an invite can be joined: it's for now. (It's over sooner when the sender leaves the server it points at, or you're already there.) */
+  inviteLiveMs: 30 * 6e4,
+  /** How long an invite to a party can be answered. */
+  partyInviteMs: 60 * 6e4
 };
 var CONTENT_TYPES = {
   html: "text/html; charset=utf-8",
   htm: "text/html; charset=utf-8",
   js: "text/javascript; charset=utf-8",
   mjs: "text/javascript; charset=utf-8",
+  cjs: "text/javascript; charset=utf-8",
   css: "text/css; charset=utf-8",
   json: "application/json; charset=utf-8",
   map: "application/json; charset=utf-8",
@@ -90,6 +372,7 @@ var CONTENT_TYPES = {
   opus: "audio/ogg",
   wav: "audio/wav",
   m4a: "audio/mp4",
+  aac: "audio/aac",
   flac: "audio/flac",
   mp4: "video/mp4",
   webm: "video/webm",
@@ -100,6 +383,11 @@ var CONTENT_TYPES = {
   mtl: "text/plain; charset=utf-8",
   fbx: "application/octet-stream",
   wasm: "application/wasm",
+  // Shaders, loaded as text.
+  glsl: "text/plain; charset=utf-8",
+  vert: "text/plain; charset=utf-8",
+  frag: "text/plain; charset=utf-8",
+  wgsl: "text/plain; charset=utf-8",
   pck: "application/octet-stream",
   data: "application/octet-stream",
   woff: "font/woff",
@@ -119,7 +407,7 @@ function contentTypeFor(path) {
   return CONTENT_TYPES[extensionOf(path)];
 }
 function isValidDeployPath(path) {
-  if (path.length === 0 || path.length > 512) return false;
+  if (path.length === 0 || path.length > LIMITS.deployPathLength) return false;
   if (path.startsWith("/") || path.includes("\\")) return false;
   if (/[\u0000-\u001f\u007f]/.test(path)) return false;
   for (const segment of path.split("/")) {
@@ -132,6 +420,7 @@ var RESERVED_SLUGS = /* @__PURE__ */ new Set(["www", "api", "play", "admin", "st
 function isValidSlug(slug) {
   return SLUG_RE.test(slug) && !slug.includes("--") && !RESERVED_SLUGS.has(slug);
 }
+var DEFAULT_PRODUCTION_BRANCH = "main";
 var BADGE_KEY_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
 var GENRES = [
   "Action",
@@ -151,6 +440,30 @@ var GENRES = [
   "Party",
   "Other"
 ];
+var tidy = (text) => text.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+function checkGuide(controls, help) {
+  const hints = [];
+  if (controls !== void 0 && controls !== null) {
+    if (!Array.isArray(controls)) throw new Error('"controls" must be a list, like [{ "keys": ["W", "A", "S", "D"], "action": "Move" }]');
+    if (controls.length > LIMITS.controlHints) throw new Error(`"controls" can have at most ${LIMITS.controlHints} items`);
+    controls.forEach((item, i) => {
+      const { keys, action } = item ?? {};
+      const name = `controls[${i}]`;
+      if (!Array.isArray(keys) || keys.length === 0 || keys.length > LIMITS.controlHintKeys) {
+        throw new Error(`${name}.keys must be 1-${LIMITS.controlHintKeys} keys or buttons, like ["Space"]`);
+      }
+      const cleaned = keys.map((k) => typeof k === "string" ? tidy(k) : "");
+      if (cleaned.some((k) => !k || k.length > LIMITS.controlKeyLength)) throw new Error(`${name}.keys are short names (at most ${LIMITS.controlKeyLength} characters), like "Space" or "Left click"`);
+      const text2 = typeof action === "string" ? tidy(action) : "";
+      if (!text2 || text2.length > LIMITS.controlActionLength) throw new Error(`${name}.action is what the keys do, in at most ${LIMITS.controlActionLength} characters`);
+      hints.push({ keys: cleaned, action: text2 });
+    });
+  }
+  if (help !== void 0 && help !== null && typeof help !== "string") throw new Error('"help" must be text');
+  const text = typeof help === "string" ? help.replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, " ").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim() : "";
+  if (text.length > LIMITS.helpLength) throw new Error(`"help" can be at most ${LIMITS.helpLength} characters`);
+  return { controls: hints, help: text };
+}
 var MAX_IMAGE_SIDE = 4096;
 function imageInfo(bytes) {
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -214,22 +527,36 @@ var LOCAL_API = "http://localhost:8787";
 var USAGE = `Usage:
   onceworlds deploy [project-dir]   Upload the game and publish it (to ${PRODUCTION_API})
   onceworlds dev [project-dir]      Deploy to a local platform (${LOCAL_API}), then redeploy on every change
+  onceworlds doctor [project-dir]   Look for what games often ship with: no viewport tag, small text fields,
+                                    localStorage, dialogs, Date.now() for shared time, keys with no touch
+                                    controls, a missing icon, thumbnails or How to play (suggestions only)
 
 Options:
   --api <url>     Platform URL (default: $ONCEWORLDS_API, else the ones above)
-  --token <t>     Deploy token (default: $ONCEWORLDS_TOKEN, GitHub Actions OIDC, or "dev" on localhost)
+  --token <t>     Local platform's deploy token (default: "dev")
+  --players <n>   dev: also print links for players 2 to n, to play a multiplayer game with yourself
+  --strict        doctor: exit with an error when it finds a likely bug (not for notes)
+
+Deploys to onceworlds.com run from GitHub Actions: the repo's Onceworlds
+workflow runs this on every push, and GitHub vouches for the repo.
 
 The project directory needs an onceworlds.json:
-  { "slug": "star-party", "name": "Star Party", "dir": "." }
+  { "slug": "my-game", "name": "My Game", "dir": "." }
 `;
 var CliError = class extends Error {
 };
 var QUIET_SKIPS = /* @__PURE__ */ new Set(["node_modules", "onceworlds.json", "package.json", "package-lock.json", "tsconfig.json", "jsconfig.json", "LICENSE"]);
-var QUIET_EXTENSIONS = /* @__PURE__ */ new Set(["md", "ts", "tsx", "jsx", "lock", "log", "yml", "yaml", "sh"]);
+var QUIET_EXTENSIONS = /* @__PURE__ */ new Set(["md", "ts", "tsx", "jsx", "lock", "lockb", "log", "yml", "yaml", "sh"]);
 async function main() {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
-    options: { api: { type: "string" }, token: { type: "string" }, help: { type: "boolean", short: "h" } }
+    options: {
+      api: { type: "string" },
+      token: { type: "string" },
+      players: { type: "string" },
+      strict: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
   });
   const [command, projectArg] = positionals;
   if (values.help || !command || command === "help") {
@@ -241,7 +568,11 @@ async function main() {
   if (command === "deploy") {
     await deploy(projectDir, api, values.token);
   } else if (command === "dev") {
-    await dev(projectDir, api, values.token);
+    const players = Number(values.players ?? 1);
+    if (!Number.isInteger(players) || players < 1 || players > 9) throw new CliError("--players is a number from 1 to 9.");
+    await dev(projectDir, api, values.token, players);
+  } else if (command === "doctor") {
+    await doctor(projectDir, values.strict === true);
   } else {
     throw new CliError(`Unknown command "${command}".
 
@@ -251,10 +582,20 @@ ${USAGE}`);
 async function deploy(projectDir, api, tokenArg, quiet = false) {
   const config = await loadConfig(projectDir);
   const root = resolve(projectDir, config.dir ?? ".");
-  const files = await collectFiles(root, quiet);
+  const { files, skipped } = await collectFiles(root);
+  if (skipped.length > 0) {
+    console.warn(`  ! ${skipped.length} unsupported file${skipped.length === 1 ? "" : "s"} not deployed:`);
+    for (const path of skipped) console.warn(`    ${path}`);
+  }
   if (!files.some((f) => f.path === "index.html")) {
     throw new CliError(`No index.html in ${root}. Set "dir" in onceworlds.json to the folder that contains it.`);
   }
+  if (!quiet) {
+    const findings = [...checkGame(await readSources(files)), ...checkListing(config)];
+    for (const f of findings.filter((x) => x.level === "warn")) console.warn(`  ! ${f.file}:${f.line}  ${f.message}`);
+    const notes = findings.filter((x) => x.level === "note").length;
+    if (notes > 0) console.log(`  ${notes} suggestion${notes === 1 ? "" : "s"} for this game: run "npx @onceworlds/cli doctor" to see them.`);
+  }
   const total = files.reduce((sum, f) => sum + f.size, 0);
   if (total > LIMITS.deployTotalBytes) throw new CliError(`Game is ${formatBytes(total)}; the limit is ${formatBytes(LIMITS.deployTotalBytes)}.`);
   const { store, images } = await loadStore(projectDir, config);
@@ -265,7 +606,7 @@ async function deploy(projectDir, api, tokenArg, quiet = false) {
       slug: config.slug,
       name: config.name,
       description: config.description ?? "",
-      productionBranch: config.productionBranch ?? "main",
+      productionBranch: config.productionBranch ?? DEFAULT_PRODUCTION_BRANCH,
       store
     },
     files: files.map(({ path, hash, size }) => ({ path, hash, size })),
@@ -282,21 +623,23 @@ async function deploy(projectDir, api, tokenArg, quiet = false) {
   });
   const result = await send("POST", `${api}/api/deploy/${start.deploymentId}/finalize`, start.uploadToken, {});
   if (!quiet) {
+    const branch = result.productionBranch ?? start.productionBranch;
     if (result.production) console.log(`\u2713 Live: ${result.playUrl}`);
-    else console.log(`\u2713 Preview (this branch isn't ${config.productionBranch ?? "main"}): ${result.previewUrl}`);
+    else console.log(`\u2713 Preview${branch ? ` (only ${branch} goes live)` : ""}: ${result.previewUrl}`);
     for (const note of result.notes ?? []) console.log(`  ${note}`);
   }
   return result;
 }
-async function dev(projectDir, api, tokenArg) {
+async function dev(projectDir, api, tokenArg, players = 1) {
   const config = await loadConfig(projectDir);
   const root = resolve(projectDir, config.dir ?? ".");
   const first = await deploy(projectDir, api, tokenArg);
   console.log(`
-  Play (reloads on every change): ${first.playUrl}?watch
-  Watching ${root}. Press Ctrl+C to stop.
+  Play (reloads on every change): ${first.playUrl}?watch`);
+  for (let n = 2; n <= players; n++) console.log(`  Player ${n}: ${first.playUrl}?player=${n}&watch`);
+  console.log(`  Watching ${root}. Press Ctrl+C to stop.
 `);
-  const projectSignature = async () => signature(await collectFiles(root, true)) + await readFile(join(projectDir, "onceworlds.json"), "utf8").catch(() => "");
+  const projectSignature = async () => signature((await collectFiles(root)).files) + await readFile(join(projectDir, "onceworlds.json"), "utf8").catch(() => "");
   let lastSignature = await projectSignature();
   let timer;
   let running = false;
@@ -335,6 +678,31 @@ async function dev(projectDir, api, tokenArg) {
   await new Promise(() => {
   });
 }
+async function readSources(files) {
+  const sources = [];
+  for (const file of files) {
+    if (!/\.(html?|m?js|css)$/i.test(file.path) || file.size > 15e5) continue;
+    sources.push({ path: file.path, text: await readFile(file.abs, "utf8") });
+  }
+  return sources;
+}
+async function doctor(projectDir, strict) {
+  const config = await loadConfig(projectDir);
+  const root = resolve(projectDir, config.dir ?? ".");
+  const { files } = await collectFiles(root);
+  const sources = await readSources(files);
+  const findings = [...checkGame(sources), ...checkListing(config)];
+  console.log(`Checked ${sources.length} file${sources.length === 1 ? "" : "s"} in ${root}.`);
+  if (findings.length === 0) {
+    console.log("Nothing to suggest.");
+    return;
+  }
+  for (const f of findings) console.log(`  ${f.level === "warn" ? "!" : "\xB7"} ${f.file}:${f.line}  ${f.message}`);
+  const warnings = findings.filter((f) => f.level === "warn").length;
+  console.log(`
+${warnings} likely problem${warnings === 1 ? "" : "s"}, ${findings.length - warnings} note${findings.length - warnings === 1 ? "" : "s"}. Nothing here stops a deploy.`);
+  if (strict && warnings > 0) process.exitCode = 1;
+}
 async function loadConfig(projectDir) {
   const file = join(projectDir, "onceworlds.json");
   let config;
@@ -407,9 +775,18 @@ async function loadStore(projectDir, config) {
     const badgeIcon = b.icon === void 0 ? null : await image(b.icon, "badge", `${field}.icon`);
     badges.push({ key, name, description, icon: badgeIcon });
   }
-  return { store: { genre, icon, thumbnails, badges }, images: [...images.values()] };
+  let guide;
+  try {
+    guide = checkGuide(config.controls, config.help);
+  } catch (err) {
+    throw new CliError(`${err.message} in onceworlds.json.`);
+  }
+  const store = { genre, icon, thumbnails, badges };
+  if (guide.controls.length > 0) store.controls = guide.controls;
+  if (guide.help) store.help = guide.help;
+  return { store, images: [...images.values()] };
 }
-async function collectFiles(root, quiet) {
+async function collectFiles(root) {
   const files = [];
   const skipped = [];
   async function walk(dir, prefix) {
@@ -439,9 +816,8 @@ async function collectFiles(root, quiet) {
     }
   }
   await walk(root, "");
-  if (skipped.length > 0 && !quiet) console.warn(`  ! skipped unsupported files: ${skipped.join(", ")}`);
   if (files.length > LIMITS.deployFiles) throw new CliError(`Too many files (${files.length}); the limit is ${LIMITS.deployFiles}.`);
-  return files;
+  return { files, skipped };
 }
 function signature(files) {
   return files.map((f) => `${f.path}:${f.hash}`).join("\n");
@@ -458,7 +834,6 @@ function gitInfo(cwd) {
 }
 async function getToken(api, tokenArg) {
   if (tokenArg) return tokenArg;
-  if (process.env.ONCEWORLDS_TOKEN) return process.env.ONCEWORLDS_TOKEN;
   const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
   const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
   if (requestUrl && requestToken) {
@@ -471,7 +846,7 @@ async function getToken(api, tokenArg) {
   const host = new URL(api).hostname;
   if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost")) return "dev";
   throw new CliError(
-    "No deploy credentials. In GitHub Actions, add `permissions: id-token: write` to the workflow. Elsewhere, set ONCEWORLDS_TOKEN."
+    "Deploys to Onceworlds run from GitHub Actions: push to GitHub and the repo's Onceworlds workflow deploys (it needs `permissions: id-token: write`)."
   );
 }
 async function send(method, url, token, body) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onceworlds/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deploy games to Onceworlds.",
   "homepage": "https://onceworlds.com",
   "type": "module",