@jgengine/shell 0.19.0 → 0.22.0

package/dist/camera/GameFirstPersonCamera.js

@@ -10,18 +10,14 @@ import { useEntityRenderCues } from "../render/useEntityRenderCues.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { GAME_SIM_FRAME_PRIORITY, ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
 import { requestRawPointerLock } from "../input/pointerLock.js";
+import { readRegisteredFirstPersonMuzzle, registerTrackedFirstPersonMuzzle } from "./customMuzzle.js";
 const DEFAULT_SENSITIVITY = 0.0025;
 const DEFAULT_MAX_PITCH = 1.45;
 const VIEWMODEL_ORIGIN = new THREE.Vector3(0.34, -0.26, -0.72);
 const MUZZLE_TIP_LOCAL = new THREE.Vector3(0, 0.03, -0.61);
-const muzzleWorld = new THREE.Vector3();
-let muzzleTracked = false;
-/** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
-export function readFirstPersonMuzzle(target) {
-    if (!muzzleTracked)
-        return false;
-    target.copy(muzzleWorld);
-    return true;
+/** Presentation muzzle in world space; camera-scoped when supplied, false leaves target unchanged. */
+export function readFirstPersonMuzzle(target, camera) {
+    return readRegisteredFirstPersonMuzzle(target, camera);
 }
 export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, weapon, }) {
     const eyeHeight = config?.eyeHeight ?? DEFAULT_EYE_HEIGHT;
@@ -107,9 +103,17 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
 }
 function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, poseRef, }) {
     const groupRef = useRef(null);
-    useEffect(() => () => {
-        muzzleTracked = false;
-    }, []);
+    const muzzleWorld = useRef(new THREE.Vector3());
+    const muzzleTracked = useRef(false);
+    useEffect(() => {
+        muzzleTracked.current = false;
+        return registerTrackedFirstPersonMuzzle(camera, (target) => {
+            if (!muzzleTracked.current)
+                return false;
+            target.copy(muzzleWorld.current);
+            return true;
+        });
+    }, [camera]);
     useFrame(() => {
         const group = groupRef.current;
         if (group === null)
@@ -128,8 +132,8 @@ function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, poseRef,
         group.rotateZ(pose?.roll ?? 0);
         group.scale.set(squash, squash, 1);
         group.updateMatrixWorld();
-        group.localToWorld(muzzleWorld.copy(MUZZLE_TIP_LOCAL));
-        muzzleTracked = true;
+        group.localToWorld(muzzleWorld.current.copy(MUZZLE_TIP_LOCAL));
+        muzzleTracked.current = true;
     }, GAME_SIM_FRAME_PRIORITY);
     if (Viewmodel !== undefined) {
         return (_jsx("group", { ref: groupRef, children: _jsx(Viewmodel, { cuesRef: cuesRef }) }));

package/dist/camera/cameraRigs.js

@@ -10,6 +10,7 @@ import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
 import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
 import { requestRawPointerLock } from "../input/pointerLock.js";
+import { resolveChaseHeading } from "./chaseHeading.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;
@@ -436,6 +437,7 @@ export function ChaseRig(props) {
     const shake = useCameraShake();
     const stateRef = useRef(createChaseRigState());
     const viewRef = useRef(null);
+    const inputSeededRef = useRef(false);
     useFrame((_, dt) => {
         const tuning = ctx.camera.chaseTuning();
         const merged = tuning === null ? config : { ...config, ...tuning };
@@ -448,7 +450,11 @@ export function ChaseRig(props) {
         }
         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;
+        if (!inputSeededRef.current && merged?.headingSource === "input" && view === "chase" && (entity !== null || props.config?.initialYaw !== undefined)) {
+            props.yawRef.current = resolveChaseHeading(merged, entity?.rotationY ?? 0, undefined, props.config?.initialYaw);
+            inputSeededRef.current = true;
+        }
+        const yaw = resolveChaseHeading(merged, entity?.rotationY ?? 0, props.yawRef.current);
         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);
@@ -478,7 +484,7 @@ export function ChaseRig(props) {
             lookBack: lookBack && view === "chase",
             fovKick: ctx.camera.takeFovKick(),
         }, resolved, dt, view === "chase" ? clampBoom : undefined);
-        props.yawRef.current = step.anchorYaw;
+        props.yawRef.current = resolveChaseHeading(merged, step.anchorYaw, props.yawRef.current);
         if (view !== "chase") {
             const seat = view === "cockpit"
                 ? merged?.seatOffsets?.cockpit ?? { x: 0, y: 1.2, z: 0.1 }

package/dist/camera/chaseHeading.d.ts

@@ -0,0 +1,9 @@
+import type { ChaseCameraConfig } from "@jgengine/core/game/playableGame";
+/**
+ * Select a chase heading without feeding target facing or camera smoothing back into input-owned yaw.
+ * An undefined input yaw seeds from `initialYaw`, or the acquired target's body heading.
+ * Seat views always use body heading; omitting `headingSource` preserves body follow.
+ *
+ * @capability chase-heading keep camera-relative input heading independent of body facing while retaining vehicle and seat camera follow
+ */
+export declare function resolveChaseHeading(config: Pick<ChaseCameraConfig, "headingSource" | "view"> | undefined, bodyYaw: number, inputYaw: number | undefined, initialYaw?: number): number;

package/dist/camera/chaseHeading.js

@@ -0,0 +1,10 @@
+/**
+ * Select a chase heading without feeding target facing or camera smoothing back into input-owned yaw.
+ * An undefined input yaw seeds from `initialYaw`, or the acquired target's body heading.
+ * Seat views always use body heading; omitting `headingSource` preserves body follow.
+ *
+ * @capability chase-heading keep camera-relative input heading independent of body facing while retaining vehicle and seat camera follow
+ */
+export function resolveChaseHeading(config, bodyYaw, inputYaw, initialYaw) {
+    return config?.headingSource === "input" && (config.view ?? "chase") === "chase" ? inputYaw ?? initialYaw ?? bodyYaw : bodyYaw;
+}

package/dist/camera/customMuzzle.d.ts

@@ -0,0 +1,14 @@
+import { Camera, Vector3 } from "three";
+/** Writes a live presentation muzzle in world space; false means this rig has no muzzle available. */
+export type FirstPersonMuzzleReader = (target: Vector3) => boolean;
+/**
+ * Register a custom rig's presentation muzzle for its Three.js camera. Newest available custom
+ * reader wins over that camera's stock muzzle; call the returned cleanup on unmount.
+ *
+ * @capability custom-viewmodel-muzzle align tracer origins with a custom viewmodel's live muzzle without changing authoritative shots
+ */
+export declare function registerFirstPersonMuzzle(camera: Camera, reader: FirstPersonMuzzleReader): () => void;
+/** @internal Stock rig registration shares camera isolation and owner-scoped cleanup. */
+export declare function registerTrackedFirstPersonMuzzle(camera: Camera, reader: FirstPersonMuzzleReader): () => void;
+/** @internal Unscoped legacy reads consider the newest 64 registrations per priority. */
+export declare function readRegisteredFirstPersonMuzzle(target: Vector3, camera?: Camera): boolean;

package/dist/camera/customMuzzle.js

@@ -0,0 +1,68 @@
+import { Camera, Vector3 } from "three";
+const MAX_READERS = 64;
+const custom = new WeakMap();
+const tracked = new WeakMap();
+const legacyCustom = [];
+const legacyTracked = [];
+function register(camera, reader, scoped, legacy) {
+    const readers = scoped.get(camera) ?? [];
+    if (readers.length >= MAX_READERS)
+        throw new RangeError("Too many muzzle readers for one camera");
+    const entry = { reader, scratch: new Vector3(), reading: false, disposed: false };
+    readers.push(entry);
+    scoped.set(camera, readers);
+    legacy.push(entry);
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        entry.disposed = true;
+        readers.splice(readers.indexOf(entry), 1);
+        legacy.splice(legacy.indexOf(entry), 1);
+        if (readers.length === 0)
+            scoped.delete(camera);
+    };
+}
+/**
+ * Register a custom rig's presentation muzzle for its Three.js camera. Newest available custom
+ * reader wins over that camera's stock muzzle; call the returned cleanup on unmount.
+ *
+ * @capability custom-viewmodel-muzzle align tracer origins with a custom viewmodel's live muzzle without changing authoritative shots
+ */
+export function registerFirstPersonMuzzle(camera, reader) {
+    return register(camera, reader, custom, legacyCustom);
+}
+/** @internal Stock rig registration shares camera isolation and owner-scoped cleanup. */
+export function registerTrackedFirstPersonMuzzle(camera, reader) {
+    return register(camera, reader, tracked, legacyTracked);
+}
+function read(readers, target) {
+    if (readers === undefined)
+        return false;
+    const pending = readers.slice(-MAX_READERS);
+    for (let i = pending.length - 1; i >= 0; i--) {
+        const entry = pending[i];
+        if (entry.reading || entry.disposed)
+            continue;
+        entry.reading = true;
+        try {
+            if (!entry.reader(entry.scratch))
+                continue;
+            const { x, y, z } = entry.scratch;
+            if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+                continue;
+            target.copy(entry.scratch);
+            return true;
+        }
+        finally {
+            entry.reading = false;
+        }
+    }
+    return false;
+}
+/** @internal Unscoped legacy reads consider the newest 64 registrations per priority. */
+export function readRegisteredFirstPersonMuzzle(target, camera) {
+    return read(camera === undefined ? legacyCustom : custom.get(camera), target) ||
+        read(camera === undefined ? legacyTracked : tracked.get(camera), target);
+}

package/dist/camera/index.d.ts

@@ -9,3 +9,4 @@ export { ControllerCameraShake, type ControllerCameraShakeProps } from "./Contro
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
 export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, type CameraOccluder, } from "./cameraCollision.js";
+export { registerFirstPersonMuzzle, type FirstPersonMuzzleReader } from "./customMuzzle.js";

package/dist/camera/index.js

@@ -9,3 +9,4 @@ export { ControllerCameraShake } from "./ControllerCameraShake.js";
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
 export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, } from "./cameraCollision.js";
+export { registerFirstPersonMuzzle } from "./customMuzzle.js";

package/dist/camera/rigResolve.d.ts

@@ -1,4 +1,7 @@
 import type { CameraRigKind, GameCameraConfig } from "@jgengine/core/game/playableGame";
+import type { CameraRigOverride } from "@jgengine/core/runtime/cameraDirector";
+/** @internal */
+export declare function resolveRuntimeCameraConfig(config: GameCameraConfig | undefined, override: CameraRigOverride | null | undefined): GameCameraConfig | undefined;
 /**
  * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
  * specific: an explicit `rig` field always wins; then `perspective: "first"`

package/dist/camera/rigResolve.js

@@ -1,3 +1,14 @@
+/** @internal */
+export function resolveRuntimeCameraConfig(config, override) {
+    if (override === null || override === undefined)
+        return config;
+    const merged = { ...config, ...override.config, rig: override.kind };
+    for (const key of ["firstPerson", "topDown", "rts", "shoulder", "lockOn", "chase", "observer", "turntable", "sideScroll", "inspection", "shake"]) {
+        if (override.config[key] !== undefined)
+            Object.assign(merged, { [key]: { ...config?.[key], ...override.config[key] } });
+    }
+    return merged;
+}
 /**
  * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
  * specific: an explicit `rig` field always wins; then `perspective: "first"`

package/dist/combat/ProjectileModels.d.ts

@@ -0,0 +1,31 @@
+import { type ReactElement } from "react";
+import * as THREE from "three";
+import type { LiveProjectile } from "@jgengine/core/combat/projectiles";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+/** Explicit opt-in shaft/head geometry when a game has no projectile model. */
+export interface ProjectileShaft {
+    length?: number;
+    radius?: number;
+    shaftColor?: THREE.ColorRepresentation;
+    headColor?: THREE.ColorRepresentation;
+}
+/** Render simulated flights without owning their travel or settlement. */
+export interface ProjectileModelsProps {
+    model?: ModelConfig | ((projectile: LiveProjectile) => ModelConfig | undefined);
+    /** Defaults to no fallback geometry. */
+    fallback?: ProjectileShaft;
+    /** The model's nose axis. Default +Y, matching the shaft fallback. */
+    forward?: readonly [number, number, number];
+    maxInstances?: number;
+    /** An alternate authoritative source; otherwise uses the context's live flights. */
+    source?: () => readonly LiveProjectile[];
+}
+/** @internal Apply live position and full velocity orientation without frame allocations. */
+export declare function applyProjectilePose(group: THREE.Group, projectile: Pick<LiveProjectile, "position" | "velocity">, forward: THREE.Vector3, direction: THREE.Vector3): void;
+/**
+ * Mount caller-owned models at authoritative projectile positions. Flight ids
+ * determine lifetime; each frame only updates transforms, and settlement removes
+ * the model. Optional shaft/head geometry is enabled only by the caller.
+ * @capability projectile-models render authoritative projectile flights with caller models or opt-in shaft/head geometry, velocity orientation, bounded instances, and settlement cleanup
+ */
+export declare function ProjectileModels({ model, fallback, forward, maxInstances, source }: ProjectileModelsProps): ReactElement;

package/dist/combat/ProjectileModels.js

@@ -0,0 +1,70 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useRef, useState } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+import { IsolatedEntityModel } from "../render/SceneModels.js";
+/** @internal Apply live position and full velocity orientation without frame allocations. */
+export function applyProjectilePose(group, projectile, forward, direction) {
+    group.position.set(...projectile.position);
+    direction.set(...projectile.velocity);
+    if (direction.lengthSq() > 1e-12)
+        group.quaternion.setFromUnitVectors(forward, direction.normalize());
+}
+function Shaft({ length = 0.85, radius = 0.012, shaftColor = "#947044", headColor = "#b9c4d0" }) {
+    const headLength = length * 0.18;
+    return _jsxs(_Fragment, { children: [_jsxs("mesh", { position: [0, -(length + headLength) / 2, 0], children: [_jsx("cylinderGeometry", { args: [radius, radius, length - headLength, 6] }), _jsx("meshStandardMaterial", { color: shaftColor, roughness: 0.78 })] }), _jsxs("mesh", { position: [0, -headLength / 2, 0], children: [_jsx("coneGeometry", { args: [radius * 3.5, headLength, 6] }), _jsx("meshStandardMaterial", { color: headColor, metalness: 0.5, roughness: 0.38 })] })] });
+}
+/**
+ * Mount caller-owned models at authoritative projectile positions. Flight ids
+ * determine lifetime; each frame only updates transforms, and settlement removes
+ * the model. Optional shaft/head geometry is enabled only by the caller.
+ * @capability projectile-models render authoritative projectile flights with caller models or opt-in shaft/head geometry, velocity orientation, bounded instances, and settlement cleanup
+ */
+export function ProjectileModels({ model, fallback, forward = [0, 1, 0], maxInstances = 256, source }) {
+    const ctx = useGameContext();
+    const entries = useRef(new Map());
+    const seen = useRef(new Set());
+    const direction = useRef(new THREE.Vector3());
+    const nose = useRef(new THREE.Vector3());
+    const [, setGeneration] = useState(0);
+    nose.current.set(...forward).normalize();
+    if (nose.current.lengthSq() === 0)
+        nose.current.set(0, 1, 0);
+    const limit = Number.isFinite(maxInstances) ? Math.max(0, Math.min(1024, Math.floor(maxInstances))) : 256;
+    useFrame(() => {
+        let changed = false;
+        const live = source?.() ?? ctx.scene.entity.activeProjectiles();
+        seen.current.clear();
+        for (let i = 0, n = Math.min(limit, live.length); i < n; i++) {
+            const flight = live[i];
+            const key = `${flight.shotId}:${flight.pellet}`;
+            seen.current.add(key);
+            const current = entries.current.get(key);
+            if (current === undefined) {
+                entries.current.set(key, { flight, group: null });
+                changed = true;
+            }
+            else {
+                current.flight = flight;
+                if (current.group !== null)
+                    applyProjectilePose(current.group, flight, nose.current, direction.current);
+            }
+        }
+        for (const key of entries.current.keys())
+            if (!seen.current.has(key)) {
+                entries.current.delete(key);
+                changed = true;
+            }
+        if (changed)
+            setGeneration((n) => n + 1);
+    });
+    return _jsx(_Fragment, { children: Array.from(entries.current, ([key, entry]) => {
+            const selected = typeof model === "function" ? model(entry.flight) : model;
+            return _jsx("group", { ref: (group) => {
+                    entry.group = group;
+                    if (group !== null)
+                        applyProjectilePose(group, entry.flight, nose.current, direction.current);
+                }, children: selected === undefined ? fallback === undefined ? null : _jsx(Shaft, { ...fallback }) : _jsx(IsolatedEntityModel, { model: selected, instanceId: key }) }, key);
+        }) });
+}

package/dist/commandSink.d.ts

@@ -14,8 +14,7 @@ export declare function localCommandSink(ctx: GameContext): CommandSink;
 export declare function remoteCommandSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): CommandSink;
 /**
  * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
- * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
- * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
+ * `authority: "server"` and a server is joined. Before join it discards commands rather than mutating a replica.
   * @internal
   */
 export declare function resolveCommandSink(ctx: GameContext, opts: {

package/dist/commandSink.js

@@ -20,13 +20,14 @@ export function remoteCommandSink(backend, serverId) {
 }
 /**
  * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
- * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
- * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
+ * `authority: "server"` and a server is joined. Before join it discards commands rather than mutating a replica.
   * @internal
   */
 export function resolveCommandSink(ctx, opts) {
     if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
         return remoteCommandSink(opts.backend, opts.serverId);
     }
+    if (opts.serverAuthoritative)
+        return { run() { } };
     return localCommandSink(ctx);
 }

package/dist/defineGame.d.ts

@@ -5,6 +5,8 @@ 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";
+import type { SkyEnvironmentConfig } from "@jgengine/core/world/features";
+import type { ResolveAuthoredObjectsOptions } from "@jgengine/core/world/authoredObjects";
 import type { PlayableGame } from "./registry.js";
 type EngineFields<TAssetRef extends ModelAssetRef> = Omit<GameDefinitionConfig<TAssetRef>, "loop" | "ui" | "multiplayer"> & {
     multiplayer?: GameDefinitionConfig<TAssetRef>["multiplayer"];
@@ -13,21 +15,26 @@ 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 | {
+    /** Tunes how the auto-mounted `AuthoredScene` places catalog-id markers into the object store. Default `true`; `excludeKinds` replaces the resolver's mob/boss exclusions, so include those when adding game-owned spawn kinds. Pass `false` when the game places all content itself. */
+    scenePlacement?: boolean | ({
         verticalOffset?: number;
-    };
+    } & ResolveAuthoredObjectsOptions);
     /** 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>;
+    /** Animated species models for cosmetic authored habitats; gameplay actors remain game-owned. */
+    sceneFlockModels?: Record<string, string | ModelConfig>;
+    /** Visible ground path kinds; omit to draw every non-scatter path, or restrict to keep flight/patrol guides out of world roads. */
+    scenePathKinds?: readonly string[];
 };
 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
+ * lighting-workspace edits render in `place()` worlds too. Defined document fields overlay the
+ * legacy world's sky, preserving settings the editor cannot represent. An 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;
+export declare function withDocumentSky(backdrop: BackdropConfig | undefined, doc: EditorDocument | undefined, worldSky?: SkyEnvironmentConfig): 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

@@ -16,26 +16,34 @@ function worldBackdrop(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
+ * lighting-workspace edits render in `place()` worlds too. Defined document fields overlay the
+ * legacy world's sky, preserving settings the editor cannot represent. An environment carrying only
  * point lights yields no sky fields and leaves the world's sky alone.
  * @internal
  */
-export function withDocumentSky(backdrop, doc) {
+export function withDocumentSky(backdrop, doc, worldSky) {
     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 };
+    return { ...backdrop, sky: {
+            ...worldSky,
+            ...sky,
+            ...(sky.sun === undefined ? {} : { sun: { ...worldSky?.sun,
+                    ...Object.fromEntries(Object.entries(sky.sun).filter(([, value]) => value !== undefined)) } }),
+            ...(sky.fog === undefined ? {} : { fog: { ...worldSky?.fog,
+                    ...Object.fromEntries(Object.entries(sky.fog).filter(([, value]) => value !== undefined)) } }),
+        } };
 }
 function isEnvironmentSource(value) {
     return typeof value === "object" && value !== null && "kind" in value && ["gradient", "hdri", "cube"].includes(value.kind);
 }
-function authoredSceneOverlay(document, placement, scatterModels, assets, world, Vfx) {
+function authoredSceneOverlay(document, diagnostics, placement, scatterModels, flockModels, pathKinds, 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 groundColorAt = useMemo(() => terrainGroundColorSampler(terrain, props.ctx.world.ground, document.terrain), [props.ctx.world.ground]);
+        return (_jsxs(_Fragment, { children: [_jsx(AuthoredScene, { document: document, diagnostics: diagnostics, field: props.ctx.world.ground, placeObjects: placement, assets: assets, ...(scatterModels === undefined ? {} : { scatterModels }), ...(flockModels === undefined ? {} : { flockModels }), ...(pathKinds === undefined ? {} : { pathKinds }), ...(groundColorAt === undefined ? {} : { groundColorAt }) }), Vfx === undefined ? null : _jsx(Vfx, { ...props })] }));
     };
 }
 const emptyUi = () => null;
@@ -47,16 +55,22 @@ 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, 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 { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, sceneFlockModels, scenePathKinds, 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, settings, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
     const game = defineEngineGame({
         ...engineFields,
+        ...(editorLayers === undefined ? {} : { authoredDocument: editorLayers }),
         multiplayer: multiplayer ?? offline(),
-        loop,
+        loop: { ...loop, onDispose(ctx) { try {
+                loop?.onDispose?.(ctx);
+            }
+            finally {
+                ctx.environment.dispose();
+            } } },
     });
     const resolvedLook = resolveGameLook({
         look,
         lighting: authoredLighting,
-        backdrop: withDocumentSky(backdrop, editorLayers),
+        backdrop: withDocumentSky(backdrop, editorLayers, engineFields.world?.kind === "environment" ? engineFields.world.sky : undefined),
         postProcessing,
         hasWorldSky: editorLayers?.environment?.preset !== undefined,
     });
@@ -87,7 +101,7 @@ export function defineGame(config) {
         editorCatalogs,
         WorldOverlay: editorLayers === undefined
             ? WorldOverlay
-            : authoredSceneOverlay(editorLayers, scenePlacement ?? true, sceneScatterModels, game.assets, game.world, WorldOverlay),
+            : authoredSceneOverlay(editorLayers, devtools !== false, scenePlacement ?? true, sceneScatterModels, sceneFlockModels, scenePathKinds, game.assets, game.world, WorldOverlay),
         viewmodel,
         renderEntity,
         renderObject,
@@ -118,6 +132,7 @@ export function defineGame(config) {
         shadows,
         graphics,
         presentation,
+        settings,
         objectStyles,
         devtools,
         capture,

package/dist/devtools/DevtoolsOverlay.d.ts

@@ -1,78 +1,11 @@
-import { type DevtoolsSnapshot } from "@jgengine/core/devtools/devtools";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { ShellMultiplayer } from "../multiplayer.js";
 import type { PlayableGame } from "../registry.js";
 export { applyStoredDevtoolsOverrides, persistDevtoolsOverrides } from "./devtoolsOverrides.js";
-/** @internal */
-export declare function withDevtoolsLatency(multiplayer: ShellMultiplayer): ShellMultiplayer;
+export { withDevtoolsLatency } from "./latencyInstrumentation.js";
 /** @internal */
 export declare function DevtoolsRendererProbe(): null;
-/** @internal */
-export declare function buildLeanReport(playable: PlayableGame): {
-    game: string;
-    at: number;
-    why: string | null;
-    frame: {
-        fps: number;
-        avgFrameMs: number;
-        p95FrameMs: number;
-        maxFrameMs: number;
-        avgSimMs: number;
-        maxSimMs: number;
-        avgOutsideMs: number;
-        maxOutsideMs: number;
-        longFrames: number;
-        samples: number;
-        phases: {
-            name: string;
-            avgMs: number;
-            maxMs: number;
-            pctOfSim: number;
-        }[];
-    } | null;
-    render: import("@jgengine/core/devtools/types").RenderSample | null;
-    latency: import("@jgengine/core/devtools/types").LatencyStats | null;
-    longFrameSummary: {
-        count: number;
-        culprits: {
-            culprit: string;
-            count: number;
-        }[];
-        maxFrameMs: number;
-        maxDrawCalls: number | undefined;
-        maxGeometries: number | undefined;
-    } | null;
-    longFrames: {
-        at: number;
-        frameMs: number;
-        simMs: number;
-        outsideMs: number;
-        culprit: string;
-        reason: string;
-        phases: {
-            name: string;
-            ms: number;
-        }[];
-        probes: Record<string, unknown>;
-        render: import("@jgengine/core/devtools/types").RenderSample | null;
-    }[];
-    probes: Record<string, unknown>;
-    logs: import("@jgengine/core/devtools/types").DevtoolsLogEntry[] | undefined;
-    controls: {
-        name: string;
-        value: unknown;
-        initial: unknown;
-    }[] | undefined;
-    discovered: {
-        id: string;
-        value: unknown;
-    }[] | undefined;
-    discoveredCount: number;
-};
-/** @internal */
-export declare function buildFullReport(playable: PlayableGame): DevtoolsSnapshot & {
-    game: string;
-};
+export { buildLeanReport, buildFullReport } from "./devtoolsReports.js";
 /** @internal */
 export declare function DevtoolsOverlay({ open, ctx, playable, multiplayer, }: {
     open: boolean;