@genex-ai/cli-demo 1.38.0 → 1.38.1-dev.1097

package/templates/skills/genex-authoritative-multiplayer/references/settings.md

@@ -0,0 +1,122 @@
+# Room settings by genre
+
+A room module says how its game feels as **data in `config`**, never as code that names the game.
+Pick the genre preset closest to the game; every setting you leave out comes from its table, and
+every engine runs the same table, so prediction matches on every client. All of it needs a
+`firstperson` or `vehicle` movement preset ([presets.md](presets.md)); a bad value is refused when the
+module loads, naming the first bad path (for example `$.config.contacts.top.speed`).
+
+| The game | `contacts.preset` | Movement | Seats on each other | Input repeat |
+|---|---|---|---|---|
+| Shooter, arena brawler | `shooter` | `firstperson` | stand on a head, slide off if the foot is mostly over the edge; players are solid and never shoved | on |
+| Platformer, co-op climber | `platformer` | `firstperson` | stand and ride; a stomp is opt-in | on |
+| Party game, minigames | `party` | `firstperson` | stand and ride, shoved by each other | on |
+| Sandbox with crates and props | `physics-sandbox` | `firstperson` or `vehicle` | stand and ride, props ride heads | on |
+| Car arena, derby | `vehicle-arena` | `vehicle` | cars slide off roofs, shove each other, bounce (restitution 0.6) | off |
+
+## Contacts
+
+`config.contacts: { preset, ... }` is how two seats in contact are handled. The server runs it after
+each tick's movement and before `step`; clients run it in their prediction. Write no contact code, and
+never run a pass of your own beside it.
+
+```js
+// shooter: the seats' hull is the movement preset's; players walk on each other's heads
+config: { tickHz: 60, maxPlayers: 10, preset: { name: "firstperson", params: {} }, contacts: { preset: "shooter" } },
+// platformer with a stomp (the upper seat bounces off, a held jump adds a boost)
+config: { tickHz: 60, maxPlayers: 8, preset: { name: "firstperson", params: {} }, contacts: { preset: "platformer", top: { policy: "bounce" } } },
+// party: a shorter landing zone is one number
+config: { tickHz: 30, maxPlayers: 12, preset: { name: "firstperson", params: {} }, contacts: { preset: "party", top: { policy: "stand", center: 0.5 } } },
+// sandbox: players stand on each other and on the crates the room simulates
+config: { tickHz: 60, maxPlayers: 8, preset: { name: "firstperson", params: {} }, physics: true, contacts: { preset: "physics-sandbox" } },
+// car arena: cars on cars slide off, whatever the preset says about hulls
+config: { tickHz: 60, maxPlayers: 6, preset: { name: "vehicle", params: {} }, contacts: { preset: "vehicle-arena" } },
+```
+
+- **What a seat does on another's top** is `top.policy`: `stand` (rest on the head; `center` is the share
+  of the lower seat's half width a landing may be off by, else it slides off; `ride: true` carries the
+  rider), `slide` (frictionless, slid off), `bounce` (a stomp: `stompMin`, `bounceSpeed`, `jumpBoost`)
+  or `ghost` (the pair never touches). **Head landing** is `stand` with a `center`: the shooter's is 0.25.
+- **A pair rule** gives two kinds of seat their own top rule. A seat's tags are its entity's `tags`
+  and `flag:k` for each bit `k` of its `flags`: `pairs: [{ a: "flag:0", b: "flag:0", top: { policy: "ghost" } }]`
+  lets seats that both carry flag bit 0 (a team) pass through each other. At most 32 pairs.
+- **Cells you can override**: `shape` (default: the movement preset's hull, a box over a `vehicle`),
+  `restitution`, `passes` (1 to 64), `offWall`, `drawing` (`predicted`, `separate`, `timeline`: how a
+  client draws other seats), `push` (`shared` or `mover`), `headFriction` (`slide` or `carry`, for props).
+- A module that needs a rule the table cannot say keeps the contact functions of
+  [module-api.md](module-api.md); do not mix the two.
+
+## Inputs
+
+`config.inputs: { preset?, repeat? }`. A starved seat (its input is late) is either stepped again
+under its last input (`repeat: "on"`, bounded to about 33 ms a starve and 100 ms in all) or held
+(`"off"`). The default is the genre's column above (`inputs.preset`, else `contacts.preset`, else on).
+Car arenas measured worse with repeats on, shooters and character games better. Override only with a
+measurement: `inputs: { repeat: "off" }`. The client follows the room's setting by itself.
+
+## Lifts
+
+`config.lifts` declares moving platforms as data, each posed by an exact function of the tick: no
+module code moves them. A rider is carried, and leaves with the lift's velocity unless `impart: "none"`.
+
+```js
+lifts: { platforms: [
+  { id: "elevator", shape: { kind: "box", half: [96, 96, 8] }, path: { points: [[0, 0, 0], [0, 0, 240]], legs: [240], waits: [60, 60], ease: "smooth" } },
+  { id: "turntable", shape: { kind: "disc", radius: 160, half: 8 }, at: [600, 0, 0], spin: { period: 600 } },
+  { id: "belt", shape: { kind: "box", half: [200, 64, 8] }, at: [0, 600, 0], surface: [300, 0] },
+] }
+```
+
+- A path has `points`, one leg length in **ticks** per leg (`legs`: one fewer than the points for the
+  default `pingpong`, one per point for `loop`), optional `waits` (one per point), `ease` (`linear` or
+  `smooth`) and `phase`. A `spin.period` is the ticks of a full turn (8 or more); `surface` is a
+  conveyor's speed in the platform's frame. 1 to 32 platforms, ids of a-z, 0-9 and `-`.
+- A platform that moves more than the movement preset's `radius` in one tick is refused, naming the
+  leg and the most allowed. Lengths in ticks scale with `tickHz`: the same elevator at 120 Hz has doubled legs.
+- The client draws a lift with `session.liftPose(id)` and, in a `firstperson` view, adds
+  `session.viewCarry()` to its yaw once a frame. The module reads `ctx.lifts.crushed()` for damage.
+- The client must send the `lifts@1` capability; `connectAuthority` does. A client that does not (the
+  Godot SDK today) is refused when the room declares lifts, never allowed to fall through them.
+  With server physics, crates ride lifts and a conveyor moves them.
+
+## Tick rate
+
+`tickHz` is 20, 30, 60 or 120. Use 60 for character and car games, 30 for slow ones. **120 is for a
+module that asks for physics** (`physics: true`): the world steps twice as often, the room counts twice
+toward a server's capacity (12 units where 60 Hz counts 6), and each tick keeps a 60 Hz tick's budget
+(8 ms, 1 ms on average), so the room gets twice the CPU a second. Check the REPORT line of
+`genex-authority-dev start` against `tick.budgetMs` ([testing.md](testing.md)).
+
+```js
+config: { tickHz: 120, maxPlayers: 4, preset: { name: "vehicle", params: {} }, physics: true, contacts: { preset: "vehicle-arena" } },
+```
+
+## Regions
+
+Pass the stand's regions beside its urls and the client joins the nearest one by measured ping:
+
+```ts
+const session = await connectAuthority({
+  urls: getAuthorityUrls(), regions: getAuthorityRegions(), room: GENEX.slug, auth: () => getColyseusAuth(),
+});
+```
+
+Each region is its own matchmaking pool: players meet others who entered through the same region. A
+region that answers no probe is tried last. A full region (503) is retried, and moves on to the next-best
+after a second refusal. Nothing to configure in the module.
+
+## The fast channel (`fast@1`)
+
+On a bad Wi-Fi link one lost TCP segment holds every input and snapshot behind it. With the fast
+channel a seat's inputs and the room's motion go by unordered datagrams (each input is sent in several,
+a lost snapshot is replaced by the next); join, game events, chat and everything else stay on the
+WebSocket. It needs nothing in the room module.
+
+- The seat asks for it (`fast@1`), the room offers it only when the server has it configured, and a seat
+  that is not offered it stays a WebSocket seat. If the datagrams stop, or the endpoint cannot be reached,
+  the seat falls back to the WebSocket by itself, mid-game, and prediction does not notice.
+- **Status:** a UDP seat in Unreal (`bFastChannel`), Unity (`GenexAuthorityOptions.Fast`, not WebGL),
+  Rust (`AuthorityOptions::fast(true)`) and TypeScript in Node (the client's `fast` option, given
+  `openUdpFastSocket` from `@genex-ai/multiplayer/authority/fast-udp`). It is off until the game turns it on. **A browser game
+  is a WebSocket seat**: browsers have no raw UDP, and WebTransport is not shipped. Godot is a WebSocket seat.
+  Do not promise a browser player UDP-like play.

package/templates/skills/genex-authoritative-multiplayer/references/testing.md

@@ -0,0 +1,118 @@
+# Testing a room module on this machine
+
+`@genex-ai/authority-dev` runs the room module exactly as Genex's servers do — the same room core,
+the same sandbox limits, the same bundler — on this machine, with no account and no network. It is
+a dev dependency of the game (`npm i -D @genex-ai/authority-dev`); `npx genex preview` uses the same
+package to check the module before it ships.
+
+| Command | What it does |
+|---|---|
+| `npx genex-authority-dev validate --module server/room.ts --root .` | The publish gate: bundles the module, fuzzes it for 30 simulated seconds with random and adversarial players, checks every tick, holds its tick time to a CPU budget, and replays the run twice. Exit 0 = passed. `--out report.json` keeps the report. |
+| `npx genex-authority-dev start --module server/room.ts --root . --bots 3 --latency 75 --report` | Serves the module on `127.0.0.1` with bots that join, wander, aim and fire, behind a 75 ms each-way link. |
+| `npx genex-authority-dev replay --module server/room.ts --root .` | Replays the validation run twice and prints both state hashes. Equal means the module is deterministic. |
+
+`--root .` lets the module import files outside its own folder (a movement step in `src/`); every
+file the bundle reads must still be inside the game. `--port` picks the port (default: any free
+one), `--jitter` adds random delay on top of `--latency`, `--duration` stops after that many seconds
+and `--seed` changes the run. `start` only ever listens on `127.0.0.1`.
+
+## Playing against the local server
+
+`start` prints one line per event on stdout:
+
+```
+LISTEN ws://127.0.0.1:<port>
+REPORT {"rooms":1,"players":4,"tick":{"p50Ms":…,"p99Ms":…,"maxMs":…,"budgetMs":…},"strikes":0,"lastFault":null,…}
+LOG {"room":"…","line":"what ctx.log wrote"}
+ERROR {"reason":"…","detail":"…"}
+```
+
+Start the game's dev server and open it with the address from `LISTEN`:
+
+```
+http://localhost:5173/?genex_local_test=1&genex_authority_url=ws://127.0.0.1:<port>
+```
+
+In local test mode `getAuthorityUrls()` returns that address and `getColyseusAuth()` a local
+placeholder, so the game's own client joins without a change. Every join is a fresh local player
+(whatever room name it sends, it meets the bots), so a second browser window is a second player.
+Only a page served from this machine may join.
+
+Read the REPORT line while you play: `strikes` above 0 or a `lastFault` means the module faulted
+(the module's own bug, named by its close code); a `tick.p99Ms` near `tick.budgetMs` means the
+module is too slow for Genex's servers; `corrections.visible` counts the bots' predictions the
+server had to correct visibly — near zero is the goal, and your own client's count is
+`session.telemetry.visibleCorrections`. Stop the server with Ctrl+C.
+
+## A room with projectiles
+
+The same commands test it; nothing extra to install. What to look for:
+
+- **The fuzz and the bots fire button bit 1.** `validate` presses it most often and other bits now
+  and then; the bots that `start` runs press only bit 1, aimed at the nearest player. Bind the main shot
+  to bit 1, or neither ever launches one.
+- **Removal is yours.** A module that never removes its projectiles fills the room's 1024 entities
+  and fails `module_ended`, with `too_many_entities` in the detail. `--out report.json` keeps the
+  report, whose `entitiesPeak` says how many entities the fuzz room held at its fullest: it should
+  stay far below 1024.
+- **A launch that throws is a fault**: an `id` passed inside `onInput`, none passed in `step`, a
+  launch in `init` (`load_failed`), or a burst past the launch budget (`RangeError`).
+- **In the browser**, at `--latency 75`: your shot leaves the frame you fire and flies on without a
+  jump when the server's arrives; another player's (a bot's) shots fly smoothly, not 100 ms behind;
+  `session.telemetry.projectilesRejected` stays near 0 while you fire steadily, and
+  `session.telemetry.projectilesConfirmed` grows with each shot.
+
+## Why validation failed
+
+`validate` (and `npx genex preview`, which runs it) names each failure by reason, with the close code
+where the module itself ended or faulted:
+
+| Reason | What happened | Fix |
+|---|---|---|
+| `build_failed` | The bundler could not build it: a syntax error, a missing file, a package import, a Node built-in. | Import only your own files; the module gets everything else through `ctx`. |
+| `outside_root` | The bundle reads a file outside the game folder (or outside `--root`). | Keep every import inside the game; pass `--root .` for shared files in `src/`. |
+| `too_large` | The bundle is over 1 MiB. | Move data out of the module; generate it in `init`. |
+| `unavailable_global` | It uses something the sandbox does not have (`Date`, `setTimeout`, `fetch`, …). | Use `ctx.tick` and `ctx.dt` for time, `ctx.random()` for randomness. |
+| `global_object` | It reaches `globalThis` instead of `ctx`. | Pass what it needs through `ctx` and `ctx.state`. |
+| `load_failed` | Its top level or `init` failed (the code says how: an error, a timeout). | Keep the top level to constants and functions; make `init` small. |
+| `module_ended` | The fuzz run ended the room: a timeout, too much memory, too many faults, a CPU budget broken. | Bound every loop by entities or players; never grow state without limit. |
+| `module_fault` | It faulted at least once and survived: a hook threw, or its output broke a limit. | Fix the throw or the output; validation allows none. |
+| `nondeterministic` | Two replays of the same run gave different states. | Remove every source of difference: a clock, unordered iteration, state outside `ctx.state`. |
+| `tick_budget` | Its tick time p99 is over the local budget. | Do less per tick; move setup to `init` and `onJoin`. |
+| `orphan_entity` | After a tick, an entity was owned by a player who had left. | Remove (or disown) a player's entities in `onLeave`. |
+| `log_flood` | One tick logged more lines, or longer lines, than a room keeps. | Log on events, not every tick. |
+| `short_run` | The fuzz ran fewer than 30 simulated seconds (`--duration`). | Run it with the default duration; a short run never passes. |
+| `host_stall` | A busy machine cut a call off by wall clock while the module stayed under its CPU limit: no verdict on the module. | Change nothing in the module; run `validate` again on a quieter machine. |
+| `physics_unavailable` | The module asks for `physics` and this validator has no physics core. | Update `@genex-ai/authority-dev`; see [physics.md](physics.md) for when servers run physics. |
+| `physics_build` | The two replays ran on different physics core builds, so they were not compared. | Change nothing; run `validate` again. |
+| `physics_backend_parity` | With `--physics-backend both`, the replay on the second physics core gave a different state from some tick on. | Report it with the tick the output names: the two cores must agree, so this is a core bug, not the module's. |
+
+## When the deploy refuses the module
+
+`npx genex preview` and `npx genex publish` print `Room module refused (<reason>)` and change
+nothing:
+
+| Reason | What to do |
+|---|---|
+| `manifest_invalid` | Fix `genex.authority` as the message says: a plain relative path to a `.js` or `.ts` file inside the game, and valid optional knobs. |
+| `toolchain_missing` | `npm i -D @genex-ai/authority-dev`, then deploy again. |
+| `toolchain_unusable` | `npm i -D @genex-ai/authority-dev@latest`, then deploy again. |
+| `bundle_failed` | The bundler's reason is printed beside it (a reason from the table above). |
+| `validate_failed` | Each validation failure is printed; the full report is at `.genex/authority/report.json`. Reproduce with `npx genex-authority-dev validate`. |
+| `sha_disagrees` | The report passed a different bundle than the one to upload: update `@genex-ai/authority-dev` and deploy again. |
+| `too_large` | The module is over 1 MiB, or its report over 64 KiB. |
+| `config_out_of_range` | The tick rate or player count is one Genex does not run (20, 30, 60 or 120 Hz, 120 only with physics; 1 to 64 players). |
+| `requires_pro` | The game's owner needs Genex Pro for Genex's servers. Testing on this machine stays free. |
+| `upload_failed` | The module store refused the upload or could not be reached; try again. |
+
+## Before calling it done
+
+1. `validate` passes and `replay` says the hashes are equal.
+2. At `--latency 75`, two players (two windows count) move, aim and fire, and see each other move
+   smoothly, about 100 ms behind.
+3. A hit lands when it looked right on the shooter's screen; a respawn snaps instead of sliding.
+   With projectiles: a shot is judged where the target is on the server, so a dodged bolt misses.
+4. Leaving and rejoining works, and the leaver's body is gone for everyone.
+5. The REPORT line shows no strikes after a few minutes of play.
+
+Say plainly what was not exercised (a full room, a slow connection, a reconnect).

package/templates/skills/genex-game-director/SKILL.md

@@ -158,11 +158,12 @@ vendored code from memory of another engine.
 | requested UI/HUD/menu/interface work, a visible UI problem, or an interface you decided this game wants built with generated art | `$genex-threejs-game-ui` |
 | selling anything for Nex (Genex's currency, bought with real money) or for real money with no currency named: a shop, an item catalog, boosts, cosmetics, "make it earn"; a fixed Nex price is a store item. Coins, gold or gems are the game's own earned currency, not this row. Also any request for a loot box, gacha, wager, casino mechanic or donation prompt, which that skill refuses and replaces | `$genex-monetization` |
 | an item for the Genex store — sell a sword, a skin or a pet for Nex with its picture and description, "other games can use it too" — or another creator's shared item added to this game (`npx genex items add <id>`). Build the item first, list it with `npx genex shop add … --json` without asking; the person puts it on sale | `$genex-items` (with `$genex-monetization`) |
-| the game calls a language model AT RUNTIME on the player's money: NPCs that answer in their own words, dialogue or quests written per save, a judge reading what the player typed — one-time calls, or a standing budget the player approves once. Check the lane with `npx genex llm models` before designing it in | `$genex-llm-in-games` |
+| the game calls a language model AT RUNTIME on the player's credits, billed as used under a per-call ceiling the game benchmarks with `npx genex llm bench`: NPCs that answer in their own words, dialogue or quests written per save, a judge reading what the player typed — one-time calls, or a standing budget the player approves once. Check the lane with `npx genex llm models` before designing it in | `$genex-llm-in-games` |
 | cinematic menu/title/pause/victory/defeat/lobby/credits video treatment | `$genex-ai-menu` |
 | drawn HUD chrome the game's style wants—one element or a matched set of frames, masks, and icons | `$genex-ai-hud` |
 | the game works but feels flat, floaty, or unresponsive: input response, camera, impacts, cooldowns, difficulty, fail/retry | `$genex-threejs-game-feel` |
 | realtime multiplayer: movement sync, shared ball/NPC, host-run scores/enemies, shots/emotes, persistence | `$genex-threejs-multiplayer` |
+| competitive multiplayer where cheating matters — ranked PvP, an arena or shooter with a winner worth faking, "so nobody can cheat", "server-authoritative": the game's room module runs on Genex's servers (`genex.authority`; the owner needs Genex Pro there, testing on this machine is free) | `$genex-authoritative-multiplayer` |
 | players talking to each other by TEXT — chat, room chat, "let them type to each other" (`room.chat` + `npx genex controller chat`) | `$genex-threejs-multiplayer` |
 | players TALKING — voice chat, mic, "hear each other", proximity/positional voice (`room.voice` + `npx genex controller voice`; party-sized, max 6 per room — say that number out loud before building the feature) | `$genex-threejs-multiplayer` |
 | player identity, sign-in, guests, saves/progress, per-player state, shared persistent world, leaderboards—mandatory for every game | `$genex-threejs-embed-auth` |

package/templates/skills/genex-getting-started/SKILL.md

@@ -161,7 +161,7 @@ downloads the game too, binary assets and all:
 
 ```bash
 mkdir my-game && cd my-game
-npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
+npx @genex-ai/cli-demo@dev link <slug>   # slug = the name in the play URL
 npm install
 ```
 
@@ -225,7 +225,7 @@ Safe to run any time — genex-owned skills are refreshed to the latest version,
 and your own files are never touched:
 
 ```bash
-npx @genex-ai/cli-demo@latest init
+npx @genex-ai/cli-demo@dev init
 ```
 
 Use `--force` only if you intentionally want your own existing files overwritten