@xgamesfun/xcore 0.3.0 → 0.4.0

package/README.md

@@ -191,14 +191,35 @@ has behind it, so the whole game runs before it is published:
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `http://127.0.0.1:8787/game/` | the published files (it runs `page.build` first, unless `--no-build`), with the play host's headers                                                                                                                                                                                                                                                                                                                |
 | `/game/api/*`                 | the game's `server/` under workerd, the runtime xgames.fun runs it on: Durable Objects with their storage kept, WebSockets, `env.GF`, the game's database (a local D1 in `.gamesfun/dev/d1/`, its migrations applied), and its secrets from `.dev.vars`. A change under `server/` or to `.dev.vars` reloads it. Miniflare (with workerd, about 140 MB) is installed once, the first time a game with a server runs |
-| `/platform/v1/*`              | sign-in, saves and leaderboards: `gamesfun.js` signs in a local player (each tab its own, so two tabs play a room together), and `env.GF.verifyPlayer` accepts its token. Saves and scores are kept in `.gamesfun/dev-platform.json`, never published                                                                                                                                                              |
+| `/platform/v1/*`              | sign-in, saves and leaderboards: `gamesfun.js` signs in a local player (each tab its own, so two tabs play a room together), and `env.GF.verifyPlayer` accepts its token. Saves and scores are kept in `.gamesfun/dev-platform.json`, never published, and held to the limits of the plan it imitates (below)                                                                                                      |
 | `/platform/v1/live`           | the game's live settings (`gf.live`, below): its announcement, config and maintenance, from `.gamesfun/live.json` (read again on each request, never published). With maintenance on there, the game's pages show the holding page and its `api/` and `/platform/v1/*` answer `503` with code `maintenance`, as hosted                                                                                             |
 | `http://127.0.0.1:8788/`      | the game's public project files (`env.GF.files`, `xcore files`), kept in `.gamesfun/dev/files/`: another origin, as `<slug>.xgamesusercontent.com` is to the published game                                                                                                                                                                                                                                        |
 | `/loot/v1/rpc`                | the economy's Solana devnet RPC: xgames.fun's shared relay (what a published page talks to unless the game brings its own: `xcore add rpc`), or your own with `XSOLANA_RPC_URL` in `.env` (its URL is never shown; a call the shared relay would refuse is said in the terminal). The economy's calls answer once it is live on devnet (`xcore loot approve`)                                                      |
 
 Games made with any engine get all of it through `gamesfun.js` (`xcore add signin`): on a plain local server it stands
-in with this browser's storage; under `xcore dev` it uses the real thing. What is not the same as hosted: no CPU or
-request limits, and the server's outbound `fetch` is not limited to `backend.json`'s origins.
+in with this browser's storage; under `xcore dev` it uses the real thing.
+
+**The plan's limits, refused as published.** `xcore dev` imitates one plan, Free unless `--plan creator` or `--plan
+scale` (it says which when it starts), and its platform refuses what xgames.fun refuses on that plan, with the same
+codes: the plan's boards (8 on Free) and board rules (16), entries a board (10,000), save bytes a game (10 MB), and
+reads (1,200) and writes (600 saves, 600 scores) a minute, the server's and the pages' counted apart; project files'
+total and the plan's file calls a minute (120). What a page may do is the same on every plan: it makes `high` boards
+only, two a player and half the plan's boards in all (the game's server makes the rest, `low` ones too, and
+`GF.scores.list` shows who made each); one player's saves from the page keep at most 1/128 of the game's save bytes
+(80 KB on Free), and with the game's saves full a player still keeps 4 KB; one player writes 60 saves and 30 scores a
+minute; a body is JSON (`content-type: application/json`) of at most 96 KB. A board read from the page shows each player
+as an id of the game's own (16 letters and digits), never their account, with `me: true` on the caller's entry; without
+a player token it reads the top 100 only (`offset` plus `limit` past 100 answers 401), may get the same answer again
+for 5 seconds, and has its own minute (a tenth of the plan's reads). Ranks and offsets are counted to 10,000 (past it a
+rank is `10001` with `rankAtLeast: true`). A public project file is an image, audio, video, a font, JSON or plain text
+whose first bytes are that type (else private), and `env.GF.files.put` holds at most 1 MB of a string or ArrayBuffer
+body (a bigger file goes as a stream with its `length`).
+
+What is not imitated, and said instead: one player's requests to the game's server a minute and its CPU a request (the
+dev log says when a request would pass them), and one address's reads of `/platform/v1` at the play edge (120 a minute;
+here every tab is one address). Not imitated at all: the network's delays, the owner's moderation (bans, blocked
+words), the board ids of the published game (these are this machine's own), and the server's outbound `fetch`, which is
+not limited to `backend.json`'s origins. The counts a minute start again when `xcore dev` does.
 
 ## 3. Players, a database, a backend
 
@@ -214,8 +235,9 @@ engine takes:
 | A Godot 4 project | `addons/gamesfun/gamesfun.gd`, autoloaded as `GamesFun`                                             | `await GamesFun.sign_in()`, `await GamesFun.saves_put("main", {})` |
 | A Unity project   | `Assets/Plugins/GamesFun/` (`GamesFun.jslib`, `GamesFun.cs`)                                        | `await GamesFun.SignIn()`, `await GamesFun.SavesPut("main", json)` |
 
-The same calls everywhere: sign in and out, the player (`id`, `name`, `level`, `wallet`, `x`), saves (any JSON, 64 KB
-each, 16 a player), leaderboards (submit, top, the player's own), the game's database (below) and its own server
+The same calls everywhere: sign in and out, the player (`id`, `name`, `level`, `wallet`, `x`; `id` is the player's
+account, `x:<X id>` or for a Google account `g:<id>`, an id different in every game, and never the wallet, which is
+`wallet`, empty when the account has none), saves (any JSON, 64 KB each, 16 a player), leaderboards (submit, top, the player's own), the game's database (below) and its own server
 (`api`). Every call answers `{data, error, status}` and none throws, so a game plays on as a guest wherever xgames.fun is
 not there.
 
@@ -232,7 +254,9 @@ from the page, so anyone can submit any score for themselves from the browser's
 makes a board nobody can write that way: `env.GF.scores.setup('ranked', {writer: 'server'})` (or a pattern for boards
 to come, `'daily-*'`), then the page's submits
 to it are refused (their answer's `code` is `'server-only'`, HTTP 403) and the server submits each run it checked; the page reads the board as before
-([docs/SERVER.md](docs/SERVER.md)).
+([docs/SERVER.md](docs/SERVER.md)). A board a page makes ranks higher first; a lower-first board (a time) is made by
+the game's server, and a page's `order: 'low'` for a new board is refused (`code: 'order'`). `scores.top` gives each
+entry's `player` as an id of this game's own and marks the signed-in player's own entry `me: true`.
 
 Where the sign-in comes from:
 
@@ -246,9 +270,15 @@ Where the sign-in comes from:
   can be made and tested before it is published. Under `xcore dev`, a local sign-in (one player a tab) and the
   platform answer as xgames.fun does, and the game's `server/` accepts its token.
 
-The token lasts an hour and stays in the page's memory. The game's `server/` checks it with `env.GF.verifyPlayer`; a
-backend of your own checks it with any JWT library against `https://<slug>-play.xgames.fun/player/v1/key` (issuer
-`xgames.fun`, audience `game:<slug>`).
+The token lasts an hour and stays in the page's memory. The game's `server/` checks it with `env.GF.verifyPlayer`,
+first thing, before any work: a request without one answers 401 at once, since strangers' requests that do work count
+toward what caps a game ([docs/SERVER.md](docs/SERVER.md), "Check the token first"). A backend of your own checks it
+with any JWT library against `https://<slug>-play.xgames.fun/player/v1/key` (issuer `xgames.fun`, audience
+`game:<slug>`). Its `sub` is the player's account (`x:<X id>`, or `g:<id>` for Google, different in every game);
+`wallet` is a claim of its own, and may be absent: a game that keeps a player's data by wallet reads `wallet`.
+xgames.fun replaces its signing key from time to time: a backend that keeps the key set must fetch it again when a
+token names a key id (`kid`) it does not hold, once, not in a loop (most JWT libraries' remote key sets do).
+`gamesfun.js` and the Godot and Unity clients check no token themselves.
 
 The page calls the game's own server with `GamesFun.api(path, init)` (Godot `GamesFun.api(path, init)`, Unity
 `GamesFun.Api(path, initJson)`): `path` is relative to the game's `api/` (`'finish'` is `api/finish`, at the
@@ -498,7 +528,7 @@ holds the addresses the economy went live at stays in the project (keep it in gi
 runs the tools from a terminal. Going live is the person's own step, approved in their own wallet: `xcore loot
 approve` in the folder with `xsolana.json`.
 
-**When loot is upgraded.** This package pins the tools for one build of loot (0.25.0). loot is upgraded in place on
+**When loot is upgraded.** This package pins the tools for one build of loot (0.26.0, on devnet since 2026-11-10). loot is upgraded in place on
 devnet, and no version so far has carried accounts over: an economy that went live on an earlier build goes live
 again (`xcore loot approve`), and the next publish brings `gf/loot/` up to the installed package. **Nothing runs by
 itself** on chain: the page client sends what a player needs (settles, refunds, claims, a draw that is due); a
@@ -549,7 +579,10 @@ vouchers changed since its last review (it never refuses for it).
 ## 5. Publish
 
 `xcore login` signs this computer in (your browser signs in to xgames.fun and hands it a publish token for 30
-days; xcore never sees your password). `xcore publish <folder>` then builds the game, checks it (the page
+days; xcore never sees your password). On the approval page you tick the games this computer may work on, or your
+whole account, and `xcore login` says which it got (`login --status` says it again). A game you publish as new from
+that sign-in is added to it; a command for any other game is refused with code `not-granted` ("your sign-in was not
+given this game"): run `xcore login` again and tick it. `xcore publish <folder>` then builds the game, checks it (the page
 check on exactly the files built), and uploads its published folder with its `server/` bundle:
 
 1. **The files**: the published folder, without hidden files, `evidence/`, `node_modules/`, `server/`, `supabase/` and the makers' notes at its top (`README.md`, `NOTES.md`, `LAUNCH.md` and the like). A `.env` file or a link
@@ -623,8 +656,11 @@ free their slot unless their link is still live. What the game's server, saves a
 | Sites that embed it  | 3 (`xcore embed`)                                                  | 10                                                   | 25                      |
 | Domains of your own  | none                                                               | 1 (`xcore domain`)                                   | 5                       |
 
-Past what is included, a game is **capped** until the month ends: its server answers at most 60 requests a minute (20
-from one player) and saves and scores slow down, but nothing is lost and the game keeps working. Paid slots are $15 for
+Past what is included, a game is **capped** until the month ends: **its server is switched off** (every `api/*` request
+answers 451 with `reason: "capped"`, and a room that is running stops within about five minutes), and saves and scores
+slow down (60 save writes, 30 score submits and 60 reads a minute). Its pages keep loading and nothing is lost: the server comes
+back by itself when the cap lifts ([docs/SERVER.md](docs/SERVER.md), "Publishing it"). An unpublished or taken-down
+game's server is switched off the same way. Paid slots are $15 for
 30 days, prepaid in SOL or USDC on xgames.fun (your console → Plans; no automatic renewal, 7 days' grace after the period
 ends; when they end, their games go back to free slots and nothing is taken down).
 Usage credit, bought the same way, lets Creator games go past what their slots include, at twice what xgames.fun pays,
@@ -706,9 +742,9 @@ without one needs none: the D1 database, `xcore db` and `xcore files` are new.
   WebAssembly). Such a server runs on a host of your own, declared with `backend use custom`; or its logic moves into
   `server/`, or into the page itself (WebAssembly is allowed: Pyodide runs Python in the browser). Each is a change to
   how the game is built: the person who made it decides.
-- **A Node server as the backend on xgames.fun**: `server/` is a Worker, not Node (Node built-ins only with
-  `nodejs_compat`, and no `fs`, `child_process` or listening sockets). A Node backend runs on a host of your own,
-  declared with `backend use custom`.
+- **A Node server as the backend on xgames.fun**: `server/` is a Worker, not Node (no Node built-ins: `nodejs_compat`
+  is not offered; no `fs`, `child_process`, raw sockets or listening sockets). A Node backend runs on a host of your
+  own, declared with `backend use custom`.
 - **Scripts, style sheets and fonts from a CDN**: the page loads code and styles from its own files only, so a copy goes
   in the game (or the package is bundled).
 - **A fallback to `index.html` for every path**: deep links of a client-side router reload to "not found"; use a hash

package/commands/dev.mjs

@@ -4,21 +4,25 @@ import { guard, parse, printJson, UsageError } from '../lib/cli.mjs';
 import { resolveGame, shown } from '../lib/games.mjs';
 import { madeByKit } from '../lib/publish/index.mjs';
 import { CMD } from '../lib/command.mjs';
+import { PLAN_NAMES } from '../lib/dev/plans.mjs';
 
-const usage = `Usage: xcore dev [dir] [--port <n>] [--no-build] [--open] [--json]
+const usage = `Usage: xcore dev [dir] [--port <n>] [--plan <name>] [--no-build] [--open] [--json]
 
 Play the game on this machine as xgames.fun will host it, with everything a published game has behind it:
   http://127.0.0.1:<port>/game/   the published files, with the play host's headers
   /game/api/*                     the game's own server/ (Durable Objects, WebSockets, env.GF), reloaded on change
-  /platform/v1/*                  sign-in (a local player), saves and leaderboards, the same store env.GF uses
+  /platform/v1/*                  sign-in (a local player), saves and leaderboards, the same store env.GF uses,
+                                  with xgames.fun's limits on the plan it imitates (Free unless --plan)
   /loot/v1/rpc                    the economy's Solana devnet RPC (XSOLANA_RPC_URL in .env, else xgames.fun's relay)
 gamesfun.js (${CMD} add signin|database|multiplayer) uses all of it here, from any engine: open the page in two
 windows to play a room together. Running server/ needs Miniflare (workerd), installed once on first use (~140 MB).
 Saves, scores and Durable Object storage are kept in <dir>/.gamesfun/ (never published).
-  --port <n>   the port (default 8787)
-  --no-build   serve what is built already; do not run gamesfun.json page.build first
-  --open       open the page in your browser
-  --json       print where it runs as JSON, then keep running`;
+  --port <n>      the port (default 8787)
+  --plan <name>   the plan to imitate: free (the default), creator or scale: its boards, saves, reads and writes a
+                  minute and file sizes, as xgames.fun holds a game on that plan (${CMD} plan shows a game's own)
+  --no-build      serve what is built already; do not run gamesfun.json page.build first
+  --open          open the page in your browser
+  --json          print where it runs as JSON, then keep running`;
 
 export default {
   name: 'dev',
@@ -28,12 +32,20 @@ export default {
     guard(async () => {
       const { values, positionals } = parse(
         args,
-        { port: { type: 'string' }, 'no-build': { type: 'boolean' }, open: { type: 'boolean' } },
+        {
+          port: { type: 'string' },
+          plan: { type: 'string' },
+          'no-build': { type: 'boolean' },
+          open: { type: 'boolean' },
+        },
         usage,
       );
       const port = values.port === undefined ? 8787 : Number(values.port);
       if (!Number.isInteger(port) || port < 0 || port > 65535)
         throw new UsageError(`--port is a port number\n\n${usage}`);
+      const plan = String(values.plan ?? 'free').toLowerCase();
+      if (!PLAN_NAMES.includes(plan))
+        throw new UsageError(`--plan is ${PLAN_NAMES.slice(0, -1).join(', ')} or ${PLAN_NAMES.at(-1)}\n\n${usage}`);
       const dir = await resolveGame(positionals[0]);
       if (madeByKit(dir)) {
         console.error(
@@ -45,18 +57,27 @@ export default {
       const { startDev } = await import('../lib/dev/index.mjs');
       let dev;
       try {
-        dev = await startDev(dir, { port, noBuild: values['no-build'] === true, log: say });
+        dev = await startDev(dir, { port, plan, noBuild: values['no-build'] === true, log: say });
       } catch (e) {
         if (e.code === 'EADDRINUSE')
           throw new Error(`port ${port} is in use: pick another with --port <n>`, { cause: e });
         throw e;
       }
       if (values.json)
-        printJson({ url: dev.url, origin: dev.origin, files: dev.files, server: dev.server, rpc: dev.rpc });
+        printJson({
+          url: dev.url,
+          origin: dev.origin,
+          files: dev.files,
+          server: dev.server,
+          rpc: dev.rpc,
+          plan: dev.plan,
+        });
       else {
         say(`\n${shown(dir)} on this machine: ${dev.url}`);
         say(`  server: ${dev.server ? (dev.server.running ? 'running' : 'not running (above)') : 'none (no server/)'}`);
-        say(`  sign-in, saves, scores: a local player; kept in ${shown(dev.store.file)}`);
+        say(
+          `  sign-in, saves, scores: a local player, with the ${dev.store.plan.name} plan's limits; kept in ${shown(dev.store.file)}`,
+        );
         say(`  project files (env.GF.files, xcore files): public ones at ${dev.files}/, an origin of their own`);
         say(`  economy RPC: ${dev.rpc}`);
         say('Ctrl+C stops it.');

package/commands/login.mjs

@@ -1,17 +1,20 @@
 import { createInterface } from 'node:readline/promises';
 import { guard, parse, printJson } from '../lib/cli.mjs';
 import { openUrl } from '../lib/open.mjs';
-import { login, signInState, storeWords, studioOrigin } from '../lib/publish/client.mjs';
+import { signInState, studioOrigin } from '../lib/publish/client.mjs';
+import { currentReach, loginWithReach, loginWords, reachWords } from '../lib/login-reach.mjs';
 import { storeName } from '../lib/credentials.mjs';
 import { CMD } from '../lib/command.mjs';
 
 const usage = `Usage: xcore login [--code] [--status] [--json]
 
 Sign in to xgames.fun so you can publish your games (${CMD} publish). Your browser opens xgames.fun: sign in
-there and approve this computer. xcore never sees your password; it keeps a publish token for 30 days in
-${storeName()} (never in a game or in this folder). ${CMD} logout ends it.
+there, tick the games this computer may work on (or your whole account) and approve. xcore says which it got; a game
+you publish as new from here is added to them, and for another, run ${CMD} login again and tick it. xcore never sees
+your password; it keeps a publish token for 30 days in ${storeName()} (never in a game or in this folder).
+${CMD} logout ends it.
   --code     no browser on this machine (SSH, a container): open the printed link anywhere and paste the code it shows
-  --status   who this computer is signed in as, and where the token is kept
+  --status   who this computer is signed in as, which games it reaches, and where the token is kept
 GAMESFUN_STUDIO=<origin> signs in to another xgames.fun (a local Studio while developing).`;
 
 export default {
@@ -24,13 +27,24 @@ export default {
       const origin = studioOrigin();
       if (values.status) {
         const { token: _token, words, ...s } = await signInState(origin);
-        if (values.json) printJson({ ...s, signedIn: s.state === 'signed-in' });
-        else console.log(s.state === 'signed-in' ? words : `${words} Run: ${s.next}`);
+        const reach = s.state === 'signed-in' ? await currentReach(origin) : null;
+        if (values.json)
+          printJson({
+            ...s,
+            signedIn: s.state === 'signed-in',
+            ...(reach ? { scope: reach.scope, games: reach.games, reachChecked: reach.checked } : {}),
+          });
+        else
+          console.log(
+            s.state === 'signed-in'
+              ? `${words}${reachWords(reach) ? ` ${reachWords(reach)}` : ''}`
+              : `${words} Run: ${s.next}`,
+          );
         return 0;
       }
       const rl = values.code ? createInterface({ input: process.stdin, output: process.stderr }) : null;
       try {
-        const r = await login({
+        const r = await loginWithReach({
           origin,
           code: values.code,
           open: url => openUrl(url, { web: true }),
@@ -38,10 +52,7 @@ export default {
           log: m => console.error(m),
         });
         if (values.json) printJson({ studio: origin, ...r });
-        else
-          console.log(
-            `Signed in to ${origin} as ${r.email}. The token is kept in ${storeWords(r.store)} until ${new Date(r.expiresAt).toISOString().slice(0, 10)}. Next: ${CMD} publish`,
-          );
+        else console.log(loginWords(r));
         return 0;
       } finally {
         rl?.close();

package/commands/logout.mjs

@@ -1,5 +1,6 @@
 import { guard, parse, printJson } from '../lib/cli.mjs';
 import { logout, studioOrigin } from '../lib/publish/client.mjs';
+import { forgetReach } from '../lib/login-reach.mjs';
 
 const usage = `Usage: xcore logout [--json]
 
@@ -26,6 +27,7 @@ export default {
       const { values } = parse(args, {}, usage);
       const origin = studioOrigin();
       const r = await logout(origin);
+      await forgetReach(origin);
       if (values.json) printJson({ studio: origin, ...r });
       else
         console.log(

package/docs/SERVER.md

@@ -35,7 +35,7 @@ my-game/
 | `main`               | default `server/index.js`; a `.js` or `.mjs` file under `server/`                                                                                                                                                                                                                                                                                               |
 | `objects`            | 0–8 Durable Objects (a room, a run, a vault): `class` is the class the entry exports, `binding` the name it has on `env` (A–Z, 0–9 and `_`, starting with a letter, at most 32 characters, never `GF` or `GF_…`). Each gets its own SQLite storage. **Append only**: once published, keep every class (removing one deletes its data, so the upload refuses it) |
 | `routes`             | `"/api/*"`, the only value for now                                                                                                                                                                                                                                                                                                                              |
-| `compatibilityFlags` | empty, or `["nodejs_compat"]` to use `node:crypto`, `node:buffer` and the other Node built-ins a Worker has                                                                                                                                                                                                                                                     |
+| `compatibilityFlags` | empty. `["nodejs_compat"]` is not offered: with Node's built-in modules a server can open raw network connections, so xgames.fun refuses a publish that asks for it, and the kit's check says so first. Use the Web APIs a Worker has (`fetch`, `crypto.subtle`, `URL`, `TextEncoder`)                                                                          |
 
 Without a `gamesfun.json` server entry, a `server/index.js` alone is a server with no objects. `server/` and
 `gamesfun.json` are **never served** as files, and a game with a server keeps no files under `api/` (its `/api/*` is
@@ -50,7 +50,7 @@ export class Vault extends DurableObject {
 }
 export default {
   async fetch(request, env, ctx) {
-    /* every /api/* request of the game, URL unchanged */
+    /* every /api/* request of the game, URL unchanged: check the player's token first (below) */
   },
 };
 ```
@@ -63,24 +63,38 @@ export default {
   `env.GF_GAME_ID`, `env.GF_SLUG` and `env.GF_CONTRACT` (`"gf-server-v1"`), and your own secrets as `env.<NAME>`
   (below, "Secrets"). No key of xgames.fun's. Keep keys out of server code: publish refuses one it finds.
 - **Runtime**: Cloudflare Workers, compatibility date `2025-06-01`.
-- **Outbound `fetch`** reaches only the origins in your `backend.json` and xgames.fun's own. To read Solana devnet
-  from the server, call xgames.fun's relay, `https://play.xgames.fun/loot/v1/rpc` (the methods loot's client uses, one
-  request a call): the public devnet RPC (`api.devnet.solana.com`) answers the Workers runtime with 403 ("Your IP or
-  provider is blocked"), under `xcore dev` as well.
-- **Limits**: set by the game's plan (README §5, `xcore plan`). Free: 50 ms of CPU per request to `fetch`, 20
-  subrequests, **600 requests a minute per game and 120 from one player**; Creator: 200 ms, 50, 6,000 and 600; a 5 MB
-  bundle on every plan. Past a rate, `/api/*` answers 429 with `retry-after: 60`, `scope` (`"player"` or `"game"`)
-  and `plan`. Keep frequent traffic,
+- **Outbound `fetch`**: the list in `backend.json` (and xgames.fun's own origins) applies to the calls your server's
+  entry makes while it answers a request; any other answers 403 with the header `x-gf-outbound: refused`. Do not rely
+  on it for anything else: keep what your Durable Objects call to what they need, in their own code. No number of calls
+  out a request is promised. To read Solana devnet from the server, call xgames.fun's relay,
+  `https://play.xgames.fun/loot/v1/rpc` (the methods loot's client uses, one request a call): the public devnet RPC
+  (`api.devnet.solana.com`) answers the Workers runtime with 403 ("Your IP or provider is blocked"), under `xcore dev`
+  as well.
+- **Limits**: set by the game's plan (README §5, `xcore plan`). Free: 50 ms of CPU per request to `fetch`, **600
+  requests a minute per game and 120 from one player**; Creator: 200 ms, 6,000 and 600; a 5 MB bundle on every plan.
+  Requests with no good game token share half of the game's minute (Free: 300), so signed-in players always have the
+  other half. Past a rate, `/api/*` answers 429 with `retry-after: 60`, `scope` (`"player"` or `"game"`) and `plan`.
+  Keep frequent traffic,
   such as positions in a real-time game, on a WebSocket rather than in many HTTP requests. A Durable
   Object's WebSocket counts as one request for its whole life, but a room's messages are held to a few milliseconds
   of CPU each **on every plan** (a bigger plan raises a request's CPU, not a room's): a room doing ~3 ms a message ran
   for minutes, one doing ~15 ms was reset within seconds (every socket closes with code 1006). Do a room's work as
   messages arrive rather than in timers, keep it to a millisecond or two per message, and reconnect on 1006. Heavy
   work (a replay, a long simulation) goes in an HTTP request instead, which gets the plan's CPU.
-- **Not allowed**: code made from text at run time (`eval`, `new Function`, `import()` of a computed path,
-  `importScripts`), files from outside the game folder (packages from `node_modules` are fine), Node built-ins without
-  `nodejs_compat`, and those a Worker does not have even with it (`node:fs`, `child_process`, `vm`, …). The check names
-  the file and line.
+- **Not allowed** (the kit's check names the file and line before anything is sent; xgames.fun refuses the same at
+  publish):
+  - **raw network connections**: an import, a re-export or an `import()` of `cloudflare:sockets`, `node:net`,
+    `node:tls`, `node:dgram`, `node:http2`, `node:module` or `node:child_process` (with or without `node:`), in the
+    server's own code or in a package it bundles. A game's server reaches the network with `fetch()` only: a
+    database driver or a mail or chat client that opens sockets runs on a host of your own;
+  - **an `import()` of a name made at run time** (`import(name)`): it could load any module. Import each module by
+    its own name; a path esbuild can list when it bundles (``import(`./levels/${name}.js`)``) is bundled, every
+    file there, and is fine. xgames.fun parses the bundle it is sent; the kit reads the same bundle with esbuild's
+    own parser, never by searching its text, so a word in a comment or a string is not an import;
+  - **Node's built-in modules** (`node:crypto`, `node:buffer`, `fs`, …): `nodejs_compat` is not offered, so use the
+    Web APIs a Worker has (`crypto.subtle`, `crypto.getRandomValues`, `TextEncoder`, `URL`);
+  - code made from text at run time (`eval`, `new Function`, `importScripts`; the runtime refuses them too), and files
+    from outside the game folder (packages from `node_modules` are fine).
 - **One request at a time, between awaits.** A Durable Object holds other requests back while it waits on its own
   storage, but an `await` of anything else (`fetch`, `env.GF.verifyPlayer`, another object) lets the next request
   in. Read and update a player's state (a daily cap, a balance) with nothing but storage calls in between: verify
@@ -106,6 +120,36 @@ export default {
   (Rapier's `rapier_wasm2d.js` is such a loader; a game running the same deterministic build in the page and in the
   server got identical results.)
 
+### Check the token first
+
+A request with no good game token is a stranger's. Check the token before any work, and answer 401 at once without
+one: the work your server does for callers with no token (reading the database, waking a room, calling out) counts
+toward what caps your game, and a capped game's server is switched off until the month ends ("Publishing it", below).
+
+```js
+export default {
+  async fetch(request, env) {
+    // what is truly public (a leaderboard everyone sees) may come before this; nothing else does
+    const token = /^Bearer\s+(\S+)$/i.exec(request.headers.get('authorization') ?? '')?.[1];
+    if (!token) return Response.json({ why: 'Sign in first.' }, { status: 401 }); // no call, no work: cheap
+    const player = await env.GF.verifyPlayer(token); // its signature, its audience (this game) and its expiry
+    if (!player.ok) return Response.json({ why: 'Sign in again.' }, { status: 401 });
+    // from here on, player.sub is who is asking
+    return Response.json(await env.GF.saves.get(player.sub));
+  },
+};
+```
+
+- `env.GF.verifyPlayer` checks the token's signature, that it was made for this game (its audience, `game:<slug>`)
+  and that it has not expired. A backend of your own that checks tokens with a JWT library checks all three:
+  `jwtVerify(token, keys, { issuer: 'xgames.fun', audience: 'game:<slug>' })`, never the signature alone (every
+  game's tokens are signed with one key, so a token without its audience checked is any game's).
+- The page sends it for you: `GamesFun.api(path)` adds `Authorization: Bearer …` for a signed-in player. A WebSocket
+  cannot carry that header: send `GamesFun.token` in the address (below).
+- `server/gf-db.js`'s `withPlayer(request, env)` is the same check (null without a token, with no call made).
+- `xcore review` names a server of the game's own whose files do work and never check a token, and an entry whose
+  `fetch` does work before its first check (fine for what is truly public, and yours to decide).
+
 ### A room over a WebSocket
 
 A Durable Object holds the room: every player's socket is accepted there, and a message from one goes to the others.
@@ -129,8 +173,14 @@ export class Room extends DurableObject {
 export default {
   async fetch(request, env) {
     const url = new URL(request.url);
-    if (url.pathname === '/api/room') return env.ROOM.get(env.ROOM.idFromName('main')).fetch(request);
-    return new Response('not found', { status: 404 });
+    if (url.pathname !== '/api/room') return new Response('not found', { status: 404 });
+    // the player first, before the room is woken: a WebSocket cannot carry an Authorization header, so the page sends
+    // its token in the address
+    const token = url.searchParams.get('token');
+    if (!token) return new Response('sign in first', { status: 401 });
+    const player = await env.GF.verifyPlayer(token);
+    if (!player.ok) return new Response('sign in again', { status: 401 });
+    return env.ROOM.get(env.ROOM.idFromName('main')).fetch(request);
   },
 };
 ```
@@ -139,6 +189,7 @@ export default {
 // the page
 const url = new URL('api/room', document.baseURI);
 url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+url.searchParams.set('token', GamesFun.token);
 const socket = new WebSocket(url);
 ```
 
@@ -146,8 +197,8 @@ const socket = new WebSocket(url);
 server, so it notes the socket instead of failing on it.
 
 **When you publish an update**, the page's files and the server change within about 30 seconds, not all at once, and
-a room that has players connected can keep running the previous code until it empties. Make your messages tolerate one
-version talking to the other (a version number in the first message is enough to tell a player to reload).
+a room that is running keeps the previous code for up to about five minutes. Make your messages tolerate one version
+talking to the other (a version number in the first message is enough to tell a player to reload).
 
 ### `env.GF`, the platform
 
@@ -157,11 +208,18 @@ Every call answers `{ok: true, …}` or `{ok: false, code, why}` (`why` is words
 | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `GF.verifyPlayer(token)`                                                                                                                                                                            | `{ok, sub, wallet, x, lvl, exp, banned}`: who the player is, from the sign-in token the page sends (no display name: show `x.handle` when they signed in with X, else a name the page sends, cleaned). `banned`: the creator's ban from the console (`{kind: 'ban' \| 'hide', until}`, or null; always null in `xcore dev`). A token made before a ban still verifies for its hour, so refuse `kind: 'ban'` yourself |
 | `GF.saves.get(player, key = 'main')`, `.put(player, key, value)`, `.delete(player, key)`, `.list(player)`                                                                                           | a player's saves: any JSON value, 64 KB each, 16 a player                                                                                                                                                                                                                                                                                                                                                            |
-| `GF.scores.submit(board, player, score, {name, order, writer})`, `.setup(board, {order, writer})`, `.top(board, {limit, offset})`, `.best(board, player)`, `.remove(board, player)`, `.drop(board)` | leaderboards: a player's best is kept; `order` `"high"` (default) or `"low"`; `writer: "server"`: only the server writes the board (or every board a pattern names: `daily-*`, `*`); `drop`: the board gone, its place among the 16 free                                                                                                                                                                             |
+| `GF.scores.submit(board, player, score, {name, order, writer})`, `.setup(board, {order, writer})`, `.top(board, {limit, offset})`, `.best(board, player)`, `.remove(board, player)`, `.drop(board)` | leaderboards: a player's best is kept; `order` `"high"` (default) or `"low"`; `writer: "server"`: only the server writes the board (or every board a pattern names: `daily-*`, `*`); `drop`: the board gone, its place among the plan's boards free                                                                                                                                                                  |
 | `GF.loot.report({round, endedAt, winners})`, `GF.loot.status()`                                                                                                                                     | a result that pays prizes by place: xgames.fun's keeper signs it with the game's host key (set up by the owner in Studio); for amounts your server works out, your own key (below, "Paying a result")                                                                                                                                                                                                                |
 | `GF.info()`                                                                                                                                                                                         | `{ok, contract, gameId, slug}`                                                                                                                                                                                                                                                                                                                                                                                       |
 | `GF.files.put(path, body, {type, public, length})`, `.get(path)`, `.head(path)`, `.list({prefix, after})`, `.delete(path)`, `.usage()`                                                              | the game's project files (below, "Project files"): replays, levels, content packs; public ones on the files site                                                                                                                                                                                                                                                                                                     |
 
+**Who the player is.** `sub` is the player's account, never their wallet: `x:<X id>` for a player signed in with X,
+or `g:<id>` for a Google account with no X, an id that is **different in every game** (so it never says who the
+person is elsewhere). `wallet` is a claim of its own: the wallet linked to the account, or null when there is none, and
+it can change (a player links another). Key a player's data (saves, rows, rooms) on `sub`; read `wallet` only for what
+is about the wallet itself (paying it, what it holds). A game that kept a player's data by wallet reads `wallet` now,
+and one that keys on `sub` must not expect a Google player's id to match the same person's in another game.
+
 `player` is the game's own word for a player; normally `verifyPlayer`'s `sub`, so nobody can write another player's.
 The page writes the same saves and boards for its own signed-in player (`/platform/v1/*`), so a board is the player's
 own word until the server takes it: **`GF.scores.setup(board, {writer: 'server'})`** (or `writer: 'server'` in the
@@ -171,7 +229,8 @@ server's own `submit`) makes a board only the server writes. From then on the pa
 the page wrote while anyone could write it is removed (`setup` answers how many, `removed`). **A pattern** names every
 board starting that way, now and to come: `GF.scores.setup('daily-*', {writer: 'server'})` before the first day, and
 nobody fills a day's board ahead of time; `GF.scores.setup('*', {writer: 'server'})` keeps the page from making
-boards at all (a board's own rule wins over a pattern, a longer pattern over a shorter one). A game has 16 boards:
+boards at all (a board's own rule wins over a pattern, a longer pattern over a shorter one). A game has 8 boards on
+Free (16 rules) and 16 on Creator and Scale (32 rules):
 **`GF.scores.drop(board)`** removes one (a past day's, once its prizes are paid) and frees its place. Only the server
 can set or lift a rule (`writer: 'any'`) or drop a board.
 
@@ -258,8 +317,9 @@ xcore secret set XSOLANA_RPC_URL         # the RPC's URL with its key: the serve
   `getProgramAccounts` only with filters and only of loot's own programs (loot, Metaplex Core, lookup tables); and
   `sendTransaction` only for the game's own transactions (one with a loot instruction, or a plain SOL send). So a
   stranger calling `api/rpc` cannot spend your RPC's credits on anything else. Mainnet URLs are not used (loot runs on devnet until it is audited).
-- The server may call only `backend.json`'s origins: `xcore add rpc` adds the RPC's (`https://host` alone, never the
-  key) when `XSOLANA_RPC_URL` is in `.dev.vars` or `.env`, and publish says when it is missing.
+- The server's entry, where `api/rpc` runs, may call only `backend.json`'s origins: `xcore add rpc` adds the RPC's
+  (`https://host` alone, never the key) when `XSOLANA_RPC_URL` is in `.dev.vars` or `.env`, and publish says when it
+  is missing.
 - Solana's public `https://api.devnet.solana.com` refuses calls from Cloudflare ("Your IP or provider is blocked",
   measured 2026-11-03): use a provider's URL.
 - Under `xcore dev`, put `XSOLANA_RPC_URL` in `.dev.vars` to run this path; in `.env` it is the dev server's own
@@ -622,6 +682,14 @@ my-vault: 278 files, 10.0 MB, nothing refused. Left out: .gamesfun/, .gitignore,
 Hosted, the game's server answers at `https://<slug>-play.xgames.fun/api/…`. A blocked or over-limit server answers
 `{error, message}` with 451, 429, 404, 503 or 502 instead of the server's own answer.
 
+**A game that is unpublished, taken down or capped** (past its plan's money for the month: README "Its plan") has its
+server switched off: every `api/*` request answers `451 {"error": "stopped", "reason": "unpublished" | "taken-down" |
+"capped", "message"}`, its Durable Objects' alarms lapse and their sockets close. A room that is running stops within
+about five minutes. Its rooms' data and its secrets are kept, and the server comes back by itself when the game is
+published again (within 30 days, to be sure of its data) or its cap lifts (the month's turn, a paid slot, usage
+credit); a version published while it is capped goes live with its pages, and its server waits. The page keeps
+loading meanwhile, so a game whose server can be off says so when `api/` answers 451.
+
 While the game's owner has it **paused for maintenance** (xgames.fun/console, the Live tab; README "Live"), xgames.fun
 answers its `api/*` itself with `503 {ok: false, code: 'maintenance', why, since}` and `retry-after: 60`, WebSocket
 upgrades included: the server's code does not run for a new request. What already runs keeps running (an open

package/lib/check.mjs

@@ -556,6 +556,7 @@ export async function pageVerify(
       const { preflight } = await import('./publish/index.mjs');
       const { scanPage } = await import('./publish/adopt.mjs');
       const pre = await preflight(game);
+      if (pre.linkName) notes.push(pre.linkName);
       const scan = existsSync(roots.out)
         ? await scanPage(roots.out, {
             backend: pre.backend,

package/lib/cli.mjs

@@ -28,6 +28,8 @@ export async function guard(fn, args = []) {
   try {
     return (await fn()) ?? 0;
   } catch (e) {
+    // xgames.fun refused a game this computer's sign-in was not given: said as that, with what to do
+    if (e?.code === 'not-granted') await (await import('./login-reach.mjs')).explainNotGranted(e).catch(() => {});
     const usage = e instanceof UsageError;
     console.error(usage ? e.message : `xcore: ${e.message}`);
     if (!usage && process.env.GAMESFUN_DEBUG) console.error(e.stack);

package/lib/client/gamesfun.js

@@ -929,7 +929,10 @@
       if (opts.order) body.order = opts.order;
       return json('POST', PLATFORM + 'scores/' + seg(board), body, 'submitting the score');
     },
-    /** → {data: [{rank, player, name, score, at}]}; anyone may read, signed in or not */
+    /**
+     * → {data: [{rank, player, name, score, at, me?}]}: `player` is an id of this game's own (never the account), `me`
+     * true on the signed-in player's entry. Anyone may read; signed out, the top 100 only (offset + limit past 100: 401)
+     */
     top: function (board, opts) {
       opts = opts || {};
       if (!seg(board)) return bad('board name');

package/lib/client/server/0001_init.sql

@@ -3,7 +3,7 @@
 -- does the same on this machine. Once this one is published, never change it: put the next change in
 -- 0002_<what>.sql (ALTER TABLE players ADD COLUMN …).
 CREATE TABLE players (
-  id TEXT PRIMARY KEY,                -- the player's id: env.GF.verifyPlayer's sub (withPlayer in gf-db.js)
+  id TEXT PRIMARY KEY,                -- the player's id: env.GF.verifyPlayer's sub (withPlayer in gf-db.js), never the wallet
   gold INTEGER NOT NULL DEFAULT 0,
   runs INTEGER NOT NULL DEFAULT 3,    -- runs left today
   updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))

package/lib/client/server/database.js

@@ -9,7 +9,8 @@
 //   POST   api/db/<collection>       {value}   a new id, the player's own        → {ok, item}
 //   DELETE api/db/<collection>/<id>            the player's own                  → {ok, deleted}
 //
-// A document is {id, owner, value, updatedAt}: `owner` is the player's id (env.GF.verifyPlayer's `sub`), or "server"
+// A document is {id, owner, value, updatedAt}: `owner` is the player's id (env.GF.verifyPlayer's `sub`: the account,
+// x:<X id> or for Google g:<id>, different in every game; never the wallet), or "server"
 // for what this server's own code writes. Every player has a space of their own in each collection: a document is
 // found by its collection, its owner and its id, so two players can both have a "main", and no player can take an id
 // in anyone else's space. A page names whose document it wants with `owner`; without it, the player's own (in a

package/lib/client/server/gf-db.js

@@ -5,7 +5,7 @@
 // database on this machine. Add a migration for each change; never change one that was published.
 //
 //   import { db, withPlayer } from './gf-db.js';
-//   const sub = await withPlayer(request, env);             // the signed-in player's id, or null
+//   const sub = await withPlayer(request, env);             // the signed-in player's id (never the wallet), or null
 //   if (!sub) return Response.json({ why: 'Sign in first.' }, { status: 401 });
 //   const me = await db(env).first('SELECT gold, runs FROM players WHERE id = ?', sub);
 //   // a rule in one statement, so two requests at once cannot both pass it
@@ -46,7 +46,11 @@ export function db(env) {
   };
 }
 
-/** The signed-in player's id (env.GF.verifyPlayer's sub), from the token gamesfun.js sends; null for a guest. */
+/**
+ * The signed-in player's id (env.GF.verifyPlayer's sub: the account, x:<X id> or for Google g:<id>, different in every
+ * game; never the wallet, which is v.wallet), from the token gamesfun.js sends; null for a guest, at once and with no
+ * call when the request has no token, so a stranger costs the server nothing: answer 401 then, before any work.
+ */
 export async function withPlayer(request, env) {
   const token = /^Bearer\s+(\S+)$/i.exec(request.headers.get('authorization') ?? '')?.[1];
   if (!token) return null;

package/lib/client/server/rooms.js

@@ -177,6 +177,7 @@ export class GameRoom extends DurableObject {
     let player = null;
     if (m.token) {
       const v = await this.env.GF.verifyPlayer(String(m.token));
+      // id: the account (x:<X id>, or g:<id> for Google, different in every game); the wallet is its own claim
       if (v?.ok) player = { id: v.sub, x: v.x?.handle ?? null, wallet: v.wallet ?? null };
     }
     // its own storage: the room takes no other message while it waits on that