@genex-ai/cli-demo 0.92.0-dev.231 → 0.93.0-dev.234

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.92.0-dev.231",
+  "version": "0.93.0-dev.234",
   "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/skills/genex-threejs-multiplayer/SKILL.md

@@ -331,6 +331,23 @@ halves of this rule are non-negotiable:
    `minPlayers: 2, maxPlayers: 2`: the instant the second player joins). If it doesn't close on
    both, the lobby is broken — fix it; do not ship a waiting room you haven't watched close.
 
+**While `status === 'searching'` the roster is EMPTY — count the queue, not `players`.** The
+matchmaker never parks a searcher in a room as a non-player: until it can seat you, you are in the
+search line and in no room at all, so `players`/`connectedPlayers` are `[]`. A pre-match screen that
+counts `players.length` there shows `0 / 2` to a player who is sitting in it, forever. Use the queue
+count — it includes YOU, so it reads `1 / 2` when you are alone — and switch to the roster the moment
+you are seated:
+
+```ts
+const v = mm.matchmaking;
+const lobbyCount = v.status === "searching" ? Math.max(v.queue.size, 1) : v.connectedPlayers.length;
+```
+
+This bites hardest in the commonest co-op shape: with `minPlayers === maxPlayers` (e.g. `2` and `2`)
+the room can only be formed once BOTH searchers exist, so you go `searching → playing` and **never
+pass through `waiting`** — the screen the player stares at is the SEARCHING screen, and driving it
+off `players.length` pins it at `0 / target` for its entire life.
+
 Two ways to present the lobby:
 
 - **A) UI lobby (Dota-style).** While `status === 'waiting'`, render an OVERLAY from `mm.matchmaking`
@@ -552,6 +569,35 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   nearest `tier.remoteAvatarCap` remotes (`$genex-threejs-adaptive-quality`) — freeze the
   mixer and billboard or hide the rest; a room allows up to 64 players and 64 live avatars
   is a real phone memory kill on its own.
+- **Build each remote's body exactly ONCE — reserve the id BEFORE the first `await`.** You read
+  `room.players` every frame, but loading a body is async and slow (seconds). If the only guard is
+  the map you fill *after* the await, every frame in that window passes it: you spawn one body per
+  frame, each stranded where it spawned — a trail of frozen clones behind the moving player — plus
+  dozens of wasted loads. Mark the id synchronously, and drop the body if that player left mid-load:
+
+  ```ts
+  const bodies = new Map<string, Body>();
+  const loading = new Set<string>();                      // the seat reservation
+  function ensureBody(p: Player) {
+    if (bodies.has(p.id) || loading.has(p.id)) return;    // BOTH — checked before any await
+    loading.add(p.id);
+    void (async () => {
+      try {
+        const body = await loadVrmClone(p.avatarUrl || "./assets/avatar.vrm");
+        if (!room.activePlayers.has(p.id)) return;        // left while loading — never add it
+        scene.add(body.scene);
+        bodies.set(p.id, body);
+      } finally { loading.delete(p.id); }                 // always release, success or throw
+    })();
+  }
+  // Each frame: ensureBody for every remote, then drop bodies whose id is gone.
+  for (const [id, body] of bodies) {
+    if (!room.activePlayers.has(id)) { scene.remove(body.scene); bodies.delete(id); }
+  }
+  ```
+
+  The same rule covers anything else you lazily load per player or per object (nameplates, weapon
+  models, audio): a check that straddles an `await` is not a guard.
 - `room.activePlayers` — the connected-only subset of `room.players`; use its size for live quorum.
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
   - `claim(id)` — **legacy** optimistic request. It flips local ownership immediately and is corrected