@jgengine/shell 0.11.0 → 0.12.0

package/dist/audio/audioEngine.js

@@ -1,7 +1,11 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+import { patchDuration } from "@jgengine/core/audio/synth";
 import { createDisposer } from "@jgengine/core/game/defineGame";
+import { clampLoopGain, clampLoopRate } from "./loopParams.js";
 import { MusicDirector } from "./musicDirector.js";
 import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
+/** setTargetAtTime time constant (~20 ms) for zipper-free live rate/gain ramps on retained loops (#1051). */
+const LOOP_PARAM_SMOOTH_TC = 0.02;
 function createNoopEngine() {
     return {
         setListenerPose: () => undefined,
@@ -20,6 +24,12 @@ function resolveAudioContextCtor() {
     return (window.AudioContext ??
         window.webkitAudioContext);
 }
+function resolveOfflineAudioContextCtor() {
+    if (typeof window === "undefined")
+        return undefined;
+    return (window.OfflineAudioContext ??
+        window.webkitOfflineAudioContext);
+}
 export function createAudioEngine(config = {}) {
     const sounds = config.sounds ?? {};
     const busDefs = config.buses ?? {};
@@ -74,65 +84,138 @@ export function createAudioEngine(config = {}) {
         }
         return pending;
     }
+    // Retained synth loops render the procedural patch to one cached buffer, then loop it as a plain
+    // BufferSource — so live pitch is `playbackRate` and live gain is a gain node, exactly like sample loops (#1051).
+    const synthBufferCache = new Map();
+    function renderSynthBuffer(soundId, patch) {
+        let pending = synthBufferCache.get(soundId);
+        if (pending === undefined) {
+            const OfflineCtor = resolveOfflineAudioContextCtor();
+            if (OfflineCtor === undefined) {
+                pending = Promise.resolve(null);
+            }
+            else {
+                try {
+                    const seconds = Math.max(patchDuration(patch), 0.05);
+                    const frames = Math.max(1, Math.ceil(seconds * context.sampleRate));
+                    const offline = new OfflineCtor(1, frames, context.sampleRate);
+                    realizeSynthPatch(offline, offline.destination, createNoiseBuffer(offline), patch);
+                    pending = offline.startRendering().catch(() => null);
+                }
+                catch {
+                    pending = Promise.resolve(null);
+                }
+            }
+            synthBufferCache.set(soundId, pending);
+        }
+        return pending;
+    }
     let listenerPosition = { x: 0, y: 0, z: 0 };
     const activeSpatialUpdaters = new Set();
+    const activeLoops = new Set();
+    const NOOP_HANDLE = {
+        setPosition: () => undefined,
+        setRate: () => undefined,
+        setGain: () => undefined,
+        stop: () => undefined,
+    };
     function playInternal(soundId, position, loop) {
         const sound = sounds[soundId];
         if (sound === undefined)
             return null;
         const bus = busGainNode(sound.bus);
-        let currentPosition = position ?? listenerPosition;
-        if (sound.synth !== undefined) {
+        const currentPosition = position ?? listenerPosition;
+        // A one-shot synth cue realises its decaying voices live and is fire-and-forget.
+        if (sound.synth !== undefined && !loop) {
             const cueGain = context.createGain();
             cueGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             cueGain.connect(bus);
             realizeSynthPatch(context, cueGain, sharedNoiseBuffer(), sound.synth);
-            return { setPosition: () => undefined, stop: () => undefined };
+            return NOOP_HANDLE;
         }
-        if (sound.url === undefined)
+        // Everything else resolves to one AudioBuffer we loop/play: sample URL, or a synth patch rendered once.
+        let bufferPromise;
+        if (sound.synth !== undefined)
+            bufferPromise = renderSynthBuffer(soundId, sound.synth);
+        else if (sound.url !== undefined)
+            bufferPromise = loadBuffer(sound.url);
+        else
             return null;
+        return playBufferSource(sound, bus, bufferPromise, currentPosition, loop);
+    }
+    function playBufferSource(sound, bus, bufferPromise, initialPosition, loop) {
         const disposer = createDisposer();
-        let liveGain = null;
-        function updateGain() {
-            if (liveGain !== null) {
-                liveGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+        let currentPosition = initialPosition;
+        // Live control state, applied on source creation so updates that race the async buffer load stick.
+        let currentRate = 1;
+        let currentUserGain = 1;
+        let sourceNode = null;
+        let userGainNode = null;
+        let falloffGain = null;
+        function updateFalloff() {
+            if (falloffGain !== null) {
+                falloffGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             }
         }
-        void loadBuffer(sound.url).then((buffer) => {
+        void bufferPromise.then((buffer) => {
             if (buffer === null)
                 return;
-            const sourceNode = context.createBufferSource();
-            sourceNode.buffer = buffer;
-            sourceNode.loop = loop || (sound.loop ?? false);
-            const gainNode = context.createGain();
-            gainNode.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-            sourceNode.connect(gainNode);
-            gainNode.connect(bus);
-            sourceNode.start();
-            liveGain = gainNode;
+            const src = context.createBufferSource();
+            src.buffer = buffer;
+            src.loop = loop || (sound.loop ?? false);
+            src.playbackRate.value = currentRate;
+            // source → per-loop user gain (setGain) → distance falloff → bus
+            const uGain = context.createGain();
+            uGain.gain.value = currentUserGain;
+            const fGain = context.createGain();
+            fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            src.connect(uGain);
+            uGain.connect(fGain);
+            fGain.connect(bus);
+            src.start();
+            sourceNode = src;
+            userGainNode = uGain;
+            falloffGain = fGain;
             disposer.onDispose(() => {
                 try {
-                    sourceNode.stop();
+                    src.stop();
                 }
                 catch {
                 }
-                sourceNode.disconnect();
-                gainNode.disconnect();
-                liveGain = null;
+                src.disconnect();
+                uGain.disconnect();
+                fGain.disconnect();
+                sourceNode = null;
+                userGainNode = null;
+                falloffGain = null;
             });
         });
         if (loop)
-            activeSpatialUpdaters.add(updateGain);
-        return {
+            activeSpatialUpdaters.add(updateFalloff);
+        const handle = {
             setPosition(next) {
                 currentPosition = next;
-                updateGain();
+                updateFalloff();
+            },
+            setRate(rate) {
+                currentRate = clampLoopRate(rate);
+                if (sourceNode !== null)
+                    sourceNode.playbackRate.setTargetAtTime(currentRate, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            },
+            setGain(gain) {
+                currentUserGain = clampLoopGain(gain);
+                if (userGainNode !== null)
+                    userGainNode.gain.setTargetAtTime(currentUserGain, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             stop() {
-                activeSpatialUpdaters.delete(updateGain);
+                activeSpatialUpdaters.delete(updateFalloff);
+                activeLoops.delete(handle);
                 disposer.dispose();
             },
         };
+        if (loop)
+            activeLoops.add(handle);
+        return handle;
     }
     return {
         setListenerPose(position) {
@@ -161,6 +244,8 @@ export function createAudioEngine(config = {}) {
             void context.resume().catch(() => undefined);
         },
         dispose() {
+            for (const handle of [...activeLoops])
+                handle.stop();
             activeSpatialUpdaters.clear();
             director?.dispose();
             void context.close().catch(() => undefined);

package/dist/audio/audioWire.d.ts

@@ -7,16 +7,34 @@ type AudioMusicPayload = {
     theme: string | null;
     transpose?: number;
 };
-/** Minimal event bus the shell wires to the audio engine. @internal */
+type AudioLoopStartPayload = {
+    id: string;
+    sound: string;
+    at?: readonly [number, number, number];
+};
+type AudioLoopSetPayload = {
+    id: string;
+    rate?: number;
+    gain?: number;
+    at?: readonly [number, number, number];
+};
+type AudioLoopStopPayload = {
+    id: string;
+};
+/** Minimal event bus the shell wires to the audio engine, including retained id-keyed loops (#1051). @internal */
 export type AudioEventBus = {
     on(event: "audio.play", handler: (payload: AudioPlayPayload) => void): () => void;
     on(event: "audio.music", handler: (payload: AudioMusicPayload) => void): () => void;
     on(event: "audio.resume", handler: () => void): () => void;
+    on(event: "audio.loopStart", handler: (payload: AudioLoopStartPayload) => void): () => void;
+    on(event: "audio.loopSet", handler: (payload: AudioLoopSetPayload) => void): () => void;
+    on(event: "audio.loopStop", handler: (payload: AudioLoopStopPayload) => void): () => void;
 };
 /**
- * Subscribe game audio events to the shell audio engine.
- * Returns a single unsubscribe that tears all three listeners down.
+ * Subscribe game audio events to the shell audio engine. Manages the retained-loop registry
+ * (`audio.loopStart`/`audio.loopSet`/`audio.loopStop`), keyed by stable id. Returns a single
+ * unsubscribe that tears every listener down and stops any loops still playing.
  * @internal
  */
-export declare function attachAudioEventWire(events: AudioEventBus, audioEngine: Pick<AudioEngine, "playOneShot" | "playMusic" | "resume">): () => void;
+export declare function attachAudioEventWire(events: AudioEventBus, audioEngine: Pick<AudioEngine, "playOneShot" | "playLoop" | "playMusic" | "resume">): () => void;
 export {};

package/dist/audio/audioWire.js

@@ -1,19 +1,62 @@
+function toVec(at) {
+    return at === undefined ? undefined : { x: at[0], y: at[1], z: at[2] };
+}
 /**
- * Subscribe game audio events to the shell audio engine.
- * Returns a single unsubscribe that tears all three listeners down.
+ * Subscribe game audio events to the shell audio engine. Manages the retained-loop registry
+ * (`audio.loopStart`/`audio.loopSet`/`audio.loopStop`), keyed by stable id. Returns a single
+ * unsubscribe that tears every listener down and stops any loops still playing.
  * @internal
  */
 export function attachAudioEventWire(events, audioEngine) {
+    const loops = new Map();
     const offPlay = events.on("audio.play", ({ sound, at }) => {
-        audioEngine.playOneShot(sound, at === undefined ? undefined : { x: at[0], y: at[1], z: at[2] });
+        audioEngine.playOneShot(sound, toVec(at));
     });
     const offMusic = events.on("audio.music", ({ theme, transpose }) => {
         audioEngine.playMusic(theme, transpose === undefined ? undefined : { transpose });
     });
     const offResume = events.on("audio.resume", () => audioEngine.resume());
+    const offLoopStart = events.on("audio.loopStart", ({ id, sound, at }) => {
+        const existing = loops.get(id);
+        if (existing !== undefined) {
+            // Same sound: idempotent — keep the running source so a per-tick re-issue never clicks.
+            if (existing.sound === sound)
+                return;
+            existing.handle.stop();
+            loops.delete(id);
+        }
+        const handle = audioEngine.playLoop(sound, toVec(at));
+        if (handle !== null)
+            loops.set(id, { sound, handle });
+    });
+    const offLoopSet = events.on("audio.loopSet", ({ id, rate, gain, at }) => {
+        const entry = loops.get(id);
+        // Unknown id: a live update may race a stop — silently drop it.
+        if (entry === undefined)
+            return;
+        if (rate !== undefined)
+            entry.handle.setRate(rate);
+        if (gain !== undefined)
+            entry.handle.setGain(gain);
+        if (at !== undefined)
+            entry.handle.setPosition({ x: at[0], y: at[1], z: at[2] });
+    });
+    const offLoopStop = events.on("audio.loopStop", ({ id }) => {
+        const entry = loops.get(id);
+        if (entry === undefined)
+            return;
+        entry.handle.stop();
+        loops.delete(id);
+    });
     return () => {
         offPlay();
         offMusic();
         offResume();
+        offLoopStart();
+        offLoopSet();
+        offLoopStop();
+        for (const { handle } of loops.values())
+            handle.stop();
+        loops.clear();
     };
 }

package/dist/audio/loopParams.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure clamps for retained-loop live control (#1051). Kept dependency-free so the
+ * playback-rate/gain windows are one testable source of truth the audio engine reads.
+ */
+/** Lowest live playback-rate multiplier (two octaves below authored pitch). */
+export declare const MIN_LOOP_RATE = 0.25;
+/** Highest live playback-rate multiplier (two octaves above authored pitch). */
+export declare const MAX_LOOP_RATE = 4;
+/**
+ * Clamp a loop playback-rate multiplier into the safe pitch window `MIN_LOOP_RATE`–`MAX_LOOP_RATE`
+ * (1 = authored pitch). Non-finite input (NaN/±Infinity) falls back to the authored `1`.
+ * @internal — the audio engine applies this; game code sets rate through `ctx.game.audio.setLoop`.
+ */
+export declare function clampLoopRate(rate: number): number;
+/**
+ * Clamp a loop gain multiplier into `0`–`1`. Non-finite input falls back to `0` (silence) so a
+ * stray NaN never blasts a loop to full volume.
+ * @internal — the audio engine applies this; game code sets gain through `ctx.game.audio.setLoop`.
+ */
+export declare function clampLoopGain(gain: number): number;

package/dist/audio/loopParams.js

@@ -0,0 +1,28 @@
+/**
+ * Pure clamps for retained-loop live control (#1051). Kept dependency-free so the
+ * playback-rate/gain windows are one testable source of truth the audio engine reads.
+ */
+/** Lowest live playback-rate multiplier (two octaves below authored pitch). */
+export const MIN_LOOP_RATE = 0.25;
+/** Highest live playback-rate multiplier (two octaves above authored pitch). */
+export const MAX_LOOP_RATE = 4;
+/**
+ * Clamp a loop playback-rate multiplier into the safe pitch window `MIN_LOOP_RATE`–`MAX_LOOP_RATE`
+ * (1 = authored pitch). Non-finite input (NaN/±Infinity) falls back to the authored `1`.
+ * @internal — the audio engine applies this; game code sets rate through `ctx.game.audio.setLoop`.
+ */
+export function clampLoopRate(rate) {
+    if (!Number.isFinite(rate))
+        return 1;
+    return Math.min(MAX_LOOP_RATE, Math.max(MIN_LOOP_RATE, rate));
+}
+/**
+ * Clamp a loop gain multiplier into `0`–`1`. Non-finite input falls back to `0` (silence) so a
+ * stray NaN never blasts a loop to full volume.
+ * @internal — the audio engine applies this; game code sets gain through `ctx.game.audio.setLoop`.
+ */
+export function clampLoopGain(gain) {
+    if (!Number.isFinite(gain))
+        return 0;
+    return Math.min(1, Math.max(0, gain));
+}

package/dist/camera/GameCameraRig.js

@@ -22,7 +22,12 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
     const followEntityId = directed.followEntityId;
     const rig = (() => {
         if (directed.cinematic !== undefined) {
-            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId, absoluteFov: true }));
+            // A director-set cinematic auto-clears when its keyframe path completes, so a
+            // one-shot flyover can never strand the camera if a game-side clear timer drifts
+            // (the rig plays in real time; sim-clock timers do not). Static config cinematics
+            // hold their final frame as before.
+            const owner = director !== undefined && director.cinematic() !== null ? director : undefined;
+            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId, absoluteFov: true, ...(owner === undefined ? {} : { onComplete: () => owner.setCinematic(null) }) }));
         }
         const kind = resolveRigKind(config);
         switch (kind) {

package/dist/camera/cameraRigs.d.ts

@@ -26,4 +26,6 @@ export declare function ChaseRig(props: RigProps): null;
  * kill-cam rig. Distinct from every other rig, which drives from mouse/keys.
  */
 export declare function ObserverRig(props: RigProps): null;
-export declare function CinematicRig(props: RigProps): null;
+export declare function CinematicRig(props: RigProps & {
+    onComplete?: () => void;
+}): null;

package/dist/camera/cameraRigs.js

@@ -4,7 +4,7 @@ import { PerspectiveCamera, Quaternion, Vector3 } from "three";
 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, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, } from "./rigMath.js";
+import { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, velocityYawTarget, } from "./rigMath.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
 import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
@@ -424,6 +424,7 @@ export function ChaseRig(props) {
     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]);
@@ -454,15 +455,24 @@ export function ChaseRig(props) {
             commit(pose, dt);
             return;
         }
+        let anchorYaw = yaw;
+        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 };
+            const targetYaw = velocityYawTarget(yaw, velocity, resolved);
+            anchorYaw = smoothYaw(anchorYawRef.current ?? targetYaw, targetYaw, resolved.velocityYawResponse, dt);
+            anchorYawRef.current = anchorYaw;
+        }
         const led = leadFollowPoint(follow, last, dt, resolved);
-        const desired = chaseDesiredPosition(led, yaw, 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, yaw, resolved), fov };
+        const pose = { position: smoothed, lookAt: chaseLookAt(led, anchorYaw, resolved), fov };
         commit(pose, dt);
         if (rollRef.current !== 0)
             camera.rotateZ(rollRef.current);
@@ -510,8 +520,12 @@ export function CinematicRig(props) {
     const cinematic = props.config?.cinematic;
     const { camera, commit, beginTransition } = useCameraCommit(props, followId);
     const elapsedRef = useRef(0);
+    const completedRef = useRef(false);
+    const onCompleteRef = useRef(props.onComplete);
+    onCompleteRef.current = props.onComplete;
     useEffect(() => {
         elapsedRef.current = 0;
+        completedRef.current = false;
         beginTransition();
     }, [cinematic]);
     useFrame((_, dt) => {
@@ -520,6 +534,10 @@ export function CinematicRig(props) {
         elapsedRef.current += dt;
         const sample = cinematicSample(cinematic.keyframes, elapsedRef.current, cinematic.loop ?? false, currentFov(camera));
         commit(sample.pose, dt);
+        if (sample.done && !completedRef.current) {
+            completedRef.current = true;
+            onCompleteRef.current?.();
+        }
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }

package/dist/camera/rigMath.d.ts

@@ -121,6 +121,12 @@ export interface ResolvedChase {
     bankPerYawRate: number;
     bankMax: number;
     bankDamping: number;
+    /** Max fraction of the slip angle the anchor yaw follows toward velocity; 0 = drift-lag off (#1051). */
+    velocityYawBlend: number;
+    /** Below this planar speed the drift-lag feature is fully off. */
+    velocityYawMinSpeed: number;
+    /** Exponential smoothing rate toward the blended anchor yaw (1-exp(-response*dt)). */
+    velocityYawResponse: number;
 }
 /** @internal */
 export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
@@ -152,6 +158,20 @@ export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved
  * @internal
  */
 export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
+/**
+ * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
+ * smoothing. When the target slides, its planar `velocity` diverges from its
+ * `heading`; this rotates the anchor from heading partway toward the velocity
+ * direction so the camera reveals the car's side while travel stays framed. The
+ * traversed fraction is `velocityYawBlend` scaled by how far the slip angle has
+ * opened (0 at straight-line travel, full at a 90° slide), so ordinary driving
+ * is untouched. Returns the raw heading — no swing — when the feature is off,
+ * when planar speed is below `velocityYawMinSpeed`, or when the target is
+ * reversing (velocity opposed to heading forward). Blending is shortest-arc, so
+ * it stays correct across the ±PI wrap seam.
+ * @internal
+ */
+export declare function velocityYawTarget(heading: number, velocity: Vec3, resolved: ResolvedChase): number;
 /** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle.
  * @internal
  */

package/dist/camera/rigMath.js

@@ -242,6 +242,9 @@ export function resolveChase(config) {
         bankPerYawRate: config?.bank?.perYawRate ?? 0,
         bankMax: config?.bank?.max ?? 0.35,
         bankDamping: config?.bank?.damping ?? 8,
+        velocityYawBlend: config?.velocityYaw === undefined ? 0 : config.velocityYaw.blend ?? 0.65,
+        velocityYawMinSpeed: config?.velocityYaw?.minSpeed ?? 4,
+        velocityYawResponse: config?.velocityYaw?.response ?? 6,
     };
 }
 /** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`.
@@ -323,6 +326,32 @@ export function chaseLookAt(follow, yaw, resolved) {
         z: follow.z + forward.z * 2,
     };
 }
+/**
+ * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
+ * smoothing. When the target slides, its planar `velocity` diverges from its
+ * `heading`; this rotates the anchor from heading partway toward the velocity
+ * direction so the camera reveals the car's side while travel stays framed. The
+ * traversed fraction is `velocityYawBlend` scaled by how far the slip angle has
+ * opened (0 at straight-line travel, full at a 90° slide), so ordinary driving
+ * is untouched. Returns the raw heading — no swing — when the feature is off,
+ * when planar speed is below `velocityYawMinSpeed`, or when the target is
+ * reversing (velocity opposed to heading forward). Blending is shortest-arc, so
+ * it stays correct across the ±PI wrap seam.
+ * @internal
+ */
+export function velocityYawTarget(heading, velocity, resolved) {
+    if (resolved.velocityYawBlend <= 0)
+        return heading;
+    const speed = Math.hypot(velocity.x, velocity.z);
+    if (speed < resolved.velocityYawMinSpeed)
+        return heading;
+    const forward = forwardVector(heading);
+    if (forward.x * velocity.x + forward.z * velocity.z < 0)
+        return heading;
+    const slip = angleDelta(heading, Math.atan2(velocity.x, velocity.z));
+    const slipFraction = clamp(Math.abs(slip) / (Math.PI / 2), 0, 1);
+    return heading + slip * resolved.velocityYawBlend * slipFraction;
+}
 /** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle.
  * @internal
  */

package/dist/defineGame.d.ts

@@ -1,7 +1,8 @@
-import type { ComponentType } from "react";
+import { type ComponentType } from "react";
 import { type GameDefinitionConfig, type GameLoop } from "@jgengine/core/game/defineGame";
 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";
 import type { PlayableGame } from "./registry.js";
 type EngineFields<TAssetRef extends ModelAssetRef> = Omit<GameDefinitionConfig<TAssetRef>, "loop" | "ui" | "multiplayer"> & {
     multiplayer?: GameDefinitionConfig<TAssetRef>["multiplayer"];
@@ -10,7 +11,20 @@ type PresentationFields = Omit<PlayableGame, "game" | "content" | "loop" | "Game
     content?: GameContextContent;
     loop?: Partial<GameLoop<GameContext>>;
     GameUI?: ComponentType;
+    /** Tunes how the auto-mounted `AuthoredScene` places the document's catalog-id markers into the object store. Default `true`; pass `false` when the game spawns its placed content as entities itself (`placeAuthoredObjects`) to avoid a double render. */
+    scenePlacement?: boolean | {
+        verticalOffset?: number;
+    };
+    /** GLB models for the auto-mounted scene's scatter palette items, keyed by palette item id; string ids resolve through the game's asset catalog. Unmatched items keep the built-in proxy meshes. */
+    sceneScatterModels?: Record<string, string | ModelConfig>;
 };
 export type GameConfig<TAssetRef extends ModelAssetRef = ModelAssetRef> = EngineFields<TAssetRef> & PresentationFields;
+/**
+ * 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`.
+ * Defaults to solo/offline multiplayer; `editorLayers` auto-mounts the authored scene document.
+ *
+ * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
+ */
 export declare function defineGame<TAssetRef extends ModelAssetRef = ModelAssetRef>(config: GameConfig<TAssetRef>): PlayableGame;
 export {};

package/dist/defineGame.js

@@ -1,17 +1,34 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { defineGame as defineEngineGame, } from "@jgengine/core/game/defineGame";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { EnvironmentScene } from "./environment.js";
+import { terrainGroundColorSampler } from "./environment/terrainGroundColor.js";
+import { AuthoredScene } from "./scene/AuthoredScene.js";
 const noop = () => { };
 function worldBackdrop(feature) {
     return function WorldBackdrop() {
         return _jsx(EnvironmentScene, { feature: feature });
     };
 }
+function authoredSceneOverlay(document, placement, scatterModels, assets, world, Vfx) {
+    const terrain = world !== undefined && world.kind === "environment" ? world.terrain : undefined;
+    return function AuthoredSceneOverlay(props) {
+        const groundColorAt = useMemo(() => terrainGroundColorSampler(terrain, props.ctx.world.ground), [props.ctx.world.ground]);
+        return (_jsxs(_Fragment, { children: [_jsx(AuthoredScene, { document: document, field: props.ctx.world.ground, placeObjects: placement, ...(scatterModels === undefined ? {} : { scatterModels, assets }), ...(groundColorAt === undefined ? {} : { groundColorAt }) }), Vfx === undefined ? null : _jsx(Vfx, { ...props })] }));
+    };
+}
 const emptyUi = () => null;
+/**
+ * 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`.
+ * Defaults to solo/offline multiplayer; `editorLayers` auto-mounts the authored scene document.
+ *
+ * @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, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, 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, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
     const game = defineEngineGame({
         ...engineFields,
         multiplayer: multiplayer ?? offline(),
@@ -39,7 +56,11 @@ export function defineGame(config) {
         environment: environment ??
             (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
         camera: camera ?? { perspective: "third" },
-        WorldOverlay,
+        editorLayers,
+        editorCatalogs,
+        WorldOverlay: editorLayers === undefined
+            ? WorldOverlay
+            : authoredSceneOverlay(editorLayers, scenePlacement ?? true, sceneScatterModels, game.assets, game.world, WorldOverlay),
         viewmodel,
         renderEntity,
         renderObject,
@@ -53,6 +74,7 @@ export function defineGame(config) {
         orientation,
         worldHealthBars,
         nameplates,
+        presentationEffects,
         audio,
         entitySounds,
         objectSounds,

package/dist/devtools/DevtoolsOverlay.d.ts

@@ -30,8 +30,8 @@ export declare function buildLeanReport(playable: PlayableGame): {
             pctOfSim: number;
         }[];
     } | null;
-    render: import("@jgengine/core/devtools/devtools").RenderSample | null;
-    latency: import("@jgengine/core/devtools/devtools").LatencyStats | null;
+    render: import("@jgengine/core/devtools/types").RenderSample | null;
+    latency: import("@jgengine/core/devtools/types").LatencyStats | null;
     longFrameSummary: {
         count: number;
         culprits: {
@@ -54,10 +54,10 @@ export declare function buildLeanReport(playable: PlayableGame): {
             ms: number;
         }[];
         probes: Record<string, unknown>;
-        render: import("@jgengine/core/devtools/devtools").RenderSample | null;
+        render: import("@jgengine/core/devtools/types").RenderSample | null;
     }[];
     probes: Record<string, unknown>;
-    logs: import("@jgengine/core/devtools/devtools").DevtoolsLogEntry[] | undefined;
+    logs: import("@jgengine/core/devtools/types").DevtoolsLogEntry[] | undefined;
     controls: {
         name: string;
         value: unknown;