@genex-ai/cli-demo 0.38.0 → 0.40.0

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,
+    };
+  }
+}

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.