@genex-ai/cli-demo 0.48.0-dev.86 → 0.48.0-dev.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.48.0-dev.86",
+  "version": "0.48.0-dev.89",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -99,7 +99,8 @@ owns the queue, roles, winner-stays, forfeit, timeout, and the win condition.
 **Choosing a preset — your own rules → `open`; a ready-made match loop → `duel`/`arena`/`teams`.**
 Presets: **open** (a room of N players — the server owns only seating/capacity/refill, you write
 everything else), **duel** (1v1 winner-stays), **arena** (N-player FFA, join-anytime), **teams**
-(balanced N-v-N), **private** (invite-code lobby). Win conditions (batteries-included presets only):
+(N-v-N with a server-owned match loop + eviction — only when you want that whole loop ready-made;
+for your own team game use `open` + the team section below), **private** (invite-code lobby). Win conditions (batteries-included presets only):
 **lastStanding** (last one alive), **firstToScore** (first to the score target), **highScoreInTime**
 (top score at the time cap), **firstToFinish** (first to finish). A round that hits the time cap
 undecided is a draw. (`open` has no win condition — it never ends a round for you.)
@@ -120,14 +121,17 @@ build teams/rounds/scoring/win-logic in game code on the primitives you already
 ```
 
 With `open`, `mm.matchmaking.status` only goes `searching`→`waiting`→`playing` (never `countdown`/
-`ended`), `players` is the live roster, and `scores`/`winnerId` stay empty — watch `players` and
-`status`, not `matchStart`/`matchEnded` (they never fire). Nobody is ever evicted. Build the rest:
+`ended`), `players` is the live roster, and `teams`/`myTeam`/`scores`/`winnerId` stay EMPTY forever
+— only the server presets fill them. Watch `players` and `status`, not `matchStart`/`matchEnded`
+(they never fire); your teams live in `shared` (mandatory section below), never in
+`mm.matchmaking.teams` — reading that empty map is how every player ends up "on one team".
+Nobody is ever evicted. Build the rest:
 
 | Want… | Do it in game code on top of `open` |
 | --- | --- |
 | Room formation & refill | Nothing — the server owns it via `minPlayers`/`maxPlayers`/`fill`. |
 | Duel (1v1) | `maxPlayers: 2, minPlayers: 2`, then start when `mm.matchmaking.players.length === 2`. |
-| Team assignment | The **host** splits `players` deterministically (sort ids, round-robin) and writes the map to `shared` (`session.shared.set('teams', …)`); everyone renders from it. Survives host migration because it lives in shared state. |
+| Team assignment | The MANDATORY team section right below this table — the **host** reconciles a balanced `id → team` map into `shared`; every client only reads it. Never computed per-client, never read from `mm.matchmaking.teams` (empty on `open`). |
 | Rounds / countdown | Host writes `{ phase, deadline }` into `shared`; clients render the countdown from the timestamp (no server clock — approximate fairness is fine at this trust tier). |
 | Scores | A host-owned entry in `shared` (or per-player state); you define what a point means. |
 | Win condition | Your code checks its own condition (you already compute the signals) and the host writes the result to `shared`. |
@@ -135,6 +139,62 @@ With `open`, `mm.matchmaking.status` only goes `searching`→`waiting`→`playin
 | Forfeit on disconnect | React to the `players` list shrinking (the SDK surfaces leaves after the reconnect grace). |
 | Spectators | A game-level role: keep a "dead"/observing player seated and just render them as a watcher. There is no server spectator concept — everyone in a room is a player. |
 
+#### Team games — the HOST assigns teams into `shared` (MANDATORY, balanced from the first frame)
+
+Any team game on `open` (1v1 on opposite sides, 2v2, N-v-N, red-vs-blue) assigns teams in GAME
+CODE — the server never will. Get this wrong and every player lands on one team and the match is
+unplayable. The non-negotiable shape: exactly ONE writer — the current host — keeps an
+`id → teamId` map in `shared`, and every client (host included) READS its own team from that map.
+The assignment is one reconciler that keeps sides balanced at all times: drop leavers, then seat
+every unassigned player on the SMALLEST team, walking the roster in sorted order. From an empty
+map that IS a round-robin split (1v1 → opposite teams, four players → 2+2), and a late joiner
+(`fill: 1`) always lands on the short-handed side. Run it in the host's fixed tick:
+
+```ts
+const TEAM_IDS = ["red", "blue"];  // your team set — three or more sides work unchanged
+
+function reconcileTeams() {        // HOST-only, every tick — cheap; writes only on change
+  if (!room.isHost) return;
+  const teams = { ...((room.shared.get("teams") ?? {}) as Record<string, string>) };
+  const roster = [...room.players.keys()].sort();           // deterministic order
+  let changed = false;
+  for (const id of Object.keys(teams))                      // 1. drop leavers
+    if (!roster.includes(id)) { delete teams[id]; changed = true; }
+  const size = (t: string) => Object.values(teams).filter((x) => x === t).length;
+  for (const id of roster) {                                // 2. newcomers → the smallest team
+    if (teams[id]) continue;
+    teams[id] = TEAM_IDS.reduce((a, b) => (size(b) < size(a) ? b : a));
+    changed = true;
+  }
+  if (changed) room.shared.set("teams", teams);             // no diff, no write (message budget)
+}
+
+// EVERY client, in the render loop — read your team, never compute it:
+const myTeam = (room.shared.get("teams") as Record<string, string> | undefined)?.[room.id] ?? null;
+if (myTeam === null) renderNeutral();                       // unassigned ≠ team red
+```
+
+The failure modes this shape exists to prevent — do NOT do any of these:
+
+- **Per-client assignment** (each client picks its own team from `players` order, join time, or
+  `Math.random()`): clients see different rosters at different moments, so they all self-assign
+  the same side. Team choice has exactly one writer — the host.
+- **Reading `mm.matchmaking.teams` / `myTeam`** — empty/`null` on `open` forever (server presets
+  only). A `myTeam ?? "red"` fallback puts EVERYONE on red.
+- **Defaulting the unassigned** (`teams[id] ?? "red"`): between joining and the host's next write
+  a player has NO team — render them neutral (or keep the lobby up), never fold them into a side.
+- **Assigning once at match start**: with `fill: 1` the queue keeps seating players mid-game; the
+  reconciler runs every tick precisely so joiner #5 lands on the 2-player side, not the 3-player one.
+- **Keeping the map anywhere but `shared`**: host-local state dies with the host's tab. In `shared`
+  the map survives host migration — the NEW host's reconciler continues from what's already there
+  (nobody's team changes; it only fills gaps).
+
+Balance beyond headcount (roles, kits, skill) stays a game decision — headcount balance via this
+reconciler is the floor every team game ships with. **Verify it like the lobby rule:** two browser
+windows on a two-team game MUST land on OPPOSITE teams (different colors, different spawn sides).
+Both on one team = broken — fix it before shipping. Full genre wiring (team spawns, friendly fire,
+team score) is Recipe 4 in [references/genre-recipes.md](references/genre-recipes.md).
+
 #### Waiting room / lobby — two patterns
 
 `open` seats you into a LIVE shared room the moment you're matched (`session` goes live, players sync)
@@ -559,6 +619,10 @@ host-driven saving works as long as ANY account is in the room.
 - [ ] Waiting room (if any): overlay driven by `mm.matchmaking.status` read every frame, gone the
       moment it flips to `'playing'` — and you WATCHED it close in two browser windows at
       `minPlayers` (never gated on `matchStart` or a host `shared` signal alone).
+- [ ] Team game: the HOST reconciles the balanced `id → team` map into `shared` (leavers dropped,
+      newcomers to the smallest team); every client READS its team from `shared` — never computed
+      per-client, never `mm.matchmaking.teams`, never a default for the unassigned — and you
+      WATCHED two browsers land on OPPOSITE teams.
 - [ ] Picked the matching recipe from [references/genre-recipes.md](references/genre-recipes.md).
 
 ## Troubleshooting auth

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -132,6 +132,48 @@ sees the correct wave and enemy positions.
 
 ---
 
+## Recipe 4 — Team vs team (1v1 sides, 2v2, N-v-N: team deathmatch, CTF, team football)
+
+Two (or more) sides; players on a side cooperate. The whole recipe hangs off ONE fact: **teams are
+assigned by the HOST into `shared`, balanced from the first frame** — the mandatory team section in
+SKILL.md is the assignment story, verbatim. Everything else is Recipe 1/2 mechanics filtered by team.
+
+| Thing | Channel | Authority |
+| --- | --- | --- |
+| Each player's avatar (+ `uid`, hp, `life`) | `me.set` / `players` | each player |
+| The team map (`id → red/blue`) | `shared` (`"teams"`) | the **host** — the SKILL.md reconciler, every tick |
+| Team scores | `shared` (exactly-once marker — SKILL.md host section) | `room.isHost` |
+| Attacks / defeats | `send` (Recipe 2 rules verbatim) | attacker / victim |
+| A contested ball / flag / payload | `objects` (Recipe 1 rules) | current owner |
+
+**Decisions:**
+- **Matchmaking config is only headcount:** `preset: "open"` with `maxPlayers` = team size × team
+  count, `minPlayers` = the count the game is playable at (`2` starts a 2v2 short-handed as a 1v1
+  and refills to full; `4` waits for a full lobby — pick one deliberately). The server seats
+  players; it will NEVER assign teams — that is your host code.
+- **Run the SKILL.md team reconciler in the host tick** — sorted roster + smallest-team =
+  round-robin balance, late joiners to the short side, the map in `shared` survives host
+  migration. Do not re-derive teams anywhere else, and never read `mm.matchmaking.teams` (empty
+  on `open`).
+- **Everything team-flavored READS the map:** tint/skin by `teams[id]`, spawn each player on their
+  team's side (respawn via `me.snap`), gate friendly fire in the hit-test — skip targets where
+  `teams[target] === teams[me]` before applying damage — and frame the HUD ("your team" vs
+  "enemy") from your own entry. A player not yet in the map renders neutral and takes no damage;
+  never fold them into a side.
+- **Score per TEAM, not per player:** the host turns Recipe 2's defeat events (or goals/captures)
+  into a team point with the exactly-once marker write, keyed by the team id; per-player stats can
+  ride alongside keyed by the stable `uid`.
+- **Win + rematch are host-written `shared` facts:** the host checks its own condition (first to
+  N, timer end) and writes `shared.set("result", { winner, at })`; everyone renders it. For a
+  rematch the host clears `result` and the scores — keep the team map so nobody's side flips.
+
+**Acceptance feel:** two browsers land on OPPOSITE teams instantly (the 1v1 case); a third and
+fourth joiner alternate sides (never 3v1); killing the host's tab mid-match changes nobody's team;
+the team score survives the host change; a just-joined player is neutral for a beat, then snaps to
+the short-handed side.
+
+---
+
 ## Not sure which? Start from the table
 
 Whatever the genre, ask per thing: *is it one player's own state* (`me.set`) *· a moving thing