@genex-ai/cli-demo 1.2.4 → 1.3.0

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