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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.2.4-dev.363",
+  "version": "1.3.0-dev.372",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/controllers/chat/chat-overlay.ts

@@ -0,0 +1,305 @@
+// Room text chat overlay — the DOM half of the Genex chat lane. Zero dependencies,
+// zero framework, no CSS file: it builds its own elements and styles them inline, the
+// same way the touch kit does, so it drops into any game.
+//
+// The transport is `room.chat` from @genex-ai/multiplayer (the relay stamps the sender,
+// sanitizes the text, and replays the recent history on connect). This file only renders
+// it and collects input.
+//
+// THE ONE THING YOU MUST WIRE: while the player is typing, the GAME MUST NOT READ THE
+// KEYBOARD. Otherwise "w" walks, "s" reverses and space jumps while someone types "was
+// space needed?". Either check `chat.isTyping` in your input code, or use the
+// `onTypingChange` callback to pause your input system:
+//
+//   const chat = new ChatOverlay({
+//     room,
+//     onTypingChange: (typing) => { keyboard.enabled = !typing; },
+//   });
+//
+// Rendering is `textContent` ONLY, never innerHTML — every line is another player's raw
+// input. The relay strips control and bidi characters, but it does not and cannot escape
+// markup for you.
+
+/** The slice of the multiplayer session this overlay needs. Structural on purpose — the
+ *  vendored file never imports the SDK, so it cannot drift out of sync with its version. */
+export interface ChatOverlayRoom {
+  id: string;
+  chat: {
+    send(text: string): void;
+    on(cb: (message: ChatLine) => void): () => void;
+    readonly history: ChatLine[];
+  };
+}
+
+export interface ChatLine {
+  id: number;
+  from: string;
+  name: string;
+  text: string;
+  at: number;
+}
+
+export interface ChatOverlayOptions {
+  room: ChatOverlayRoom;
+  /** Called when typing starts/stops. Pause the game's keyboard input here. */
+  onTypingChange?: (typing: boolean) => void;
+  /** Lines kept on screen. Default 8. */
+  maxLines?: number;
+  /** Milliseconds a line stays visible after the chat closes; 0 keeps them forever. Default 9000. */
+  fadeAfterMs?: number;
+  /** Key that opens the composer. Default "Enter". */
+  openKey?: string;
+  /** Mount point. Default document.body. */
+  parent?: HTMLElement;
+  /** Placeholder text in the composer. */
+  placeholder?: string;
+  /** Colour used for your own name. Default a soft blue. */
+  selfColor?: string;
+}
+
+const ROOT_STYLE: Partial<CSSStyleDeclaration> = {
+  position: "fixed",
+  left: "calc(env(safe-area-inset-left, 0px) + 14px)",
+  bottom: "calc(env(safe-area-inset-bottom, 0px) + 14px)",
+  zIndex: "9000",
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "flex-start",
+  gap: "6px",
+  maxWidth: "min(46vw, 420px)",
+  fontFamily: "system-ui, sans-serif",
+  fontSize: "13px",
+  lineHeight: "1.45",
+  // The log must never eat clicks meant for the game; the composer re-enables them.
+  pointerEvents: "none",
+  userSelect: "none",
+};
+
+const LOG_STYLE: Partial<CSSStyleDeclaration> = {
+  display: "flex",
+  flexDirection: "column",
+  gap: "3px",
+  width: "100%",
+  maxHeight: "34vh",
+  overflow: "hidden",
+  transition: "opacity 260ms ease",
+};
+
+const LINE_STYLE: Partial<CSSStyleDeclaration> = {
+  margin: "0",
+  padding: "3px 8px",
+  borderRadius: "6px",
+  background: "rgba(6, 9, 18, 0.55)",
+  color: "rgba(255, 255, 255, 0.92)",
+  textShadow: "0 1px 2px rgba(0, 0, 0, 0.6)",
+  wordBreak: "break-word",
+  // A single line must not be able to push the game off screen.
+  overflowWrap: "anywhere",
+};
+
+const INPUT_STYLE: Partial<CSSStyleDeclaration> = {
+  display: "none",
+  width: "min(46vw, 420px)",
+  boxSizing: "border-box",
+  padding: "7px 10px",
+  border: "1px solid rgba(255, 255, 255, 0.28)",
+  borderRadius: "7px",
+  background: "rgba(6, 9, 18, 0.88)",
+  color: "rgba(255, 255, 255, 0.95)",
+  font: "inherit",
+  outline: "none",
+  pointerEvents: "auto",
+};
+
+const HINT_STYLE: Partial<CSSStyleDeclaration> = {
+  padding: "3px 8px",
+  borderRadius: "6px",
+  background: "rgba(6, 9, 18, 0.45)",
+  color: "rgba(255, 255, 255, 0.6)",
+  fontSize: "12px",
+  cursor: "pointer",
+  pointerEvents: "auto",
+};
+
+export class ChatOverlay {
+  readonly root: HTMLDivElement;
+  private readonly log: HTMLDivElement;
+  private readonly input: HTMLInputElement;
+  private readonly hint: HTMLDivElement;
+  private readonly opts: Required<Omit<ChatOverlayOptions, "room" | "onTypingChange" | "parent">> & {
+    room: ChatOverlayRoom;
+    onTypingChange?: (typing: boolean) => void;
+  };
+  private readonly offChat: () => void;
+  private readonly onKeyDown: (e: KeyboardEvent) => void;
+  private typing = false;
+  private fadeTimer: ReturnType<typeof setTimeout> | null = null;
+  private disposed = false;
+
+  constructor(options: ChatOverlayOptions) {
+    const parent = options.parent ?? document.body;
+    this.opts = {
+      room: options.room,
+      onTypingChange: options.onTypingChange,
+      maxLines: options.maxLines ?? 8,
+      fadeAfterMs: options.fadeAfterMs ?? 9000,
+      openKey: options.openKey ?? "Enter",
+      placeholder: options.placeholder ?? "Say something…",
+      selfColor: options.selfColor ?? "rgb(132, 176, 255)",
+    };
+
+    this.root = document.createElement("div");
+    Object.assign(this.root.style, ROOT_STYLE);
+
+    this.log = document.createElement("div");
+    Object.assign(this.log.style, LOG_STYLE);
+    this.root.appendChild(this.log);
+
+    this.hint = document.createElement("div");
+    Object.assign(this.hint.style, HINT_STYLE);
+    // Touch devices have no Enter key to discover, so they get a tappable affordance and
+    // pointer users get the shortcut spelled out.
+    this.hint.textContent =
+      navigator.maxTouchPoints > 0 ? "💬 Tap to chat" : `Press ${this.opts.openKey} to chat`;
+    this.hint.addEventListener("click", () => this.open());
+    this.root.appendChild(this.hint);
+
+    this.input = document.createElement("input");
+    this.input.type = "text";
+    // The relay clamps at 500 anyway; stopping at the browser avoids typing into a void.
+    this.input.maxLength = 500;
+    this.input.placeholder = this.opts.placeholder;
+    this.input.autocomplete = "off";
+    this.input.setAttribute("aria-label", "Chat message");
+    Object.assign(this.input.style, INPUT_STYLE);
+    this.root.appendChild(this.input);
+
+    parent.appendChild(this.root);
+
+    // Existing history first (a late joiner opens into a conversation, not a blank pane),
+    // then live lines. `chat.on` also fires for history the client hadn't seen, so this is
+    // additive rather than a race.
+    for (const line of this.opts.room.chat.history) this.append(line);
+    this.offChat = this.opts.room.chat.on((line) => this.append(line));
+
+    this.onKeyDown = (e: KeyboardEvent) => {
+      if (this.disposed) return;
+      if (!this.typing) {
+        if (e.key !== this.opts.openKey) return;
+        // Don't steal the key from another text field the game may own.
+        if (isTextEntry(e.target)) return;
+        e.preventDefault();
+        this.open();
+        return;
+      }
+      // While typing, keys belong to the composer. stopPropagation keeps game listeners
+      // bound to window/document from seeing them at all — belt to onTypingChange's braces.
+      e.stopPropagation();
+      if (e.key === "Escape") {
+        e.preventDefault();
+        this.close();
+      } else if (e.key === "Enter") {
+        e.preventDefault();
+        this.submit();
+      }
+    };
+    // Capture phase: the game's own key handlers usually bind on window/document in the
+    // bubble phase, so intercepting here is what actually keeps "w" out of the movement code.
+    window.addEventListener("keydown", this.onKeyDown, true);
+
+    this.scheduleFade();
+  }
+
+  /** True while the composer has focus — the game must ignore keyboard input meanwhile. */
+  get isTyping(): boolean {
+    return this.typing;
+  }
+
+  open(): void {
+    if (this.disposed || this.typing) return;
+    this.typing = true;
+    this.input.style.display = "block";
+    this.hint.style.display = "none";
+    this.log.style.opacity = "1";
+    if (this.fadeTimer) {
+      clearTimeout(this.fadeTimer);
+      this.fadeTimer = null;
+    }
+    this.input.focus();
+    this.opts.onTypingChange?.(true);
+  }
+
+  close(): void {
+    if (this.disposed || !this.typing) return;
+    this.typing = false;
+    this.input.value = "";
+    this.input.blur();
+    this.input.style.display = "none";
+    this.hint.style.display = "block";
+    this.scheduleFade();
+    this.opts.onTypingChange?.(false);
+  }
+
+  /** Send whatever is in the composer and close it. */
+  submit(): void {
+    const text = this.input.value;
+    // Close first: the line arrives back from the relay, and the game should be taking
+    // keyboard input again by the time it renders.
+    this.close();
+    if (text.trim()) this.opts.room.chat.send(text);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.typing) this.opts.onTypingChange?.(false);
+    window.removeEventListener("keydown", this.onKeyDown, true);
+    this.offChat();
+    if (this.fadeTimer) clearTimeout(this.fadeTimer);
+    this.root.remove();
+  }
+
+  private append(line: ChatLine): void {
+    const el = document.createElement("p");
+    Object.assign(el.style, LINE_STYLE);
+
+    const who = document.createElement("span");
+    who.style.fontWeight = "600";
+    if (line.from === this.opts.room.id) who.style.color = this.opts.selfColor;
+    // textContent, not innerHTML — both of these are other players' input.
+    who.textContent = `${line.name}: `;
+
+    const body = document.createElement("span");
+    body.textContent = line.text;
+
+    el.appendChild(who);
+    el.appendChild(body);
+    this.log.appendChild(el);
+
+    while (this.log.childElementCount > this.opts.maxLines) {
+      this.log.firstElementChild?.remove();
+    }
+    this.log.style.opacity = "1";
+    this.scheduleFade();
+  }
+
+  private scheduleFade(): void {
+    if (this.fadeTimer) {
+      clearTimeout(this.fadeTimer);
+      this.fadeTimer = null;
+    }
+    if (this.typing || this.opts.fadeAfterMs <= 0) return;
+    this.fadeTimer = setTimeout(() => {
+      this.fadeTimer = null;
+      if (!this.typing) this.log.style.opacity = "0";
+    }, this.opts.fadeAfterMs);
+  }
+}
+
+/** Is the event target already a text-entry surface the game owns? */
+function isTextEntry(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT";
+}

package/templates/controllers/voice/voice-proximity.ts

@@ -0,0 +1,247 @@
+// Proximity voice — the spatial half of the Genex voice lane.
+//
+// The SDK (`room.voice`) owns the microphone, the WebRTC mesh and the roster. It hands you
+// a `MediaStream` per participant and deliberately does NOT play it when you join with
+// `{ spatial: true }`. This file is what turns those streams into voices that come from
+// where the speaker actually is: one THREE.PositionalAudio per participant, moved to that
+// player's position every frame.
+//
+// Why proximity and not a flat room mix: in a 3D game, distance-attenuated voice is the
+// entire point. It also softens the 6-participant cap — with falloff, six audible
+// neighbours in a bigger room reads as a populated world rather than as a hard limit.
+//
+// Wiring (three lines plus your per-frame update):
+//
+//   const voice = new ProximityVoice({ room, listener, camera });
+//   await voice.join();                          // MUST be inside a click/tap handler
+//   // per frame: voice.update((id) => remoteBodies.get(id)?.position ?? null);
+//
+// `join()` asks for the microphone. Browsers gate that prompt — and audio playback — on a
+// user gesture, so calling it at boot silently fails. Put it behind a button.
+import * as THREE from "three";
+
+/** The slice of the multiplayer session this needs. Structural so the vendored file never
+ *  imports the SDK and cannot drift out of sync with its version. */
+export interface ProximityVoiceRoom {
+  id: string;
+  voice: {
+    join(options?: {
+      iceServers?: RTCIceServer[];
+      startMuted?: boolean;
+      spatial?: boolean;
+    }): Promise<void>;
+    leave(): void;
+    readonly active: boolean;
+    readonly participants: ReadonlyArray<{
+      id: string;
+      name: string;
+      stream: MediaStream | null;
+      speaking: boolean;
+      muted: boolean;
+    }>;
+    setMicEnabled(on: boolean): void;
+    readonly micEnabled: boolean;
+    readonly speaking: boolean;
+    mute(playerId: string): void;
+    unmute(playerId: string): void;
+  };
+  on(event: string, cb: (payload: never) => void): () => void;
+}
+
+export interface ProximityVoiceOptions {
+  room: ProximityVoiceRoom;
+  /** Your THREE.AudioListener — normally attached to the camera. */
+  listener: THREE.AudioListener;
+  /** Scene node the voice sources are parented to. Defaults to the listener's parent chain root. */
+  scene?: THREE.Object3D;
+  /** Distance (world units) at which a voice starts falling off. Default 6. */
+  refDistance?: number;
+  /** Beyond this, a voice is effectively inaudible. Default 45. */
+  maxDistance?: number;
+  /** Falloff steepness. Default 1.4 — a little sharper than linear reads as "nearby". */
+  rolloffFactor?: number;
+  /** TURN servers. Without one, players behind symmetric NAT never connect (~10–20%). */
+  iceServers?: RTCIceServer[];
+  /** Push-to-talk key. Default "KeyV"; pass null for open-mic. */
+  pushToTalkKey?: string | null;
+}
+
+type Voice = {
+  id: string;
+  audio: THREE.PositionalAudio;
+  holder: THREE.Object3D;
+  stream: MediaStream;
+};
+
+export class ProximityVoice {
+  private readonly room: ProximityVoiceRoom;
+  private readonly listener: THREE.AudioListener;
+  private readonly scene: THREE.Object3D;
+  private readonly opts: Required<
+    Pick<ProximityVoiceOptions, "refDistance" | "maxDistance" | "rolloffFactor">
+  >;
+  private readonly iceServers: RTCIceServer[] | undefined;
+  private readonly pttKey: string | null;
+  private readonly voices = new Map<string, Voice>();
+  private readonly offVoice: () => void;
+  private onKeyDown: ((e: KeyboardEvent) => void) | null = null;
+  private onKeyUp: ((e: KeyboardEvent) => void) | null = null;
+  private disposed = false;
+
+  constructor(options: ProximityVoiceOptions) {
+    this.room = options.room;
+    this.listener = options.listener;
+    this.scene = options.scene ?? topLevelParent(options.listener);
+    this.opts = {
+      refDistance: options.refDistance ?? 6,
+      maxDistance: options.maxDistance ?? 45,
+      rolloffFactor: options.rolloffFactor ?? 1.4,
+    };
+    this.iceServers = options.iceServers;
+    this.pttKey = options.pushToTalkKey === undefined ? "KeyV" : options.pushToTalkKey;
+    // The SDK re-emits the whole participant list on every change (join, leave, connect,
+    // speaking, mute), so reconciling from scratch is both simplest and always correct.
+    this.offVoice = this.room.on("voice", () => this.sync());
+    // Declares "this game uses voice" to the publish-time bundle scan, which is what earns
+    // the game a scoped `allow="microphone …"` on the dashboard frame. A global on purpose:
+    // it survives minification, exactly like the quality kit's __GENEX_MODEL_RUNGS__.
+    // Rolling your own voice UI instead of this class? Set it yourself, or the embedded
+    // build will be denied the microphone by Permissions Policy.
+    (window as Window & { __GENEX_VOICE__?: boolean }).__GENEX_VOICE__ = true;
+  }
+
+  /** True while this client is transmitting. */
+  get transmitting(): boolean {
+    return this.room.voice.active && this.room.voice.micEnabled;
+  }
+
+  get participants(): ProximityVoiceRoom["voice"]["participants"] {
+    return this.room.voice.participants;
+  }
+
+  /** Ask for the mic and join. MUST be called from a click/tap handler. Rejects when the
+   *  player denies permission — show that, don't swallow it. */
+  async join(): Promise<void> {
+    // spatial: true is what stops the SDK from playing the audio flat; this class plays it.
+    await this.room.voice.join({
+      spatial: true,
+      iceServers: this.iceServers,
+      startMuted: this.pttKey !== null,
+    });
+    if (this.pttKey !== null) this.bindPushToTalk(this.pttKey);
+    this.sync();
+  }
+
+  leave(): void {
+    this.room.voice.leave();
+    for (const id of [...this.voices.keys()]) this.dropVoice(id);
+  }
+
+  /** Per frame: move every voice to its speaker. Return null for a player you cannot place
+   *  (not spawned yet, culled) — their voice is parked rather than left at a stale spot. */
+  update(positionOf: (playerId: string) => THREE.Vector3 | null | undefined): void {
+    if (this.disposed) return;
+    for (const voice of this.voices.values()) {
+      const at = positionOf(voice.id);
+      // A voice left at the last known position is worse than a silent one: it sounds like
+      // someone is standing where nobody is. Mute rather than lie about where they are.
+      const placed = at != null;
+      if (placed) voice.holder.position.copy(at);
+      if (voice.audio.getVolume() !== (placed ? 1 : 0)) voice.audio.setVolume(placed ? 1 : 0);
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unbindPushToTalk();
+    this.offVoice();
+    this.leave();
+  }
+
+  // ---- internals ----
+
+  private sync(): void {
+    if (this.disposed) return;
+    const live = new Set<string>();
+    for (const p of this.room.voice.participants) {
+      if (!p.stream) continue; // still negotiating — nothing to attach yet
+      live.add(p.id);
+      const existing = this.voices.get(p.id);
+      // A reconnect can hand back a NEW stream for the same player; rebuild in that case.
+      if (existing && existing.stream !== p.stream) this.dropVoice(p.id);
+      if (!this.voices.has(p.id)) this.addVoice(p.id, p.stream);
+      const voice = this.voices.get(p.id);
+      if (voice) voice.audio.setVolume(p.muted ? 0 : voice.audio.getVolume() || 1);
+    }
+    for (const id of [...this.voices.keys()]) if (!live.has(id)) this.dropVoice(id);
+  }
+
+  private addVoice(id: string, stream: MediaStream): void {
+    const holder = new THREE.Object3D();
+    holder.name = `voice:${id}`;
+    this.scene.add(holder);
+    const audio = new THREE.PositionalAudio(this.listener);
+    audio.setRefDistance(this.opts.refDistance);
+    audio.setMaxDistance(this.opts.maxDistance);
+    audio.setRolloffFactor(this.opts.rolloffFactor);
+    audio.setDistanceModel("exponential");
+    audio.setMediaStreamSource(stream);
+    holder.add(audio);
+    this.voices.set(id, { id, audio, holder, stream });
+  }
+
+  private dropVoice(id: string): void {
+    const voice = this.voices.get(id);
+    if (!voice) return;
+    this.voices.delete(id);
+    try {
+      voice.audio.disconnect();
+    } catch {
+      /* already disconnected */
+    }
+    voice.holder.removeFromParent();
+  }
+
+  private bindPushToTalk(code: string): void {
+    this.unbindPushToTalk();
+    this.onKeyDown = (e: KeyboardEvent) => {
+      if (e.code !== code || e.repeat) return;
+      // Never grab the key while the player is typing — chat's composer owns it then.
+      if (isTextEntry(e.target)) return;
+      this.room.voice.setMicEnabled(true);
+    };
+    this.onKeyUp = (e: KeyboardEvent) => {
+      if (e.code !== code) return;
+      this.room.voice.setMicEnabled(false);
+    };
+    window.addEventListener("keydown", this.onKeyDown);
+    window.addEventListener("keyup", this.onKeyUp);
+    // A key held while the tab loses focus never fires keyup — without this the mic
+    // stays open after the player alt-tabs away, which is the worst possible bug here.
+    window.addEventListener("blur", this.onKeyUp as unknown as EventListener);
+  }
+
+  private unbindPushToTalk(): void {
+    if (this.onKeyDown) window.removeEventListener("keydown", this.onKeyDown);
+    if (this.onKeyUp) {
+      window.removeEventListener("keyup", this.onKeyUp);
+      window.removeEventListener("blur", this.onKeyUp as unknown as EventListener);
+    }
+    this.onKeyDown = null;
+    this.onKeyUp = null;
+  }
+}
+
+function topLevelParent(node: THREE.Object3D): THREE.Object3D {
+  let current: THREE.Object3D = node;
+  while (current.parent) current = current.parent;
+  return current;
+}
+
+function isTextEntry(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT";
+}

package/templates/skills/genex-game-director/references/routing-map.md

@@ -63,6 +63,8 @@ copy demo architecture.
 | 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` |
+| 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` |
 
 ## Request-sized execution

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.