@genex-ai/cli-demo 0.34.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "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

@@ -85,17 +85,71 @@ owns the queue, roles, winner-stays, forfeit, timeout, and the win condition.
 ```jsonc
 "genex": {
   "matchmaking": {
-    "preset": "arena",                 // duel | arena | teams | private
+    "preset": "arena",                 // open | duel | arena | teams | private
     "winCondition": "firstToScore",    // lastStanding | firstToScore | highScoreInTime | firstToFinish
     "config": { "scoreTarget": 20, "maxPlayers": 8 }   // numeric knobs, optional
   }
 }
 ```
 
-Presets: **duel** (1v1 winner-stays), **arena** (N-player FFA, join-anytime), **teams** (balanced
-N-v-N), **private** (invite-code lobby). Win conditions: **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.
+**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):
+**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.)
+
+### `open` — the default building block (bring your own rules)
+
+Reach for **`open`** first: a room of up to `maxPlayers` that the queue seats and (optionally)
+refills, and NOTHING else — no rounds, no scores, no win condition, no winner-stays eviction. You
+build teams/rounds/scoring/win-logic in game code on the primitives you already have (host election,
+`shared`, per-player state, the `players` list). Config knobs (all numbers):
+
+```jsonc
+"genex": { "matchmaking": { "preset": "open", "config": {
+  "maxPlayers": 10,   // seat cap (clamped 2..64)
+  "minPlayers": 2,    // quorum to flip waiting→playing (default 1)
+  "fill": 1           // 1 = keep full: grow to max + refill freed seats (default); 0 = lock for good once simultaneously full (no substitutes)
+} } } }
+```
+
+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:
+
+| 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. |
+| 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`. |
+| Winner-stays / rotation | The losing **client** leaves voluntarily — `mm.cancel()` then `matchmake()` again; the freed seat refills (`fill: 1`). There is NO forced kick (a server-only power, deliberately not exposed) — a modified client can squat its seat, so if you need *enforced* rotation use `duel`/`arena`/`teams` instead. |
+| 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. |
+
+#### Waiting room / lobby — two patterns
+
+`open` seats you into a LIVE shared room the moment you're matched (`session` goes live, players sync)
+but doesn't "start" anything — so the pre-game lobby is simply **your room before it's grown to the
+size you want**. Set `minPlayers` to your target (so `status` stays `waiting` until enough arrive) and
+let the **host** own the "go" moment by writing a start signal to `shared` (it survives host migration).
+The lobby and the game are ONE `open` room — never spin up a second room for it. Two ways to present it:
+
+- **A) UI lobby (Dota-style).** While waiting, render an OVERLAY from `mm.matchmaking` instead of the
+  game: the roster + count (`players.length` / target), each player's name, and optionally a per-player
+  "ready" toggle (store it in per-player state or a `shared` map). The host begins when all are ready
+  (or `players.length >= N`) by writing e.g. `session.shared.set('phase', { started: true, at: <ts> })`;
+  every client sees it and swaps the overlay for the game.
+- **B) Physical lobby (Roblox-style).** The waiting area IS a 3D scene in the SAME room: render a lobby
+  and let players walk their avatars around, syncing position with `me.set` on the tick exactly like
+  in-game. Show a "N / target — starting soon" sign driven by `players.length`. A "ready pad" is a nice
+  affordance: players stand on it, the host counts how many are on it (from their synced positions) and
+  writes a `shared` countdown; when it elapses everyone moves their camera/scene into the match — no
+  re-matchmaking, they're already together.
 
 **Private lobbies** (for `preset: 'private'`) don't use `matchmake()` — a host makes an invite code
 and friends join it; the lobby is persistent (rounds replay, nobody is evicted):