@genex-ai/cli-demo 0.39.0 → 0.41.0

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

@@ -0,0 +1,240 @@
+import * as THREE from "three";
+import RAPIER from "@dimforge/rapier3d-compat";
+import type { ObjectControlResult, Session } from "@genex-ai/multiplayer";
+import {
+  followBody,
+  placeBody,
+  readNetworkPose,
+  roundPose,
+  stateFromBody,
+  type NetworkPoseState,
+  type PoseSafety,
+} from "./pose.ts";
+
+export interface NetworkedVehicleUnit {
+  syncFromBody(): void;
+}
+
+export interface NetworkedVehiclePhysics {
+  registerBody(body: RAPIER.RigidBody, object: THREE.Object3D): void;
+  unregisterBody(body: RAPIER.RigidBody): void;
+  snapBodyInterpolation(body: RAPIER.RigidBody): void;
+}
+
+export interface NetworkedVehicleOptions<TPlayer extends Record<string, unknown>> {
+  id: string;
+  room: () => Session<TPlayer> | null;
+  body: RAPIER.RigidBody;
+  object: THREE.Object3D;
+  unit: NetworkedVehicleUnit;
+  physics: NetworkedVehiclePhysics;
+  safety?: PoseSafety;
+  publishHz?: number;
+  /** Called after authority is confirmed, before vehicle controls take over. */
+  onEnter?: () => void;
+  /** Place/unpark the character and return the discontinuous player state to publish. */
+  onExit?: (vehiclePose: NetworkPoseState) => TPlayer | undefined;
+  /**
+   * Called when seat authority is lost WITHOUT a clean exit() — the relay reassigned the object
+   * (steal, orphan repair, host reset). The helper has already stopped driving and switched the
+   * body back to a follower; use this to dismount the character and restore on-foot controls.
+   */
+  onSeatLost?: () => void;
+}
+
+export interface NetworkedVehicleEnterOptions {
+  /**
+   * Claim the seat even when another player currently owns (occupies) it. Off by default:
+   * idle vehicles are unowned, so an existing owner IS the current driver, and the relay's
+   * short anti-thrash hold only protects the first 300 ms of a drive — without this gate any
+   * walk-up claim would hijack an occupied vehicle and force-dismount its driver.
+   */
+  steal?: boolean;
+}
+
+/** Confirmed single-seat ownership with idle-unowned persistence semantics. */
+export class NetworkedVehicle<TPlayer extends Record<string, unknown>> {
+  readonly id: string;
+  driving = false;
+
+  private readonly room: () => Session<TPlayer> | null;
+  private readonly body: RAPIER.RigidBody;
+  private readonly object: THREE.Object3D;
+  private readonly unit: NetworkedVehicleUnit;
+  private readonly physics: NetworkedVehiclePhysics;
+  private readonly safety: PoseSafety;
+  private readonly publishEveryMs: number;
+  private readonly onEnter?: () => void;
+  private readonly onExit?: (vehiclePose: NetworkPoseState) => TPlayer | undefined;
+  private readonly onSeatLost?: () => void;
+  private registered = false;
+  private pendingSeat: Promise<ObjectControlResult> | null = null;
+  private lastPublishAt = 0;
+  private lastEpoch: number | undefined;
+
+  constructor(options: NetworkedVehicleOptions<TPlayer>) {
+    this.id = options.id;
+    this.room = options.room;
+    this.body = options.body;
+    this.object = options.object;
+    this.unit = options.unit;
+    this.physics = options.physics;
+    this.safety = options.safety ?? {};
+    this.publishEveryMs = 1000 / (options.publishHz ?? 30);
+    this.onEnter = options.onEnter;
+    this.onExit = options.onExit;
+    this.onSeatLost = options.onSeatLost;
+    this.body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true);
+  }
+
+  async enter(options: NetworkedVehicleEnterOptions = {}): Promise<ObjectControlResult> {
+    const room = this.room();
+    if (!room) return this.localFailure("disconnected");
+    if (this.pendingSeat) return this.pendingSeat;
+    const view = room.objects.get<NetworkPoseState>(this.id);
+    // Occupancy gate: idle vehicles stay unowned, so a present owner IS the current driver.
+    // The relay accepts a rival claim once its 300 ms anti-thrash hold lapses — it arbitrates
+    // ownership, not seats — so the seat semantics live here. Refuse without an explicit steal.
+    if (!options.steal && view?.owner !== undefined && !view.isMine) {
+      return {
+        requestId: "local",
+        operation: "claim",
+        id: this.id,
+        accepted: false,
+        owner: view.owner,
+        sequence: 0,
+        reason: "held",
+      };
+    }
+    const rawBeforeClaim = readNetworkPose(view?.stateRaw, this.safety);
+    const pending = room.objects.claimConfirmed(this.id);
+    this.pendingSeat = pending;
+    const result = await pending;
+    this.pendingSeat = null;
+    if (!result.accepted) return result;
+
+    const rawAfterClaim = readNetworkPose(
+      room.objects.get<NetworkPoseState>(this.id)?.stateRaw,
+      this.safety,
+    );
+    const entryPose = rawAfterClaim ?? rawBeforeClaim;
+    if (entryPose) placeBody(this.body, entryPose);
+    this.body.setBodyType(RAPIER.RigidBodyType.Dynamic, true);
+    this.body.wakeUp();
+    if (!this.registered) {
+      this.physics.registerBody(this.body, this.object);
+      this.registered = true;
+    }
+    this.unit.syncFromBody();
+    this.physics.snapBodyInterpolation(this.body);
+    this.driving = true;
+    this.onEnter?.();
+    room.objects.set(this.id, roundPose(stateFromBody(this.body, room.id)));
+    return result;
+  }
+
+  async exit(): Promise<ObjectControlResult> {
+    const room = this.room();
+    if (!room) return this.localFailure("disconnected", "release");
+    const pose = roundPose(stateFromBody(this.body));
+    room.objects.set(this.id, pose);
+    const result = await room.objects.releaseConfirmed(this.id);
+    if (!result.accepted) return result;
+
+    const playerState = this.onExit?.(pose);
+    if (playerState) room.me.snap(playerState);
+    this.driving = false;
+    if (this.registered) {
+      this.physics.unregisterBody(this.body);
+      this.registered = false;
+    }
+    this.body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true);
+    return result;
+  }
+
+  updateFollower(): void {
+    if (this.driving) {
+      const p = this.body.translation();
+      const q = this.body.rotation();
+      this.object.position.set(p.x, p.y, p.z);
+      this.object.quaternion.set(q.x, q.y, q.z, q.w);
+      return;
+    }
+    const room = this.room();
+    const view = room?.objects.get<NetworkPoseState>(this.id);
+    const pose = readNetworkPose(view?.state, this.safety);
+    if (!pose) return;
+    this.body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true);
+    const snapped = this.lastEpoch !== undefined && view !== undefined && view.epoch !== this.lastEpoch;
+    this.lastEpoch = view?.epoch;
+    if (snapped) {
+      placeBody(this.body, pose, false);
+      this.physics.snapBodyInterpolation(this.body);
+    } else {
+      followBody(this.body, pose);
+    }
+    this.object.position.set(pose.x, pose.y, pose.z);
+    this.object.quaternion.fromArray(pose.q);
+  }
+
+  publish(now = performance.now()): void {
+    const room = this.room();
+    if (!room || !this.driving || now - this.lastPublishAt < this.publishEveryMs) return;
+    if (!room.objects.get(this.id)?.isMine) {
+      // Seat authority moved without a clean exit (steal / orphan repair / host reset).
+      this.bailOut();
+      this.onSeatLost?.();
+      return;
+    }
+    this.lastPublishAt = now;
+    room.objects.set(this.id, roundPose(stateFromBody(this.body, room.id)));
+  }
+
+  /** Host-only initial seed/reset. Leaves the idle vehicle unowned afterwards. */
+  async seedIdle(state: NetworkPoseState): Promise<ObjectControlResult> {
+    const room = this.room();
+    if (!room) return this.localFailure("disconnected");
+    if (!room.isHost) return this.localFailure("not-host");
+    const result = await room.objects.claimConfirmed(this.id, { authority: "host" });
+    if (!result.accepted) return result;
+    placeBody(this.body, state, false);
+    this.unit.syncFromBody();
+    this.physics.snapBodyInterpolation(this.body);
+    room.objects.snap(this.id, roundPose(state));
+    const release = await room.objects.releaseConfirmed(this.id);
+    return release.accepted ? result : release;
+  }
+
+  /** Finalize an object the relay reassigned after its driver disconnected. */
+  async releaseOrphanIfHost(): Promise<void> {
+    const room = this.room();
+    const view = room?.objects.get<NetworkPoseState>(this.id);
+    if (!room?.isHost || this.driving || !view?.isMine) return;
+    const raw = readNetworkPose(view.stateRaw, this.safety);
+    if (raw) room.objects.snap(this.id, roundPose({ ...raw, driverId: undefined }));
+    await room.objects.releaseConfirmed(this.id);
+  }
+
+  bailOut(): void {
+    this.driving = false;
+    if (this.registered) {
+      this.physics.unregisterBody(this.body);
+      this.registered = false;
+    }
+    this.body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true);
+  }
+
+  private localFailure(
+    reason: "disconnected" | "not-host",
+    operation: "claim" | "release" | "remove" = "claim",
+  ): ObjectControlResult {
+    return {
+      requestId: "local",
+      operation,
+      id: this.id,
+      accepted: false,
+      sequence: 0,
+      reason,
+    };
+  }
+}

package/templates/controllers/network/pose.ts

@@ -0,0 +1,114 @@
+import RAPIER from "@dimforge/rapier3d-compat";
+
+export type NetworkQuaternion = [number, number, number, number];
+
+export interface NetworkPoseState extends Record<string, unknown> {
+  x: number;
+  y: number;
+  z: number;
+  q: NetworkQuaternion;
+  vx?: number;
+  vy?: number;
+  vz?: number;
+  avx?: number;
+  avy?: number;
+  avz?: number;
+  driverId?: string;
+}
+
+export interface PoseSafety {
+  /** Absolute coordinate ceiling for this game. Default 10,000. */
+  maxPosition?: number;
+  /** Linear/angular component ceiling. Default 250. */
+  maxVelocity?: number;
+  /** Quaternion squared-length tolerance around 1. Default 0.1. */
+  quaternionTolerance?: number;
+}
+
+const finite = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value);
+
+export function readNetworkPose(
+  raw: Record<string, unknown> | undefined,
+  safety: PoseSafety = {},
+): NetworkPoseState | null {
+  if (!raw || !finite(raw.x) || !finite(raw.y) || !finite(raw.z)) return null;
+  const maxPosition = safety.maxPosition ?? 10_000;
+  if (Math.max(Math.abs(raw.x), Math.abs(raw.y), Math.abs(raw.z)) > maxPosition) return null;
+  if (!Array.isArray(raw.q) || raw.q.length !== 4 || !raw.q.every(finite)) return null;
+  const q = raw.q as NetworkQuaternion;
+  const qLen2 = q[0] ** 2 + q[1] ** 2 + q[2] ** 2 + q[3] ** 2;
+  if (!Number.isFinite(qLen2) || qLen2 < 1e-8) return null;
+  const tolerance = safety.quaternionTolerance ?? 0.1;
+  if (Math.abs(qLen2 - 1) > tolerance) return null;
+
+  const maxVelocity = safety.maxVelocity ?? 250;
+  for (const key of ["vx", "vy", "vz", "avx", "avy", "avz"] as const) {
+    const value = raw[key];
+    if (value !== undefined && (!finite(value) || Math.abs(value) > maxVelocity)) return null;
+  }
+  if (
+    raw.driverId !== undefined &&
+    (typeof raw.driverId !== "string" || raw.driverId.length > 128)
+  ) return null;
+
+  const invLength = 1 / Math.sqrt(qLen2);
+  return {
+    ...raw,
+    x: raw.x,
+    y: raw.y,
+    z: raw.z,
+    q: [q[0] * invLength, q[1] * invLength, q[2] * invLength, q[3] * invLength],
+  } as NetworkPoseState;
+}
+
+export function stateFromBody(body: RAPIER.RigidBody, driverId?: string): NetworkPoseState {
+  const p = body.translation();
+  const q = body.rotation();
+  const v = body.linvel();
+  const av = body.angvel();
+  return {
+    x: p.x,
+    y: p.y,
+    z: p.z,
+    q: [q.x, q.y, q.z, q.w],
+    vx: v.x,
+    vy: v.y,
+    vz: v.z,
+    avx: av.x,
+    avy: av.y,
+    avz: av.z,
+    ...(driverId ? { driverId } : {}),
+  };
+}
+
+export function placeBody(body: RAPIER.RigidBody, state: NetworkPoseState, wake = true): void {
+  body.setTranslation({ x: state.x, y: state.y, z: state.z }, wake);
+  body.setRotation({ x: state.q[0], y: state.q[1], z: state.q[2], w: state.q[3] }, wake);
+  body.setLinvel({ x: state.vx ?? 0, y: state.vy ?? 0, z: state.vz ?? 0 }, wake);
+  body.setAngvel({ x: state.avx ?? 0, y: state.avy ?? 0, z: state.avz ?? 0 }, wake);
+}
+
+export function followBody(body: RAPIER.RigidBody, state: NetworkPoseState): void {
+  body.setNextKinematicTranslation({ x: state.x, y: state.y, z: state.z });
+  body.setNextKinematicRotation({ x: state.q[0], y: state.q[1], z: state.q[2], w: state.q[3] });
+}
+
+export function roundPose(state: NetworkPoseState, places = 3): NetworkPoseState {
+  const scale = 10 ** places;
+  const round = (value: number | undefined): number | undefined =>
+    value === undefined ? undefined : Math.round(value * scale) / scale;
+  return {
+    ...state,
+    x: round(state.x)!,
+    y: round(state.y)!,
+    z: round(state.z)!,
+    q: state.q.map((value) => round(value)!) as NetworkQuaternion,
+    vx: round(state.vx),
+    vy: round(state.vy),
+    vz: round(state.vz),
+    avx: round(state.avx),
+    avy: round(state.avy),
+    avz: round(state.avz),
+  };
+}

package/templates/controllers/shared/physics-world.ts

@@ -321,6 +321,16 @@ export class PhysicsWorld {
     this.bodyStates.delete(body.handle);
   }
 
+  /** Reset render interpolation history to the body's CURRENT pose. */
+  snapBodyInterpolation(body: RAPIER.RigidBody): void {
+    const t = body.translation();
+    const r = body.rotation();
+    this.previousState.set(body.handle, {
+      position: new THREE.Vector3(t.x, t.y, t.z),
+      rotation: new THREE.Quaternion(r.x, r.y, r.z, r.w),
+    });
+  }
+
   /**
    * Unregister the body's Object3D, drop event handlers for all of its
    * colliders, and remove the body (and its colliders) from the world.

package/templates/controllers/vehicle/vehicle-controller.ts

@@ -484,6 +484,11 @@ export class VehicleController {
     }
   }
 
+  /** Refresh cached pose/velocity/axes immediately after an external body placement. */
+  syncFromBody(): void {
+    this.updateVehicleInfo();
+  }
+
   private updateVehicleInfo(): void {
     this.vehiclePos.copy(this.body.translation());
     this.vehicleQuat.copy(this.body.rotation());

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -28,6 +28,9 @@ a character controller from scratch and do not swap in a kinematic-controller
 tutorial: this one is a real dynamic body that pushes crates, rides moving
 platforms, climbs stairs and slides on too-steep slopes out of the box.
 
+Because these files are game-owned, never run `genex controller character --force` over an edited
+fork as a migration strategy. Install a fresh copy elsewhere and port only the named changes.
+
 ## What you get
 
 | Module (under `src/controllers/`) | Exports you use | Job |
@@ -131,6 +134,11 @@ preset table with provenance, the density/spring scaling rule, and the
   out of the box**. Cap it (e.g. `Math.PI / 4`) if steep slopes should slide.
 - The capsule ships with friction `-0.5` **on purpose** (grip is synthesized by
   the controller). Do not "fix" it to a positive value.
+- CCD is enabled by default. For high-energy multiplayer arenas, set
+  `maxExternalLinearSpeed` above every intended run/jump/fall speed and provide `isPoseAllowed`.
+  `onRecovery` fires after body, root, velocity, and controller caches are restored in the same
+  frame; use it to call `physics.snapBodyInterpolation(character.body)`, reset the camera target,
+  and publish `room.me.snap(...)`. Bounds and spawn coordinates stay in game code.
 
 ## Animations + animation packs
 
@@ -209,7 +217,8 @@ body, a `CharacterController`, or any physics for it. Simulating remote
 players' physics locally guarantees divergence — every client would compute a
 different world.
 
-- Publish your own `currPos` + yaw on the fixed 10–20 Hz tick, not per frame.
+- Publish your own `currPos` + `currQuat` as a four-number quaternion on the fixed 10–20 Hz tick,
+  not per frame. Never reduce multiplayer rotation to scalar yaw.
 - To animate remotes, sync the six animation booleans (`isOnGround`,
   `isFalling`, `isMoving`, `runActive`, `jumpActive`, `crouchActive`) and feed
   them to a per-remote `CharacterAnimations` — see the animations reference.

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

@@ -34,13 +34,17 @@ example, the shared-object/ball code, rotation, and host usage. Read
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer@^0.8.0
+npm i @genex-ai/multiplayer@^0.9.0
 ```
 
-> Pin `@^0.8.0` (not a bare `npm i`): `inputs`/`onHostTick`, auto-reconnect, and the `reconnecting`
-> events this skill relies on landed in 0.8. An older resolve would throw `room.onHostTick is not a function` at runtime.
+> Pin `@^0.9.0` (not a bare `npm i`): confirmed object controls, discontinuity snaps, host-tick
+> teardown, and reconnect rebasing landed in 0.9. An older resolve does not have
+> `room.objects.claimConfirmed` or `room.me.snap`.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.8.0** (`objects`/`host` since 0.4; `matchmake()` since 0.5; presets + `score()`/`finish()` since 0.6; `createPrivate()`/`joinPrivate()` since 0.7; matchmake auto-retry + `retry()` since 0.7.1; auto-reconnect + `inputs`/`onHostTick` since 0.8; soft ownership handoff — claim-on-touch objects glide instead of teleporting — since 0.8.4).
+This skill targets `@genex-ai/multiplayer` **≥ 0.9.0** (`objects`/`host` since 0.4;
+`matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
+since 0.8; soft ownership handoff since 0.8.4; confirmed controls, snap epochs, and host-tick
+lifecycle guarantees since 0.9).
 
 ## Trust model (say it plainly in your game's copy)
 
@@ -189,16 +193,18 @@ const room = await connect<State>({
 });
 ```
 
-**Capacity:** a room holds up to **64 players** (up to 48 of them guests). Above that, the
-relay opens a **second room for the same game** — two parallel worlds, no error. If your
-game needs seated, one-world competition, use the matchmaking presets instead of one big
-`connect()` room.
+**Capacity:** 64 players is the relay's **mechanical seat cap**, not a proven high-motion physics
+envelope. Object-heavy rooms amplify fanout; measure the exact game at 8/16/32/64 before promising a
+supported count. Above the cap the relay opens another room for the same game. If the game needs one
+seated competitive world, use matchmaking rather than one large `connect()` room.
 
 ## Disconnects & reconnection (built in — render it, don't rebuild it)
 
-The SDK auto-reconnects after a network blip or brief signal loss: the relay holds your seat
-for a grace window (~30 s), and on recovery **nothing changed** — same session id, objects
-still yours, host unchanged, and in a match **a blip is not a forfeit**. Your only job is UI:
+The SDK auto-reconnects after a network blip or brief signal loss: the relay holds your seat for a
+grace window (~30 s). A short blip keeps the same session id, ownership, and host. If a disconnected
+host exceeds the shorter simulation lease, an active peer takes authority once; the old host can
+return to its seat but is demoted. Long reconnects rebase remote smoothing rather than replaying a
+whole-map catch-up streak. Your UI still reflects connection state:
 
 ```ts
 room.on("reconnecting", ({ attempt }) => showOverlay(`Reconnecting… (${attempt})`));
@@ -243,20 +249,28 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.id` — your own session id.
 - `room.me.set(state)` — publish your state, **replaces it wholesale**. Fixed **10–20 Hz tick**,
   never per frame.
+- `room.me.snap(state)` — respawn/teleport/mode edge. Publishes a discontinuity epoch so remotes
+  hard-reseed instead of interpolating from the old pose. Never use for ordinary movement.
 - `room.players` — fresh `Map` each read, **includes you** (skip `id === room.id`). Each value is
   `{ id, name, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you); `stateRaw` is
   the raw latest (hit-tests, discrete values).
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
-  - `claim(id)` — take ownership (last claim wins; call on kick/contact). Claiming is optimistic:
-    you own it locally the instant you call it, but if another player claimed the same tick the
-    server's last-claim-wins verdict can revoke you — a `set()` you sent before losing the race is
-    dropped. For contested objects, keep publishing while `isMine` stays true, not just once.
+  - `claim(id)` — **legacy** optimistic request. It flips local ownership immediately and is corrected
+    if the relay rejects it. Keep only for reversible old-game behavior.
+  - `await claimConfirmed(id, options?)` — authoritative accepted/rejected result for a kick, seat,
+    reset, or other irreversible action. Ordinary claims, including host-player contact, honor the
+    relay minimum hold. `reason: "held"` includes `retryAfterMs`; retry only while contact/intent is
+    still valid. `{ authority: "host" }` is reserved for current-host seed/reset lifecycle work.
+    A real hold bypass returns `host-authority`; a non-host request returns `not-host`. A current-owner
+    reassert is accepted as `already-owner` without extending the hold.
   - `set(id, state)` — publish it (only lands while you own it; full flat object each call).
-  - `get(id)` → `{ id, owner, isMine, state, stateRaw }` or `undefined`. `state` is auto-smoothed
+  - `get(id)` → `{ id, owner, isMine, epoch, state, stateRaw }` or `undefined`. `state` is auto-smoothed
     (or live if `isMine`); `stateRaw` is the raw latest.
-  - `release(id)` — give up ownership. `remove(id)` — destroy it (for transient bullets/pickups);
-    **owner-only** — claim it first, or let the current owner remove it (the relay rejects a
-    non-owner's destroy).
+  - `release(id)` / `remove(id)` — legacy fire-and-forget operations.
+  - `releaseConfirmed(id)` / `removeConfirmed(id)` — acknowledged, idempotent operations; use when
+    local mode/state depends on convergence. Remove stays owner-only.
+  - `snap(id, state)` — owner-only reset/teleport with an object discontinuity epoch. Ordinary motion
+    stays on `set`.
   - `ids()` — all object ids seen.
 - `room.isHost` / `room.host` — you are (or who is) the elected authority. Use to pick the single
   writer of `shared` scores/rounds and the single simulator of host-owned objects. Settles within
@@ -272,26 +286,30 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.inputs.send(payload)` / `room.inputs.on((fromId, payload) => …)` — the host-routed
   input channel for host-authoritative physics: anyone sends, ONLY the current host receives.
   See [references/host-physics.md](references/host-physics.md).
-- `room.onHostTick(hz, cb)` — run a fixed simulation tick only while you are the host
-  (auto-starts/stops across host migration). Returns a disposer.
+- `room.onHostTick(hz, cb)` — fixed simulation only while connected and host. It pauses during
+  reconnect, resumes only if still host, and stops on demotion, deliberate leave, or terminal
+  disconnect. Returns a disposer for removing the subsystem earlier.
 
 ## Your message budget (every publish is one relay message)
 
-Every `me.set`, `objects.set`, `objects.claim`, `send`, and `inputs.send` costs **one relay
-message**, and the relay caps each connection at **~120 messages/second sustained** (drops
-above that — you'll see a console warning "the relay dropped N of your messages"). The
-budget math that matters:
+Every publish costs one relay message. The relay uses a global ceiling plus reserved lanes: player
+state 30/s sustained, object control 40/s, host input 60/s, and bulk object/shared/custom traffic
+120/s (all with bursts). A bulk-object flood therefore cannot consume the avatar or control lane.
+Drops still produce the SDK warning; confirmed controls additionally resolve `rate-limited` rather
+than silently disappearing. The budget math that matters:
 
 - Your own state (`me.set`) at 15 Hz + ONE driven/owned moving object at 15 Hz = 30/s. Fine.
 - The pattern that blows the budget: **republishing IDLE objects every tick.** A host that
   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.
-- If you see the drop warning, count your sends-per-tick: streams × tick-rate must stay well
-  under 120/s with headroom for claims and events.
-- Over budget, the relay spreads the loss across ALL your streams (everything gets choppy at
-  once) rather than freezing one — so a single stuttering object is your cue to check the whole
-  budget, not just that object. The warning is the signal; don't design at the edge of the cap.
+- **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.
 
 ## The loop you must build (input → local → tick → render)
 
@@ -325,7 +343,9 @@ relay enforce it), the owner simulates it, and everyone else reads it auto-smoot
 interpolation as a player. Ownership survives the owner leaving (reassigned to the host).
 
 ```ts
-if (iKickedIt) room.objects.claim("ball");          // become the owner on contact
+const result = await room.objects.claimConfirmed("ball");
+if (result.accepted) applyKickAndFeedback();
+else if (result.reason === "held" && stillTouching) retryAfter(result.retryAfterMs);
 
 if (room.objects.get("ball")?.isMine) {
   room.objects.set("ball", stepBallPhysics());       // only the owner's writes land
@@ -334,8 +354,11 @@ const ball = room.objects.get("ball");
 if (ball) drawBall(ball.state);                       // smoothed for everyone, live for the owner
 ```
 
-**Only claim on interaction, not every frame.** Keep object state flat. Full code and the handoff
-details are in [references/realtime-patterns.md](references/realtime-patterns.md).
+**Keep contact validity alive until acceptance; do not consume one rejected rising edge forever.**
+Never claim every frame: maintain one pending request, then retry after the relay delay only while the
+contact remains valid. Keep object state flat. For Rapier pushables, install the shipped state machine
+with `genex controller networked-physics`; see
+[references/host-physics.md](references/host-physics.md).
 
 ## Host authority (scores, rounds, enemies)
 
@@ -350,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
 
@@ -454,11 +505,18 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer@^0.8.0` (auto-reconnect, `inputs`, `onHostTick` — pin `^0.8.0`, a bare install can resolve older); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.9.0` (confirmed controls, snap epochs, reconnect-safe host ticks); config wired into the build.
 - [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
 - [ ] Numbers rounded (~2 decimals) before `me.set`/`objects.set`.
 - [ ] Pushable/ownable objects (ball, box, prop) use claim-on-touch + a Rapier proxy (the soft handoff glides the handoff); only a genuine simultaneous tug-of-war (sumo) uses the host-authoritative pattern. See host-physics.md.
+- [ ] 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 —