@jgengine/shell 0.18.1 → 0.19.0

package/dist/camera/cameraRigs.js

@@ -5,10 +5,11 @@ import { snapPixelPerfectPosition } from "@jgengine/core/game/pixelPerfect";
 import { usePlayer } from "@jgengine/react/hooks";
 import { useGameContext } from "@jgengine/react/provider";
 import { ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
-import { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, rtsPanWorldDir, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, velocityYawTarget, } from "./rigMath.js";
+import { cinematicSample, clamp, clampBoomToHit, createChaseRigState, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, rtsPanWorldDir, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, stepChase, topDownPose, } from "./rigMath.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
 import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
+import { requestRawPointerLock } from "../input/pointerLock.js";
 export { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
 export const CAMERA_RIG_FRAME_PRIORITY = ORBIT_CAMERA_FRAME_PRIORITY;
 export const CAMERA_POST_FRAME_PRIORITY = ORBIT_CAMERA_FRAME_PRIORITY + 0.5;
@@ -306,7 +307,7 @@ export function ShoulderRig(props) {
     useEffect(() => {
         const requestLock = () => {
             if (document.pointerLockElement !== domElement)
-                void domElement.requestPointerLock?.();
+                requestRawPointerLock(domElement);
         };
         const onMove = (event) => {
             if (document.pointerLockElement !== domElement)
@@ -345,8 +346,13 @@ export function ShoulderRig(props) {
     useFrame((_, dt) => {
         const sample = readFollow(ctx, followId);
         const follow = sample?.pos ?? { x: 0, y: 0, z: 0 };
-        const adsTarget = aimingRef.current ? 1 : 0;
-        aimRef.current += (adsTarget - aimRef.current) * (1 - Math.exp(-(config?.adsTransitionSpeed ?? 10) * dt));
+        const weapon = followId === null ? null : (props.config?.weapon?.(followId) ?? null);
+        if (weapon === null) {
+            const adsTarget = aimingRef.current ? 1 : 0;
+            aimRef.current += (adsTarget - aimRef.current) * (1 - Math.exp(-(config?.adsTransitionSpeed ?? 10) * dt));
+        }
+        else
+            aimRef.current = weapon.handling.adsProgress;
         const hip = resolveShoulder(config, false);
         const ads = resolveShoulder(config, true);
         const blended = {
@@ -355,7 +361,11 @@ export function ShoulderRig(props) {
             distance: hip.distance + (ads.distance - hip.distance) * aimRef.current,
             fov: hip.fov + (ads.fov - hip.fov) * aimRef.current,
         };
-        const pose = shoulderPose(follow, props.yawRef.current, props.pitchRef.current, sideRef.current, blended);
+        const handling = weapon?.handling;
+        const yaw = props.yawRef.current - (handling === undefined ? 0 : handling.aimYaw + handling.cameraYaw);
+        // This rig's pitch is camera elevation, so a muzzle climb lowers it.
+        const pitch = props.pitchRef.current - (handling === undefined ? 0 : handling.aimPitch + handling.cameraPitch);
+        const pose = shoulderPose(follow, yaw, pitch, sideRef.current, blended);
         commit(pose, dt);
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
@@ -424,73 +434,71 @@ export function ChaseRig(props) {
     const staticResolved = useMemo(() => resolveChase(config), [config]);
     const { camera, commit, beginTransition } = useCameraCommit(props, followId);
     const shake = useCameraShake();
-    const posRef = useRef(null);
-    const lastFollowRef = useRef(null);
-    const lastYawRef = useRef(null);
-    const anchorYawRef = useRef(null);
-    const rollRef = useRef(0);
-    const view = config?.view ?? "chase";
-    useEffect(beginTransition, [view]);
+    const stateRef = useRef(createChaseRigState());
+    const viewRef = useRef(null);
     useFrame((_, dt) => {
         const tuning = ctx.camera.chaseTuning();
-        const resolved = tuning === null ? staticResolved : resolveChase({ ...config, ...tuning });
-        const sample = readFollow(ctx, followId);
-        const follow = sample?.pos ?? { x: 0, y: 0, z: 0 };
-        const yaw = sample?.yaw ?? 0;
-        const last = lastFollowRef.current ?? follow;
-        const speed = dt > 0 ? Math.hypot(follow.x - last.x, follow.z - last.z) / dt : 0;
-        lastFollowRef.current = follow;
-        const lastYaw = lastYawRef.current ?? yaw;
-        lastYawRef.current = yaw;
-        rollRef.current = bankRollStep(rollRef.current, yaw, lastYaw, dt, resolved);
-        const fov = speedToFov(speed, tuning?.fov ?? config?.fov);
+        const merged = tuning === null ? config : { ...config, ...tuning };
+        const resolved = tuning === null ? staticResolved : resolveChase(merged);
+        const view = merged?.view ?? "chase";
+        if (viewRef.current !== view) {
+            beginTransition();
+            viewRef.current = view;
+            stateRef.current.offset = null;
+        }
+        const entity = followId === null ? null : ctx.scene.entity.get(followId);
+        const follow = entity === null ? { x: 0, y: 0, z: 0 } : { x: entity.position[0], y: entity.position[1], z: entity.position[2] };
+        const yaw = entity?.rotationY ?? 0;
+        const v = entity?.velocity;
+        const published = v !== undefined && (v[0] !== 0 || v[1] !== 0 || v[2] !== 0);
+        const lookBack = resolved.lookBackAction !== null && ctx.input.isDown(resolved.lookBackAction);
+        const clampBoom = resolved.collision
+            ? (pivot, desired) => {
+                const dx = desired.x - pivot.x;
+                const dy = desired.y - pivot.y;
+                const dz = desired.z - pivot.z;
+                const length = Math.hypot(dx, dy, dz);
+                if (length <= 1e-6)
+                    return desired;
+                const hit = ctx.scene.raycast({
+                    origin: [pivot.x, pivot.y, pivot.z],
+                    direction: [dx / length, dy / length, dz / length],
+                    maxDistance: length + resolved.collisionRadius,
+                    excludeInstanceIds: followId === null ? undefined : [followId],
+                    filter: { entities: false },
+                });
+                return clampBoomToHit(pivot, desired, hit?.distance ?? null, resolved.collisionRadius, resolved.collisionMinDistance);
+            }
+            : undefined;
+        const step = stepChase(stateRef.current, {
+            follow,
+            yaw,
+            bodyPitch: entity?.rotationX ?? 0,
+            velocity: published ? { x: v[0], y: v[1], z: v[2] } : null,
+            lookBack: lookBack && view === "chase",
+            fovKick: ctx.camera.takeFovKick(),
+        }, resolved, dt, view === "chase" ? clampBoom : undefined);
+        props.yawRef.current = step.anchorYaw;
         if (view !== "chase") {
             const seat = view === "cockpit"
-                ? config?.seatOffsets?.cockpit ?? { x: 0, y: 1.2, z: 0.1 }
+                ? merged?.seatOffsets?.cockpit ?? { x: 0, y: 1.2, z: 0.1 }
                 : view === "hood"
-                    ? config?.seatOffsets?.hood ?? { x: 0, y: 1, z: 1.4 }
-                    : config?.seatOffsets?.rear ?? { x: 0, y: 1.6, z: -1.5 };
-            const lookBack = view === "rear";
-            const pose = seatPose(follow, lookBack ? yaw + Math.PI : yaw, seat, fov);
-            if (lookBack) {
-                pose.position = seatPose(follow, yaw, seat, fov).position;
-            }
+                    ? merged?.seatOffsets?.hood ?? { x: 0, y: 1, z: 1.4 }
+                    : merged?.seatOffsets?.rear ?? { x: 0, y: 1.6, z: -1.5 };
+            const seatLooksBack = view === "rear" || lookBack;
+            const pose = seatPose(follow, seatLooksBack ? yaw + Math.PI : yaw, seat, step.pose.fov);
+            if (seatLooksBack)
+                pose.position = seatPose(follow, yaw, seat, step.pose.fov).position;
             props.yawRef.current = yaw;
             commit(pose, dt);
             return;
         }
-        // Anchor yaw always eases toward its target (#1370): with drift-lag configured the target is
-        // the velocity-blended yaw at velocityYawResponse, otherwise the raw body facing at
-        // yawResponse — so a strafe-flipped facing arcs the boom around the character instead of
-        // teleporting it to the far side. yawResponse: Infinity restores the legacy rigid follow.
-        let targetYaw = yaw;
-        let response = resolved.yawResponse;
-        if (resolved.velocityYawBlend > 0) {
-            const velocity = dt > 0
-                ? { x: (follow.x - last.x) / dt, y: 0, z: (follow.z - last.z) / dt }
-                : { x: 0, y: 0, z: 0 };
-            targetYaw = velocityYawTarget(yaw, velocity, resolved);
-            response = resolved.velocityYawResponse;
+        if (resolved.shakePerSpeed > 0 && step.speed > 0) {
+            shake.shake(Math.min(resolved.shakePerSpeed * step.speed * dt, 0.1));
         }
-        const anchorYaw = Number.isFinite(response)
-            ? smoothYaw(anchorYawRef.current ?? targetYaw, targetYaw, response, dt)
-            : targetYaw;
-        anchorYawRef.current = anchorYaw;
-        // Report camera yaw back to the shell like every other player-facing rig, so
-        // on-foot movement and aim stay camera-relative instead of frozen at yaw 0.
-        props.yawRef.current = anchorYaw;
-        const led = leadFollowPoint(follow, last, dt, resolved);
-        const desired = chaseDesiredPosition(led, anchorYaw, resolved);
-        const prev = posRef.current ?? desired;
-        const smoothed = springArmStep(prev, desired, resolved.springDamping, dt);
-        posRef.current = smoothed;
-        if (resolved.shakePerSpeed > 0 && speed > 0) {
-            shake.shake(Math.min(resolved.shakePerSpeed * speed * dt, 0.1));
-        }
-        const pose = { position: smoothed, lookAt: chaseLookAt(led, anchorYaw, resolved), fov };
-        commit(pose, dt);
-        if (rollRef.current !== 0)
-            camera.rotateZ(rollRef.current);
+        commit(step.pose, dt);
+        if (step.roll !== 0)
+            camera.rotateZ(step.roll);
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }

package/dist/camera/orbitCameraMath.js

@@ -17,8 +17,8 @@ export const DEFAULT_ORBIT_CAMERA = {
     minDistance: 4,
     maxDistance: 28,
     targetHeight: 1.2,
-    initialDistance: 9,
-    initialHeight: 5.5,
+    initialDistance: 7,
+    initialHeight: 2.4,
     followLock: true,
     followEnabled: true,
     rotateSpeed: 0.22,

package/dist/camera/rigMath.d.ts

@@ -136,6 +136,23 @@ export interface ResolvedChase {
     velocityYawResponse: number;
     /** Exponential smoothing rate the anchor yaw follows the body's facing with (#1370). `Infinity` restores the legacy rigid follow. */
     yawResponse: number;
+    fovBase: number;
+    fovMax: number;
+    fovSpeedForMax: number;
+    /** Exponential FOV smoothing rate; `Infinity` applies the curve unsmoothed. */
+    fovResponse: number;
+    distanceExtra: number;
+    distanceSpeedForMax: number;
+    /** Fraction of body pitch the boom follows; 0 keeps a level boom. */
+    pitchBlend: number;
+    pitchMax: number;
+    pitchResponse: number;
+    fovKickDecay: number;
+    fovKickMax: number;
+    lookBackAction: string | null;
+    collision: boolean;
+    collisionRadius: number;
+    collisionMinDistance: number;
 }
 /** @internal */
 export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
@@ -143,6 +160,10 @@ export declare function resolveChase(config: ChaseCameraConfig | undefined): Res
  * @internal
  */
 export declare function leadFollowPoint(follow: Vec3, previous: Vec3, dt: number, resolved: ResolvedChase): Vec3;
+/** Velocity-lead the follow point along a known planar velocity, clamped to `leadMax`.
+ * @internal
+ */
+export declare function leadFromVelocity(follow: Vec3, velocity: Vec3, resolved: ResolvedChase): Vec3;
 /** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped.
  * @internal
  */
@@ -159,14 +180,71 @@ export declare function resolveObserver(config: ObserverCameraConfig | undefined
  * @internal
  */
 export declare function observerPose(subject: Vec3, angle: number, resolved: ResolvedObserver, fov: number): CameraPose;
-/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). `pitch` (nose-up positive) tilts the boom around the vehicle's right axis.
+ * @internal
+ */
+export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase, pitch?: number, distance?: number): Vec3;
+/** Camera offset from the follow point for a boom `distance` back and `height` up, tilted by `pitch` (nose-up positive).
+ * @internal
+ */
+export declare function chaseBoomOffset(yaw: number, pitch: number, distance: number, height: number): Vec3;
+/** Look point ahead of / above a chased vehicle, tilted by `pitch` like the boom.
  * @internal
  */
-export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
-/** Look point ahead of / above a chased vehicle.
+export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase, pitch?: number): Vec3;
+/** Mutable per-rig chase state; {@link stepChase} advances it in place. */
+export interface ChaseRigState {
+    /** Smoothed camera offset from the led follow point; springing the offset, not the world position, keeps the boom length at any constant speed. */
+    offset: Vec3 | null;
+    anchorYaw: number | null;
+    lastYaw: number | null;
+    lastFollow: Vec3 | null;
+    roll: number;
+    pitch: number;
+    fov: number | null;
+    kick: number;
+    lookingBack: boolean;
+}
+/** @internal */
+export declare function createChaseRigState(): ChaseRigState;
+/** What the chase rig reads from its target each frame. */
+export interface ChaseSample {
+    follow: Vec3;
+    /** Body heading (radians). */
+    yaw: number;
+    /** Body `rotationX` (three.js convention: positive = nose down). */
+    bodyPitch: number;
+    /** Sim velocity when the entity publishes one; `null` falls back to the frame-to-frame position delta. */
+    velocity: Vec3 | null;
+    lookBack: boolean;
+    /** FOV impulse (degrees) queued since the last frame. */
+    fovKick: number;
+}
+/** One frame of chase output from {@link stepChase}. */
+export interface ChaseStepResult {
+    pose: CameraPose;
+    /** Camera roll to apply after the pose, radians. */
+    roll: number;
+    /** Forward chase yaw to report to the shell; unaffected by look-back. */
+    anchorYaw: number;
+    /** Planar speed used for FOV, distance and shake. */
+    speed: number;
+}
+/** Pulls a desired camera position in toward `pivot` when something blocks the boom. */
+export type ChaseBoomClamp = (pivot: Vec3, desired: Vec3) => Vec3;
+/**
+ * One frame of the chase rig: speed from sim velocity, smoothed FOV plus decaying kicks, drift-lag
+ * anchor yaw, pitch follow, distance by speed, look-back, and a boom spring that eases the offset
+ * from the target rather than its world position, so the camera holds its distance at speed.
+ * @internal
+ */
+export declare function stepChase(state: ChaseRigState, sample: ChaseSample, resolved: ResolvedChase, dt: number, clampBoom?: ChaseBoomClamp): ChaseStepResult;
+/**
+ * Where a blocked boom should put the camera: `hitDistance` along the pivot→desired ray, less
+ * `radius`, but never nearer the pivot than `minDistance`. `null` hit returns `desired` unchanged.
  * @internal
  */
-export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
+export declare function clampBoomToHit(pivot: Vec3, desired: Vec3, hitDistance: number | null, radius: number, minDistance: number): Vec3;
 /**
  * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
  * smoothing. When the target slides, its planar `velocity` diverges from its

package/dist/camera/rigMath.js

@@ -253,6 +253,9 @@ export function lockOnPose(player, target, config, fov) {
 const DEFAULT_CHASE_YAW_RESPONSE = 5;
 /** @internal */
 export function resolveChase(config) {
+    const fovSpeedForMax = config?.fov?.speedForMax ?? 24;
+    const collision = config?.collision ?? true;
+    const collisionBlock = typeof collision === "object" ? collision : undefined;
     return {
         distance: config?.distance ?? 6,
         height: config?.height ?? 2.6,
@@ -268,16 +271,39 @@ export function resolveChase(config) {
         velocityYawMinSpeed: config?.velocityYaw?.minSpeed ?? 4,
         velocityYawResponse: config?.velocityYaw?.response ?? 6,
         yawResponse: config?.yawResponse ?? DEFAULT_CHASE_YAW_RESPONSE,
+        fovBase: config?.fov?.base ?? 55,
+        fovMax: config?.fov?.max ?? 78,
+        fovSpeedForMax,
+        fovResponse: config?.fov?.response ?? 6,
+        distanceExtra: config?.distanceBySpeed?.extra ?? 0,
+        distanceSpeedForMax: config?.distanceBySpeed?.speedForMax ?? fovSpeedForMax,
+        pitchBlend: config?.pitchFollow === undefined ? 0 : config.pitchFollow.blend ?? 1,
+        pitchMax: config?.pitchFollow?.max ?? 0.6,
+        pitchResponse: config?.pitchFollow?.response ?? 5,
+        fovKickDecay: config?.fovKick?.decay ?? 7,
+        fovKickMax: config?.fovKick?.max ?? 20,
+        lookBackAction: config?.lookBackAction ?? null,
+        collision: collision !== false,
+        collisionRadius: collisionBlock?.radius ?? 0.3,
+        collisionMinDistance: collisionBlock?.minDistance ?? 0.8,
     };
 }
 /** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`.
  * @internal
  */
 export function leadFollowPoint(follow, previous, dt, resolved) {
-    if (resolved.leadTime <= 0 || dt <= 0)
+    if (dt <= 0)
         return follow;
-    let leadX = ((follow.x - previous.x) / dt) * resolved.leadTime;
-    let leadZ = ((follow.z - previous.z) / dt) * resolved.leadTime;
+    return leadFromVelocity(follow, { x: (follow.x - previous.x) / dt, y: 0, z: (follow.z - previous.z) / dt }, resolved);
+}
+/** Velocity-lead the follow point along a known planar velocity, clamped to `leadMax`.
+ * @internal
+ */
+export function leadFromVelocity(follow, velocity, resolved) {
+    if (resolved.leadTime <= 0)
+        return follow;
+    let leadX = velocity.x * resolved.leadTime;
+    let leadZ = velocity.z * resolved.leadTime;
     const magnitude = Math.hypot(leadX, leadZ);
     if (magnitude > resolved.leadMax) {
         leadX *= resolved.leadMax / magnitude;
@@ -327,28 +353,120 @@ export function observerPose(subject, angle, resolved, fov) {
         fov,
     };
 }
-/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). `pitch` (nose-up positive) tilts the boom around the vehicle's right axis.
  * @internal
  */
-export function chaseDesiredPosition(follow, yaw, resolved) {
-    const back = forwardVector(yaw);
+export function chaseDesiredPosition(follow, yaw, resolved, pitch = 0, distance = resolved.distance) {
+    const offset = chaseBoomOffset(yaw, pitch, distance, resolved.height);
+    return { x: follow.x + offset.x, y: follow.y + offset.y, z: follow.z + offset.z };
+}
+/** Camera offset from the follow point for a boom `distance` back and `height` up, tilted by `pitch` (nose-up positive).
+ * @internal
+ */
+export function chaseBoomOffset(yaw, pitch, distance, height) {
+    const forward = forwardVector(yaw);
+    const cos = Math.cos(pitch);
+    const sin = Math.sin(pitch);
+    const along = -distance * cos - height * sin;
+    return { x: forward.x * along, y: -distance * sin + height * cos, z: forward.z * along };
+}
+/** Look point ahead of / above a chased vehicle, tilted by `pitch` like the boom.
+ * @internal
+ */
+export function chaseLookAt(follow, yaw, resolved, pitch = 0) {
+    const forward = forwardVector(yaw);
+    const cos = Math.cos(pitch);
+    const sin = Math.sin(pitch);
+    const along = 2 * cos - resolved.lookHeight * sin;
     return {
-        x: follow.x - back.x * resolved.distance,
-        y: follow.y + resolved.height,
-        z: follow.z - back.z * resolved.distance,
+        x: follow.x + forward.x * along,
+        y: follow.y + 2 * sin + resolved.lookHeight * cos,
+        z: follow.z + forward.z * along,
     };
 }
-/** Look point ahead of / above a chased vehicle.
+/** @internal */
+export function createChaseRigState() {
+    return { offset: null, anchorYaw: null, lastYaw: null, lastFollow: null, roll: 0, pitch: 0, fov: null, kick: 0, lookingBack: false };
+}
+/**
+ * One frame of the chase rig: speed from sim velocity, smoothed FOV plus decaying kicks, drift-lag
+ * anchor yaw, pitch follow, distance by speed, look-back, and a boom spring that eases the offset
+ * from the target rather than its world position, so the camera holds its distance at speed.
  * @internal
  */
-export function chaseLookAt(follow, yaw, resolved) {
-    const forward = forwardVector(yaw);
+export function stepChase(state, sample, resolved, dt, clampBoom) {
+    const { follow, yaw } = sample;
+    const last = state.lastFollow ?? follow;
+    const velocity = sample.velocity ?? (dt > 0 ? { x: (follow.x - last.x) / dt, y: 0, z: (follow.z - last.z) / dt } : { x: 0, y: 0, z: 0 });
+    state.lastFollow = follow;
+    const speed = Math.hypot(velocity.x, velocity.z);
+    const lastYaw = state.lastYaw ?? yaw;
+    state.lastYaw = yaw;
+    state.roll = bankRollStep(state.roll, yaw, lastYaw, dt, resolved);
+    const targetFov = speedToFov(speed, { base: resolved.fovBase, max: resolved.fovMax, speedForMax: resolved.fovSpeedForMax });
+    state.fov =
+        state.fov === null || !Number.isFinite(resolved.fovResponse)
+            ? targetFov
+            : state.fov + (targetFov - state.fov) * smoothBlend(dt, resolved.fovResponse);
+    state.kick = clamp(state.kick * Math.exp(-resolved.fovKickDecay * dt) + sample.fovKick, -resolved.fovKickMax, resolved.fovKickMax);
+    let targetYaw = yaw;
+    let response = resolved.yawResponse;
+    if (resolved.velocityYawBlend > 0) {
+        targetYaw = velocityYawTarget(yaw, velocity, resolved);
+        response = resolved.velocityYawResponse;
+    }
+    const anchorYaw = Number.isFinite(response)
+        ? smoothYaw(state.anchorYaw ?? targetYaw, targetYaw, response, dt)
+        : targetYaw;
+    state.anchorYaw = anchorYaw;
+    const pitchTarget = clamp(-sample.bodyPitch * resolved.pitchBlend, -resolved.pitchMax, resolved.pitchMax);
+    state.pitch =
+        resolved.pitchBlend <= 0 ? 0 : state.pitch + (pitchTarget - state.pitch) * smoothBlend(dt, resolved.pitchResponse);
+    const snap = state.offset === null || sample.lookBack !== state.lookingBack;
+    state.lookingBack = sample.lookBack;
+    const boomYaw = sample.lookBack ? anchorYaw + Math.PI : anchorYaw;
+    const boomPitch = sample.lookBack ? -state.pitch : state.pitch;
+    const extra = resolved.distanceSpeedForMax > 0 ? resolved.distanceExtra * clamp(speed / resolved.distanceSpeedForMax, 0, 1) : 0;
+    const led = sample.lookBack ? follow : leadFromVelocity(follow, velocity, resolved);
+    const desiredOffset = chaseBoomOffset(boomYaw, boomPitch, resolved.distance + extra, resolved.height);
+    let offset = snap || state.offset === null ? desiredOffset : springArmStep(state.offset, desiredOffset, resolved.springDamping, dt);
+    if (clampBoom !== undefined) {
+        const up = chaseLookAt(led, boomYaw, resolved, boomPitch);
+        const pivot = { x: led.x, y: up.y, z: led.z };
+        const wanted = { x: led.x + offset.x, y: led.y + offset.y, z: led.z + offset.z };
+        const allowed = clampBoom(pivot, wanted);
+        offset = { x: allowed.x - led.x, y: allowed.y - led.y, z: allowed.z - led.z };
+    }
+    state.offset = offset;
     return {
-        x: follow.x + forward.x * 2,
-        y: follow.y + resolved.lookHeight,
-        z: follow.z + forward.z * 2,
+        pose: {
+            position: { x: led.x + offset.x, y: led.y + offset.y, z: led.z + offset.z },
+            lookAt: chaseLookAt(led, boomYaw, resolved, boomPitch),
+            fov: state.fov + state.kick,
+        },
+        roll: sample.lookBack ? -state.roll : state.roll,
+        anchorYaw,
+        speed,
     };
 }
+/**
+ * Where a blocked boom should put the camera: `hitDistance` along the pivot→desired ray, less
+ * `radius`, but never nearer the pivot than `minDistance`. `null` hit returns `desired` unchanged.
+ * @internal
+ */
+export function clampBoomToHit(pivot, desired, hitDistance, radius, minDistance) {
+    if (hitDistance === null)
+        return desired;
+    const dx = desired.x - pivot.x;
+    const dy = desired.y - pivot.y;
+    const dz = desired.z - pivot.z;
+    const length = Math.hypot(dx, dy, dz);
+    if (length <= 1e-6)
+        return desired;
+    const allowed = clamp(hitDistance - radius, Math.min(minDistance, length), length);
+    const scale = allowed / length;
+    return { x: pivot.x + dx * scale, y: pivot.y + dy * scale, z: pivot.z + dz * scale };
+}
 /**
  * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
  * smoothing. When the target slides, its planar `velocity` diverges from its

package/dist/defineGame.d.ts

@@ -1,5 +1,7 @@
 import { type ComponentType } from "react";
+import type { EditorDocument } from "@jgengine/core/editor/types";
 import { type GameDefinitionConfig, type GameLoop } from "@jgengine/core/game/defineGame";
+import type { BackdropConfig } from "@jgengine/core/game/playableGame";
 import type { GameContext, GameContextContent } from "@jgengine/core/runtime/gameContext";
 import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
@@ -19,6 +21,13 @@ type PresentationFields = Omit<PlayableGame, "game" | "content" | "loop" | "Game
     sceneScatterModels?: Record<string, string | ModelConfig>;
 };
 export type GameConfig<TAssetRef extends ModelAssetRef = ModelAssetRef> = EngineFields<TAssetRef> & PresentationFields;
+/**
+ * The scene document's authored sky fills `backdrop.sky` when the game did not set one, so editor
+ * lighting-workspace edits render in `place()` worlds too. A document environment carrying only
+ * point lights yields no sky fields and leaves the world's sky alone.
+ * @internal
+ */
+export declare function withDocumentSky(backdrop: BackdropConfig | undefined, doc: EditorDocument | undefined): BackdropConfig | undefined;
 /**
  * The one public authoring entry point: compose engine fields (systems, world, physics, input) and
  * presentation fields (camera, HUD, audio, authored scene) into a `PlayableGame` ready for `GameHost`.

package/dist/defineGame.js

@@ -3,7 +3,7 @@ import { useMemo } from "react";
 import { defineGameDefinition as defineEngineGame, } from "@jgengine/core/game/defineGame";
 import { syncLifecyclePhase } from "@jgengine/core/game/gamePhase";
 import { offline } from "@jgengine/core/runtime/adapter";
-import { lightingFromDocument } from "@jgengine/core/editor/environment";
+import { lightingFromDocument, skyFromDocument } from "@jgengine/core/editor/environment";
 import { resolveGameLook } from "@jgengine/core/render/lookPreset";
 import { EnvironmentScene } from "./environment.js";
 import { terrainGroundColorSampler } from "./environment/terrainGroundColor.js";
@@ -14,6 +14,20 @@ function worldBackdrop(feature) {
         return _jsx(EnvironmentScene, { feature: feature });
     };
 }
+/**
+ * The scene document's authored sky fills `backdrop.sky` when the game did not set one, so editor
+ * lighting-workspace edits render in `place()` worlds too. A document environment carrying only
+ * point lights yields no sky fields and leaves the world's sky alone.
+ * @internal
+ */
+export function withDocumentSky(backdrop, doc) {
+    if (backdrop?.sky !== undefined || doc === undefined)
+        return backdrop;
+    const sky = skyFromDocument(doc);
+    if (sky === undefined || Object.keys(sky).length === 0)
+        return backdrop;
+    return { ...backdrop, sky };
+}
 function isEnvironmentSource(value) {
     return typeof value === "object" && value !== null && "kind" in value && ["gradient", "hdri", "cube"].includes(value.kind);
 }
@@ -33,7 +47,7 @@ const emptyUi = () => null;
  * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
  */
 export function defineGame(config) {
-    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting: authoredLighting, environmentSource, backdrop, look, postProcessing, shadows, graphics, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
+    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, gamepad, localPlayers, viewports, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting: authoredLighting, environmentSource, backdrop, look, postProcessing, shadows, graphics, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
     const game = defineEngineGame({
         ...engineFields,
         multiplayer: multiplayer ?? offline(),
@@ -42,7 +56,7 @@ export function defineGame(config) {
     const resolvedLook = resolveGameLook({
         look,
         lighting: authoredLighting,
-        backdrop,
+        backdrop: withDocumentSky(backdrop, editorLayers),
         postProcessing,
         hasWorldSky: editorLayers?.environment?.preset !== undefined,
     });
@@ -84,6 +98,9 @@ export function defineGame(config) {
         prompts,
         pointer,
         touch,
+        gamepad,
+        localPlayers,
+        viewports,
         orientation,
         worldHealthBars,
         nameplates,

package/dist/devtools/DevtoolsOverlay.js

@@ -5,6 +5,7 @@ import { devtools, instrumentLatency, } from "@jgengine/core/devtools/devtools";
 import { fallbackSeamsSnapshot } from "@jgengine/core/devtools/fallbackSeams";
 import { textureErrorsSnapshot } from "@jgengine/core/devtools/textureErrors";
 import { MOVEMENT_TUNING } from "@jgengine/core/movement/movementModel";
+import { heavyModels } from "../render/modelLoad.js";
 import { collisionDebug } from "./collisionDebug.js";
 import { readStoredOverrides } from "./devtoolsOverrides.js";
 import { diagnose } from "./perfDiagnose.js";
@@ -212,6 +213,7 @@ export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
             devtools.probes.register("objects", () => ctx.scene.object.list().length),
             devtools.probes.register("fallbacks", () => fallbackSeamsSnapshot()),
             devtools.probes.register("textureErrors", () => textureErrorsSnapshot()),
+            devtools.probes.register("heavyModels", () => heavyModels()),
         ];
         return () => {
             for (const dispose of disposers)

package/dist/devtools/agentBridge.d.ts

@@ -15,6 +15,12 @@ type EditorHost = {
     gameId: string;
     handle(request: AgentBridgeRequest): unknown;
 };
+/**
+ * @internal
+ * Resolves true once `isLive()` reports a mounted editor host, polling every `intervalMs` up to
+ * `timeoutMs`. `editor_summon` awaits this so the next RPC verb in a `drive` batch finds the editor.
+ */
+export declare function waitForEditorHost(isLive: () => boolean, timeoutMs?: number, intervalMs?: number, sleep?: (ms: number) => Promise<void>): Promise<boolean>;
 declare global {
     interface Window {
         __jgengineAgent?: {

package/dist/devtools/agentBridge.js

@@ -3,6 +3,20 @@ import { getSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
 import { isHudAnchor, listActiveHudLayouts, } from "@jgengine/core/ui/hudLayout";
 import { listHudPanelTypes, resolvePanelResize, resizePanelSize, } from "@jgengine/core/ui/hudDocument";
 import { buildFullReport, buildLeanReport } from "./DevtoolsOverlay.js";
+/**
+ * @internal
+ * Resolves true once `isLive()` reports a mounted editor host, polling every `intervalMs` up to
+ * `timeoutMs`. `editor_summon` awaits this so the next RPC verb in a `drive` batch finds the editor.
+ */
+export async function waitForEditorHost(isLive, timeoutMs = 15_000, intervalMs = 100, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+    for (let waited = 0;; waited += intervalMs) {
+        if (isLive())
+            return true;
+        if (waited >= timeoutMs)
+            return false;
+        await sleep(intervalMs);
+    }
+}
 async function saveScene(editorHost) {
     const endpoint = getSaveEndpoint();
     if (endpoint === null)
@@ -239,7 +253,7 @@ export function installAgentBridge(options) {
                     return { ok: false, error: "no editor summoner on this page — open with ?mode=editor" };
                 }
                 window.__jgengineSummonEditor();
-                return { ok: true, live: false };
+                return waitForEditorHost(() => window.__jgengineEditorHost !== undefined).then((live) => live ? { ok: true, live: true } : { ok: false, error: "editor did not mount within 15s" });
             }
             case "save_scene": {
                 const editorHost = window.__jgengineEditorHost;

package/dist/diagnostics/FpsCounter.d.ts

@@ -0,0 +1,17 @@
+import { type ReactElement } from "react";
+/** Mutable frame tally shared between the in-Canvas probe and the DOM readout. */
+export interface FrameTally {
+    frames: number;
+}
+/** Counts rendered frames. Mount inside the Canvas. @internal */
+export declare function FpsProbe({ tally }: {
+    tally: FrameTally;
+}): null;
+/**
+ * Player-facing frames-per-second readout, sampled twice a second from rendered frames (not
+ * display refreshes), so it reflects the frame-rate limit and GPU load.
+ * @internal shell-internal; shown by the `graphics.showFps` setting.
+ */
+export declare function FpsCounter({ tally }: {
+    tally: FrameTally;
+}): ReactElement;