@xgamesfun/xcore 0.2.1 → 0.4.0

package/skills/bring-your-own-game/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bring-your-own-game
-description: Help someone bring a web game they already made without this kit (plain HTML/JS, or a Vite, Next.js static export, Astro, SvelteKit, Nuxt, Create React App or Parcel project) to xgames.fun - adopt it, fix what does not fit the hosting (server-side rendering, paths from the root, CDN scripts and fonts, undeclared backend origins, secrets, size limits), check it with the page check, connect their own backend or a server/ Worker, add a loot economy, and publish it. Use when the person has an existing game folder or repository and wants web3, xgames.fun hosting, or the kit's checks for it; never rebuild such a game through the creation loop.
+description: Help someone bring a web game they already made without this kit (plain HTML/JS, or a Vite, Next.js static export, Astro, SvelteKit, Nuxt, Create React App or Parcel project) to xgames.fun - adopt it, fix what does not fit the hosting (server-side rendering, paths from the root, CDN scripts and fonts, undeclared backend origins, secrets, size limits), check it with the page check, connect their own backend or a server/ Worker, add a loot economy, review what a cheater gets from it, and publish it. Use when the person has an existing game folder or repository and wants web3, xgames.fun hosting, or the kit's checks for it; never rebuild such a game through the creation loop.
 ---
 
 # Bring your own game
@@ -12,7 +12,7 @@ here is `@xgamesfun/xcore` (the `xcore` command: `npx -y @xgamesfun/xcore …`,
 @xgamesfun/xcore`; never a bare `npx xcore`, which is another package), which needs no kit; with the kit, its MCP tools
 (`gamesfun_adopt` and the rest, named below) do the same.
 
-The order: **adopt → fix the list → check → (backend) → (economy) → publish when they ask.**
+The order: **adopt → fix the list → check → (backend) → (economy) → (review, when it pays) → publish when they ask → (review --live).**
 
 ## 1. Adopt
 
@@ -57,6 +57,17 @@ stays on their host as a backend (README, "A game with its own Node server"). Su
 Never edit their build tool's output by hand (it is made again on every build): change the source or the config.
 Adopt again after the fixes; the list should be empty.
 
+**Full screen.** Most players meet a game in a post on X or on a phone, where it first shows in a small frame. When adopt
+warns that the game has no way to go full screen, offer the person a button for it (their game, their call): a small
+button in a corner of the first screen, big enough for a thumb, that calls `GamesFun.fullscreen()` from the click
+(`gamesfun.js`, loaded by `xcore add signin`; Godot `await GamesFun.fullscreen()`; Unity `Screen.fullScreen`).
+Pressed again it comes back. It answers `{on, how}`: on xgames.fun the page around the game goes full screen, or fills
+the screen in an app's own browser (X's on a phone among them); on the game's own link the browser does; in a frame
+that allows none (a post on X on a computer) the game opens in a tab of its own (`how: 'tab'`); an iPhone's Safari has
+no full screen for a page (`how: 'none'`): there the button can hide, or say "Add to Home Screen".
+`GamesFun.onFullscreen(on => …)` follows it (Esc, the browser's own controls). A game that goes full screen already
+(its own button, or its engine's) needs nothing.
+
 ## 3. Check
 
 ```bash
@@ -68,7 +79,9 @@ console errors, nothing missing, nothing from the root, something on screen), it
 screenshots in `evidence/verify-N/` and look at them. A failing check 4 names the origin and why: declare it in
 `backend.json` if the game really calls it, or remove the call. The page check does not say the game plays well:
 that is the person's own game; ask them what to try, and try it with `xcore dev <folder>` (the game as xgames.fun
-hosts it, with its server, sign-in, saves, rooms and economy RPC) or their own.
+hosts it, with its server, sign-in, saves, rooms and economy RPC, refusing what xgames.fun refuses on the Free plan;
+`--plan creator` for a Creator game) or their own. A refusal there (`rate`, `full`, `too-many`, `order`) is one the
+published game would get: fix the game, not the stand-in.
 
 ## 4. Players, a database, a backend (only when the game has or needs them)
 
@@ -100,7 +113,11 @@ supabase|railway` with the kit installed). Without the kit, they set one up them
   ([docs/SERVER.md](../../docs/SERVER.md)): a Worker on `/api/*`, Durable Objects for rooms, `env.GF` for sign-in, saves
   and scores. Their page calls it with a relative address (`fetch('api/scores')`): `/api/*` at the published origin,
   `/game/api/*` under `xcore dev`, which runs it under workerd with a local `env.GF`. A Node-only server stays on
-  their own host.
+  their own host, and so does anything that opens raw sockets (a database driver, a mail or chat client): xgames.fun
+  refuses `cloudflare:sockets`, `node:net` and the like, an `import()` of a name made at run time, and `nodejs_compat`.
+  Every route that does work checks the player's token first (`env.GF.verifyPlayer`; 401 at once without one): a
+  stranger's request that does work counts toward what caps the game. Key a player's data on `sub` (the account:
+  `x:…`, or `g:…` for Google, different in every game), never on the wallet; `wallet` is its own claim, maybe null.
 
 ## 5. An economy (only when they ask: tokens, NFTs, a shop, prizes, staking)
 
@@ -139,8 +156,9 @@ out of `.dev.vars` or repeat it.
 
 Design it so a cheater gains little (docs/SERVER.md, "How much your server can check" and "Who gets paid"): never send
 the page a run's whole seed up front (reveal randomness as the run goes); give slack per second, not per request; one
-open run per player; pay only proven wallets (the page calls `gf.loot.link()` once; a wallet sign-in needs none);
-a wallet is free, so for rewards worth farming set `VOUCHERS.payOnly` to `'x'` and give every grant a `perDay` total.
+open run per player; pay only proven wallets (the page calls `gf.loot.link()` once; a player whose xgames.fun account
+has a wallet linked needs none); a wallet is free, so for rewards worth farming set `VOUCHERS.payOnly` to `'x'` (X only)
+or `'account'` (X or Google; a Google account is easier to make) and give every grant a `perDay` total.
 
 A page alone can't prove a score or a win: anyone can change it in the console. A leaderboard that must be fair is
 one the server owns: `env.GF.scores.setup(board, {writer: 'server'})` refuses the page's submits to it (a pattern,
@@ -152,7 +170,35 @@ your server can check". A bounded result earns small capped amounts; entry fees
 replayed one. Without a server,
 offer what the player pays for or the chain decides (a shop, boxes, raffles, staking, perks), and say why.
 
-## 6. Publish (only when they ask)
+## 6. Review (a game whose server pays results)
+
+Before publishing a game that pays results, read it as a cheater would:
+
+```bash
+xcore review <folder>           # evidence/review-N/review.md and review.json; exits 1 on a high finding
+xcore loot review               # the economy's part alone (@xgamesfun/solana's xsolana_review)
+```
+
+- **Fix every high finding** (a `PAY.check` that pays from the request alone, a route anyone can call, a seed in the
+  page, `.dev.vars` in git…), and run it again. Mediums are the person's to decide with you: say each one plainly.
+- **Declare `trust` honestly** on every grant a voucher pays: `"decides"` (the server runs the game; the page sends
+  only inputs), `"replays"` (the server runs the page's inputs again) or `"bounds"` (the page plays and reports; the
+  server checks its clock, order and caps). It is what `PAY.check` really does, not what you hope it does: a server
+  that times a run the page simulated is `bounds`, whatever it is called. (The field needs the `@xgamesfun/solana`
+  that has `review`: 0.25.0's `xcore loot check` refuses it, so with that one leave it out and still tell the person
+  the level in words.)
+- **Tell the person**, in plain words, from the end of `review.md`: for each paid route, the level it uses, what a
+  cheater gets (a bounded result pays a script that waits and reports, without playing; a decided one pays what a bot
+  that plays well wins), and what the stronger level would cost to build (replaying: a deterministic step and about
+  3 ms of CPU a second played; deciding: the rules moved to the server, a request each step). Let them choose: a
+  smaller prize and tighter caps, or the stronger level. Never call a bounded result safe.
+
+After publishing, `xcore review <folder> --live` asks the published game as a stranger (no sign-in, a forged one;
+nothing it sends can spend or sign) and checks its voucher key and economy against the folder. Under `xcore dev`,
+give its address: `--live http://127.0.0.1:<port>/game/`. `xcore publish` reminds you when the economy or `server/`
+changed since the last review.
+
+## 7. Publish (only when they ask)
 
 ```bash
 xcore publish <folder> --check  # the offline part: what goes up, what refuses it
@@ -160,11 +206,14 @@ xcore publish <folder>          # or gamesfun_login, then gamesfun_publish {"gam
 ```
 
 It builds, runs the page check on exactly those files, uploads the published folder and the `server/` bundle. A failed
-check makes a private draft only. Tell them the link, what you changed in their files, what the checks proved and what
+check makes a private draft only. `xcore login` asks the person to tick, on xgames.fun's approval page, the games this
+computer may work on (or their whole account), and says which it got; a command refused with code `not-granted` means
+the sign-in was not given that game: they run `xcore login` again and tick it (never work around it). Tell them the link, what you changed in their files, what the checks proved and what
 nothing checked (their gameplay, their backend's own behaviour).
 
 A game with a `server/`, saves or scores runs under its **plan** (`xcore plan <folder>`): Free by default (50 ms of CPU
-and 600 requests a minute, $1 of use a month, then capped and slow until the month ends). When the game needs more
+and 600 requests a minute, $1 of use a month; past it the game is capped until the month ends: its server is switched
+off and saves and scores slow down). When the game needs more
 (a server that replays play, many players at once), tell them: a paid slot makes it Creator
 (`xcore plan activate <folder>` once they have one), and the paid slot moves between their games at any time. Everyone
 has 2 free slots: a third game is refused on publish (`no-free-slot`) until they archive one on their console