@xgamesfun/xcore 0.2.0 → 0.3.0

package/lib/dev/live.mjs

@@ -0,0 +1,162 @@
+// The game's live operations on this machine, for `xcore dev`. Hosted, the game's owner sets an announcement, a remote
+// config and maintenance mode on xgames.fun/console (the Live tab), and the play edge answers GET /platform/v1/live
+// itself (gamesfun.js's gf.live). Here they come from a file the creator writes, read again on every request:
+//
+//   <game>/.gamesfun/live.json   (a hidden folder: never published)
+//   {
+//     "announcement": {"text": "Double XP all weekend!", "level": "info", "startsAt": "2026-11-09T18:00:00Z", "endsAt": null},
+//     "config": {"difficulty": "hard", "event": true},
+//     "maintenance": {"message": "Back at 7pm"}          // or true, or null / left out: not paused
+//   }
+//
+// The rules are the hosted ones (xgames.fun's play edge, parseLive): the announcement only between its start and end,
+// plain text cut to 280 characters, info or warning; the config a JSON object of at most 8,192 bytes (a bigger one, or
+// one that is not an object, is left out here and said in the log: xgames.fun refuses it). While maintenance is on, the
+// dev host serves the holding page for the game's HTML pages and answers 503 {ok: false, code: 'maintenance'} to its
+// /game/api/* and /platform/v1/* (but /platform/v1/live and the local sign-in), as xgames.fun does.
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+// Shown to people as written (the same on Windows); path.join(dir, LIVE_FILE) still reads it there.
+export const LIVE_FILE = '.gamesfun/live.json';
+export const LIVE_TEXT_CHARS = 280;
+export const LIVE_CONFIG_BYTES = 8192;
+export const MAINTENANCE_DEFAULT = 'This game is paused for maintenance. It will be back soon.';
+export const LIVE_EMPTY = Object.freeze({ announcement: null, config: {}, version: 0, maintenance: null });
+
+// eslint-disable-next-line no-control-regex -- control characters never reach a player's screen (tabs and new lines may)
+const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f]/g;
+const text = (v, max) => (typeof v === 'string' ? v.replace(CONTROL, '').trim().slice(0, max) : '');
+const time = v => {
+  const t = typeof v === 'number' ? v : typeof v === 'string' && v ? Date.parse(v) : NaN;
+  return Number.isFinite(t) && t > 0 ? t : null;
+};
+
+/**
+ * The file's value → {live: {announcement, config, version, maintenance} as players would get it at `now`, problems:
+ * [words]}. Times may be ms or ISO text here (the console sends ms).
+ */
+export function parseLiveFile(value, now = Date.now()) {
+  const problems = [];
+  if (value === null || value === undefined) return { live: LIVE_EMPTY, problems };
+  if (typeof value !== 'object' || Array.isArray(value))
+    return { live: LIVE_EMPTY, problems: [`${LIVE_FILE} is a JSON object: {announcement, config, maintenance}.`] };
+  let announcement = null;
+  const a = value.announcement;
+  if (a && typeof a === 'object' && text(a.text, LIVE_TEXT_CHARS)) {
+    const startsAt = time(a.startsAt),
+      endsAt = time(a.endsAt);
+    if ([...a.text].length > LIVE_TEXT_CHARS)
+      problems.push(`the announcement is cut to ${LIVE_TEXT_CHARS} characters (xgames.fun refuses a longer one)`);
+    if (a.level !== undefined && a.level !== 'info' && a.level !== 'warning')
+      problems.push(`an announcement's level is info or warning, not ${JSON.stringify(a.level)}`);
+    if ((startsAt === null || startsAt <= now) && (endsAt === null || endsAt > now))
+      announcement = {
+        id: createHash('sha256').update(`${a.text}\n${startsAt}\n${endsAt}`).digest('hex').slice(0, 12),
+        text: text(a.text, LIVE_TEXT_CHARS),
+        level: a.level === 'warning' ? 'warning' : 'info',
+        startsAt,
+        endsAt,
+      };
+  } else if (a) problems.push('the announcement needs its text: {"text": "…"}');
+  let config = {};
+  const c = value.config;
+  if (c !== undefined && c !== null) {
+    const bytes = Buffer.byteLength(JSON.stringify(c));
+    if (typeof c !== 'object' || Array.isArray(c)) problems.push('the config is a JSON object: {"difficulty": "hard"}');
+    else if (bytes > LIVE_CONFIG_BYTES)
+      problems.push(`the config is ${bytes} bytes as JSON; xgames.fun takes ${LIVE_CONFIG_BYTES} at most`);
+    else config = c;
+  }
+  const m = value.maintenance;
+  const maintenance =
+    m === true || (m && typeof m === 'object')
+      ? { message: text(m?.message, LIVE_TEXT_CHARS) || MAINTENANCE_DEFAULT, since: time(m?.since) ?? null }
+      : null;
+  const version = Object.keys(config).length ? (Number.isSafeInteger(value.version) ? value.version : 1) : 0;
+  return { live: { announcement, config, version, maintenance }, problems };
+}
+
+/** Reads <game>/.gamesfun/live.json now. → {live, problems, exists}; never throws (a broken file is said, not fatal). */
+export async function readLive(dir, now = Date.now()) {
+  let raw;
+  try {
+    raw = await readFile(path.join(dir, LIVE_FILE), 'utf8');
+  } catch {
+    return { live: LIVE_EMPTY, problems: [], exists: false };
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (e) {
+    return { live: LIVE_EMPTY, problems: [`${LIVE_FILE} is not JSON: ${e.message}`], exists: true };
+  }
+  return { ...parseLiveFile(value, now), exists: true };
+}
+
+/** The holding page xgames.fun's play edge serves for the game's HTML while it is paused (503, never cached). */
+export function maintenancePage(maintenance) {
+  const esc = s =>
+    s.replace(/[&<>"']/g, ch => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+  return (
+    '<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta http-equiv="refresh" content="60"><title>Back soon</title>' +
+    '<body style="margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0e;color:#d0d0d8;font:16px/1.5 system-ui,sans-serif">' +
+    `<main style="max-width:32rem;padding:24px;text-align:center"><p style="margin:0 0 8px;font-weight:600;color:#fff">Paused for maintenance</p><p style="margin:0">${esc(maintenance.message)}</p>` +
+    `<p style="margin:16px 0 0;font-size:13px;opacity:.6">xcore dev: ${LIVE_FILE} has maintenance on.</p></main></body>`
+  );
+}
+/** The refusal of /api/* and /platform/v1/* while paused, as xgames.fun's play edge answers it. */
+export const maintenanceBody = m => ({ ok: false, code: 'maintenance', why: m.message, since: m.since });
+
+const LIVE_PATH = '/platform/v1/live';
+/**
+ * The dev host's live routes (./index.mjs route, tried before the platform's): GET /platform/v1/live from the file, and
+ * while maintenance is on, the holding page for the game's HTML under /game/ and 503 'maintenance' for /game/api/* and
+ * /platform/v1/* (not /platform/v1/live, nor the local sign-in /platform/v1/dev/*). → true when it answered.
+ * `say(problems)`: the file's problems, each time they change.
+ */
+export function createLiveRoutes({ dir, apiAt = '/game/api/', say = () => {}, now = () => Date.now() }) {
+  let said = '';
+  const current = async () => {
+    const r = await readLive(dir, now());
+    const words = r.problems.join('; ');
+    if (words !== said) {
+      said = words;
+      if (words) say(r.problems);
+    }
+    return r.live;
+  };
+  const isApi = p => p.startsWith(apiAt) || p === apiAt.slice(0, -1);
+  const isPlatform = p => p.startsWith('/platform/v1/') && p !== LIVE_PATH && !p.startsWith('/platform/v1/dev/');
+  const isPage = (p, method) =>
+    (method === 'GET' || method === 'HEAD') &&
+    p.startsWith('/game/') &&
+    !isApi(p) &&
+    (p.endsWith('/') || /\.html?$/i.test(p));
+  const send = (res, status, type, body, extra = {}) => {
+    res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store', ...extra });
+    res.end(body);
+    return true;
+  };
+  return {
+    current,
+    /** Whether a WebSocket upgrade to `pathname` is refused now (the game is paused). */
+    async refuseUpgrade(pathname) {
+      return isApi(pathname) && !!(await current()).maintenance;
+    },
+    async handle(req, res, url) {
+      const p = url.pathname;
+      if (p === LIVE_PATH && (req.method === 'GET' || req.method === 'HEAD'))
+        return send(res, 200, 'application/json; charset=utf-8', JSON.stringify({ ok: true, ...(await current()) }));
+      if (!isApi(p) && !isPlatform(p) && !isPage(p, req.method)) return false;
+      const m = (await current()).maintenance;
+      if (!m) return false;
+      if (isPage(p, req.method))
+        return send(res, 503, 'text/html; charset=utf-8', maintenancePage(m), { 'retry-after': '60' });
+      return send(res, 503, 'application/json; charset=utf-8', JSON.stringify(maintenanceBody(m)), {
+        'retry-after': '60',
+      });
+    },
+  };
+}

package/lib/dev/platform.mjs

@@ -116,10 +116,13 @@ export function createPlatformStore({
       expires: exp * 1000,
     };
   }
-  /** env.GF.verifyPlayer, on this machine: xgames.fun's answer shape (no name: hosted it has none), plus `dev: true`. */
+  /**
+   * env.GF.verifyPlayer, on this machine: xgames.fun's answer shape (no name: hosted it has none), plus `dev: true`.
+   * `banned` is always null here: xcore dev has no owner's bans (hosted, it is the creator's ban on any of the token's ids).
+   */
   function verifyPlayer(token) {
     const { name: _name, ...v } = readToken(token);
-    return v;
+    return v.ok ? { ...v, banned: null } : v;
   }
   /** The local sign-in token's claims as verifyPlayer answers them, plus the local player's `name` (the page's /me). */
   function readToken(token) {

package/lib/economy.mjs

@@ -35,6 +35,18 @@ export function solanaCommand(env = process.env) {
   return [process.execPath, path.join(root, bin)];
 }
 
+/** Does the installed package's command have `command` (a version from before it says it has none)? Read from its
+ *  command's own source, so nothing runs. */
+export function solanaHas(command, env = process.env) {
+  const xsolana = solanaCommand(env);
+  if (!xsolana) return false;
+  try {
+    return new RegExp(`['"]${command}['"]`).test(readFileSync(xsolana[1], 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
 // ---- The page client in a game ---------------------------------------------------------------------------------------
 // A published page has no node_modules: the package's page side (@xgamesfun/solana/play and every file it imports, all
 // relative plain ES modules with no dependency) is copied into a game with an economy as gf/loot/. Its record

package/lib/publish/adopt.mjs

@@ -728,6 +728,7 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
 
   let rootPaths = 0,
     sw = false,
+    fullscreen = false, // a way to go full screen: the page's own button, an engine's, or GamesFun.fullscreen()
     devices = new Map(), // what it asks for → where
     callsApi = [];
   // a file the page loads by a path from the root: the first three are listed, the rest counted
@@ -903,6 +904,10 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
         });
       }
       if (!engine && /serviceWorker\s*\.\s*register\s*\(/.test(text)) sw = true;
+      if (
+        /\b(?:webkitR|r)equestFullscreen\b|\bfullscreen\s*\(|gf:fullscreen|window_set_mode|\bSetFullscreen\b/.test(text)
+      )
+        fullscreen = true;
       for (const [what, re] of [
         ['the camera or microphone', /getUserMedia\s*\(/],
         ['the location', /geolocation\s*\.\s*(getCurrentPosition|watchPosition)/],
@@ -977,6 +982,12 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
       what: `${at('index.html')} names no tab icon: browsers ask for /favicon.ico, and the live game's console shows a 404 for it`,
       fix: 'Add one beside the page and link it relatively: <link rel="icon" href="./icon.png"> (or put a favicon.ico at the root of what is published)',
     });
+  // most players come from a post on X or a phone, where the game first shows in a small frame
+  if (!fullscreen && files.some(f => /\.html?$/i.test(f.rel)))
+    warn.push({
+      what: 'it has no way to go full screen: in a post on X and on a phone the game first shows in a small frame',
+      fix: "Give it a full screen button that calls GamesFun.fullscreen() (gamesfun.js, xcore add signin): on xgames.fun the page around it goes full screen (or fills the screen in an app's own browser, X's among them), and elsewhere the browser does, or the game opens in a tab of its own. Or call the browser's element.requestFullscreen() from a click",
+    });
   if (sw)
     warn.push({
       what: 'it registers a service worker',

package/lib/publish/plans.mjs

@@ -1,7 +1,10 @@
 // `xcore plan`'s calls to xgames.fun. A plan is a game's backend tier: Free by default (strict), or
 // Creator when its owner puts it in one of their paid game slots (priced per game slot a month; a slot moves between
 // games at any time without changing the bill), or Scale, which xgames.fun's operator grants.
-//   GET  /api/kit/plan                                  → {ok, slots, used, billing, capCents, monthCents, includedCents, games}
+// Every game sits in a slot: 2 free ones for everyone (their games on Free), any more are paid (their games on Creator).
+//   GET  /api/kit/plan                                  → {ok, slots, used, billing, capCents, monthCents, includedCents, games,
+//                                                          gameSlots?: {free: {slots, used}, paid: {slots, used}, granted, open}}
+//                                                          (slots/used: the paid slots; gameSlots: from xgames.fun 2026-11-08)
 //   GET  /api/kit/games/<gameId>/plan                   → {ok, game, tier, capped, comp, limits, monthCents, includedCents, slots, used}
 //   POST /api/kit/games/<gameId>/plan  {"active": bool} → the same, and changed
 // The game is the folder's own (its .gamesfun/publish.json for this Studio); the credential is publish's.
@@ -69,7 +72,7 @@ export function describeGame(r) {
     lines.push(
       '  capped: its server answers slowly (60 requests a minute) until the month ends, or until it gets more room',
     );
-  if (r.slots !== undefined) lines.push(`  game slots: ${r.used ?? 0} of ${r.slots} in use`);
+  if (r.slots !== undefined) lines.push(`  paid slots: ${r.used ?? 0} of ${r.slots} in use`);
   return lines.join('\n');
 }
 
@@ -78,12 +81,18 @@ export function describeAccount(r) {
   const open = r.payments?.on || r.billing;
   const until = r.periodEnd ? `, paid through ${new Date(r.periodEnd).toISOString().slice(0, 10)}` : '';
   const how = r.payments?.on
-    ? ` (buy or renew on xgames.fun: Studio → Plans, in ${(r.payments.currencies ?? ['SOL', 'USDC']).join(' or ')}${r.payments.cluster === 'devnet' ? ', devnet test payments' : ''})`
+    ? ` (buy or renew on xgames.fun: your console → Plans, in ${(r.payments.currencies ?? ['SOL', 'USDC']).join(' or ')}${r.payments.cluster === 'devnet' ? ', devnet test payments' : ''})`
     : open
       ? ''
       : ' (buying slots is not open on this xgames.fun yet)';
+  const s = r.gameSlots;
   const lines = [
-    `Game slots: ${r.used ?? 0} of ${r.slots ?? 0} in use${until}${how}`,
+    ...(s
+      ? [
+          `Free slots: ${s.free.used} of ${s.free.slots} in use (their games run on Free)${s.open === 0 ? '; a new game needs one: archive a game or move one to a paid slot' : ''}`,
+        ]
+      : []),
+    `${s ? 'Paid slots' : 'Game slots'}: ${r.used ?? 0} of ${r.slots ?? 0} in use${s ? ' (their games run on Creator)' : ''}${until}${how}`,
     `This month: ${dollars(r.monthCents)}${r.includedCents == null ? '' : ` of ${dollars(r.includedCents)} included`}${r.creditCents ? `; usage credit ${dollars(r.creditCents)}` : ''}${r.capCents ? `; spending cap ${dollars(r.capCents)}` : ''}`,
   ];
   for (const g of r.games ?? [])