@genex-ai/cli-demo 0.39.0 → 0.40.0

package/README.md

@@ -15,7 +15,7 @@ genex sfx "<prompt>"       # generate a sound fx  → prints an asset URL
 genex texture "<prompt>"   # generate a texture   → prints an asset URL
 genex image "<prompt>"     # generate an image    → prints an asset URL
 genex video "<prompt>"     # generate a video     → prints an asset URL
-genex controller <type>    # install a tuned character|car|drone controller → src/controllers/
+genex controller <type>    # character|car|drone|networked-physics → src/controllers/
 genex controller anims <sel…>  # download extra character animation clips (by tag or name) → public/assets/anims/
 ```
 

package/dist/index.js

@@ -2365,7 +2365,12 @@ function formatMb(bytes) {
 }
 
 // src/commands/controller.ts
-var CONTROLLER_KINDS = ["character", "car", "drone"];
+var CONTROLLER_KINDS = [
+  "character",
+  "car",
+  "drone",
+  "networked-physics"
+];
 var SHARED = [
   "shared/math.ts",
   "shared/physics-world.ts",
@@ -2443,6 +2448,23 @@ var CONTROLLER_FILE_SETS = {
       `const drone = new DroneController({ world: physics.world, body, chassis, propellers, config: dronePresets["camera-drone"].config });`,
       `physics.onBeforeStep(() => { drone.setMovement(keyboard.getDroneMovement()); drone.update(); });`
     ]
+  },
+  "networked-physics": {
+    code: [
+      ...SHARED,
+      "network/pose.ts",
+      "network/networked-pushable.ts",
+      "network/networked-vehicle.ts",
+      "NETWORKING.md",
+      NOTICE
+    ],
+    assets: [],
+    skill: "genex-threejs-multiplayer",
+    sketch: [
+      `const box = new NetworkedPushable({ id: "box:1", room: () => room, body, object: mesh });`,
+      `physics.onBeforeStep(() => box.update()); physics.onAfterStep(() => box.publish());`,
+      `contacts.onChange((active) => box.setContact(active)); // retries held claims while contact persists`
+    ]
   }
 };
 var CODE_DEST = path13.join("src", "controllers");
@@ -2457,7 +2479,7 @@ async function runController(opts) {
   if (!kind || !CONTROLLER_KINDS.includes(kind)) {
     log.error(
       `Missing or unknown controller type${kind ? ` "${kind}"` : ""}. Usage: ${c.cyan(
-        "genex controller <character|car|drone> [--force]"
+        "genex controller <character|car|drone|networked-physics> [--force]"
       )} or ${c.cyan("genex controller anims <tag|clip \u2026>")}`
     );
     process.exitCode = 1;
@@ -2508,7 +2530,7 @@ async function runController(opts) {
   log.plain(c.bold("Next steps"));
   log.plain(
     `  1. ${c.cyan(
-      kind === "character" ? "npm i @dimforge/rapier3d-compat @pixiv/three-vrm" : "npm i @dimforge/rapier3d-compat"
+      kind === "character" ? "npm i @dimforge/rapier3d-compat @pixiv/three-vrm" : kind === "networked-physics" ? "npm i @dimforge/rapier3d-compat @genex-ai/multiplayer" : "npm i @dimforge/rapier3d-compat"
     )} (three is already in the scaffold).`
   );
   log.plain(`  2. Load the ${c.cyan(set.skill)} skill for wiring, presets, and tuning.`);
@@ -2641,7 +2663,8 @@ ${c.bold("Usage")}
   genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
   genex image "<prompt>" [options]   Generate an image (PNG); prints a public asset URL.
   genex video "<prompt>" [options]   Generate a video (mp4); prints a public asset URL.
-  genex controller <type> [--force]  Install a physics controller (character|car|drone)
+  genex controller <type> [--force]  Install a physics controller
+                                     (character|car|drone|networked-physics)
                                      into src/controllers (+ assets into public/assets).
   genex controller anims <sel \u2026>     Download extra character animation clips by tag or
                                      exact name (sword, stealth, Celebration, \u2026) into
@@ -2740,6 +2763,7 @@ ${c.bold("Examples")}
   genex image "neon graffiti tag, spray-paint style" --transparent
   genex video "swirling neon plasma, seamless loop" --loop
   genex controller character
+  genex controller networked-physics
   genex explore "grass"
   genex explore
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -40,6 +40,7 @@
   },
   "devDependencies": {
     "@dimforge/rapier3d-compat": "^0.19.3",
+    "@genex-ai/multiplayer": "workspace:*",
     "@pixiv/three-vrm": "^3.5.4",
     "@types/three": "^0.185.0",
     "three": "^0.185.1",

package/templates/controllers/NETWORKING.md

@@ -0,0 +1,29 @@
+# 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.
+
+Install `genex controller networked-physics` for confirmed-authority Rapier pushable and vehicle
+state machines. They use one local fixed-step body: dynamic only for the confirmed owner and a
+kinematic proxy driven directly from the SDK-smoothed remote state otherwise. Do not add a second
+remote lerp or shadow physics simulation.
+
+Use ordinary `set` for continuous movement. Use `me.snap` / `objects.snap` only for a deliberate
+respawn, teleport, goal reset, or vehicle mode edge. Irreversible impulses, seats, reset feedback,
+release, and removal must wait for the confirmed object-control result. The networked helpers watch
+the relay-owned object `epoch` and direct-place Rapier followers on snaps, so a reset cannot create a
+synthetic kinematic sweep through bystanders.
+
+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()`
+(steal, orphan repair, host reset). When a driver disconnects, the relay parks the orphaned vehicle
+on the host — the host should call `releaseOrphanIfHost()` (each vehicle, when it observes itself as
+a non-driving owner) to snap the pose clean and return the vehicle to the idle-unowned state.
+
+The complete recipe (what to publish per controller, remote playback, and genuine simultaneous
+contested physics via the host) lives in the multiplayer skill:
+`genex-threejs-multiplayer` → `references/host-physics.md`. Load that skill before writing
+any networking code.

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

@@ -19,6 +19,14 @@ export type { ControllerUserData };
 
 const clamp = THREE.MathUtils.clamp;
 
+function finiteVec(v: { x: number; y: number; z: number }): boolean {
+  return Number.isFinite(v.x) && Number.isFinite(v.y) && Number.isFinite(v.z);
+}
+
+function finiteQuat(q: { x: number; y: number; z: number; w: number }): boolean {
+  return finiteVec(q) && Number.isFinite(q.w) && Math.hypot(q.x, q.y, q.z, q.w) > 1e-6;
+}
+
 /** Default platform mass-ratio falloff curve: flat 0 until half the character's
  *  mass, then rising to full inheritance at equal-or-heavier platforms. */
 const DEFAULT_CURVE_DATA: CurveData = {
@@ -72,6 +80,12 @@ type ResolvedMovementInput = {
 /** Crouch input interpretation — see {@link CharacterControllerOptions.crouchMode}. */
 export type CrouchMode = "toggle" | "hold";
 
+export interface CharacterRecoveryEvent {
+  reason: "non-finite" | "out-of-bounds";
+  position: { x: number; y: number; z: number };
+  linearVelocity: { x: number; y: number; z: number };
+}
+
 /**
  * Options for {@link CharacterController}. Every value has a tuned default —
  * start from a preset in `./presets.ts` and only override what feels wrong.
@@ -97,6 +111,20 @@ export interface CharacterControllerOptions {
   density?: number;
   /** Allow the body to sleep when at rest. Default `true`. */
   canSleep?: boolean;
+  /** Continuous collision detection for high-speed prop/vehicle impacts. Default `true`. */
+  ccd?: boolean;
+  /**
+   * Optional absolute body-speed ceiling in m/s. Set it comfortably above intended run/jump/fall
+   * speeds; it is a last-resort external-impulse guard, not locomotion tuning.
+   */
+  maxExternalLinearSpeed?: number;
+  /** Optional game-owned arena/bounds predicate. Non-finite poses are rejected regardless. */
+  isPoseAllowed?: (position: Readonly<{ x: number; y: number; z: number }>) => boolean;
+  /**
+   * Called after an unsafe pose was atomically restored to the constructor spawn. Pair this with
+   * `physics.snapBodyInterpolation(body)`, camera reset, and `room.me.snap(...)` when networked.
+   */
+  onRecovery?: (event: CharacterRecoveryEvent) => void;
   /** Initial gravity scale while airborne and not falling. Default `1`. */
   gravityScale?: number;
   /**
@@ -314,6 +342,11 @@ export class CharacterController {
   private readonly counterMoveImpFactor: number;
   private readonly initialGravityScale: number;
   private readonly massRatioFallOffCurve: CurveLUT;
+  private readonly maxExternalLinearSpeed: number | undefined;
+  private readonly isPoseAllowed: CharacterControllerOptions["isPoseAllowed"];
+  private readonly onRecovery: CharacterControllerOptions["onRecovery"];
+  private readonly recoveryPosition = new THREE.Vector3();
+  private readonly recoveryRotation = new THREE.Quaternion();
 
   // ── input state ──
   private readonly movementState: ResolvedMovementInput = {
@@ -531,6 +564,9 @@ export class CharacterController {
     this.applyCounterMoveImp = options.applyCounterMoveImp ?? true;
     this.counterMoveImpFactor = options.counterMoveImpFactor ?? 1;
     this.initialGravityScale = options.gravityScale ?? 1;
+    this.maxExternalLinearSpeed = options.maxExternalLinearSpeed;
+    this.isPoseAllowed = options.isPoseAllowed;
+    this.onRecovery = options.onRecovery;
 
     const curveData = options.massRatioFallOffCurveData ?? DEFAULT_CURVE_DATA;
     this.massRatioFallOffCurve = bakeCurveLUT(curveData.points, curveData.samples ?? 50);
@@ -547,7 +583,10 @@ export class CharacterController {
       .setCanSleep(options.canSleep ?? true)
       .setGravityScale(this.initialGravityScale);
     this._body = world.createRigidBody(bodyDesc);
+    this._body.enableCcd(options.ccd ?? true);
     this._body.userData = options.userData ?? {};
+    this.recoveryPosition.set(position.x, position.y, position.z);
+    this.recoveryRotation.copy(rotation);
 
     // Capsule args order matches the JSX args: (halfHeight, radius).
     const colliderDesc = RAPIER.ColliderDesc.capsule(capsuleHalfHeight, this.capsuleRadius)
@@ -838,6 +877,27 @@ export class CharacterController {
     this.lastInputDir.set(0, 0, 1).applyQuaternion(this.unparkQuat);
     this.parked = false;
     this._body.wakeUp();
+    // Camera/gameplay getters read these caches on the same exit frame, before
+    // the next controller update. Keep body, root, and cached truth aligned.
+    this.updateCharacterInfo();
+  }
+
+  /**
+   * Atomically restore the body, visual root, velocities, and controller pose cache. The caller owns
+   * camera/interpolation/network discontinuity state; use `onRecovery` to update those in this frame.
+   */
+  recover(position = this.recoveryPosition, rotation = this.recoveryRotation): void {
+    const p = finiteVec(position) ? position : this.recoveryPosition;
+    const q = finiteQuat(rotation) ? rotation : this.recoveryRotation;
+    this._body.setTranslation(p, false);
+    this._body.setRotation(q, false);
+    this._body.setLinvel(this.fixedZero, false);
+    this._body.setAngvel(this.fixedZero, false);
+    this.root.position.copy(p);
+    this.root.quaternion.copy(q);
+    this.lastInputDir.set(0, 0, 1).applyQuaternion(q);
+    this.updateCharacterInfo();
+    this._body.wakeUp();
   }
 
   /**
@@ -851,6 +911,7 @@ export class CharacterController {
     // Skip the whole controller loop when disabled or parked
     if (!this.enabled || this.parked) return;
     const characterBody = this._body;
+    if (this.recoverUnsafePose()) return;
     let isSleeping = characterBody.isSleeping();
 
     // Correct frame rate difference
@@ -1028,6 +1089,35 @@ export class CharacterController {
     this.currentAngVelOnUp.copy(this.currentAngVel).projectOnVector(this.characterYAxis);
   }
 
+  /** Recover before any impulses or publication can observe an unsafe pose. */
+  private recoverUnsafePose(): boolean {
+    const p = this._body.translation();
+    const q = this._body.rotation();
+    const v = this._body.linvel();
+    const av = this._body.angvel();
+    const finite = finiteVec(p) && finiteQuat(q) && finiteVec(v) && finiteVec(av);
+    const allowed = finite && (this.isPoseAllowed?.(p) ?? true);
+    if (!finite || !allowed) {
+      const event: CharacterRecoveryEvent = {
+        reason: finite ? "out-of-bounds" : "non-finite",
+        position: { x: p.x, y: p.y, z: p.z },
+        linearVelocity: { x: v.x, y: v.y, z: v.z },
+      };
+      this.recover();
+      this.onRecovery?.(event);
+      return true;
+    }
+    const max = this.maxExternalLinearSpeed;
+    if (max !== undefined && Number.isFinite(max) && max > 0) {
+      const speed = Math.hypot(v.x, v.y, v.z);
+      if (speed > max) {
+        const scale = max / speed;
+        this._body.setLinvel({ x: v.x * scale, y: v.y * scale, z: v.z * scale }, true);
+      }
+    }
+    return false;
+  }
+
   /**
    * Update gravity/upAxis direction and value (upstream l.499-513; the custom
    * gravity-field branch is dropped per the v1 port scope — world gravity may

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

@@ -356,6 +356,9 @@ export class DroneController {
         this.addPropeller(propellerOptions);
       }
     }
+    // Cache the supplied body's real pose immediately. Without this, getters
+    // and the chassis can remain at zero until the first awake physics step.
+    this.updateVehicleInfo();
   }
 
   // ---- per-frame ----
@@ -595,6 +598,11 @@ export class DroneController {
 
   // ---- internals ----
 
+  /** Refresh cached pose/velocity/axes immediately after an external body placement. */
+  syncFromBody(): void {
+    this.updateVehicleInfo();
+  }
+
   /** Update vehicle collider pos/vel/quat/axis from the rigid body. */
   private updateVehicleInfo(): void {
     const translation = this.bodyRef.translation();

package/templates/controllers/interact/enter-exit.ts

@@ -68,6 +68,8 @@ export interface VehicleUnitLike extends FollowTargetLike {
   readonly bodyXAxis: THREE.Vector3;
   /** World-space body Z axis (live vector). */
   readonly bodyZAxis: THREE.Vector3;
+  /** Refresh cached pose/axes after an external body placement. */
+  syncFromBody(): void;
 }
 
 /**
@@ -479,10 +481,8 @@ export class EnterExitManager {
    * Port of the upstream `computeExitTransform` — exact math and order.
    * Writes `this.exitPos` / `this.exitRot`.
    *
-   * Faithful non-guard: if the vehicle is flipped so bodyZAxis is parallel
-   * to upAxis, projectOnPlane yields a near-zero vector and normalize()
-   * produces NaN — upstream does not guard this either (realistic trigger:
-   * exiting a nose-down drone along its up axis).
+   * A flipped/nose-down vehicle can make bodyZ parallel to up. Establish a
+   * finite fallback basis before normalizing so an exit can never create NaN.
    */
   private computeExitTransform(
     vehicle: VehicleUnitLike,
@@ -491,7 +491,16 @@ export class EnterExitManager {
   ): void {
     this.exitPos.copy(vehicle.currPos).addScaledVector(exitDirection, exitLength);
     const up = vehicle.upAxis;
-    this.exitZAxis.copy(vehicle.bodyZAxis).projectOnPlane(up).normalize();
+    this.exitZAxis.copy(vehicle.bodyZAxis).projectOnPlane(up);
+    if (this.exitZAxis.lengthSq() < 1e-6) {
+      this.exitZAxis.copy(vehicle.bodyXAxis).projectOnPlane(up);
+      if (this.exitZAxis.lengthSq() < 1e-6) {
+        if (Math.abs(up.y) < 0.9) this.exitZAxis.set(0, 1, 0);
+        else this.exitZAxis.set(1, 0, 0);
+        this.exitZAxis.projectOnPlane(up);
+      }
+    }
+    this.exitZAxis.normalize();
     // Cross order matters: X = up x Z. Swapping mirrors the spawn basis.
     this.exitXAxis.crossVectors(up, this.exitZAxis);
     // makeBasis takes COLUMN vectors X, Y, Z.

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

@@ -0,0 +1,263 @@
+import * as THREE from "three";
+import RAPIER from "@dimforge/rapier3d-compat";
+import type {
+  ObjectControlOptions,
+  ObjectControlResult,
+  Session,
+} from "@genex-ai/multiplayer";
+import {
+  followBody,
+  placeBody,
+  readNetworkPose,
+  roundPose,
+  stateFromBody,
+  type NetworkPoseState,
+  type PoseSafety,
+} from "./pose.ts";
+
+export interface NetworkedPushableOptions<TPlayer extends Record<string, unknown>> {
+  id: string;
+  room: () => Session<TPlayer> | null;
+  body: RAPIER.RigidBody;
+  object: THREE.Object3D;
+  safety?: PoseSafety;
+  publishHz?: number;
+  keepaliveMs?: number;
+  releaseAfterRestMs?: number;
+  restSpeed?: number;
+  minimumOwnMs?: number;
+  onInvalidState?: (raw: Record<string, unknown>) => void;
+  onOwnerChange?: (owner: string | undefined) => void;
+  onRecovery?: (state: NetworkPoseState) => void;
+  onControl?: (result: ObjectControlResult) => void;
+}
+
+/**
+ * Reusable distributed Rapier proxy: dynamic only for the confirmed owner,
+ * kinematic follower otherwise. It consumes the SDK-smoothed state directly;
+ * it never adds a second interpolation buffer.
+ */
+export class NetworkedPushable<TPlayer extends Record<string, unknown>> {
+  private readonly id: string;
+  private readonly room: () => Session<TPlayer> | null;
+  private readonly body: RAPIER.RigidBody;
+  private readonly object: THREE.Object3D;
+  private readonly safety: PoseSafety;
+  private readonly publishEveryMs: number;
+  private readonly keepaliveMs: number;
+  private readonly releaseAfterRestMs: number;
+  private readonly restSpeed: number;
+  private readonly minimumOwnMs: number;
+  private readonly onInvalidState?: (raw: Record<string, unknown>) => void;
+  private readonly onOwnerChange?: (owner: string | undefined) => void;
+  private readonly onRecovery?: (state: NetworkPoseState) => void;
+  private readonly onControl?: (result: ObjectControlResult) => void;
+
+  private touching = false;
+  private wasMine = false;
+  private pendingClaim: Promise<ObjectControlResult> | null = null;
+  private pendingRelease: Promise<ObjectControlResult> | null = null;
+  private retryAt = 0;
+  private ownedAt = 0;
+  private restSince = 0;
+  private lastPublishAt = 0;
+  private lastPayload = "";
+  private lastEpoch: number | undefined;
+  private lastOwner: string | undefined;
+
+  constructor(options: NetworkedPushableOptions<TPlayer>) {
+    this.id = options.id;
+    this.room = options.room;
+    this.body = options.body;
+    this.object = options.object;
+    this.safety = options.safety ?? {};
+    this.publishEveryMs = 1000 / (options.publishHz ?? 20);
+    this.keepaliveMs = options.keepaliveMs ?? 500;
+    this.releaseAfterRestMs = options.releaseAfterRestMs ?? 2000;
+    this.restSpeed = options.restSpeed ?? 0.1;
+    this.minimumOwnMs = options.minimumOwnMs ?? 500;
+    this.onInvalidState = options.onInvalidState;
+    this.onOwnerChange = options.onOwnerChange;
+    this.onRecovery = options.onRecovery;
+    this.onControl = options.onControl;
+    this.body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true);
+  }
+
+  /** Keep this true for the whole contact, not just the collision rising edge. */
+  setContact(active: boolean): void {
+    this.touching = active;
+    if (!active) this.retryAt = 0;
+  }
+
+  async requestClaim(options: ObjectControlOptions = {}): Promise<ObjectControlResult> {
+    const room = this.room();
+    if (!room) return this.localFailure("disconnected");
+    if (this.pendingClaim) return this.pendingClaim;
+    const promise = room.objects.claimConfirmed(this.id, options);
+    this.pendingClaim = promise;
+    const result = await promise;
+    this.pendingClaim = null;
+    this.onControl?.(result);
+    if (!result.accepted && this.touching && (result.reason === "held" || result.reason === "rate-limited")) {
+      // Both reasons are transient and carry (or imply) a server-computed retry delay. Ignoring
+      // it for rate-limited would re-claim every round-trip and keep the control lane saturated.
+      this.retryAt = performance.now() + Math.max(16, result.retryAfterMs ?? 50);
+    } else if (!result.accepted && (result.reason === "timeout" || result.reason === "disconnected")) {
+      // Outcome unknown / transport down — back off instead of hammering; the shared owner
+      // mirror converges regardless (an actually-applied claim flips isMine on its own).
+      this.retryAt = performance.now() + 250;
+    } else {
+      this.retryAt = 0;
+    }
+    return result;
+  }
+
+  /** Confirm authority before applying an irreversible kick/weapon impulse. */
+  async withAuthority(action: (body: RAPIER.RigidBody) => void): Promise<ObjectControlResult> {
+    const result = await this.requestClaim();
+    if (!result.accepted) return result;
+    this.becomeOwner();
+    action(this.body);
+    return result;
+  }
+
+  update(): void {
+    const room = this.room();
+    if (!room) return;
+    const view = room.objects.get<NetworkPoseState>(this.id);
+    if (view?.owner !== this.lastOwner) {
+      this.lastOwner = view?.owner;
+      this.onOwnerChange?.(this.lastOwner);
+    }
+    const mine = view?.isMine === true;
+    const now = performance.now();
+
+    if (this.touching && !mine && !this.pendingClaim && now >= this.retryAt) {
+      void this.requestClaim();
+    }
+
+    if (mine && !this.wasMine) this.becomeOwner();
+    if (!mine && this.wasMine) {
+      this.body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true);
+      this.restSince = 0;
+    }
+    this.wasMine = mine;
+
+    if (mine) {
+      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);
+      this.maybeReleaseAtRest(now);
+      return;
+    }
+
+    const raw = view?.state as Record<string, unknown> | undefined;
+    const pose = readNetworkPose(raw, this.safety);
+    if (!pose) {
+      if (raw && Object.keys(raw).length > 0) this.onInvalidState?.(raw);
+      return;
+    }
+    this.object.position.set(pose.x, pose.y, pose.z);
+    this.object.quaternion.fromArray(pose.q);
+    const snapped = this.lastEpoch !== undefined && view !== undefined && view.epoch !== this.lastEpoch;
+    this.lastEpoch = view?.epoch;
+    if (snapped) {
+      placeBody(this.body, pose, false);
+      this.onRecovery?.(pose);
+    } else {
+      followBody(this.body, pose);
+    }
+  }
+
+  publish(now = performance.now()): void {
+    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));
+    const payload = JSON.stringify(state);
+    if (payload === this.lastPayload && now - this.lastPublishAt < this.keepaliveMs) return;
+    this.lastPayload = payload;
+    this.lastPublishAt = now;
+    room.objects.set(this.id, state);
+  }
+
+  async release(): Promise<ObjectControlResult> {
+    const room = this.room();
+    if (!room) return this.localFailure("disconnected", "release");
+    if (this.pendingRelease) return this.pendingRelease;
+    const pending = room.objects.releaseConfirmed(this.id);
+    this.pendingRelease = pending;
+    const result = await pending;
+    this.pendingRelease = null;
+    this.onControl?.(result);
+    return result;
+  }
+
+  async reset(state: NetworkPoseState): Promise<ObjectControlResult> {
+    const room = this.room();
+    if (!room) return this.localFailure("disconnected");
+    const result = await room.objects.claimConfirmed(this.id, { authority: "host" });
+    this.onControl?.(result);
+    if (!result.accepted) return result;
+    this.body.setBodyType(RAPIER.RigidBodyType.Dynamic, true);
+    placeBody(this.body, state);
+    this.object.position.set(state.x, state.y, state.z);
+    this.object.quaternion.fromArray(state.q);
+    room.objects.snap(this.id, roundPose(state));
+    this.wasMine = true;
+    this.ownedAt = performance.now();
+    return result;
+  }
+
+  private becomeOwner(): void {
+    const room = this.room();
+    const raw = room?.objects.get<NetworkPoseState>(this.id)?.stateRaw;
+    const pose = readNetworkPose(raw, this.safety);
+    this.body.setBodyType(RAPIER.RigidBodyType.Dynamic, true);
+    // Preserve the current kinematic proxy pose: it is exactly what the local
+    // player saw at acceptance, so replacing it with delayed raw truth creates
+    // a visible backward jump. Seed velocity from raw authority instead so
+    // momentum survives the handoff without rewinding the body.
+    if (pose) {
+      this.body.setLinvel({ x: pose.vx ?? 0, y: pose.vy ?? 0, z: pose.vz ?? 0 }, true);
+      this.body.setAngvel({ x: pose.avx ?? 0, y: pose.avy ?? 0, z: pose.avz ?? 0 }, true);
+    }
+    this.body.wakeUp();
+    this.wasMine = true;
+    this.ownedAt = performance.now();
+    this.restSince = 0;
+  }
+
+  private maybeReleaseAtRest(now: number): void {
+    if (this.touching || now - this.ownedAt < this.minimumOwnMs) {
+      this.restSince = 0;
+      return;
+    }
+    const velocity = this.body.linvel();
+    const speed = Math.hypot(velocity.x, velocity.y, velocity.z);
+    if (speed > this.restSpeed) {
+      this.restSince = 0;
+      return;
+    }
+    this.restSince ||= now;
+    if (now - this.restSince >= this.releaseAfterRestMs) {
+      this.restSince = now;
+      void this.release();
+    }
+  }
+
+  private localFailure(
+    reason: "disconnected",
+    operation: "claim" | "release" | "remove" = "claim",
+  ): ObjectControlResult {
+    return {
+      requestId: "local",
+      operation,
+      id: this.id,
+      accepted: false,
+      sequence: 0,
+      reason,
+    };
+  }
+}