@onceworlds/cli 0.1.1 → 0.2.1

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,30 +31,49 @@ 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
+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 the GitHub
 account that owns the repo (or any member of its organization) before the first
-deploy.
+deploy. 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.
+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
 
 `onceworlds.json` at the root of the repo:
 
 ```json
-{ "slug": "star-party", "name": "Star Party", "description": "Grab stars with everyone online.", "dir": "." }
+{
+  "slug": "kart-rush",
+  "name": "Kart Rush",
+  "description": "Race friends around twisty tracks.",
+  "dir": ".",
+  "genre": "Racing",
+  "icon": "store/icon.png",
+  "thumbnails": ["store/thumb-1.png", "store/thumb-2.png"],
+  "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),
+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.
 
 ## 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.
 
 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

@@ -13,19 +13,25 @@ var OIDC_AUDIENCE = "onceworlds";
 var LIMITS = {
   roomMaxPlayersDefault: 16,
   roomMaxPlayersCap: 50,
-  publicServersPerGame: 20,
+  teamsMax: 8,
   messageBytes: 16 * 1024,
   presenceBytes: 1024,
   stateKeyLength: 64,
   stateValueBytes: 16 * 1024,
   stateKeys: 256,
   messagesPerSecond: 60,
+  /** Bytes one player may send to a room per second, on average (bursts up to 4x). */
+  roomBytesPerSecond: 128 * 1024,
   presenceHz: 20,
   chatLength: 200,
   chatIntervalMs: 750,
   chatHistory: 50,
+  chatChannelsPerPlayer: 10,
   saveValueBytes: 64 * 1024,
   saveKeysPerGame: 100,
+  /** All of one player's saves in one game together (guests get less until they sign in). */
+  saveBytesPerGame: 1024 * 1024,
+  guestSaveBytesPerGame: 128 * 1024,
   deployFiles: 2e3,
   deployFileBytes: 25 * 1024 * 1024,
   deployTotalBytes: 100 * 1024 * 1024,
@@ -33,14 +39,70 @@ var LIMITS = {
   envValueBytes: 4 * 1024,
   proxyRequestBytes: 1024 * 1024,
   proxyResponseBytes: 10 * 1024 * 1024,
+  proxyMaxOutputTokens: 8192,
   proxyCallsPerDay: 2e3,
-  errorReportsPerPage: 10
+  proxyCallsPerDayMax: 1e5,
+  proxyCallsPerPlayerPerDay: 100,
+  proxyCallsPerNetworkPerDay: 1e3,
+  proxyMediaCallsPerDay: 100,
+  proxyMediaCallsPerDayMax: 1e4,
+  proxyMediaCallsPerPlayerPerDay: 20,
+  proxyMediaCallsPerNetworkPerDay: 25,
+  errorReportsPerPage: 10,
+  gameNameLength: 60,
+  gameDescriptionLength: 1e3,
+  galleryItems: 10,
+  mediaImageBytes: 5 * 1024 * 1024,
+  mediaVideoBytes: 30 * 1024 * 1024,
+  badgesPerGame: 100,
+  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,
+  bioLength: 500,
+  friendsMax: 200,
+  friendRequestsMax: 100,
+  passwordMinLength: 8,
+  passwordMaxLength: 72,
+  /** Account creation attempts, with or without email, per network (IP, or IPv6 /64) in 24 hours. */
+  signupsPerNetworkPerDay: 100,
+  /** New guest players per network per day (each one can hold saves). */
+  guestsPerNetworkPerDay: 300,
+  /** Visits a game gets per network (IP, or IPv6 /64) 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
 };
 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",
@@ -66,6 +128,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",
@@ -76,6 +139,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",
@@ -108,6 +176,82 @@ 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",
+  "Adventure",
+  "Fighting",
+  "Obby",
+  "Puzzle",
+  "Racing",
+  "Roleplay",
+  "Shooter",
+  "Simulation",
+  "Sports",
+  "Strategy",
+  "Survival",
+  "Tycoon",
+  "Horror",
+  "Party",
+  "Other"
+];
+var MAX_IMAGE_SIDE = 4096;
+function imageInfo(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const ascii = (at, text) => text.split("").every((c, i) => bytes[at + i] === c.charCodeAt(0));
+  if (bytes.length >= 24 && bytes[0] === 137 && ascii(1, "PNG\r\n\n") && ascii(12, "IHDR")) {
+    return { type: "image/png", width: view.getUint32(16), height: view.getUint32(20) };
+  }
+  if (bytes.length >= 10 && (ascii(0, "GIF87a") || ascii(0, "GIF89a"))) {
+    return { type: "image/gif", width: view.getUint16(6, true), height: view.getUint16(8, true) };
+  }
+  if (bytes.length >= 30 && ascii(0, "RIFF") && ascii(8, "WEBP")) {
+    if (ascii(12, "VP8 ")) {
+      return { type: "image/webp", width: view.getUint16(26, true) & 16383, height: view.getUint16(28, true) & 16383 };
+    }
+    if (ascii(12, "VP8L") && bytes[20] === 47) {
+      const bits = view.getUint32(21, true);
+      return { type: "image/webp", width: (bits & 16383) + 1, height: (bits >> 14 & 16383) + 1 };
+    }
+    if (ascii(12, "VP8X")) {
+      const width = (bytes[24] | bytes[25] << 8 | bytes[26] << 16) + 1;
+      const height = (bytes[27] | bytes[28] << 8 | bytes[29] << 16) + 1;
+      return { type: "image/webp", width, height };
+    }
+    return null;
+  }
+  if (bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216) {
+    let at = 2;
+    while (at + 9 < bytes.length) {
+      if (bytes[at] !== 255) return null;
+      const marker = bytes[at + 1];
+      if (marker === 255) {
+        at++;
+        continue;
+      }
+      const length = view.getUint16(at + 2);
+      const isFrame = marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204;
+      if (isFrame) return { type: "image/jpeg", width: view.getUint16(at + 7), height: view.getUint16(at + 5) };
+      at += 2 + length;
+    }
+  }
+  return null;
+}
+function imageSizeProblem(slot, width, height) {
+  if (width < 1 || height < 1 || width > MAX_IMAGE_SIDE || height > MAX_IMAGE_SIDE) {
+    return `Images can be at most ${MAX_IMAGE_SIDE}\xD7${MAX_IMAGE_SIDE} pixels.`;
+  }
+  if (slot === "thumbnail") {
+    if (Math.abs(width * 9 - height * 16) > 0.02 * width * 9) return "Thumbnails must be 16:9, like 1920\xD71080.";
+    if (width < 480) return "Thumbnails must be at least 480 pixels wide.";
+    return null;
+  }
+  const min = slot === "icon" ? 128 : 64;
+  if (Math.abs(width - height) > Math.max(2, 0.01 * Math.max(width, height))) return "This image must be square.";
+  if (width < min) return `This image must be at least ${min}\xD7${min} pixels.`;
+  return null;
+}
 
 // src/index.ts
 var PRODUCTION_API = "https://onceworlds.com";
@@ -118,15 +262,18 @@ var USAGE = `Usage:
 
 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")
+
+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,
@@ -152,12 +299,17 @@ ${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.`);
   }
   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);
   if (!quiet) console.log(`Deploying ${config.slug} (${files.length} files, ${formatBytes(total)}) to ${api}`);
   const token = await getToken(api, tokenArg);
   const start = await send("POST", `${api}/api/deploy`, token, {
@@ -165,12 +317,13 @@ 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 })),
     git: gitInfo(projectDir)
   });
-  const byHash = new Map(files.map((f) => [f.hash, f]));
+  const byHash = new Map([...images, ...files].map((f) => [f.hash, f]));
   const uploads = start.missing.map((hash) => byHash.get(hash));
   if (uploads.length > 0 && !quiet) {
     console.log(`  \u2191 uploading ${uploads.length} changed file(s), ${formatBytes(uploads.reduce((s, f) => s + f.size, 0))}`);
@@ -181,8 +334,9 @@ 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;
@@ -195,7 +349,8 @@ async function dev(projectDir, api, tokenArg) {
   Play (reloads on every change): ${first.playUrl}?watch
   Watching ${root}. Press Ctrl+C to stop.
 `);
-  let lastSignature = signature(await collectFiles(root, true));
+  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;
   let again = false;
@@ -206,7 +361,7 @@ async function dev(projectDir, api, tokenArg) {
     }
     running = true;
     try {
-      const current = signature(await collectFiles(root, true));
+      const current = await projectSignature();
       if (current !== lastSignature) {
         await deploy(projectDir, api, tokenArg, true);
         lastSignature = current;
@@ -250,7 +405,64 @@ ${USAGE}` : `Could not parse ${file}: ${err.message}`);
   if (typeof config.name !== "string" || !config.name.trim()) throw new CliError('"name" is required in onceworlds.json.');
   return config;
 }
-async function collectFiles(root, quiet) {
+async function loadStore(projectDir, config) {
+  const images = /* @__PURE__ */ new Map();
+  const image = async (value, slot, field) => {
+    if (typeof value !== "string" || !value.trim()) throw new CliError(`"${field}" in onceworlds.json must be the path of an image, like "store/icon.png".`);
+    const abs = resolve(projectDir, value);
+    if (!abs.startsWith(projectDir + sep)) throw new CliError(`"${field}" in onceworlds.json (${value}) must be inside the project folder.`);
+    let data;
+    try {
+      data = await readFile(abs);
+    } catch {
+      throw new CliError(`"${field}" in onceworlds.json: ${value} doesn't exist.`);
+    }
+    if (data.byteLength > LIMITS.mediaImageBytes) {
+      throw new CliError(`${value} is ${formatBytes(data.byteLength)}; game page images can be at most ${formatBytes(LIMITS.mediaImageBytes)}.`);
+    }
+    const info = imageInfo(data);
+    if (!info) throw new CliError(`${value} ("${field}") must be a PNG, JPEG, WebP or GIF.`);
+    const problem = imageSizeProblem(slot, info.width, info.height);
+    if (problem) throw new CliError(`${value} ("${field}") is ${info.width}\xD7${info.height}. ${problem}`);
+    const hash = createHash("sha256").update(data).digest("hex");
+    images.set(hash, { path: value, abs, hash, size: data.byteLength });
+    return { hash, size: data.byteLength };
+  };
+  const list = (value, max, field) => {
+    if (value === void 0) return [];
+    if (!Array.isArray(value)) throw new CliError(`"${field}" in onceworlds.json must be a list.`);
+    if (value.length > max) throw new CliError(`"${field}" in onceworlds.json can have at most ${max} items.`);
+    return value;
+  };
+  let genre = "";
+  if (config.genre !== void 0 && config.genre !== "") {
+    genre = GENRES.find((g) => g.toLowerCase() === String(config.genre).toLowerCase()) ?? "";
+    if (!genre) throw new CliError(`"genre" in onceworlds.json must be one of: ${GENRES.join(", ")}.`);
+  }
+  const icon = config.icon === void 0 ? null : await image(config.icon, "icon", "icon");
+  const thumbnails = [];
+  for (const [i, path] of list(config.thumbnails, LIMITS.galleryItems, "thumbnails").entries()) {
+    thumbnails.push(await image(path, "thumbnail", `thumbnails[${i}]`));
+  }
+  const badges = [];
+  for (const [i, value] of list(config.badges, LIMITS.badgesPerGame, "badges").entries()) {
+    const b = value ?? {};
+    const field = `badges[${i}]`;
+    const key = typeof b.id === "string" ? b.id : "";
+    if (!BADGE_KEY_RE.test(key)) throw new CliError(`"${field}.id" in onceworlds.json must be lowercase letters, digits and dashes, like "first-win".`);
+    if (badges.some((other) => other.key === key)) throw new CliError(`Two badges in onceworlds.json have the id "${key}".`);
+    const name = typeof b.name === "string" ? b.name.trim() : "";
+    if (!name || name.length > LIMITS.badgeNameLength) throw new CliError(`Badge "${key}" needs a name of 1-${LIMITS.badgeNameLength} characters.`);
+    const description = typeof b.description === "string" ? b.description.trim() : "";
+    if (description.length > LIMITS.badgeDescriptionLength) {
+      throw new CliError(`Badge "${key}": descriptions can be at most ${LIMITS.badgeDescriptionLength} characters.`);
+    }
+    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()] };
+}
+async function collectFiles(root) {
   const files = [];
   const skipped = [];
   async function walk(dir, prefix) {
@@ -280,9 +492,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");
@@ -299,7 +510,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) {
@@ -312,7 +522,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.1.1",
+  "version": "0.2.1",
   "description": "Deploy games to Onceworlds.",
   "homepage": "https://onceworlds.com",
   "type": "module",