@genex-ai/cli-demo 0.39.0 → 0.40.0

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -19,6 +19,17 @@ ownership to "whoever touched last" is itself the wrong model.
 
 ## Tier 1 — pushable / ownable body (claim-on-touch + a Rapier proxy)
 
+Install the product helper first:
+
+```bash
+genex controller networked-physics
+```
+
+`NetworkedPushable` owns the confirmed-claim/retry, dynamic-to-kinematic switch, visible-proxy pose
+plus raw-momentum handoff seed,
+single-smoothed follower, moved-only publishing, keepalive, release-on-rest, finite pose validation,
+and host reset snap. Prefer that helper over copying this explanatory state machine.
+
 The object is a REAL Rapier body on every client, and its body TYPE follows ownership:
 
 - **You own it → a `dynamic` body.** Your (dynamic) character capsule collides with it and Rapier's
@@ -45,14 +56,16 @@ const body = physics.createBody({
   userData: { controller: { excludeCharacterRay: true } },
 });
 ballCollider(physics.world, body, RADIUS, { friction: 0.5, restitution: 0.35, density: 0.6 });
-let wasTouching = false, wasMine = false, claimCd = 0;
+let touching = false, wasMine = false, pendingClaim: Promise<unknown> | null = null, retryAt = 0;
 const MAX_SPEED = 24;
 
 // The host seeds the canonical spawn ONCE so the object exists on `objects` for late joiners.
-function ensureInit() {
+async function ensureInit() {
   if (room.isHost && room.objects.get("ball") === undefined) {
-    room.objects.claim("ball");
-    room.objects.set("ball", { x, y, z, q: [0, 0, 0, 1], vx: 0, vy: 0, vz: 0 });
+    const result = await room.objects.claimConfirmed("ball", { authority: "host" });
+    if (!result.accepted) return;
+    room.objects.snap("ball", { x, y, z, q: [0, 0, 0, 1], vx: 0, vy: 0, vz: 0 });
+    await room.objects.releaseConfirmed("ball");
   }
 }
 
@@ -61,18 +74,17 @@ function updateBall(dt: number) {
   let v = room.objects.get<BallState>("ball");
   let mine = !!v?.isMine;
 
-  // Rising-EDGE claim: sustained contact yields NO new rising edge, so ONE owner holds it (no per-frame
-  // ownership ping-pong). A short cooldown throttles a steal-war. Use HORIZONTAL distance — the feet sit
-  // at ground level while the ball centre is at y≈RADIUS, so a 3D distance would eat into your reach.
+  // Keep contact validity alive. One rejected collision edge must not consume the attempt forever:
+  // retry after the relay hold delay while STILL touching, with at most one request in flight.
   const dx = ballMesh.position.x - feet.x, dz = ballMesh.position.z - feet.z;
-  const touching = onFoot && Math.hypot(dx, dz) < RADIUS + REACH;
-  if (claimCd > 0) claimCd -= dt;
-  if (touching && !wasTouching && !mine && claimCd <= 0) {
-    room.objects.claim("ball");            // optimistic: isMine flips true locally THIS frame
-    claimCd = 0.25;
-    v = room.objects.get<BallState>("ball"); mine = !!v?.isMine;
+  touching = onFoot && Math.hypot(dx, dz) < RADIUS + REACH;
+  if (touching && !mine && !pendingClaim && performance.now() >= retryAt) {
+    pendingClaim = room.objects.claimConfirmed("ball").then((result) => {
+      if (!result.accepted && touching && (result.reason === "held" || result.reason === "rate-limited")) {
+        retryAt = performance.now() + (result.retryAfterMs ?? 50); // both carry a server retry delay — honor it
+      } else retryAt = 0;
+    }).finally(() => { pendingClaim = null; });
   }
-  wasTouching = touching;
 
   if (mine && !wasMine) {
     // Gained ownership → dynamic. SEED velocity from the wire (NEVER zero, or a rolling ball
@@ -121,15 +133,16 @@ function publishBall() {
 
 Rules that make it correct:
 
-- **Rising-edge claim + a short cooldown** (~0.25s), never "am I touching": sustained contact must not
-  re-claim every frame. Add a minimum-hold (~0.5s) before you'll `release`, so a shove finishes under
-  your sim.
+- **Sustained-contact confirmed claim:** keep one request pending; after `held`, retry at
+  `retryAfterMs` only while contact still exists. Never spam every frame and never let one rejected
+  collision edge permanently disable the interaction.
 - **Never zero velocity on claim** — seed `linvel` from the published `vx/vy/vz`, or a rolling ball snaps
   to a dead stop on every handoff.
 - **Publish velocity, not just position** — the next owner seeds from it, so the object keeps its motion
   across the handoff.
 - **Release-on-rest** (optional): once you own an object that's been at rest + untouched a couple of
-  seconds, `room.objects.release("ball")` so ownership doesn't pile up on a lone wanderer — its last
+  seconds, `await room.objects.releaseConfirmed("ball")` so ownership doesn't pile up on a lone
+  wanderer — its last
   state persists on the wire for the next toucher, who re-claims.
 - **Distributed by construction:** each client publishes only what it currently owns, so the message
   budget spreads across players instead of funnelling every object through one host's send budget. This
@@ -168,13 +181,14 @@ room.inputs.on((fromId, payload) => {
   if (p?.obj && Array.isArray(p.push)) pending.push(p as { obj: string; push: number[] });
 });
 
-room.onHostTick(30, (dtMs) => {
+room.onHostTick(30, async (dtMs) => {
   // 1) First tick after election: adopt the objects + seed the physics world from the
   //    last published truth (stateRaw) — NEVER from zero, or the world teleports.
   for (const id of CONTESTED_IDS) {
     const view = room.objects.get(id);
-    if (!view || !view.isMine) {
-      room.objects.claim(id);
+    if (!view?.isMine) {
+      const result = await room.objects.claimConfirmed(id, { authority: "host" });
+      if (!result.accepted) continue;
       seedRapierBody(id, view?.stateRaw); // position/rotation/velocity from the wire
     }
   }
@@ -201,6 +215,10 @@ for (const id of CONTESTED_IDS) {
 
 Rules that make it correct:
 
+- `onHostTick` pauses during reconnect and stops on demotion/leave/terminal disconnect. Bound the input
+  queue, attribute input from the callback's authenticated `fromId` (never payload `from`), and discard
+  stale pre-failover inputs when a new host adopts raw state.
+
 - **Sim internals that must survive migration** (velocities, cooldowns, aggro) either live in
   the published object state or get mirrored at low rate into a dedicated object
   (`objects.set("sim", …)`) the next host reads on adoption. Positions/rotations come free

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

@@ -104,9 +104,10 @@ ownership changes (no snap), and the object survives its owner leaving (reassign
 // ball.ts
 const ball = { x: 0, y: 0.5, z: 0, vx: 0, vy: 0, vz: 0 }; // the owner's local sim
 
-// claim on contact (you kicked it) — NOT every frame
-function kick(dir: THREE.Vector3, power: number) {
-  room.objects.claim("ball");
+// Confirm on the contact edge; retry a `held` result only while contact remains.
+async function kick(dir: THREE.Vector3, power: number) {
+  const result = await room.objects.claimConfirmed("ball");
+  if (!result.accepted) return;
   ball.vx += dir.x * power; ball.vz += dir.z * power;
 }
 
@@ -129,13 +130,14 @@ function drawBall() {
 
 Rules that keep it correct:
 
-- **Claim on interaction, not continuously.** Whoever last kicked owns and simulates it.
+- **Confirm ownership before an irreversible interaction.** On `held`, respect `retryAfterMs` and
+  retry only while the original contact/action is still valid.
 - **Keep object fields flat** (`x/y/z`, a 4-number quaternion). Nested objects snap instead of glide.
 - **Only the owner's `set` lands** — the relay drops writes from non-owners, so you never get two
   clients fighting over the ball. You don't need to check "am I owner" before drawing, only before
   simulating.
-- **Transient objects** (bullets, pickups): `room.objects.remove(id)` when they expire, so they
-  don't pile up.
+- **Transient objects** (bullets, pickups): the owner awaits `room.objects.removeConfirmed(id)`
+  when they expire, so destruction is acknowledged and idempotent across reconnects.
 
 ## Host authority (scores, rounds, world)
 

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

@@ -29,6 +29,9 @@ Existing files are never overwritten (use `--force` to refresh). For the
 on-foot character that enters these vehicles, also run
 `npx genex controller character` and load `$genex-threejs-character-controller`.
 
+These files become game-owned. Do not use `--force` as an upgrade mechanism after editing them;
+install into a scratch project and port the targeted `syncFromBody`/transition changes.
+
 ## The loop contract (get this right first)
 
 Every controller exposes `update(dt?)` that must run once per **fixed physics
@@ -106,20 +109,32 @@ On enter/exit: the on-foot character **disappears into the vehicle on enter
 behavior, not a bug. Don't leave the character mesh standing next to a car it
 is supposedly driving; see [references/enter-exit.md](references/enter-exit.md).
 
-## Multiplayer: vehicle occupancy is shared state
+## Multiplayer: vehicle occupancy is confirmed object ownership
 
 If the game is multiplayer, **who is in what vehicle must be synced** — a
 remote player vanishing into an apparently empty car reads as a bug. Load
 `$genex-threejs-multiplayer` before writing any networking code, then:
 
-- Publish occupancy with the player's state (e.g. `driving: "car" | null`)
-  or as a shared key — and the occupied vehicle's pose with it.
+- Install `genex controller networked-physics` and use `NetworkedVehicle`. A seat is the vehicle
+  object's confirmed owner—not a writable `shared` key. Enter only after `claimConfirmed` accepts;
+  two simultaneous entrants therefore produce one driver and one clean loser.
+- **Occupied means owned.** Idle vehicles stay unowned, so a present owner IS the current driver —
+  `enter()` refuses an owned vehicle by default (the relay's short hold only protects the first
+  ~300 ms of a drive, so without this gate any walk-up claim would hijack a moving car and dump its
+  driver). Pass `enter({ steal: true })` only when carjacking is an intended mechanic, and wire
+  `onSeatLost` so a forcibly dismounted driver returns to on-foot controls instead of a dead seat.
+- Publish `driving: "car" | null` in the player's state for remote visuals. Use `me.snap` on entry/exit
+  mode edges, and continuous `objects.set` only from the confirmed driver.
 - Same authority rule as the character: the **local player simulates the
-  physics of whatever they occupy**; remote vehicles are interpolated
-  visuals only. Never run `VehicleController`/`DroneController` for a
-  remote player — drive a plain mesh from their synced pose.
-- An unoccupied vehicle needs one owner too: elect one client (e.g. the
-  first in the room) to simulate it and publish its pose as shared state.
+  physics of whatever they occupy**; remote vehicles are visuals only —
+  draw the SDK-smoothed `objects.get(id).state` directly on a plain mesh
+  (never re-lerp/buffer it) and never run `VehicleController`/
+  `DroneController` for a remote player.
+- Idle vehicles remain unowned at their last raw pose. The host may explicitly claim+snap+release to
+  seed/reset, but must not continuously adopt or republish parked vehicles. Persist raw idle truth.
+- On accepted entry, seed the body from `stateRaw`, enable/register/wake it, call `syncFromBody`, and
+  `snapBodyInterpolation` before controls/camera read it. On exit, publish final pose, player-snap the
+  character, unregister, then wait for confirmed release.
 
 ## Boundaries and troubleshooting
 

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

@@ -98,9 +98,9 @@ registered vehicle wins the prompt.
   reappears. Raise it if the character spawns inside a wide chassis. The
   default equals the default sensor radius so immediate re-entry stays
   possible — intended.
-- Exiting a flipped vehicle whose forward axis is parallel to up produces a
-  degenerate exit basis (faithful upstream non-guard). If vehicles in your
-  game can end up nose-down, right them before allowing exit.
+- Flipped/nose-down vehicles are supported: the manager projects the live forward axis and falls back
+  to body-X/world-Z before normalization, so the exit basis remains finite. Still choose an
+  `exitLength` that clears the actual chassis collider.
 
 ## Seat visuals: Sitting_Enter / Driving_Loop / Sitting_Exit
 
@@ -186,15 +186,24 @@ far-from-Y gravity direction will misbehave. For rigs beyond this, see
 
 ## Multiplayer
 
-Occupancy is shared state — remote players must see who is in what. With
+Occupancy uses confirmed object ownership — remote players must see who is in what. With
 `$genex-threejs-multiplayer` (load it before writing any networking code):
 
 - Put `driving: "car" | "drone" | null` in each player's synced state; on
   remote change, show/hide that player's on-foot avatar and seat their
   visual in the vehicle (the seat-visual pattern above, minus the physics).
-- The occupant simulates the vehicle and publishes its pose; everyone else
-  interpolates a plain mesh. Never run the vehicle controllers for a remote
-  player's vehicle.
-- Gate entry on a shared occupancy key so two players can't board the same
-  seat: claim it (e.g. `room.shared.set("occupant:car", room.id)`) and treat
-  a losing race as "prompt stays up".
+- The occupant simulates the vehicle and publishes its pose; everyone else draws the
+  SDK-smoothed `objects.get(vehicleId).state` directly on a plain mesh — the SDK already
+  interpolates it. Never buffer/lerp that `state` a second time, and never run the vehicle
+  controllers for a remote player's vehicle.
+- Install `genex controller networked-physics` and use `NetworkedVehicle`: gate entry on
+  `NetworkedVehicle.enter()` / `objects.claimConfirmed(vehicleId)` **before** parking the
+  character or switching the `EnterExitManager` active unit — a rejected seat must leave the
+  on-foot prompt and controls untouched. Do NOT put the claim inside `onOccupantEnter` after the
+  park: `performInteract` has no rollback, so a rejection there strands a hidden character wired
+  to a vehicle it never won. Never use `shared.set("occupant:car", ...)` as a lock—any client can
+  overwrite it. An accepted seat seeds from raw pose, calls `syncFromBody` +
+  `snapBodyInterpolation`, and becomes the only publisher.
+- Exit publishes final vehicle truth, uses `me.snap` for the player mode edge, unregisters the local
+  body, and waits for `releaseConfirmed`. Idle vehicles stay unowned; host seed/reset is the narrow
+  `{ authority: "host" }` claim+snap+release path.

package/templates/controllers/shared/NETWORKING.md

@@ -1,11 +0,0 @@
-# Networking these controllers
-
-These controllers simulate **your own player only** (self-authoritative, zero input
-latency). To show OTHER players' rigs in a multiplayer game, publish a small flat state on
-a fixed tick and play it back on a visual-only remote rig — never instantiate a controller
-or a Rapier body for a remote player.
-
-The complete recipe (what to publish per controller, remote playback, contested-contact
-physics via the host) lives in the multiplayer skill:
-`genex-threejs-multiplayer` → `references/host-physics.md`. Load that skill before writing
-any networking code.