@genex-ai/cli-demo 0.40.0 → 0.41.0

package/package.json

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

package/templates/controllers/NETWORKING.md

@@ -16,6 +16,11 @@ release, and removal must wait for the confirmed object-control result. The netw
 the relay-owned object `epoch` and direct-place Rapier followers on snaps, so a reset cannot create a
 synthetic kinematic sweep through bystanders.
 
+Game facts that must travel WITH a pushable's pose (a scorer id, a goal epoch, a power-up flag)
+go in the `extraState` option — they merge into every publish after the pose fields and come back
+untouched on `view.state`/`view.stateRaw`. Do not put them in a separate `shared` key when they
+must stay atomic with the object's motion.
+
 Vehicle seat rules the helper enforces: idle vehicles stay unowned, so a present owner IS the current
 driver — `NetworkedVehicle.enter()` refuses an owned vehicle unless the game passes
 `{ steal: true }`, and `onSeatLost` fires if the relay moves the seat without a clean `exit()`

package/templates/controllers/network/networked-pushable.ts

@@ -26,6 +26,13 @@ export interface NetworkedPushableOptions<TPlayer extends Record<string, unknown
   releaseAfterRestMs?: number;
   restSpeed?: number;
   minimumOwnMs?: number;
+  /**
+   * Game facts to ride along with every published pose (a scorer id, a goal epoch, a power-up
+   * flag). Merged into the object state AFTER the pose fields, evaluated per publish. Keep it
+   * small and flat; readers get it back on `view.state`/`view.stateRaw` untouched, and it also
+   * flows through `reset()`/`snap` payloads you build yourself.
+   */
+  extraState?: () => Record<string, unknown>;
   onInvalidState?: (raw: Record<string, unknown>) => void;
   onOwnerChange?: (owner: string | undefined) => void;
   onRecovery?: (state: NetworkPoseState) => void;
@@ -48,6 +55,7 @@ export class NetworkedPushable<TPlayer extends Record<string, unknown>> {
   private readonly releaseAfterRestMs: number;
   private readonly restSpeed: number;
   private readonly minimumOwnMs: number;
+  private readonly extraState?: () => Record<string, unknown>;
   private readonly onInvalidState?: (raw: Record<string, unknown>) => void;
   private readonly onOwnerChange?: (owner: string | undefined) => void;
   private readonly onRecovery?: (state: NetworkPoseState) => void;
@@ -76,6 +84,7 @@ export class NetworkedPushable<TPlayer extends Record<string, unknown>> {
     this.releaseAfterRestMs = options.releaseAfterRestMs ?? 2000;
     this.restSpeed = options.restSpeed ?? 0.1;
     this.minimumOwnMs = options.minimumOwnMs ?? 500;
+    this.extraState = options.extraState;
     this.onInvalidState = options.onInvalidState;
     this.onOwnerChange = options.onOwnerChange;
     this.onRecovery = options.onRecovery;
@@ -174,7 +183,8 @@ export class NetworkedPushable<TPlayer extends Record<string, unknown>> {
     const room = this.room();
     if (!room?.objects.get(this.id)?.isMine) return;
     if (now - this.lastPublishAt < this.publishEveryMs) return;
-    const state = roundPose(stateFromBody(this.body));
+    // Pose first, then game facts — extras can never clobber the transport-critical fields.
+    const state = { ...(this.extraState?.() ?? {}), ...roundPose(stateFromBody(this.body)) };
     const payload = JSON.stringify(state);
     if (payload === this.lastPayload && now - this.lastPublishAt < this.keepaliveMs) return;
     this.lastPayload = payload;

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

@@ -303,6 +303,11 @@ than silently disappearing. The budget math that matters:
   owns several parked vehicles/props must NOT `objects.set` each of them at full tick rate —
   publish an object **when it changed**, plus a low-rate keepalive (~1–2 Hz) so late joiners
   converge. Unchanged pose ⇒ no message.
+- **Per-projectile objects need a hard cap + confirmed removal.** Each live projectile at 30 Hz
+  is 30/s of bulk budget, and every spawned id counts against the room's 128-object cap forever
+  unless removed. Cap live projectiles per player (2–3), remove the OLDEST via
+  `objects.removeConfirmed` before spawning past the cap, and `removeConfirmed` on impact/expiry
+  — uncapped spawns are how a shooter silently kills its own object budget.
 - If you see the drop warning, count each lane separately and also leave headroom under the global
   ceiling. Reserved capacity protects presence and control, but it is not permission to spam bulk.
 
@@ -368,9 +373,37 @@ if (room.isHost) room.shared.set("round", nextRound);   // only the host advance
 room.on("host", (id) => {});                             // host migrated (someone left)
 ```
 
+**Award points exactly once — even across a host migration.** A newly-elected host re-observes
+whatever condition the old host may already have scored (the goal state, the defeat event — they
+are still on the wire). Never bump a score from a re-observable condition alone: carry a
+**monotonic marker in the same `shared` write**, so the score and its dedupe commit atomically:
+
+```ts
+// One shared "scores" map holds both the tallies and reserved "__" marker rows.
+function awardOnce(scorerUid: string, name: string, marker: `__${string}`, seq: number) {
+  if (!room.isHost || !Number.isSafeInteger(seq)) return false;
+  const scores = { ...((room.shared.get("scores") ?? {}) as Record<string, { name: string; points: number }>) };
+  if ((scores[marker]?.points ?? -1) >= seq) return false;      // already awarded by SOME host
+  scores[scorerUid] = { name, points: (scores[scorerUid]?.points ?? 0) + 1 };
+  scores[marker] = { name: "", points: seq };                    // the marker rides the same write
+  room.shared.set("scores", scores);
+  return true;
+}
+// goals: seq = a goalEpoch you bump on each reset · kills: seq = the victim's `life` counter
+```
+
+**Key scores by a STABLE identity, never the session id.** A session id dies on every reload —
+the points orphan into a duplicate row and the player's color changes. Publish a short `uid` in
+each player's state (from the embed identity: `const { user } = await waitForPlayer()`,
+`uid = user.id` — stable for signed-in players AND guests; see `$genex-threejs-embed-auth`), and
+key `scores`/colors/`isMe` by that uid. When an event only carries a session id, map it via
+`room.players.get(sid)?.stateRaw.uid`.
+
 For host-simulated NPCs, the host claims and drives each enemy as an `object`; when the host
 leaves, its enemies are reassigned to the new host, which reads their `stateRaw` and keeps
 simulating. See the co-op recipe in [references/genre-recipes.md](references/genre-recipes.md).
+For PvP combat (hitscan, melee, projectiles, defeat/respawn) follow the shooter recipe there —
+its damage/defeat dedupe rules are what keep kills exactly-once under lag.
 
 ### Pushable / contested physics — pick the tier
 
@@ -479,6 +512,11 @@ host-driven saving works as long as ANY account is in the room.
 - [ ] Irreversible actions wait for `claimConfirmed`; held contact retries after `retryAfterMs` while still valid.
 - [ ] Respawn/reset/vehicle-mode discontinuities use `me.snap`/`objects.snap`; ordinary motion uses `set`.
 - [ ] Idle/unchanged objects republish at ≤2 Hz keepalive, never every tick (message budget).
+- [ ] PvP combat follows the shooter recipe: attacks/defeats are `send` events with `seq`/`life`
+      dedupe keys, the victim applies its own damage, respawn publishes via `me.snap`, and
+      projectiles are hard-capped objects removed with `removeConfirmed`.
+- [ ] Host score writes are exactly-once (marker in the same `shared` write) and keyed by the
+      stable embed `uid`, never the session id.
 - [ ] Host renders objects OWNED BY OTHERS from the stream (authority follows ownership).
 - [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
       hang) and passes `auth: getColyseusAuth()!` (the relay rejects tokenless joins —

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

@@ -40,36 +40,56 @@ a contested kick settles on one owner within a snapshot; the owner leaving doesn
 
 ---
 
-## Recipe 2 — Shooter / arena (top-down or FPS .io)
+## Recipe 2 — Shooter / arena PvP (hitscan, melee, projectiles)
 
-Fast players, instant hits, a live scoreboard. No shared physics object needed for hitscan.
+Fast players, instant hits, a live scoreboard. No shared physics object needed for hitscan or melee.
+(This is the exact model the netcode-park reference runs live: fists/swords, a hitscan rifle, and
+slow physical projectiles, all against the same damage/defeat rules.)
 
 | Thing | Channel | Authority |
 | --- | --- | --- |
-| Player pos + rotation + hp | `me.set` / `players` (hp read via `stateRaw`) | each player |
-| A shot being fired | `send("shot", …)` | the shooter |
+| Player pos + rotation + hp + `life` | `me.set` / `players` (hp/life read via `stateRaw`) | each player |
+| A shot / swing being fired | `send("combat:attack", { from, seq, slot, targets, … })` | the attacker |
 | Damage applied | victim's own `me.set` (hp) | the victim |
-| Score / round | `shared` | `room.isHost` |
-| Slow physical projectiles (grenades, rockets) | `objects` (one per projectile, `remove` on expiry) | the thrower |
+| A defeat (kill credit) | `send("combat:defeat", { victim, attacker, life })` | the victim |
+| Score / round | `shared` (exactly-once marker — see SKILL.md host section) | `room.isHost` |
+| Slow physical projectiles (grenades, rockets) | `objects` — one per projectile, **hard cap + `removeConfirmed`** | the thrower |
 
 **Decisions:**
-- **The shooter judges the hit locally** ("favor the shooter"): raycast against what *you* see,
-  then `send("shot", { hit: targetId })` — and draw your own muzzle flash / tracer **right there**,
-  because `send` never echoes back to you. This is how casual browser shooters feel responsive; a
-  high-ping victim occasionally "dies behind a wall", which is inherent to server-less shooters —
-  set that expectation, don't try to fix it with more smoothing.
-- **The victim applies its own damage** on receiving the shot (`if (m.hit === room.id) me.hp -= …`)
-  — each player owns their own hp, so there's no write conflict.
-- **Hit-tests read `stateRaw`, not `state`** — you want the raw latest position, not the
-  render-delayed smoothed one. Same for reading remote hp (a discrete value; `state` would lerp it
-  to fractions).
-- **Hitscan uses `send`, not objects** — a shot is an event, not continuous state. Reserve
-  `objects` for a *slow, visible* projectile the players can dodge (a rocket): claim on spawn,
-  `objects.set` its arc, `objects.remove` on impact.
-- **Scoreboard is host-only:** the host tallies kills into `shared`; everyone renders it.
-
-**Acceptance feel:** movement is smooth for 4–8 players; hits register on what you aimed at; the
-scoreboard updates for everyone; one player on a throttled/backgrounded tab doesn't drag others.
+- **The attacker judges the hit locally** ("favor the shooter"): raycast/cone-check against what
+  *you* see, then broadcast ONE attack event naming the `targets` — and draw your own muzzle
+  flash / tracer / swing arc **right there**, because `send` never echoes back to you. A high-ping
+  victim occasionally "dies behind a wall"; that's inherent to server-less shooters — set the
+  expectation, don't chase it with more smoothing.
+- **Melee is the same event, different hit-test:** a range + cone check over `players`'
+  `stateRaw` positions (plus a line-of-sight ray), targets sorted by distance — single-target for
+  a punch, every candidate in the arc for a sword sweep.
+- **Skip dead targets up front:** ignore players whose `stateRaw.hp <= 0` in every hit-test, so a
+  corpse can't be re-hit during its respawn window.
+- **The victim applies its own damage** on receiving an attack event that names it — each player
+  owns their own hp, so there's no write conflict. **Dedupe per attack:** the attacker stamps every
+  event with a `seq`; the victim keeps a small bounded set of handled `${from}:${seq}` keys and
+  ignores repeats (events can arrive more than once around blips).
+- **Defeat is exactly-once:** at hp 0 the VICTIM broadcasts `combat:defeat { victim, attacker,
+  life }` — `life` is a counter in its player state that increments on every respawn, so everyone
+  (including the scoring host) dedupes defeats on the `${victim}:${life}` key. The HOST turns that
+  event into a point with the exactly-once marker write from the multiplayer skill's host section.
+- **Respawn is a discontinuity:** reset hp, bump `life`, place the body at the spawn point, then
+  publish with `room.me.snap(state)` — never `set`, or remotes glide the corpse across the map.
+- **Hit-tests read `stateRaw`, not `state`** — the raw latest position, not the render-delayed
+  smoothed one. Same for reading remote hp/life (discrete values; `state` would lerp them).
+- **Hitscan/melee use `send`, never objects** — a shot is an event, not continuous state. Reserve
+  `objects` for a *slow, visible* projectile players can dodge (a rocket): `claim` on spawn,
+  `objects.set` its arc at ~30 Hz, `removeConfirmed` on impact/expiry, and a **hard per-player
+  cap** that removes the oldest live projectile before spawning a new one (netcode-park ships
+  cap = 2). Uncapped per-projectile spawns walk into the room's 128-object cap AND the message
+  budget; the cap is what kept projectiles smooth for everyone in live testing.
+- **Scoreboard is host-only and keyed by the stable `uid`**, never the session id (see the
+  multiplayer skill's host section) — a reload must keep the player's points and color.
+
+**Acceptance feel:** movement is smooth for 4–8 players; hits register on what you aimed at; a kill
+scores exactly one point even if the host changes mid-fight; the scoreboard survives a reload; one
+player on a throttled/backgrounded tab doesn't drag others.
 
 ---
 

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -137,7 +137,24 @@ Rules that keep it correct:
   clients fighting over the ball. You don't need to check "am I owner" before drawing, only before
   simulating.
 - **Transient objects** (bullets, pickups): the owner awaits `room.objects.removeConfirmed(id)`
-  when they expire, so destruction is acknowledged and idempotent across reconnects.
+  when they expire, so destruction is acknowledged and idempotent across reconnects. **Always cap
+  them**: every spawned id counts against the room's 128-object limit until removed, and each live
+  projectile publishing at 30 Hz spends 30/s of your bulk budget. Keep a small per-player cap
+  (2–3, netcode-park ships 2) and remove the OLDEST before spawning past it:
+
+  ```ts
+  const live = new Map<string, Projectile>(); // insertion order = age
+  function spawnProjectile(id: string, state: Record<string, unknown>) {
+    while (live.size >= MAX_LIVE_PROJECTILES) {
+      const oldest = live.keys().next().value!;
+      live.delete(oldest);
+      void room.objects.removeConfirmed(oldest); // acknowledged — no ghost debris for late joiners
+    }
+    room.objects.claim(id);
+    room.objects.set(id, state);
+    live.set(id, makeProjectile(id));
+  }
+  ```
 
 ## Host authority (scores, rounds, world)
 

package/templates/skills/genex-threejs-vehicle-controllers/SKILL.md

@@ -75,7 +75,11 @@ games with no on-foot character.
   VELOCITY vs POSITION control modes, the PD gain mass-scaling rule, presets.
 - [references/enter-exit.md](references/enter-exit.md) — `EnterExitManager`,
   park/unpark, sensor tuning, seat animations (`Sitting_Enter` /
-  `Driving_Loop` / `Sitting_Exit`), follow-camera handoff.
+  `Driving_Loop` / `Sitting_Exit`), follow-camera handoff — **including the
+  touch interact button**: on phones there is no F key, so the enter prompt
+  must be tappable (and an Exit button shown while driving) or the shared
+  link is unenterable on mobile. Wire it whenever you wire the touch
+  joysticks (`navigator.maxTouchPoints > 0`).
 
 ## Presets at a glance
 

package/templates/skills/genex-threejs-vehicle-controllers/references/enter-exit.md

@@ -70,6 +70,20 @@ physics.onCollisionEvent((h1, h2, started) =>
 // Interact: EDGE-triggered (key transition, never a held-key poll — that
 // would enter and exit every frame). kb.onInteract is the F key, pre-guarded.
 kb.onInteract(() => mgr.requestInteract());
+
+// TOUCH DEVICES: there is no F key on a phone — make the SAME prompt tappable, or the
+// game is unenterable on the shared link. One button, the exact same code path as the key
+// (claim-before-park in multiplayer included); it doubles as the Exit button while driving.
+if (navigator.maxTouchPoints > 0) {
+  promptEl.style.pointerEvents = "auto";      // the prompt div IS the button
+  promptEl.addEventListener("pointerdown", (e) => {
+    e.preventDefault();
+    onInteractPressed();                      // whatever your F-key handler calls
+  });
+  // While driving there's no proximity prompt — show a fixed "Exit" button instead:
+  exitBtn.style.display = mgrIsDriving ? "block" : "none"; // toggle in onHandoff
+  exitBtn.addEventListener("pointerdown", () => mgr.requestInteract());
+}
 ```
 
 Loop order per fixed substep (inside `physics.onBeforeStep`): **`mgr.update(dt)`