@genex-ai/cli-demo 1.2.4-dev.363 → 1.3.0

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -46,7 +46,8 @@ npm i @genex-ai/multiplayer@^0.12.0
 > landed in 0.10; confirmed object controls, snaps, host-tick teardown, and reconnect rebasing
 > in 0.9. An older resolve does not have those.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.13.0** (`objects`/`host` since 0.4; verified per-player `avatarUrl` since 0.12;
+This skill targets `@genex-ai/multiplayer` **≥ 0.15.0** (`objects`/`host` since 0.4; verified per-player `avatarUrl` since 0.12;
+room text chat via `room.chat` since 0.14; mesh voice via `room.voice` since 0.15;
 `matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
 since 0.8; soft ownership handoff since 0.8.4; confirmed controls, snap epochs, and host-tick
 lifecycle guarantees since 0.9; regional relay selection via `getColyseusUrls()` since 0.10; host-only `setRoomOpen()` since 0.13;
@@ -536,9 +537,11 @@ of five kinds — put each on its channel and the game just works:
 | Your own avatar (position, rotation, anim) | `me.set` → others read `players` | you (each player their own) |
 | A moving thing nobody owns (**ball**, puck, NPC) | `objects` (claim + set) | the one current **owner** |
 | Slow agreed facts (score, round, wave, seed) | `shared` | the **host** (`isHost`) |
-| One-off actions (shot, emote, hit, chat) | `send` + `on` | whoever did it |
+| One-off actions (shot, emote, hit) | `send` + `on` | whoever did it |
 | Discrete per-player values (hp, ammo, flags) | in `me.set`, read via `stateRaw` | you |
 | Which avatar MODEL a player is (VRM look) | already on `players` as `p.avatarUrl` — sync nothing | the **relay** (verified identity) |
+| **Text chat** | `room.chat` — its own channel, NOT `send` | the **relay** (stamps the sender) |
+| **Voice chat** | `room.voice` — peer-to-peer audio, max 6 | nobody (the relay carries no audio) |
 
 Getting the channel right is the whole game. A ball on `shared` stutters (not smoothed) and
 fights (many writers). A ball on `objects` glides and has one owner. That's the difference.
@@ -651,6 +654,28 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   you**, so apply your own action's local effect directly (draw your own tracer at fire time),
   not inside `on(...)`. Relay-internal names (`state`, `shared`, `claim`, `obj`, `release`,
   `destroy`, `match:*`, `__*`) are refused — pick your own event names. `room.leave()`.
+- `room.chat` — room text chat, **its own channel, not `send`**: `chat.send(text)`,
+  `chat.on(m => …)`, `chat.history`, `chat.mute(id)` / `chat.unmute(id)` / `chat.muted`.
+  The relay stamps `m.from`/`m.name` from the verified session (nobody can post under
+  another player's name), sanitizes `m.text`, caps it at 500 chars, and replays the last
+  ~50 lines so a late joiner sees the conversation. **Your own lines echo back to you** —
+  render only what arrives in `on`, or every message appears twice. UI:
+  `npx genex controller chat`, and you MUST pass its `onTypingChange` (or check
+  `chat.isTyping`) so the game stops reading the keyboard while someone types — otherwise
+  typing "was that a wall?" walks and jumps the player. Render `m.text` with `textContent`,
+  never `innerHTML`. See [references/realtime-patterns.md](references/realtime-patterns.md).
+- `room.voice` — mesh voice chat: `voice.join(opts)` / `leave()` / `setMicEnabled(on)` /
+  `mute(id)` / `participants` / `active` / `speaking`, plus `room.on('voice', …)` and
+  `room.on('voice:rejected', …)`. **Party-sized: the relay caps it at 6** (audio is a full
+  mesh — everyone uploads to everyone, and reliability, not bandwidth, breaks first). The
+  room still holds 64 players; the 7th `join()` is refused, so handle `voice:rejected`
+  instead of retrying. `join()` MUST run inside a click/tap — browsers gate both the mic
+  prompt and audio playback on a user gesture — and it REJECTS when the player denies the
+  mic, which is an ordinary outcome to show, not an error to swallow. For a 3D game use
+  `npx genex controller voice` (proximity audio + push-to-talk); it joins with
+  `{ spatial: true }` and drives a `THREE.PositionalAudio` per speaker. **Configure TURN
+  for anything real**: ~10–20% of players are behind symmetric NAT and connect to nobody
+  without it, while everyone else works — a miserable bug to diagnose from a report.
 - `room.inputs.send(payload)` / `room.inputs.on((fromId, payload) => …)` — the host-routed
   input channel for host-authoritative physics: anyone sends, ONLY the current host receives.
   See [references/host-physics.md](references/host-physics.md).
@@ -912,8 +937,8 @@ from any still capture whether movement feels smooth.** Don't try — it leads t
 
 1. **Trust the SDK's smoothing.** Draw `state` directly; don't add your own.
 2. **Verify it *runs*:** two clients, distinct meshes, both move, no console errors, each sees the
-   other (and the ball, if any). That's all a capture can prove. Local test mode (the embed-auth
-   skill's `?genex_local_test=1`) can NOT do this: it mints no relay credential, so `connect()`
+   other (and the ball, if any). That's all a capture can prove. Local test mode (what the dev
+   server boots into — the embed-auth skill) can NOT do this: it mints no relay credential, so `connect()`
    fails there by design and two local-test tabs never see each other — run the two-client check
    on the published game (or have the owner open their draft), and if multiplayer wasn't
    exercised, say exactly that in your handoff instead of implying it was.

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -180,9 +180,10 @@ room.on("host", () => {/* host migrated — the new host takes over writing */})
 de-duped) — but for a value you render every frame, read `room.shared.get(...)` in your loop (as
 `updateHud` does) rather than wiring render state through the event.
 
-## Custom events (shots, emotes, chat)
+## Custom events (shots, emotes)
 
-For one-off actions that aren't continuous state, use `send`. The shooter judges the hit **locally**
+For one-off actions that aren't continuous state, use `send`. (Text chat is NOT one of these —
+it has its own channel, `room.chat`; see below.) The shooter judges the hit **locally**
 against what it sees (favor-the-shooter) and announces it; the victim applies its own damage.
 
 **`send` reaches only OTHER clients — it never echoes back to you.** So apply your own action's
@@ -210,6 +211,47 @@ if (!t) return;
 const px = t.stateRaw.x, pz = t.stateRaw.z;   // test against the raw latest
 ```
 
+## Text chat
+
+Chat has its own channel — **never build it on `send`**. The relay stamps the sender from the
+verified session, sanitizes the text, and replays the recent history to late joiners; `send` gives
+you none of that and lets a client post under any name it likes.
+
+Install the overlay with `npx genex controller chat` (writes `src/controllers/chat/chat-overlay.ts`),
+then wire it:
+
+```ts
+import { ChatOverlay } from "./controllers/chat/chat-overlay.ts";
+
+const chat = new ChatOverlay({
+  room,
+  onTypingChange: (typing) => { keyboard.enabled = !typing; },   // ← REQUIRED, see below
+});
+```
+
+**The one bug everybody ships: the game reads the keyboard while the player types.** Someone
+types "was that a wall?" and their character walks, reverses and jumps. Either pass
+`onTypingChange` (above) or check `chat.isTyping` in your input code. There is no third option.
+
+Rolling your own UI instead? Three rules:
+
+```ts
+room.chat.send("on my way");            // your OWN line comes back via on() — don't also append it
+room.chat.on((m) => {
+  el.textContent = `${m.name}: ${m.text}`;   // textContent, NEVER innerHTML — remote input
+});
+room.chat.history;                       // render on mount: a late joiner sees the conversation
+```
+
+- **Your own lines echo back** (unlike `send`), in server order with the server's timestamp.
+  Appending locally on submit shows every message twice.
+- **`m.name` is relay-verified** — safe to display, and a player cannot post under another name.
+- **`m.text` is sanitized but not markup-escaped** — control and bidi characters are stripped by
+  the relay, but you must still render it as text.
+
+Chat has its own rate budget (~2 lines/second per player), separate from gameplay traffic: a chat
+flood cannot starve movement, and a busy game cannot starve chat.
+
 ## Persistence helper
 
 ```ts

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -129,13 +129,9 @@ everything twice.
    visible; the lock may only ever engage from the Play/Resume click or a
    gameplay canvas click (the phase binding `setPaused(phase !== "playing")` is
    what guarantees this — check it rides `setPhase`, not the render loop).
-   Headless caveat, measured on Chromium 151: `requestPointerLock` does NOT
-   throw — it locks, with or without a user gesture, so the lock and the
-   unlocked cue ARE yours to assert headless. What does not survive is the
-   both-axes look check: synthesised mouse movement cancels to a net zero
-   delta, so turning right then left proves nothing about direction. Assert the
-   wiring and the cue in a screenshot, and say plainly that confirming which way
-   the view turns needs one manual pass with a real mouse.
+   Headless caveat: `requestPointerLock` throws in headless Chromium —
+   assert the wiring and the unlocked cue in a screenshot, and say plainly that
+   the lock itself needs one manual click (do the both-axes look check there).
 7. **Ask the scene the three things the screenshot cannot answer** (below). Run it
    once, in the same browser you already have open.
 

package/templates/skills/genex-updates/SKILL.md

@@ -38,7 +38,7 @@ update, so update immediately.)
 Run exactly the command the nudge printed, from the game project root:
 
 ```bash
-npm i -D @genex-ai/cli-demo@dev   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@latest   # the genex CLI (a dev dependency)
 npm i @genex-ai/embed-sdk@latest     # identity/saves SDK (ships inside the game)
 npm i @genex-ai/multiplayer@latest   # multiplayer SDK (only if the game uses it)
 ```