@jgengine/shell 0.36.0 → 0.38.0

package/dist/render/triangleAttribution.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from "three";
+/** One line of the triangle table: the draws sharing one geometry inside one named model. */
+export interface TriangleLine {
+    /** Model ancestor names plus the mesh name, or the material name when nothing is named. */
+    label: string;
+    /** Triangles one instance submits. */
+    perInstance: number;
+    /** Instances drawn from this geometry. */
+    instances: number;
+    /** Draw calls this line costs. */
+    draws: number;
+    /** `perInstance * instances` - the triangles this line puts in the frame. */
+    triangles: number;
+}
+/** Where one scene's triangles are, biggest line first. */
+export interface TriangleAttribution {
+    /** Every triangle the scene graph would submit for one camera pass, instances included. */
+    triangles: number;
+    /** How many of those belong to meshes that cast shadows, so the shadow pass pays them again. */
+    casters: number;
+    lines: readonly TriangleLine[];
+}
+/**
+ * Sum a scene's triangles by model and geometry, which is the attribution a triangle budget needs:
+ * a total says a frame is heavy, a table says which authored object made it heavy. Walks the graph
+ * once; call it on demand, never per frame.
+ * @capability triangle-attribution per-model triangle table with instance counts, for perf probes
+ */
+export declare function attributeTriangles(root: THREE.Object3D, limit?: number): TriangleAttribution;
+/**
+ * The `render/triangles` probe for one scene: the table, its two headline numbers, and the one-line
+ * summary a report prints. Reads the graph on every call, so wrap it in a short cache when a
+ * snapshot reads counters and state together.
+ * @internal
+ */
+export declare function triangleProbe(root: THREE.Object3D): {
+    table(): TriangleAttribution;
+    counters(): Record<string, number>;
+    state(): string;
+};

package/dist/render/triangleAttribution.js

@@ -0,0 +1,88 @@
+import * as THREE from "three";
+function triangleCount(mesh) {
+    if (mesh.isPoints === true)
+        return 0;
+    if (mesh.isLine === true)
+        return 0;
+    const geometry = mesh.geometry;
+    if (geometry === undefined || geometry === null)
+        return 0;
+    const index = geometry.getIndex();
+    const position = geometry.getAttribute("position");
+    const vertices = index !== null ? index.count : position?.count ?? 0;
+    return Math.round(vertices / 3);
+}
+const MAX_LABEL_DEPTH = 3;
+function labelOf(mesh) {
+    const names = [];
+    let node = mesh;
+    for (let depth = 0; node !== null && node !== undefined && depth < MAX_LABEL_DEPTH + 1; depth += 1) {
+        if (typeof node.name === "string" && node.name.length > 0)
+            names.push(node.name);
+        node = node.parent;
+    }
+    if (names.length > 0)
+        return names.reverse().join("/");
+    const material = mesh.material;
+    const first = Array.isArray(material) ? material[0] : material;
+    return first?.name || first?.type || mesh.type;
+}
+/**
+ * Sum a scene's triangles by model and geometry, which is the attribution a triangle budget needs:
+ * a total says a frame is heavy, a table says which authored object made it heavy. Walks the graph
+ * once; call it on demand, never per frame.
+ * @capability triangle-attribution per-model triangle table with instance counts, for perf probes
+ */
+export function attributeTriangles(root, limit = 12) {
+    const lines = new Map();
+    let triangles = 0;
+    let casters = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        const per = triangleCount(mesh);
+        if (per === 0)
+            return;
+        const instances = mesh.isInstancedMesh === true
+            ? Math.max(0, mesh.count)
+            : 1;
+        const total = per * instances;
+        triangles += total;
+        if (mesh.castShadow === true)
+            casters += total;
+        const label = labelOf(mesh);
+        const key = `${label}#${mesh.geometry.uuid}`;
+        const line = lines.get(key);
+        if (line === undefined)
+            lines.set(key, { label, perInstance: per, instances, draws: 1, triangles: total });
+        else {
+            line.instances += instances;
+            line.draws += 1;
+            line.triangles += total;
+        }
+    });
+    const sorted = [...lines.values()].sort((a, b) => b.triangles - a.triangles);
+    return { triangles, casters, lines: limit > 0 ? sorted.slice(0, limit) : sorted };
+}
+/**
+ * The `render/triangles` probe for one scene: the table, its two headline numbers, and the one-line
+ * summary a report prints. Reads the graph on every call, so wrap it in a short cache when a
+ * snapshot reads counters and state together.
+ * @internal
+ */
+export function triangleProbe(root) {
+    const table = () => attributeTriangles(root);
+    return {
+        table,
+        counters: () => {
+            const { triangles, casters, lines } = table();
+            return { triangles, casters, lines: lines.length };
+        },
+        state: () => {
+            const { triangles, casters, lines } = table();
+            const top = lines[0];
+            return top === undefined
+                ? `${triangles} triangles`
+                : `${triangles} triangles · casters ${casters} · top ${top.label} ${top.triangles}`;
+        },
+    };
+}

package/dist/scatter/InstancedScatter.d.ts

@@ -1,5 +1,17 @@
+import * as THREE from "three";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 import { type ScatterInstance } from "@jgengine/core/world/scatterRegion";
+/** One instanced draw unit - a single species within a single spatial chunk. @internal */
+export interface ScatterBatch {
+    key: string;
+    item: string;
+    /** Per-instance transforms, parallel to `instances`. */
+    matrices: THREE.Matrix4[];
+    /** The placements themselves, so the level pass can read a stable id and a world position. */
+    instances: ScatterInstance[];
+}
+/** Groups resolved instances by spatial chunk then species so each batch is one cullable draw. @internal */
+export declare function scatterBatchInstances(instances: readonly ScatterInstance[], chunkSize: number): ScatterBatch[];
 /** Props for {@link InstancedScatter}: the resolved instances plus chunking/instance-cap knobs. */
 export interface InstancedScatterProps {
     instances: readonly ScatterInstance[];

package/dist/scatter/InstancedScatter.js

@@ -1,18 +1,21 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Suspense, useEffect, useMemo, useRef } from "react";
-import { useLoader } from "@react-three/fiber";
+import { Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import { useFrame, useLoader, useThree } from "@react-three/fiber";
 import * as THREE from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
 import { chunkScatterInstances } from "@jgengine/core/world/scatterRegion";
 import { beginFallbackSeam, reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
+import { createModelVariantSelector } from "@jgengine/core/world/modelLod";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
 import { buildScatterProxy } from "./scatterProxies.js";
 import { buildScatterModelSources, disposeScatterModelSources } from "./scatterModels.js";
+import { writeScatterVariantLevel } from "./scatterVariants.js";
 /** Chunk edge (m): dense fields split into this-sized buckets, each frustum-culled independently. */
 const DEFAULT_CHUNK_SIZE = 24;
 const DEFAULT_MAX_INSTANCES = 20000;
-/** Groups resolved instances by spatial chunk then species so each batch is one cullable draw. */
-function batchInstances(instances, chunkSize) {
+/** Groups resolved instances by spatial chunk then species so each batch is one cullable draw. @internal */
+export function scatterBatchInstances(instances, chunkSize) {
     const batches = [];
     const matrix = new THREE.Matrix4();
     const position = new THREE.Vector3();
@@ -29,12 +32,15 @@ function batchInstances(instances, chunkSize) {
             matrix.compose(position, quaternion, scale);
             const bucket = byItem.get(instance.item);
             if (bucket === undefined)
-                byItem.set(instance.item, [matrix.clone()]);
-            else
-                bucket.push(matrix.clone());
+                byItem.set(instance.item, { matrices: [matrix.clone()], instances: [instance] });
+            else {
+                bucket.matrices.push(matrix.clone());
+                bucket.instances.push(instance);
+            }
+        }
+        for (const [item, bucket] of byItem) {
+            batches.push({ key: `${chunk.key}:${item}`, item, matrices: bucket.matrices, instances: bucket.instances });
         }
-        for (const [item, matrices] of byItem)
-            batches.push({ key: `${chunk.key}:${item}`, item, matrices });
     }
     return batches;
 }
@@ -71,8 +77,68 @@ function ScatterModelSourceInstances({ source, matrices }) {
     }, [matrices, source]);
     return _jsx("instancedMesh", { ref: meshRef, args: [source.geometry, source.material, matrices.length], castShadow: true, receiveShadow: true });
 }
+/**
+ * One detail level's draw source, instanced across every chunk of one species. Each frame it asks the
+ * shared variant selector for each placement's level and draws only the ones it owns, composing into
+ * a reserved matrix slot so the far level's instances cost a second instanced draw, not per-frame
+ * allocation. A cell that holds near and far placements feeds both levels from the same batch.
+ */
+function ScatterVariantSourceInstances({ source, batch, level, selector }) {
+    const meshRef = useRef(null);
+    const camera = useThree((state) => state.camera);
+    const slots = useMemo(() => batch.matrices.map(() => new THREE.Matrix4()), [batch]);
+    const cameraPosition = useMemo(() => new THREE.Vector3(), []);
+    const lastCamera = useRef(new THREE.Vector3(Number.POSITIVE_INFINITY, 0, 0));
+    const writeLevel = useCallback((from) => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        const count = writeScatterVariantLevel(level, selector, from, batch.instances, batch.matrices, source.localMatrix, slots);
+        mesh.count = count;
+        mesh.visible = count > 0;
+        mesh.instanceMatrix.needsUpdate = true;
+        if (count > 0)
+            mesh.computeBoundingSphere();
+    }, [level, selector, batch, source, slots]);
+    useLayoutEffect(() => {
+        camera.getWorldPosition(cameraPosition);
+        lastCamera.current.copy(cameraPosition);
+        writeLevel(cameraPosition);
+    }, [camera, writeLevel, cameraPosition]);
+    useFrame((state) => {
+        state.camera.getWorldPosition(cameraPosition);
+        if (cameraPosition.distanceToSquared(lastCamera.current) < 0.25)
+            return;
+        lastCamera.current.copy(cameraPosition);
+        writeLevel(cameraPosition);
+    }, CAMERA_POST_FRAME_PRIORITY + 0.1);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [source.geometry, source.material, batch.matrices.length], castShadow: source.castShadow ?? true, receiveShadow: source.receiveShadow ?? true }));
+}
+/** Renders one level of a variant model: the level's own GLB harvested into instanced draws. */
+function ScatterVariantLevel({ model, url, level, selector, batches }) {
+    const gltf = useLoader(GLTFLoader, url, (loader) => {
+        loader.setMeshoptDecoder(MeshoptDecoder);
+    });
+    const { sources, root } = useMemo(() => {
+        const levelModel = { ...model, url, variants: undefined };
+        return buildScatterModelSources(gltf.scene, levelModel);
+    }, [gltf, model, url]);
+    useEffect(() => () => disposeScatterModelSources(root), [root]);
+    return (_jsx(_Fragment, { children: sources.map((source, sourceIndex) => batches.map((batch) => (_jsx(ScatterVariantSourceInstances, { source: source, batch: batch, level: level, selector: selector }, `${batch.key}:${sourceIndex}`)))) }));
+}
+/**
+ * A species whose model declares detail levels: one GLB per level, each level's instanced draws
+ * claiming only the placements the one shared selector put on it. The selector lives here so a
+ * placement keeps its hysteresis across every level component instead of each level deciding alone.
+ */
+function ScatterVariantSpecies({ model, batches }) {
+    const variants = model.variants;
+    const selector = useMemo(() => createModelVariantSelector(variants), [variants]);
+    useEffect(() => () => selector.clear(), [selector]);
+    return (_jsx(_Fragment, { children: variants.levels.map((level, index) => (_jsx(Suspense, { fallback: null, children: _jsx(ScatterVariantLevel, { model: model, url: level.url, level: index, selector: selector, batches: batches }) }, `${level.url}:${index}`))) }));
+}
 /** Loads one species' real catalog GLB once, harvests its instanceable draw sources, then GPU-instances them across every chunk that species appears in. */
-function ScatterModelSpecies({ model, batches }) {
+function ScatterSingleSpecies({ model, batches }) {
     const gltf = useLoader(GLTFLoader, model.url, (loader) => {
         loader.setMeshoptDecoder(MeshoptDecoder);
     });
@@ -80,6 +146,12 @@ function ScatterModelSpecies({ model, batches }) {
     useEffect(() => () => disposeScatterModelSources(root), [root]);
     return (_jsx(_Fragment, { children: sources.map((source, sourceIndex) => batches.map((batch) => (_jsx(ScatterModelSourceInstances, { source: source, matrices: batch.matrices }, `${batch.key}:${sourceIndex}`)))) }));
 }
+/** One species draw: the level switch for a model with `variants`, the single GLB otherwise. */
+function ScatterModelSpecies({ model, batches }) {
+    return model.variants === undefined
+        ? _jsx(ScatterSingleSpecies, { model: model, batches: batches })
+        : _jsx(ScatterVariantSpecies, { model: model, batches: batches });
+}
 /**
  * Renders resolved {@link ScatterInstance}s grouped into per-chunk, per-species GPU-instanced draws
  * that frustum-cull independently. Species with no `resolveItem` mapping (or a `null` result) render
@@ -89,7 +161,7 @@ function ScatterModelSpecies({ model, batches }) {
  * `resolveScatter` — never one node per placement.
  */
 export function InstancedScatter({ instances, chunkSize = DEFAULT_CHUNK_SIZE, maxInstances = DEFAULT_MAX_INSTANCES, resolveItem, }) {
-    const batches = useMemo(() => batchInstances(instances.length > maxInstances ? instances.slice(0, maxInstances) : instances, chunkSize), [instances, chunkSize, maxInstances]);
+    const batches = useMemo(() => scatterBatchInstances(instances.length > maxInstances ? instances.slice(0, maxInstances) : instances, chunkSize), [instances, chunkSize, maxInstances]);
     const { proxyBatches, modelSpecies } = useMemo(() => {
         // Dev diagnostic (no-op unless armed): re-zero the scatter seam before re-tallying which species
         // fall to a stylized proxy (no resolveItem mapping / a null result). Reported once per species.

package/dist/scatter/scatterVariants.d.ts

@@ -0,0 +1,30 @@
+import type * as THREE from "three";
+import type { ModelVariantSelector } from "@jgengine/core/world/modelLod";
+/** A scatter placement as the level pass reads it: a stable id and a world position. */
+export interface ScatterVariantMember {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** A camera position the level pass measures from. */
+export interface ScatterVariantCamera {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * Writes the matrices of the members the shared variant selector put on `level` into `out`, in source
+ * order, and returns how many were written. `out` is the level mesh's reserved capacity (one matrix
+ * per member), so a frame writes matrices and `count` without allocating.
+ *
+ * Every member is asked for its level through the same {@link ModelVariantSelector} the static prop
+ * path uses, so hysteresis and the `lodBandIndex` boundary are identical, and a chunk cell holding
+ * near and far members of one species splits between this level's draw and the other levels'.
+ *
+ * `keep` lets an orthogonal instance cull (tier distance, occlusion) drop a member without changing
+ * the level answer, so culling and level selection compose in one pass over the batch.
+ */
+export declare function writeScatterVariantLevel(level: number, selector: ModelVariantSelector, camera: ScatterVariantCamera, members: readonly ScatterVariantMember[], transforms: readonly THREE.Matrix4[], localMatrix: THREE.Matrix4, out: THREE.Matrix4[], keep?: (index: number) => boolean): number;
+/** Triangle total for per-level instance counts, so a fixture reports real geometry, not instance counts. */
+export declare function scatterVariantTriangles(counts: readonly number[], triangles: readonly number[]): number;

package/dist/scatter/scatterVariants.js

@@ -0,0 +1,36 @@
+/**
+ * Writes the matrices of the members the shared variant selector put on `level` into `out`, in source
+ * order, and returns how many were written. `out` is the level mesh's reserved capacity (one matrix
+ * per member), so a frame writes matrices and `count` without allocating.
+ *
+ * Every member is asked for its level through the same {@link ModelVariantSelector} the static prop
+ * path uses, so hysteresis and the `lodBandIndex` boundary are identical, and a chunk cell holding
+ * near and far members of one species splits between this level's draw and the other levels'.
+ *
+ * `keep` lets an orthogonal instance cull (tier distance, occlusion) drop a member without changing
+ * the level answer, so culling and level selection compose in one pass over the batch.
+ */
+export function writeScatterVariantLevel(level, selector, camera, members, transforms, localMatrix, out, keep) {
+    let count = 0;
+    for (let index = 0; index < members.length; index += 1) {
+        const member = members[index];
+        const dx = member.x - camera.x;
+        const dy = member.y - camera.y;
+        const dz = member.z - camera.z;
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (selector.level(member.id, distance) !== level)
+            continue;
+        if (keep !== undefined && !keep(index))
+            continue;
+        out[count].multiplyMatrices(transforms[index], localMatrix);
+        count += 1;
+    }
+    return count;
+}
+/** Triangle total for per-level instance counts, so a fixture reports real geometry, not instance counts. */
+export function scatterVariantTriangles(counts, triangles) {
+    let total = 0;
+    for (let index = 0; index < counts.length; index += 1)
+        total += (counts[index] ?? 0) * (triangles[index] ?? 0);
+    return total;
+}

package/dist/world/StaticObjectModels.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode } from "react";
 import * as THREE from "three";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import { type ModelVariantSelector } from "@jgengine/core/world/modelLod";
 import { type StaticObjectBatch } from "./staticObjectBatches.js";
 /**
  * Report what static object batching is doing to `debug_snapshot().systems`: the grouped batches, the
@@ -14,6 +15,23 @@ export declare function useStaticObjectBatchProbe(scene: THREE.Object3D, stats:
     instances: number;
     singles: number;
 }): void;
+/** Members of one level drawn through the individual renderer, for a level whose asset cannot be instanced. @internal */
+export declare function LevelSingles({ objects, level, selector, single }: {
+    objects: readonly SceneObject[];
+    level: number;
+    selector: ModelVariantSelector;
+    single: (object: SceneObject) => ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A batch whose model declares detail levels: every level draws its own instanced meshes and claims
+ * only the instances the shared distance switch put on it, so near and far trees of one species keep
+ * their own mesh inside one batch cell.
+ * @internal
+ */
+export declare function VariantStaticObjects({ batch, single }: {
+    batch: StaticObjectBatch;
+    single: (object: SceneObject) => ReactNode;
+}): import("react").JSX.Element;
 /** Render compatible authored or `scenery` props as shared model draws, preserving unsupported models. @internal */
 export declare function StaticObjectModels({ batch, single }: {
     batch: StaticObjectBatch;

package/dist/world/StaticObjectModels.js

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useFrame, useLoader } from "@react-three/fiber";
 import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import * as THREE from "three";
+import { createModelVariantSelector } from "@jgengine/core/world/modelLod";
 import { devtools } from "@jgengine/core/devtools/devtools";
 import { useGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "../render/modelLoad.js";
@@ -31,11 +32,26 @@ export function useStaticObjectBatchProbe(scene, stats) {
         },
     }), [scene]);
 }
-function ObjectSource({ source, objects, batch }) {
+/** Live members of one batch after the per-frame compatibility gate removed any that changed at runtime. */
+function useBatchMembers(batch) {
+    const ctx = useGameContext();
+    const [excluded, setExcluded] = useState([]);
+    const fallbackObjects = useRef(new Map());
+    useFrame(() => {
+        const next = incompatibleStaticObjectIds(batch, ctx.scene.object.get, ctx.scene.object.catalog, excluded, fallbackObjects.current);
+        if (next !== excluded)
+            setExcluded(next);
+    });
+    const objects = useMemo(() => batch.objects.filter((object) => !excluded.includes(object.instanceId)), [batch, excluded]);
+    return { objects, excluded };
+}
+function ObjectSource({ source, objects, batch, selector, level }) {
     const ctx = useGameContext();
     const visibility = useRenderVisibility();
     const ref = useRef(null);
     const scratch = useMemo(() => new THREE.Object3D(), []);
+    const cameraPosition = useRef(new THREE.Vector3());
+    const probe = useMemo(() => new THREE.Vector3(), []);
     const attach = useCallback((mesh) => {
         ref.current = mesh;
         if (mesh !== null)
@@ -45,26 +61,26 @@ function ObjectSource({ source, objects, batch }) {
         const mesh = ref.current;
         return () => { mesh?.dispose(); };
     }, [objects.length, source]);
-    useFrame(() => {
-        if (ref.current !== null)
-            syncStaticObjectSource(ref.current, source, objects, (id) => {
-                const object = ctx.scene.object.get(id);
-                return object !== null && object.catalogId === batch.objects[0].catalogId &&
-                    isCompatibleStaticObject(object, batch.model, ctx.scene.object.catalog(id)) ? object : null;
-            }, visibility.current, scratch);
+    useFrame((state) => {
+        if (ref.current === null)
+            return;
+        let accept;
+        if (selector !== undefined && level !== undefined) {
+            const camera = cameraPosition.current;
+            state.camera.getWorldPosition(camera);
+            accept = (live) => selector.level(live.instanceId, camera.distanceTo(probe.set(live.position[0], live.position[1], live.position[2]))) === level;
+        }
+        syncStaticObjectSource(ref.current, source, objects, (id) => {
+            const object = ctx.scene.object.get(id);
+            return object !== null && object.catalogId === batch.objects[0].catalogId &&
+                isCompatibleStaticObject(object, batch.model, ctx.scene.object.catalog(id)) ? object : null;
+        }, visibility.current, scratch, accept);
     }, CAMERA_POST_FRAME_PRIORITY + 0.1);
     return _jsx("instancedMesh", { ref: attach, args: [source.geometry, source.material, objects.length], userData: { [STATIC_BATCH_MESH_KEY]: true }, castShadow: source.castShadow, receiveShadow: source.receiveShadow, dispose: null });
 }
 function LoadedStaticObjects({ batch, single }) {
     const ctx = useGameContext();
-    const [excluded, setExcluded] = useState([]);
-    const fallbackObjects = useRef(new Map());
-    useFrame(() => {
-        const next = incompatibleStaticObjectIds(batch, ctx.scene.object.get, ctx.scene.object.catalog, excluded, fallbackObjects.current);
-        if (next !== excluded)
-            setExcluded(next);
-    });
-    const objects = useMemo(() => batch.objects.filter((object) => !excluded.includes(object.instanceId)), [batch, excluded]);
+    const { objects, excluded } = useBatchMembers(batch);
     const gltf = useLoader(sharedGltfLoader, batch.model.url);
     const supported = useMemo(() => canInstanceStaticScene(gltf.scene, gltf.animations), [gltf]);
     const harvested = useMemo(() => supported ? buildScatterModelSources(gltf.scene, batch.model) : null, [supported, gltf, batch.model]);
@@ -94,7 +110,75 @@ function LoadedStaticObjects({ batch, single }) {
         return _jsx(_Fragment, { children: batch.objects.map(single) });
     return _jsxs(_Fragment, { children: [harvested.sources.map((source, index) => objects.length === 0 ? null : _jsx(ObjectSource, { source: source, objects: objects, batch: batch }, index)), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
 }
+/** One detail level's GLB, harvested into instanced draws that only claim the instances the selector put on this level. */
+function VariantLevel({ url, model, batch, objects, level, selector, measure, single }) {
+    const ctx = useGameContext();
+    const gltf = useLoader(sharedGltfLoader, url);
+    const supported = useMemo(() => canInstanceStaticScene(gltf.scene, gltf.animations), [gltf]);
+    const harvested = useMemo(() => supported ? buildScatterModelSources(gltf.scene, model) : null, [supported, gltf, model]);
+    useEffect(() => () => { if (harvested !== null)
+        disposeScatterModelSources(harvested.root); }, [harvested]);
+    useEffect(() => {
+        if (harvested === null || !measure)
+            return;
+        const root = new THREE.Group();
+        for (const source of harvested.sources) {
+            const mesh = new THREE.Mesh(source.geometry, source.material);
+            mesh.matrixAutoUpdate = false;
+            mesh.matrix.copy(source.localMatrix);
+            root.add(mesh);
+        }
+        const key = batch.objects[0].catalogId;
+        if (batch.model.dims?.maxY === undefined) {
+            const bounds = measureLocalBounds(root);
+            if (bounds !== null)
+                reportMeasuredBounds(ctx, "object", key, bounds);
+        }
+        const triangles = measureLocalCollisionTriangles(root);
+        if (triangles !== null)
+            reportMeasuredCollisionMesh(ctx, "object", key, triangles);
+    }, [ctx, harvested, batch, measure]);
+    if (harvested === null)
+        return _jsx(LevelSingles, { objects: objects, level: level, selector: selector, single: single });
+    return _jsx(_Fragment, { children: harvested.sources.map((source, index) => _jsx(ObjectSource, { source: source, objects: objects, batch: batch, selector: selector, level: level }, index)) });
+}
+/** Members of one level drawn through the individual renderer, for a level whose asset cannot be instanced. @internal */
+export function LevelSingles({ objects, level, selector, single }) {
+    const ctx = useGameContext();
+    const visibility = useRenderVisibility();
+    const camera = useMemo(() => new THREE.Vector3(), []);
+    const probe = useMemo(() => new THREE.Vector3(), []);
+    const [members, setMembers] = useState(objects);
+    useFrame((state) => {
+        state.camera.getWorldPosition(camera);
+        const next = objects.flatMap((object) => {
+            const live = ctx.scene.object.get(object.instanceId);
+            if (live === null || !visibility.current(live.instanceId))
+                return [];
+            probe.set(live.position[0], live.position[1], live.position[2]);
+            return selector.level(live.instanceId, camera.distanceTo(probe)) === level ? [live] : [];
+        });
+        if (next.length !== members.length || next.some((member, index) => member !== members[index]))
+            setMembers(next);
+    });
+    return _jsx(_Fragment, { children: members.map(single) });
+}
+/**
+ * A batch whose model declares detail levels: every level draws its own instanced meshes and claims
+ * only the instances the shared distance switch put on it, so near and far trees of one species keep
+ * their own mesh inside one batch cell.
+ * @internal
+ */
+export function VariantStaticObjects({ batch, single }) {
+    const ctx = useGameContext();
+    const { objects, excluded } = useBatchMembers(batch);
+    const levels = batch.model.variants.levels;
+    const selector = useMemo(() => createModelVariantSelector(batch.model.variants), [batch.model]);
+    return _jsxs(_Fragment, { children: [levels.map((level, index) => (_jsx(VariantLevel, { url: level.url, model: { ...batch.model, url: level.url, variants: undefined }, batch: batch, objects: objects, level: index, selector: selector, measure: index === 0, single: single }, `${level.url}:${index}`))), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
+}
 /** Render compatible authored or `scenery` props as shared model draws, preserving unsupported models. @internal */
 export function StaticObjectModels({ batch, single }) {
-    return _jsx(IsolatedModelPart, { model: batch.model, seam: "object", children: _jsx(LoadedStaticObjects, { batch: batch, single: single }) });
+    return (_jsx(IsolatedModelPart, { model: batch.model, seam: "object", children: batch.model.variants === undefined
+            ? _jsx(LoadedStaticObjects, { batch: batch, single: single })
+            : _jsx(VariantStaticObjects, { batch: batch, single: single }) }));
 }

package/dist/world/staticObjectBatches.d.ts

@@ -63,5 +63,5 @@ export interface StaticBatchCounts {
 export declare function countStaticBatchDraws(scene: THREE.Object3D): StaticBatchCounts;
 /** Rejects loaded scenes whose behavior cannot be represented by static instanced draws. @internal */
 export declare function canInstanceStaticScene(scene: THREE.Object3D, clips: readonly THREE.AnimationClip[]): boolean;
-/** Compact visible placements and update picking identities without allocating per instance. @internal */
-export declare function syncStaticObjectSource(mesh: THREE.InstancedMesh, source: ScatterModelSource, objects: readonly SceneObject[], get: (id: string) => SceneObject | null, visible: (id: string) => boolean, scratch: THREE.Object3D): void;
+/** Compact visible placements and update picking identities without allocating per instance. `accept` narrows the range to one detail level of a variant model. @internal */
+export declare function syncStaticObjectSource(mesh: THREE.InstancedMesh, source: ScatterModelSource, objects: readonly SceneObject[], get: (id: string) => SceneObject | null, visible: (id: string) => boolean, scratch: THREE.Object3D, accept?: (live: SceneObject) => boolean): void;

package/dist/world/staticObjectBatches.js

@@ -155,8 +155,8 @@ export function canInstanceStaticScene(scene, clips) {
     });
     return supported;
 }
-/** Compact visible placements and update picking identities without allocating per instance. @internal */
-export function syncStaticObjectSource(mesh, source, objects, get, visible, scratch) {
+/** Compact visible placements and update picking identities without allocating per instance. `accept` narrows the range to one detail level of a variant model. @internal */
+export function syncStaticObjectSource(mesh, source, objects, get, visible, scratch, accept) {
     const ids = (mesh.userData[POINTER_OBJECT_INSTANCES_KEY] ??= []);
     const poses = (mesh.userData["jgStaticObjectPoses"] ??= []);
     if (mesh.userData["jgStaticObjectSource"] !== source) {
@@ -168,7 +168,7 @@ export function syncStaticObjectSource(mesh, source, objects, get, visible, scra
     const composed = scratch.matrixWorld;
     for (const object of objects) {
         const live = get(object.instanceId);
-        if (live === null || !visible(live.instanceId))
+        if (live === null || !visible(live.instanceId) || (accept !== undefined && !accept(live)))
             continue;
         if (poses[count] === live) {
             ids[count++] = live.instanceId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,9 +39,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.36.0",
-    "@jgengine/react": "^0.36.0",
-    "@jgengine/ws": "^0.36.0"
+    "@jgengine/core": "^0.38.0",
+    "@jgengine/react": "^0.38.0",
+    "@jgengine/ws": "^0.38.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.36.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.36.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/SKILL.md

@@ -29,7 +29,7 @@ Existing React games keep their entity store and use the focused
 
 - **Every game owns its UI end-to-end.** Custom composition, skin, placement, terminology, motion, and one main menu. The website/runner is a bare loader. Composing and reskinning the shipped blocks is correct use; a genre HUD kit, theme preset, or unarranged default stack dropped in as the game's identity is not.
 - **The main menu is a game front-end, not marketing.** The runner loads straight into the game's own menu; it offers the real front-end verbs the game supports — New Game, Continue/Load (save slots), Create/Choose character or class, Settings, Credits — each an authored screen in the game's art direction, not a landing page or raw scaffold. See [reference.md](reference.md#main-menu).
-- **Menus come from the shipped blocks, navigated by `useMenuNav`.** `TitleMenu`/`MenuScreen` (`@jgengine/react`) give the animated screen over the live scene (transform/opacity only, reduced-motion aware, unmounted after exit), `PauseMenu` the pause shape, `SettingsSection`/`SettingsTabs` the settings surface, `SaveSlotMenu` the slot list, `CreditsPanel` the credits screen, `LoadingScreen` the boot screen with rotating tips. `useMenuNav` (`@jgengine/react/menuNav`) is the one keyboard + gamepad focus model for any menu: roving focus, confirm/back, disabled rows skipped, no focus trap. Games keep wording, layout, art and terminology.
+- **Menus come from the shipped blocks, navigated by `useMenuNav`.** `GameMenu` (`@jgengine/react/gameMenu`) is the front-end surface: full-bleed over a live scene or key art, a logo sized by `--jg-menu-logo-size`, animated primary verbs with a generated selection tick, and a detail pane that follows the highlight — with `ContinuePane`, `NewCharacterPane`, `SaveSlotsPane` (cards with thumbnails), `CreditsPane` and the game's own settings surface as its panes, and `GamePauseMenu` the same system sized down. It locks the document scroll, so the surface is exactly the viewport at any size. `TitleMenu`/`MenuScreen` (`@jgengine/react`) remain for a plainer animated screen over the live scene (transform/opacity only, reduced-motion aware, unmounted after exit), `PauseMenu` the small pause shape, `SettingsSection`/`SettingsTabs` the settings surface, `SaveSlotMenu` a bare slot list, `CreditsPanel` the credits screen, `LoadingScreen` the boot screen with rotating tips. `useMenuNav` (`@jgengine/react/menuNav`) is the one keyboard + gamepad focus model for any menu: roving focus, confirm/back, disabled rows skipped, no focus trap. Games keep wording, layout, art and terminology.
 - **Settings is game-owned and reachable from a sensible place.** Every game ships settings as *its* settings — skinned and placed inline with its UI (main menu and pause), never the engine's stock face floated into a corner. Credits are a reachable in-game screen, not attribution buried in a build artifact.
 - **Route the front-end with `useMenuRouter`, and generate the credits.** `useMenuRouter(root)` is the screen stack behind title → save select → settings → credits: `open`/`back`/`replace`/`reset`, `path` for depth, and Escape-to-back bound by default (`escapeToBack: false` when the game owns Escape). `menuStackReducer` is the same transition as a pure function. For credits, `creditsForSourceIds(ids)` (`@jgengine/assets/credits`) turns the pack ids a game declares to `buildCatalog` into licensed, attributed sections, `mergeCredits` folds them into hand-authored lines, and `CreditsScreen` renders the result HudTheme-skinned.
 - **Skin the shared chrome with one `HudTheme` token object.** `hudThemeVars(theme)` emits the whole `--jg-*` vocabulary — bar fills and troughs, `HudFrame variation="themed"`, painted slots, the minimap ring, plus surfaces, edges, text, status colors, fonts, and rarity — so one theme spread on any HUD ancestor reskins the `@jgengine/react` primitives and the `registry/jgengine` blocks together. Author your own with `deriveHudTheme({ accent, surface })` or `hudTheme({ ... })`; `HUD_THEME_PRESETS` / `resolveHudTheme("<preset>")` are demo/scaffold starting points, never a game's identity. A component that needs a token no theme emits fails `check-hud-tokens` — add it to `HudTheme` rather than inventing a second vocabulary. Caller `style`/`renderItem` overrides still win.