@xgamesfun/xcore 0.1.0 → 0.2.1

package/lib/add.mjs

@@ -1,10 +1,11 @@
-// `xcore add signin|database`: games.fun's player sign-in, saves and leaderboards, and a database of the game's own,
+// `xcore add signin|database`: xgames.fun's player sign-in, saves and leaderboards, and a database of the game's own,
 // put into a game made without the kit, in the shape its engine takes:
 //   - a web page: gamesfun.js beside the page (the folder its build copies as it is) and a <script> in index.html;
 //   - a Godot 4 project: addons/gamesfun/gamesfun.gd, autoloaded as GamesFun in project.godot;
 //   - a Unity project: Assets/Plugins/GamesFun/ (GamesFun.jslib and GamesFun.cs).
-// The database is server code (docs/SERVER.md): server/database.js, one Durable Object with SQLite storage, and the
-// Worker that routes api/db/ to it, declared in gamesfun.json → server. Publish puts it on games.fun with the game.
+// The database is the game's own D1 (gamesfun.json → database, docs/SERVER.md): a game with a server of its own reaches
+// it from its code (server/gf-db.js), and a game with none gets xcore's stock server, which serves the page's gf.db.
+// The older database, server/database.js (one Durable Object with SQLite storage), is kept for a game that has it.
 import { createPrivateKey, createPublicKey, randomBytes } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
@@ -12,6 +13,14 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { CMD } from './command.mjs';
 import { CONFIG_FILE, pageRoots } from './publish/page.mjs';
+import {
+  DATABASE_DEFAULTS,
+  DEFAULT_COLLECTIONS,
+  OLD_DEFAULT_RULES,
+  OWNER_SPACES,
+  readServerConfig,
+} from './server/contract.mjs';
+import { dataCallLine, ownerlessDataCalls } from './server/data-calls.mjs';
 import { BACKEND_FILE } from './publish/scan.mjs';
 import { serverRpc } from './solana-rpc.mjs';
 import { isPageFolder, shown as shownPath } from './games.mjs';
@@ -195,7 +204,7 @@ export async function addSignin(dir) {
         'A script that also runs without the autoload (headless tests, godot --script) cannot use the bare name GamesFun: there, get_node_or_null("/root/GamesFun"), and play on when it is null.',
         'Export for the Web with Thread Support off, then adopt the project with that folder: ' +
           `${CMD} adopt . --out <the export folder>.`,
-        'In the editor and in a desktop build, sign-in, saves, leaderboards and the database answer an error and the game plays on; on games.fun and under xcore check they work (a local player on this machine).',
+        'In the editor and in a desktop build, sign-in, saves, leaderboards and the database answer an error and the game plays on; on xgames.fun and under xcore check they work (a local player on this machine).',
       ],
     };
   }
@@ -211,7 +220,7 @@ export async function addSignin(dir) {
         'When the browser keeps the sign-in window shut (a phone, a post on X), GamesFun.SignInCode gives {code, site}: show "Go to <site>/go and enter <code>".',
         'Build for WebGL with Compression Format Disabled (or Decompression Fallback on) and threads off, then adopt the project with the build folder: ' +
           `${CMD} adopt . --out <the build folder>.`,
-        'In the editor every call answers an error and the game plays on; in a WebGL build, on games.fun and under xcore check, it works (a local player on this machine).',
+        'In the editor every call answers an error and the game plays on; in a WebGL build, on xgames.fun and under xcore check, it works (a local player on this machine).',
       ],
     };
   }
@@ -260,7 +269,7 @@ export async function addSignin(dir) {
         : []),
       'In the game: const gf = GamesFun; const player = await gf.signIn() (from a click), gf.onChange(player => …), await gf.saves.put("main", {...}), await gf.scores.submit("best", score), await gf.scores.top("best"); every call is listed at the top of gamesfun.js.',
       'When the browser keeps the sign-in window shut (a phone, a post on X), gf.onCode(({code, site, window}) => …) says what to show: "Go to <site>/go and enter <code>". Show it plainly when window is false (the browser blocked the window). When a window opened, show it only as a quiet line, never an overlay: the player is still signing in there, and X’s login page hides from the game whether that window is still open.',
-      'On this machine (localhost, xcore check) a local player and this browser’s storage stand in; under xcore dev a local sign-in, the platform and the game’s server answer as games.fun will; once published, games.fun signs players in.',
+      'On this machine (localhost, xcore check) a local player and this browser’s storage stand in; under xcore dev a local sign-in, the platform and the game’s server answer as xgames.fun will; once published, xgames.fun signs players in.',
     ],
   };
 }
@@ -273,6 +282,13 @@ const PARTS = {
     handler: 'handleDatabase',
     what: 'its database answers api/db/',
   },
+  // the page's documents in the game's own D1 (gamesfun.json → database.collections): written by addDocs, not addPart
+  docs: {
+    file: 'gf-docs.js',
+    object: null,
+    handler: 'handleDocs',
+    what: "the page's gf.db answers api/db/ from the game's database, under gamesfun.json → database.collections",
+  },
   rooms: {
     file: 'rooms.js',
     object: ROOM_OBJECT,
@@ -297,8 +313,10 @@ const OURS = 'Written by `xcore add';
 /** server/index.js for the parts xcore wrote (only ever rewritten while it is xcore's own). */
 export function serverIndex(parts) {
   const list = Object.keys(PARTS).filter(k => parts.includes(k));
-  const commands = list.map(k => (k === 'rooms' ? 'multiplayer' : k)).join('` and `xcore add ');
-  return `// The game's server on games.fun (docs/SERVER.md in @xgamesfun/xcore). ${OURS} ${commands}\`:
+  const commands = [...new Set(list.map(k => ({ rooms: 'multiplayer', docs: 'database' })[k] ?? k))].join(
+    '` and `xcore add ',
+  );
+  return `// The game's server on xgames.fun (docs/SERVER.md in @xgamesfun/xcore). ${OURS} ${commands}\`:
 // ${list.map(k => PARTS[k].what).join('; ')}. To add routes of the game's own, delete the words "Written by" above
 // first: xcore then leaves this file alone (and says which two lines to add for anything it adds later).
 ${list.map(k => `import { ${PARTS[k].handler} } from './${PARTS[k].file}';`).join('\n')}
@@ -323,22 +341,8 @@ ${list.map(k => `    const ${k} = await ${PARTS[k].handler}(request, env);\n
 `;
 }
 
-/** One part of server code (the database, the rooms) into the game: its file, its object, its route. */
-async function addPart(dir, part, { render = text => text } = {}) {
-  const signin = await addSignin(dir);
-  const written = [...signin.written];
-  const spec = PARTS[part];
-  const server = path.join(dir, 'server');
-  // the settings at its top (ROOM, RULES, LIMITS, PAY) are the person's: kept as they set them
-  await put(path.join(server, spec.file), render(read(`server/${spec.file}`)), written, dir, { settings: true });
-  const index = ['index.js', 'index.mjs'].map(f => path.join(server, f)).find(f => existsSync(f));
-  const indexText = index ? await readFile(index, 'utf8') : null;
-  const ours = indexText === null || indexText.includes(OURS);
-  if (ours) {
-    const parts = Object.keys(PARTS).filter(k => k === part || existsSync(path.join(server, PARTS[k].file)));
-    await put(index ?? path.join(server, 'index.js'), serverIndex(parts), written, dir);
-  }
-  // gamesfun.json → server.objects: the part's Durable Object, beside any the server has
+/** gamesfun.json, read and checked for one more part: valid JSON, and room for its Durable Object. Throws in words. */
+async function serverConfig(dir, spec) {
   const cfgFile = path.join(dir, CONFIG_FILE);
   let cfg = {};
   if (existsSync(cfgFile)) {
@@ -349,9 +353,30 @@ async function addPart(dir, part, { render = text => text } = {}) {
     }
   }
   const objects = Array.isArray(cfg.server?.objects) ? cfg.server.objects : [];
+  if (spec.object && !objects.some(o => o?.binding === spec.object.binding) && objects.length >= 8)
+    throw new Error(`${CONFIG_FILE} already declares 8 Durable Objects, the most a game's server may have.`);
+  return { cfgFile, cfg, objects };
+}
+
+/** One part of server code (the database, the rooms) into the game: its file, its object, its route. */
+async function addPart(dir, part, { render = text => text } = {}) {
+  // everything that can refuse is asked before the first file is written, so a refusal leaves the game as it was
+  await serverConfig(dir, PARTS[part]);
+  // a game whose database the stock server served: from now on its own server answers api/*, and server/gf-docs.js
+  // goes on answering the page's gf.db there
+  const wasStock = !!(await readServerConfig(dir)).stock;
+  const signin = await addSignin(dir);
+  const written = [...signin.written];
+  const spec = PARTS[part];
+  const server = path.join(dir, 'server');
+  // the settings at its top (ROOM, RULES, LIMITS, PAY) are the person's: kept as they set them
+  await put(path.join(server, spec.file), render(read(`server/${spec.file}`)), written, dir, { settings: true });
+  const docs = await addDocs(dir, written, { wasStock });
+  const { index, indexText, ours } = await routeParts(dir, written, part);
+  // gamesfun.json → server.objects: the part's Durable Object, beside any the server has (read again: adding the
+  // sign-in may have written it)
+  const { cfgFile, cfg, objects } = await serverConfig(dir, spec);
   if (spec.object && !objects.some(o => o?.binding === spec.object.binding)) {
-    if (objects.length >= 8)
-      throw new Error(`${CONFIG_FILE} already declares 8 Durable Objects, the most a game's server may have.`);
     cfg.server = { ...(cfg.server ?? {}), objects: [...objects, spec.object] };
     await writeFile(cfgFile, JSON.stringify(cfg, null, 2) + '\n');
     written.push(`declared ${spec.object.class} (${spec.object.binding}) in ${CONFIG_FILE} → server.objects`);
@@ -362,11 +387,75 @@ async function addPart(dir, part, { render = text => text } = {}) {
       : [
           `server/${path.basename(index)} is your own: route ${{ rooms: 'the rooms', database: "the database's calls", rpc: 'api/rpc', vouchers: 'api/vouchers/' }[part]} in it.${spec.object ? ` Add \`export { ${spec.object.class} } from './${spec.file}';\` at the top, and` : ''} First thing in fetch: \`const r = await ${spec.handler}(request, env); if (r) return r;\` (with \`import { ${spec.handler} } from './${spec.file}';\`).`,
         ];
+  route.push(...docsRoute(docs, { ours, indexText, index, wasStock }));
   return { signin, written, route };
 }
 
+/** database.js's documents code, between its marks: what the stock server and server/gf-docs.js share. */
+export function docsSource() {
+  const db = read('server/database.js');
+  const start = db.indexOf("// ---- the documents' code");
+  const end = db.indexOf("// ---- end of the documents' code ----");
+  if (start < 0 || end < start) throw new Error("database.js has lost its documents' marks");
+  const core = db.slice(db.indexOf('\n', start) + 1, end).trim();
+  return read('server/gf-docs.js').replace('// __DOCS_CORE__', core);
+}
+
+/**
+ * The page's documents for a game with a server of its own: server/gf-docs.js, which answers api/db/ from the game's D1
+ * under gamesfun.json → database.collections, when the game has a database with collections. A game the stock server
+ * served (`wasStock`) keeps the rules it had: written out in gamesfun.json, so the helper reads the same ones.
+ * → true when the game has the helper
+ */
+async function addDocs(dir, written, { wasStock = false } = {}) {
+  const { cfgFile, cfg } = await serverConfig(dir, {});
+  const d = cfg.database;
+  if (!d || typeof d !== 'object' || Array.isArray(d)) return false;
+  if (d.collections === undefined) {
+    if (!wasStock) return false;
+    d.collections = structuredClone(DEFAULT_COLLECTIONS);
+    await writeFile(cfgFile, JSON.stringify(cfg, null, 2) + '\n');
+    written.push(
+      `wrote the stock server's rules into ${CONFIG_FILE} → database.collections, which server/gf-docs.js reads`,
+    );
+  }
+  await put(path.join(dir, 'server', PARTS.docs.file), docsSource(), written, dir, { settings: true });
+  return true;
+}
+
 /**
- * The RPC's origin in backend.json → origins, which is all a game's server may call on games.fun: the folder's own
+ * server/index.js routing every part xcore wrote into server/, rewritten only while it is xcore's own (with `part`, the
+ * one being added, counted in). → {index, indexText (before), ours}
+ */
+async function routeParts(dir, written, part = null) {
+  const server = path.join(dir, 'server');
+  const index = ['index.js', 'index.mjs'].map(f => path.join(server, f)).find(f => existsSync(f));
+  const indexText = index ? await readFile(index, 'utf8') : null;
+  const ours = indexText === null || indexText.includes(OURS);
+  if (ours) {
+    const parts = Object.keys(PARTS).filter(k => k === part || existsSync(path.join(server, PARTS[k].file)));
+    await put(index ?? path.join(server, 'index.js'), serverIndex(parts), written, dir);
+  }
+  return { index, indexText, ours };
+}
+
+/** What to say about server/gf-docs.js: how to route it in a server/index.js of the person's own, and a stock game's move. */
+function docsRoute(docs, { ours, indexText, index, wasStock }) {
+  if (!docs) return [];
+  const out = [];
+  if (!ours && !indexText.includes(PARTS.docs.handler))
+    out.push(
+      `server/${path.basename(index)} is your own: route the page's documents in it. First thing in fetch: \`const db = await handleDocs(request, env); if (db) return db;\` (with \`import { handleDocs } from './gf-docs.js';\`). Until it does, every gf.db call answers 404, and publish refuses the game.`,
+    );
+  if (wasStock)
+    out.push(
+      `This game's database was served by xcore's stock server (the page's gf.db, at api/db/). Now it has a server of its own, and server/gf-docs.js answers gf.db there from the same documents (table gf_docs), under the same rules (${CONFIG_FILE} → database.collections).`,
+    );
+  return out;
+}
+
+/**
+ * The RPC's origin in backend.json → origins, which is all a game's server may call on xgames.fun: the folder's own
  * XSOLANA_RPC_URL (.dev.vars, else .env), its origin only (the key is in its path or query). → the step to say, or null.
  */
 async function allowRpc(dir, written) {
@@ -406,8 +495,8 @@ export async function addRpc(dir) {
       ...route,
       `Get a devnet RPC URL of your own (Helius, Triton or QuickNode; their free plans fit a small game). Under ${CMD} dev, put XSOLANA_RPC_URL=… in the folder's .dev.vars (a hidden file publish never sends; keep it out of git).`,
       ...(origin ? [origin] : []),
-      `Publish (${CMD} publish), then give the URL to the game's server: \`${CMD} secret set XSOLANA_RPC_URL\` (it asks for it; games.fun keeps it on the server, never the page, and it reaches the next request with no publish). Until it is set, api/rpc says so and the page keeps using games.fun's shared relay, so nothing breaks.`,
-      "Why: games.fun's shared relay counts every call toward the game's plan ($10 a million calls, the economy's biggest cost a player); through the game's own RPC a call is one request to its server (about $0.30 a million) and the RPC's own plan.",
+      `Publish (${CMD} publish), then give the URL to the game's server: \`${CMD} secret set XSOLANA_RPC_URL\` (it asks for it; xgames.fun keeps it on the server, never the page, and it reaches the next request with no publish). Until it is set, api/rpc says so and the page keeps using xgames.fun's shared relay, so nothing breaks.`,
+      "Why: xgames.fun's shared relay counts every call toward the game's plan ($10 a million calls, the economy's biggest cost a player); through the game's own RPC a call is one request to its server (about $0.30 a million) and the RPC's own plan.",
       "Each call counts toward the game server's requests (on Free 120 a minute from one player and 600 a game): the economy's reads every few seconds fit; RPC.methods at the top of server/rpc.js is what it passes on.",
     ],
   };
@@ -458,7 +547,7 @@ export async function seedAddress(seed) {
   return encodeBase58(new Uint8Array(spki.subarray(-32)));
 }
 
-/** A new voucher key: {seed (hex), address}. The live key is made this way and sent to games.fun, never kept here. */
+/** A new voucher key: {seed (hex), address}. The live key is made this way and sent to xgames.fun, never kept here. */
 export async function newVoucherKey() {
   const seed = randomBytes(32).toString('hex');
   return { seed, address: await seedAddress(seed) };
@@ -476,6 +565,13 @@ export async function addVouchers(dir) {
     throw new Error(
       `${dir} has no economy yet: a voucher is claimed from a grant in it. Make it first (${CMD} loot add ${shownPath(dir)}, then a grant in ${ECONOMY_FILE}), and run this again.`,
     );
+  // a bad test key refuses here, before any file is written
+  const vars = path.join(dir, '.dev.vars');
+  const varsText = existsSync(vars) ? await readFile(vars, 'utf8') : '';
+  if (/^\s*VOUCHER_SEED\s*=/m.test(varsText) && !/^\s*VOUCHER_SEED\s*=\s*["']?[0-9a-fA-F]{64}["']?\s*$/m.test(varsText))
+    throw new Error(
+      `.dev.vars has a VOUCHER_SEED that is not a 32-byte seed in hex (64 characters): fix it or delete that line, and run this again.`,
+    );
   let from = path.relative(path.join(dir, 'server'), economy).split(path.sep).join('/');
   if (!from.startsWith('.')) from = `./${from}`;
   const { signin, written, route } = await addPart(dir, 'vouchers', {
@@ -498,8 +594,8 @@ export async function addVouchers(dir) {
     address,
     steps: [
       ...route,
-      `Two keys sign vouchers: a test key for ${CMD} dev (its seed in .dev.vars; address ${address}) and the live key, made on games.fun so it is never on this machine. A copy of this folder can sign only what the grant lets the test key sign.`,
-      `Once published (${CMD} publish): ${CMD} secret set VOUCHER_SEED --new-key makes the live key on the server and prints its address. Put that address in the grant that pays results, in ${where}: "vouchers": ["<the live key's address>"] (up to three keys; the keeper's can stay beside it); then ${CMD} loot check, ${CMD} loot approve, ${CMD} publish.`,
+      `Two keys sign vouchers: a test key for ${CMD} dev (its seed in .dev.vars; address ${address}) and the live key, which ${CMD} secret set VOUCHER_SEED --new-key makes and sends to xgames.fun only, never keeping it on this machine. A copy of this folder can sign only what the grant lets the test key sign.`,
+      `Once published (${CMD} publish): ${CMD} secret set VOUCHER_SEED --new-key makes the live key, sends it to the game's server on xgames.fun only, and prints its address. Put that address in the grant that pays results, in ${where}: "vouchers": ["<the live key's address>"] (up to three keys; the keeper's can stay beside it); then ${CMD} loot check, ${CMD} loot approve, ${CMD} publish.`,
       named.length
         ? `${where} names the test key in ${named.map(k => `"${k}"`).join(', ')}: claims signed under ${CMD} dev pay on devnet. Take it out of the grant before the economy holds anything of value.`
         : `To claim a voucher signed under ${CMD} dev, add the test key's address too (devnet only; take it out before the economy holds anything of value).`,
@@ -513,19 +609,148 @@ export async function addVouchers(dir) {
   };
 }
 
-/** The game's own database (server/database.js) and the page calls for it. → {engine, written, steps} */
+/**
+ * The game's own database: a D1 database of its own (gamesfun.json → database; xgames.fun's STORAGE.md §8.2).
+ *   - A game with a server of its own gets the block, an example first migration (server/migrations/0001_init.sql)
+ *     and server/gf-db.js (prepared queries, and withPlayer: the signed-in player's id), for its own routes.
+ *   - A game with no server gets the block with `collections`: xcore's stock server serves the page's gf.db from it.
+ *   - A game that has server/database.js (the older way, a Durable Object) keeps it, brought up to date.
+ * → {engine, written, steps}
+ */
 export async function addDatabase(dir) {
+  if (existsSync(path.join(dir, 'server', 'database.js'))) return addDatabaseObject(dir);
+  // everything that can refuse is asked before the first file is written
+  const { cfgFile, cfg } = await serverConfig(dir, {});
+  const before = await readServerConfig(dir);
+  const own = before.has && !before.stock;
+  if (cfg.database !== undefined && before.database?.problems.length)
+    throw new Error(`${CONFIG_FILE} database: ${before.database.problems.join('; ')}; fix it first`);
+  if (cfg.database === undefined && (cfg.server?.objects ?? []).some(o => o?.binding === DATABASE_DEFAULTS.binding))
+    throw new Error(
+      `${CONFIG_FILE} has a Durable Object bound as ${DATABASE_DEFAULTS.binding}: add "database": {"binding": "GAME_DB"} (another name) to ${CONFIG_FILE} first, then run this again`,
+    );
+  const signin = await addSignin(dir);
+  const written = [...signin.written];
+  // gamesfun.json read again: adding the sign-in may have written it
+  const { cfg: now } = await serverConfig(dir, {});
+  if (now.database === undefined) {
+    now.database = own
+      ? { engine: 'd1', binding: DATABASE_DEFAULTS.binding, migrations: DATABASE_DEFAULTS.migrations }
+      : { engine: 'd1', binding: DATABASE_DEFAULTS.binding, collections: structuredClone(DEFAULT_COLLECTIONS) };
+    await writeFile(cfgFile, JSON.stringify(now, null, 2) + '\n');
+    written.push(`declared the game's database in ${CONFIG_FILE} → database (env.${now.database.binding})`);
+  }
+  const database = (await readServerConfig(dir)).database;
+  const call = { godot: 'await GamesFun.db_add("levels", {...})', unity: 'await GamesFun.DbAdd("levels", json)' };
+  const later = [
+    `${CMD} dev runs the database on this machine (kept in .gamesfun/dev/d1/, never published), with the same migrations; ${CMD} db query "SELECT …" reads it, and ${CMD} db query … --live the one on xgames.fun.`,
+    `${CMD} publish makes the game's database on xgames.fun (one a game, kept between publishes) and applies the new migrations before the new version goes live. ${CMD} db export --live keeps a copy; ${CMD} db restore <time> --live goes back up to 30 days.`,
+  ];
+  // a stock game may have migrations of its own too: their line endings are kept as they are
+  const migrationsFolder = path.join(dir, ...database.migrationsDir.split('/'));
+  if (!own && existsSync(migrationsFolder)) await migrationsAttributes(migrationsFolder, written, dir);
+  if (!own)
+    return {
+      engine: signin.engine,
+      written,
+      steps: [
+        ...signin.steps.filter(x => !/^(In the game|From GDScript|From C#):/.test(x)),
+        `From the game: ${call[signin.engine] ?? 'await gf.db.add("levels", {...})'}, get, put, list, delete (documents in collections, any JSON up to 64 KB). This game has no server of its own, so xcore's stock server answers them from its database.`,
+        `Each player has a space of their own in every collection, and reads and writes only that. Change it per collection in ${CONFIG_FILE} → database.collections: {"read": "anyone"} lets everyone read one (another player's document by its owner: gf.db.get("levels", id, {owner})); {"write": "server"} is for what players must not set themselves, and needs a server of your own to write it.`,
+        'A list comes a page at a time, newest first: pass the answer\'s after back for the next one (gf.db.list("levels", {after})).',
+        ...later,
+      ],
+    };
+  // a server of its own: the example migration (only while there is none) and the helper for its routes
+  const folder = migrationsFolder;
+  if (!database.migrations.length)
+    await put(path.join(folder, '0001_init.sql'), read('server/0001_init.sql'), written, dir);
+  await migrationsAttributes(folder, written, dir);
+  await put(
+    path.join(dir, 'server', 'gf-db.js'),
+    read('server/gf-db.js').replace('__BINDING__', database.binding),
+    written,
+    dir,
+  );
+  // the page's documents too (gf.db), when the block has collections: server/gf-docs.js, routed in server/index.js
+  const docs = await addDocs(dir, written);
+  const route = docs ? docsRoute(docs, { ...(await routeParts(dir, written)), wasStock: false }) : [];
+  return {
+    engine: signin.engine,
+    written,
+    steps: [
+      ...signin.steps.filter(x => !/^(In the game|From GDScript|From C#):/.test(x)),
+      ...route,
+      ...(docs
+        ? [
+            `The page's documents (gf.db: ${call[signin.engine] ?? 'await gf.db.add("levels", {...})'}, get, put, list, delete) are server/gf-docs.js's, in the same database (table gf_docs), under ${CONFIG_FILE} → database.collections; this server's own code reaches them with docsOf(env).`,
+          ]
+        : [
+            `The page's gf.db documents are not served here: to keep them in this database too, add "collections": {"*": {"read": "owner", "write": "owner"}} to ${CONFIG_FILE} → database and run ${CMD} add database again (it writes server/gf-docs.js and routes it).`,
+          ]),
+      `This game has a server of its own: its code reads and writes the database. import { db, withPlayer } from './gf-db.js'; then in a route: const sub = await withPlayer(request, env) (the signed-in player's id, or null), and db(env).first / all / run / batch with ? for every value. env.${database.binding} is D1 itself.`,
+      `Its tables come from ${database.migrationsDir}/ (0001_init.sql is an example: change it now, before it is published). Every later change is a new file, 0002_<what>.sql: once a migration is published it never changes, and a changed one is refused.`,
+      'A rule that must hold however many requests come at once is one statement: UPDATE players SET runs = runs - 1 WHERE id = ? AND runs > 0 RETURNING runs; several that go together, db(env).batch([...]), all or none.',
+      ...later,
+    ],
+  };
+}
+
+/** A migration's bytes are its sha256: git must not change their line endings (core.autocrlf on Windows would). */
+export const MIGRATIONS_GITATTRIBUTES =
+  "# a migration's bytes are its sha256 (xgames.fun refuses one that changed): no line-ending conversion\n*.sql -text\n";
+async function migrationsAttributes(folder, written, dir) {
+  const file = path.join(folder, '.gitattributes');
+  if (!existsSync(file)) await put(file, MIGRATIONS_GITATTRIBUTES, written, dir);
+}
+
+/**
+ * The older database (server/database.js: one Durable Object with SQLite storage, and the route to it), kept for a
+ * game that has it: brought up to date, and still working. A new game's database is its own D1 (addDatabase).
+ * → {engine, written, steps}
+ */
+export async function addDatabaseObject(dir) {
+  // what can refuse (gamesfun.json unreadable, its 8 Durable Objects taken) is asked before database.js is touched
+  await serverConfig(dir, PARTS.database);
+  // an untouched RULES from 0.1.0 is the old default, not the person's choice: it becomes the new one
+  const dbFile = path.join(dir, 'server', 'database.js');
+  let opened = false,
+    upgraded = false;
+  if (existsSync(dbFile)) {
+    const text = await readFile(dbFile, 'utf8');
+    // 0.1.0's database.js: one id a collection, whoever wrote it (no space of each player's own)
+    upgraded = !text.includes(OWNER_SPACES);
+    if (text.includes(OLD_DEFAULT_RULES)) {
+      await writeFile(dbFile, text.replace(OLD_DEFAULT_RULES, settingsBlock(read('server/database.js'), 'RULES').text));
+      opened = true;
+    }
+  }
   const { signin, written, route } = await addPart(dir, 'database');
   const call = { godot: 'await GamesFun.db_add("levels", {...})', unity: 'await GamesFun.DbAdd("levels", json)' };
+  // the server's own 0.1.0 calls, which mean something else over the new database.js: each said with its change
+  const calls = upgraded ? await ownerlessDataCalls(dir) : [];
   return {
     engine: signin.engine,
     written,
+    calls,
     steps: [
       ...signin.steps.filter(x => !/^(In the game|From GDScript|From C#):/.test(x)),
       ...route,
-      `From the game: ${call[signin.engine] ?? 'await gf.db.add("levels", {...})'}, get, put, list, delete (documents in collections, any JSON up to 64 KB). Anyone reads; a signed-in player writes only their own documents. Change that per collection in RULES at the top of server/database.js, and use write: "server" for anything players must not set themselves (a prize, a verified score).`,
-      'Your server code reaches it past those rules with dataOf(env) (import { dataOf } from "./database.js").',
-      `On this machine the page keeps documents in the browser instead; ${CMD} publish puts the database on games.fun with the game (a Durable Object with SQLite storage, kept between publishes).`,
+      ...(calls.length
+        ? [
+            `server/database.js was 0.1.0's, where a document was found by its id alone, whoever wrote it. Now every player has a space of their own, and dataOf(env) without an owner is the server's: change ${calls.length === 1 ? 'this call' : `these ${calls.length} calls`} before you publish (publish says them again until each names its owner):\n${calls.map(c => `    ${dataCallLine(c)}`).join('\n')}`,
+          ]
+        : []),
+      'server/database.js is the older database (a Durable Object). It keeps working; a game\'s database is now a D1 of its own (gamesfun.json → database, docs/SERVER.md "A database of its own"), which xcore db can query, export and restore.',
+      ...(opened
+        ? [
+            "RULES in server/database.js was the old default, where anyone read every document: it is now read: 'owner' (each player reads only their own). To keep a collection public, name it: levels: { read: 'anyone', write: 'owner' }.",
+          ]
+        : []),
+      `From the game: ${call[signin.engine] ?? 'await gf.db.add("levels", {...})'}, get, put, list, delete (documents in collections, any JSON up to 64 KB). Each player has a space of their own in every collection, and reads and writes only that: no player can take or see another's documents. Change that per collection in RULES at the top of server/database.js: read: "anyone" lets everyone read a collection (another player's document by its owner: gf.db.get("levels", id, {owner})), and write: "server" is for anything players must not set themselves (a prize, a verified score).`,
+      'A list comes a page at a time, newest first: pass the answer\'s after back for the next one (gf.db.list("levels", {after})).',
+      'Your server code reaches it past those rules with dataOf(env) (import { dataOf } from "./database.js"): its own documents (owner "server") by default, a player\'s with {owner: sub}.',
+      `On this machine the page keeps documents in the browser instead; ${CMD} publish puts the database on xgames.fun with the game (a Durable Object with SQLite storage, kept between publishes).`,
       "Every call counts toward the game server's requests (on Free 120 a minute from one player and 600 shared by all its players; on Creator 600 and 6,000): read and write when something happens (a level saved, a profile changed), not every frame.",
     ],
   };
@@ -537,19 +762,19 @@ export async function addMultiplayer(dir) {
   const how = {
     godot: [
       "From GDScript, Godot's own multiplayer: `var peer = await GamesFun.join_room(code)` then `multiplayer.multiplayer_peer = peer` in place of an ENetMultiplayerPeer (null: GamesFun.room_error says why). The first player in is the server (id 1); RPCs, MultiplayerSpawner and MultiplayerSynchronizer work as over ENet, all reliable and ordered. In the editor and a desktop build the same call makes a local ENet game (Debug → Customize Run Instances to run two).",
-      'A code: GamesFun.room_from_link() (the room a shared link opened) or GamesFun.room_code() (a new one); share GamesFun.room_link(code), which opens the game in that room on games.fun and in a post on X.',
+      'A code: GamesFun.room_from_link() (the room a shared link opened) or GamesFun.room_code() (a new one); share GamesFun.room_link(code), which opens the game in that room on xgames.fun and in a post on X.',
       'Godot\'s ENet does not run in a browser: replace ENetMultiplayerPeer.create_server/create_client with join_room, and keep the rest of the game\'s multiplayer code. A Host button: join_room(GamesFun.room_code(), {"host": true}); a Join button: join_room(code, {"host": false}), which fails as ENet does when no one is there. A variable typed ENetMultiplayerPeer becomes MultiplayerPeer.',
       "The peer leaves its room when the game lets go of it (multiplayer.multiplayer_peer = null with no variable holding it) or on peer.close(). ROOM.maxPlayers in server/rooms.js is create_server's max_clients, for every room. Every packet is reliable and ordered, unreliable ones too; a frame's packets go to the room as one message.",
       "When the host leaves, its clients see server_disconnected, as over ENet (Godot's server is never handed on).",
     ],
     unity: [
       "From C#: `var room = await GamesFun.JoinRoom(code)` (null: GamesFun.RoomError says why; JoinRoom(code, name, host: true) opens a new room only, host: false joins one only); room.Id, room.Host, room.IsHost; room.OnMessage, OnBytes, OnJoin, OnLeave, OnHost, OnClose; room.Send(json, to), room.SendBytes(bytes, to), room.Lock(), room.Leave(). The first player in is the host (Id 1); to: a player's id, 0 everyone else, -id everyone but one.",
-      'A code: await GamesFun.RoomFromLink() (the room a shared link opened) or GamesFun.RoomCode(); share await GamesFun.RoomLink(code), which opens the game in that room on games.fun and in a post on X.',
+      'A code: await GamesFun.RoomFromLink() (the room a shared link opened) or GamesFun.RoomCode(); share await GamesFun.RoomLink(code), which opens the game in that room on xgames.fun and in a post on X.',
       "A netcode library's own transport (Netcode for GameObjects, Mirror) needs a server of its own: run game logic on the host (IsHost) and send state with room.Send / SendBytes instead.",
     ],
     page: [
       'In the game: `const { data: room, error } = await GamesFun.rooms.join(code)` (opts {name, host}: host true opens a new room only, false joins one only); room.id, room.host, room.isHost, room.peers; room.on("message" | "bytes" | "join" | "leave" | "host" | "close", …); room.send(data, to), room.sendBytes(bytes, to), room.lock(), room.leave(). The first player in is the host (id 1); to: a player\'s id, 0 everyone else, -id everyone but one.',
-      'A code: GamesFun.rooms.fromLink() (the room a shared link opened) or GamesFun.rooms.code(); share GamesFun.rooms.link(code), which opens the game in that room on games.fun and in a post on X.',
+      'A code: GamesFun.rooms.fromLink() (the room a shared link opened) or GamesFun.rooms.code(); share GamesFun.rooms.link(code), which opens the game in that room on xgames.fun and in a post on X.',
     ],
   };
   return {
@@ -560,7 +785,7 @@ export async function addMultiplayer(dir) {
       ...route,
       ...how[signin.engine],
       "A room is a relay: the host's game decides what happens, and the room never reads a message. ROOM at the top of server/rooms.js sets the most players (16), whether only signed-in players may join, and the message limits.",
-      `On this machine, tabs of the same browser share a room (open the game twice); ${CMD} publish puts the rooms on games.fun with the game. A player's connection counts once toward the game server's requests (on Free 120 a minute from one player and 600 a game; on Creator 600 and 6,000), however many messages it carries.`,
+      `On this machine, tabs of the same browser share a room (open the game twice); ${CMD} publish puts the rooms on xgames.fun with the game. A player's connection counts once toward the game server's requests (on Free 120 a minute from one player and 600 a game; on Creator 600 and 6,000), however many messages it carries.`,
     ],
   };
 }

package/lib/browser.mjs

@@ -111,8 +111,11 @@ export async function ensureBrowser({ log = console.error, install = true, env =
   log(
     "xcore: no Chrome or Edge found (set CHROME_PATH to use another). Downloading Playwright's Chromium once (about 170 MB) into its cache…",
   );
-  const cli = createRequire(import.meta.url).resolve('playwright-core/cli.js');
-  const r = spawnSync(process.execPath, [cli, 'install', 'chromium'], { stdio: 'inherit', windowsHide: true });
+  // its progress goes to stderr: stdout stays the command's own (the JSON of --json)
+  const r = spawnSync(process.execPath, [playwrightCli(), 'install', 'chromium'], {
+    stdio: ['ignore', 2, 2],
+    windowsHide: true,
+  });
   const after = await playwrightChromium();
   if (r.status !== 0 || !after.installed) {
     throw new Error(
@@ -124,6 +127,12 @@ export async function ensureBrowser({ log = console.error, install = true, env =
   return { path: after.path, kind: 'chromium', source: 'playwright (installed now)' };
 }
 
+/** playwright-core's own command line (its `install`). Found beside its package.json: the package's exports do not
+ *  name cli.js, so it cannot be resolved by that name. → its path */
+export function playwrightCli() {
+  return path.join(path.dirname(createRequire(import.meta.url).resolve('playwright-core/package.json')), 'cli.js');
+}
+
 /** A headless browser for the page check (HEADED=1 shows it). `chromium`: another Playwright BrowserType (the kit's). */
 export async function launchBrowser({ chromium = null, headless = process.env.HEADED !== '1' } = {}) {
   const type = chromium ?? (await import('playwright-core')).chromium;

package/lib/check.mjs

@@ -1,4 +1,4 @@
-// The page check: a game made anywhere, checked as games.fun hosts it. `xcore check` and publish run it for a brought
+// The page check: a game made anywhere, checked as xgames.fun hosts it. `xcore check` and publish run it for a brought
 // game (gamesfun.json → page, ./publish/page.mjs: `xcore adopt`); the kit runs it for a copy of one of its starts
 // that is a page of its own, adding that copy's own two checks (`start`, below).
 //
@@ -8,7 +8,7 @@
 //   2  it fits the hosting: what publish would refuse (index.html at the root, .env files, links, secrets,
 //      backend.json, the host's own paths) and what breaks once hosted (limits, paths from the root, scripts, styles,
 //      fonts or frames from other sites): ./publish/adopt.mjs
-//   3  the page starts: its published files served under a folder (as games.fun Studio's preview serves them) with the
+//   3  the page starts: its published files served under a folder (as xgames.fun Studio's preview serves them) with the
 //      play host's page policy (./publish/hosting.mjs), in Chrome at a phone's size and a desktop's: no error thrown,
 //      nothing in the console's errors, none of its own files missing, and it shows something
 //   4  it stays inside its origins: every request the page made is one the hosted page may make (its own files, the
@@ -38,7 +38,7 @@ const VIEWS = [
   { name: 'desktop', width: 1280, height: 800 },
 ];
 const SETTLE_MS = Number(process.env.GF_PAGE_SETTLE_MS ?? 5000);
-/** Where the page is served on the check's own origin: under a folder, as games.fun Studio's preview and the kit's dev server serve it. */
+/** Where the page is served on the check's own origin: under a folder, as xgames.fun Studio's preview and the kit's dev server serve it. */
 export const MOUNT = '/game/';
 /** Where the check's own server takes Chrome's policy-violation reports (outside MOUNT: never a file of the game). */
 const REPORTS = '/__gf/csp-report';
@@ -55,17 +55,18 @@ const readJsonSync = file => {
  * The published files as static files under MOUNT, with the play host's headers (its page policy for these backend
  * origins, its permissions, nosniff, its types). → {url (the page's), origin, server (Node's), close}
  * `xcore dev` (./dev/index.mjs) adds: `route(req, res, url)`, tried first (→ true when it answered: the game's server,
- * the platform, the RPC); `html(text)`, applied to each .html file served; `port` (default: any free one).
+ * the platform, the RPC); `html(text)`, applied to each .html file served; `port` (default: any free one); `files`: the
+ * origin of the game's files (its files domain here), which the page may load pictures, sounds and fonts from.
  */
 export function servePage(
   dir,
-  { backend = [], server = false, route = null, html = null, port = 0, overlay = null } = {},
+  { backend = [], server = false, route = null, html = null, port = 0, overlay = null, files = [] } = {},
 ) {
   const root = resolve(dir);
   const over = overlay ? resolve(overlay) : null;
   // the play host's policy, plus a report address on this check's own server: Chrome reports every violation there,
   // a Web Worker's too, which no page event shows (a worker gets its policy from its own script's headers)
-  const base = pageHeaders(backend);
+  const base = pageHeaders(backend, null, files);
   const headers = {
     ...base,
     'content-security-policy': `${base['content-security-policy']}; report-uri ${REPORTS}`,
@@ -576,7 +577,7 @@ export async function pageVerify(
         bad.length === 0,
         bad.length
           ? bad.slice(0, 8).join('; ')
-          : `${pre.built.tree.files.length} files${pre.built.added?.length ? ` (with the ${pre.built.added.length} records games.fun keeps)` : ''}, ${(pre.built.bytes / 1048576).toFixed(1)} MB, nothing publish would refuse (${CMD} adopt lists what is worth a look)`,
+          : `${pre.built.tree.files.length} files${pre.built.added?.length ? ` (with the ${pre.built.added.length} records xgames.fun keeps)` : ''}, ${(pre.built.bytes / 1048576).toFixed(1)} MB, nothing publish would refuse (${CMD} adopt lists what is worth a look)`,
       );
     } else check(2, 'it fits the hosting', null, 'not read: the build failed');
   } else for (const c of await base.kept(game)) check(c.n, c.name, c.ok, c.detail);
@@ -584,7 +585,7 @@ export async function pageVerify(
   if (!built || !existsSync(join(roots.out, 'index.html'))) {
     const why = !built
       ? 'not run: the build failed'
-      : `no index.html in ${relative(game, roots.out).split(sep).join('/') || 'the game'}${roots.build ? ' (build it first, or verify without --no-build)' : ''}`;
+      : `no index.html in ${relative(game, roots.out).split(sep).join('/') || 'the game'}${roots.build ? ' (build it first, or check it without --no-build)' : ''}`;
     check(3, 'the page starts', built ? false : null, why);
     check(4, 'it stays inside its origins', null, 'not run: the page did not start');
   } else {
@@ -600,7 +601,7 @@ export async function pageVerify(
         ...v.errors.map(e => `${v.name}: ${e}`),
         ...v.missing.map(m =>
           /^api\//.test(m) && !hasServer
-            ? `${v.name}: missing ${m}: the page expects a server at api/, and games.fun answers api/ only from the game's own server/ (docs/SERVER.md); otherwise call a backend of your own (${CMD} backend use custom)`
+            ? `${v.name}: missing ${m}: the page expects a server at api/, and xgames.fun answers api/ only from the game's own server/ (docs/SERVER.md); otherwise call a backend of your own (${CMD} backend use custom)`
             : /^(undefined|null|NaN) \(/.test(m)
               ? `${v.name}: missing ${m}: the page asked for a file named ${m.split(' ')[0]}, a path from a variable that was not set (a field missing from its data, or a load that failed before it)`
               : `${v.name}: missing ${m}`,

package/lib/cli.mjs

@@ -17,18 +17,33 @@ export function parse(args, options, usage) {
 
 export class UsageError extends Error {}
 
-/** Run a command body: prints errors plainly (no stack for expected ones) and maps them to exit codes. */
-export async function guard(fn) {
+/**
+ * Run a command body: prints errors plainly (no stack for expected ones) and maps them to exit codes. `args`: the
+ * command's arguments; with --json among them a failure is also said on stdout, as
+ * { ok: false, error, code?, state?, next? }, so a script or an agent reads why from the JSON it asked for (`code` is
+ * the refusal's word: 'usage', 'login', 'files', 'secrets', 'build'…; `next`, the command that moves it on).
+ */
+export async function guard(fn, args = []) {
+  const json = args.includes('--json');
   try {
     return (await fn()) ?? 0;
   } catch (e) {
-    if (e instanceof UsageError) {
-      console.error(e.message);
-      return 2;
-    }
-    console.error(`xcore: ${e.message}`);
-    if (process.env.GAMESFUN_DEBUG) console.error(e.stack);
-    return 1;
+    const usage = e instanceof UsageError;
+    console.error(usage ? e.message : `xcore: ${e.message}`);
+    if (!usage && process.env.GAMESFUN_DEBUG) console.error(e.stack);
+    if (json)
+      printJson({
+        ok: false,
+        error: usage ? e.message.split('\n')[0] : e.message,
+        ...(usage
+          ? { code: 'usage' }
+          : typeof e.code === 'string' && !/^E[A-Z]+$/.test(e.code)
+            ? { code: e.code }
+            : {}),
+        ...(typeof e.state === 'string' ? { state: e.state } : {}),
+        ...(typeof e.next === 'string' ? { next: e.next } : {}),
+      });
+    return usage ? 2 : 1;
   }
 }