@jgengine/shell 0.27.0 → 0.28.0

package/dist/world/StaticObjectModels.d.ts

@@ -1,6 +1,19 @@
 import { type ReactNode } from "react";
+import * as THREE from "three";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
 import { type StaticObjectBatch } from "./staticObjectBatches.js";
+/**
+ * Report what static object batching is doing to `debug_snapshot().systems`: the grouped batches, the
+ * total instances behind them, and how many instances survived per-instance culling this frame. A
+ * batch whose instances are all outside the view contributes a draw of zero, so `drawn` is the culling
+ * evidence, not a claim.
+ * @internal
+ */
+export declare function useStaticObjectBatchProbe(scene: THREE.Object3D, stats: {
+    batches: number;
+    instances: number;
+    singles: number;
+}): void;
 /** 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

@@ -1,21 +1,46 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame, useLoader } from "@react-three/fiber";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import * as THREE from "three";
+import { devtools } from "@jgengine/core/devtools/devtools";
 import { useGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "../render/modelLoad.js";
 import { IsolatedModelPart } from "../render/SceneModels.js";
+import { freezeStaticTransforms } from "../render/staticTransforms.js";
 import { measureLocalBounds, reportMeasuredBounds } from "../render/measureBounds.js";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "../render/measureCollisionMesh.js";
 import { buildScatterModelSources, disposeScatterModelSources } from "../scatter/scatterModels.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
 import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
-import { canInstanceStaticScene, incompatibleStaticObjectIds, isCompatibleStaticObject, syncStaticObjectSource } from "./staticObjectBatches.js";
+import { canInstanceStaticScene, countStaticBatchDraws, incompatibleStaticObjectIds, isCompatibleStaticObject, STATIC_BATCH_MESH_KEY, syncStaticObjectSource } from "./staticObjectBatches.js";
+/**
+ * Report what static object batching is doing to `debug_snapshot().systems`: the grouped batches, the
+ * total instances behind them, and how many instances survived per-instance culling this frame. A
+ * batch whose instances are all outside the view contributes a draw of zero, so `drawn` is the culling
+ * evidence, not a claim.
+ * @internal
+ */
+export function useStaticObjectBatchProbe(scene, stats) {
+    const ref = useRef(stats);
+    ref.current = stats;
+    useEffect(() => devtools.probes.registerSystem("render/staticBatches", {
+        counters: () => ({ ...ref.current, ...countStaticBatchDraws(scene) }),
+        state: () => {
+            const { draws, drawn } = countStaticBatchDraws(scene);
+            return `${ref.current.batches} batches · ${draws} draws · ${drawn}/${ref.current.instances} instances drawn`;
+        },
+    }), [scene]);
+}
 function ObjectSource({ source, objects, batch }) {
     const ctx = useGameContext();
     const visibility = useRenderVisibility();
     const ref = useRef(null);
     const scratch = useMemo(() => new THREE.Object3D(), []);
+    const attach = useCallback((mesh) => {
+        ref.current = mesh;
+        if (mesh !== null)
+            freezeStaticTransforms(mesh);
+    }, []);
     useEffect(() => {
         const mesh = ref.current;
         return () => { mesh?.dispose(); };
@@ -28,7 +53,7 @@ function ObjectSource({ source, objects, batch }) {
                     isCompatibleStaticObject(object, batch.model, ctx.scene.object.catalog(id)) ? object : null;
             }, visibility.current, scratch);
     }, CAMERA_POST_FRAME_PRIORITY + 0.1);
-    return _jsx("instancedMesh", { ref: ref, args: [source.geometry, source.material, objects.length], castShadow: source.castShadow, receiveShadow: source.receiveShadow, dispose: null });
+    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();

package/dist/world/WorldParticles.d.ts

@@ -11,8 +11,9 @@ export declare function transformParticleVector(point: Vec3, origin: Vec3, yaw:
 /** @internal Cosmetic catch-up follows game time, with bounded work after suspension. */
 export declare function resolveParticleDelta(previousTime: number, gameTime: number): number;
 /** Renders the existing director and pooled simulator; named bursts reuse the standing pool. @internal */
-export declare function WorldParticles({ quality, particleCap, diagnostics }: {
+export declare function WorldParticles({ quality, particleCap, particleBudget, diagnostics }: {
     quality: GraphicsQuality;
     particleCap?: number;
+    particleBudget?: number;
     diagnostics?: boolean;
 }): ReactElement;

package/dist/world/WorldParticles.js

@@ -2,14 +2,16 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useRef, useState } from "react";
 import { devtools } from "@jgengine/core/devtools/devtools";
+import { DEFAULT_GRAPHICS_PROFILES } from "@jgengine/core/settings/graphicsProfile";
 import { createParticleSystem } from "@jgengine/core/vfx/particles";
+import { planParticleBudget } from "@jgengine/core/vfx/particleBudget";
 import { useGameContext } from "@jgengine/react/provider";
 import { ParticleField } from "../vfx/ParticleField.js";
-const QUALITY_POOL_CAP = { low: 128, medium: 256, high: 512, ultra: 1024 };
 /** The requested visual pool clamped to the graphics tier. */
 export function resolveParticleBudget(quality, requested, particleCap) {
-    const rawCap = particleCap ?? QUALITY_POOL_CAP[quality];
-    const cap = Number.isFinite(rawCap) ? Math.max(1, Math.floor(rawCap)) : QUALITY_POOL_CAP[quality];
+    const tier = DEFAULT_GRAPHICS_PROFILES[quality].particleCap;
+    const rawCap = particleCap ?? tier;
+    const cap = Number.isFinite(rawCap) ? Math.max(1, Math.floor(rawCap)) : tier;
     return Number.isFinite(requested) ? Math.max(1, Math.floor(Math.min(requested, cap))) : cap;
 }
 const MAX_CONCURRENT_BURSTS = 32;
@@ -43,11 +45,12 @@ export function resolveParticleDelta(previousTime, gameTime) {
     return Number.isFinite(previousTime) && Number.isFinite(gameTime) ? Math.max(0, Math.min(0.1, gameTime - previousTime)) : 0;
 }
 /** Renders the existing director and pooled simulator; named bursts reuse the standing pool. @internal */
-export function WorldParticles({ quality, particleCap, diagnostics = false }) {
+export function WorldParticles({ quality, particleCap, particleBudget, diagnostics = false }) {
     const ctx = useGameContext();
     const emittersRef = useRef(new Map());
     const burstsRef = useRef([]);
     const previousTime = useRef(ctx.time.now());
+    const budget = useRef({ cap: 0, particles: 0, dropped: [] });
     const timing = useRef({ poolsCreated: 0, poolsRetired: 0, updateSamples: 0, lastUpdateMs: 0, totalUpdateMs: 0, maxUpdateMs: 0, droppedCatchupSeconds: 0 });
     const resources = useRef({ fieldsMounted: 0, fieldsUnmounted: 0, liveFields: 0, attributeBytes: 0, totalUploadMs: 0, maxUploadMs: 0, uploadSamples: 0 });
     const [, setGeneration] = useState(0);
@@ -121,10 +124,23 @@ export function WorldParticles({ quality, particleCap, diagnostics = false }) {
         const emitters = emittersRef.current;
         function sync() {
             let changed = false;
+            const cap = resolveParticleBudget(quality, undefined, particleBudget ?? DEFAULT_GRAPHICS_PROFILES[quality].particleBudget);
+            const specs = ctx.particles.emitters();
+            const queued = ctx.particles.drainBursts();
+            const plan = planParticleBudget([
+                ...specs.map((spec) => ({ id: spec.id, priority: spec.priority ?? 0, requested: resolveParticleBudget(quality, spec.config.max, particleCap) })),
+                ...queued.map((burst) => ({ id: `burst:${burst.seq}`, priority: burst.priority ?? 0, requested: resolveParticleBudget(quality, Math.min(burst.count, burst.config.max ?? burst.count), particleCap) })),
+            ], cap);
+            const granted = new Map(plan.grants.map((grant) => [grant.id, grant.particles]));
+            budget.current = { cap, particles: plan.particles, dropped: plan.dropped };
             const liveIds = new Set();
-            for (const spec of ctx.particles.emitters()) {
+            for (const spec of specs) {
+                const poolMax = granted.get(spec.id) ?? 0;
+                if (poolMax <= 0) {
+                    emitters.delete(spec.id);
+                    continue;
+                }
                 liveIds.add(spec.id);
-                const poolMax = resolveParticleBudget(quality, spec.config.max, particleCap);
                 const current = emitters.get(spec.id);
                 if (current === undefined || current.poolMax !== poolMax) {
                     const next = { spec, poolMax, group: current?.group ?? null, pose: pose(spec),
@@ -155,14 +171,16 @@ export function WorldParticles({ quality, particleCap, diagnostics = false }) {
                 timing.current.poolsRetired++;
                 changed = true;
             }
-            for (const burst of ctx.particles.drainBursts()) {
+            for (const burst of queued) {
                 const named = burst.emitterId === undefined ? undefined : emitters.get(burst.emitterId);
                 if (named !== undefined) {
                     syncPose(named);
                     named.system.emit(burst.count);
                     continue;
                 }
-                const poolMax = resolveParticleBudget(quality, Math.min(burst.count, burst.config.max ?? burst.count), particleCap);
+                const poolMax = granted.get(`burst:${burst.seq}`) ?? 0;
+                if (poolMax <= 0)
+                    continue;
                 const spec = { id: `burst:${burst.seq}`, config: burst.config, ...burst.options };
                 const resolved = pose(spec);
                 const system = createParticleSystem({ ...burst.config, rate: 0, max: poolMax, seed: burst.config.seed ?? burst.seq }, { collision: collisionFor(() => spec, resolved), acceleration: accelerationFor(() => spec, resolved) });
@@ -170,7 +188,7 @@ export function WorldParticles({ quality, particleCap, diagnostics = false }) {
                     const base = spec.follow === undefined ? burst.config.position ?? [0, 0, 0] : [0, 0, 0];
                     system.configure({ position: [resolved.position[0] + base[0], resolved.position[1] + base[1], resolved.position[2] + base[2]] });
                 }
-                system.emit(burst.count);
+                system.emit(Math.min(burst.count, poolMax));
                 timing.current.poolsCreated++;
                 burstsRef.current.push({ seq: burst.seq, system, blending: burst.blending ?? "additive", render: spec.render, collisionEffect: spec.collisionEffect,
                     position: spec.space === "local" ? resolved.position : [0, 0, 0], rotationY: spec.space === "local" ? resolved.yaw : 0 });
@@ -186,7 +204,7 @@ export function WorldParticles({ quality, particleCap, diagnostics = false }) {
         sync();
         const off = ctx.particles.subscribe(sync);
         return off;
-    }, [ctx, quality, particleCap]);
+    }, [ctx, quality, particleCap, particleBudget]);
     useEffect(() => {
         if (!diagnostics)
             return;
@@ -204,6 +222,7 @@ export function WorldParticles({ quality, particleCap, diagnostics = false }) {
                 read(burst.system);
             const sample = timing.current, fields = resources.current;
             return { scope: "WorldParticles", emitters: emittersRef.current.size, bursts: burstsRef.current.length, count, capacity, renderBufferBytes,
+                cap: budget.current.cap, budgetParticles: budget.current.particles, dropped: budget.current.dropped.length, droppedIds: budget.current.dropped,
                 poolsCreated: sample.poolsCreated, poolsRetired: sample.poolsRetired,
                 updateSamples: sample.updateSamples, lastUpdateMs: sample.lastUpdateMs, maxUpdateMs: sample.maxUpdateMs,
                 avgUpdateMs: sample.updateSamples === 0 ? 0 : sample.totalUpdateMs / sample.updateSamples,

package/dist/world/WorldScene.js

@@ -1,14 +1,15 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { modelWithAuthoredMaterials } from "@jgengine/core/editor/materialAuthoring";
 import { modelWithAuthoredNodeVisibility } from "@jgengine/core/editor/modelNodeVisibility";
-import { useFrame } from "@react-three/fiber";
+import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { createEmptyEditorDocument } from "@jgengine/core/editor/index";
 import { resolveAuthoredObjects } from "@jgengine/core/world/authoredObjects";
 import { useLiveEditorDocument } from "../scene/AuthoredScene.js";
-import { StaticObjectModels } from "./StaticObjectModels.js";
+import { StaticObjectModels, useStaticObjectBatchProbe } from "./StaticObjectModels.js";
 import { groupStaticObjects } from "./staticObjectBatches.js";
+import { groundSpeed } from "@jgengine/core/scene/entityStore";
 import { objectVisualScale } from "@jgengine/core/scene/objectStore";
 import { WORLD_ITEM_ENTITY_NAME } from "@jgengine/core/game/worldItem";
 import { beginFallbackSeam, endFallbackPass, reportFallbackSeam, } from "@jgengine/core/devtools/fallbackSeams";
@@ -20,15 +21,18 @@ import { useDisposable } from "../render/useDisposable.js";
 import { WindClock } from "../render/modelWind.js";
 import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
+import { CharacterCrowd } from "../render/CharacterCrowd.js";
+import { CharacterCrowdRegistry, crowdEligible, crowdKindOf, crowdKindReady, } from "../render/crowdRegistry.js";
+import { characterLodTier, clearCharacterLodTier, setCharacterLodTier, } from "../render/characterLod.js";
 import { resolveEntityModel, resolveObjectModel } from "../render/resolveModel.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
-import { writeEntityPose, writeRenderPose } from "./entityPose.js";
+import { writePoseIfChanged, writeRenderPoseIfChanged, emptyPoseMemo } from "./entityPose.js";
 import { createSnapshotBuffer } from "@jgengine/core/runtime/snapshotBuffer";
 import { POINTER_ENTITY_KEY, POINTER_OBJECT_KEY } from "../pointer/pointerService.js";
 const EMPTY_DOCUMENT = createEmptyEditorDocument();
 const GROUND_SIZE = 160;
 const GROUND_SEGMENTS = 80;
-function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, selected, onSelect, }) {
+function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, selected, crowd, onSelect, }) {
     const groupRef = useRef(null);
     const ctx = useGameContext();
     const visibleRef = useRenderVisibility();
@@ -36,18 +40,40 @@ function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, select
     const role = entity.role;
     const name = entity.name;
     const color = isLocal ? "#4ade80" : role === "npc" ? colorFromId(name) : "#9ca3af";
+    const tierRef = useRef(undefined);
+    const crowdModel = custom === undefined && !isLocal && crowdEligible(model) && crowd !== undefined ? model : undefined;
+    const crowdKind = crowdModel === undefined ? undefined : crowdKindOf(crowdModel);
     const scratchRef = useRef([0, 0, 0, 0]);
-    useFrame(() => {
+    const memoRef = useRef(emptyPoseMemo());
+    useFrame((state) => {
         const group = groupRef.current;
         if (group === null)
             return;
         const live = ctx.scene.entity.get(entityId);
         if (live === null)
             return;
-        writeRenderPose(group, ctx, entityId, live, scratchRef.current);
-        group.visible = live.hidden !== true && visibleRef.current(entityId);
+        writeRenderPoseIfChanged(group, ctx, entityId, live, scratchRef.current, memoRef.current);
+        let tier;
+        if (crowdModel !== undefined && crowd !== undefined && crowdKind !== undefined && crowdKindReady(crowdKind)) {
+            const [x, y, z] = live.position;
+            const distance = Math.sqrt((state.camera.position.x - x) ** 2 + (state.camera.position.y - y) ** 2 + (state.camera.position.z - z) ** 2);
+            tier = characterLodTier(distance, crowdModel.lod === false ? undefined : crowdModel.lod, tierRef.current);
+            setCharacterLodTier(entityId, tier);
+            if (tier === "crowd") {
+                crowd.set(entityId, crowdKind, { x, y, z, rotationY: live.rotationY ?? 0, speed: groundSpeed(live) });
+            }
+            else {
+                crowd.delete(entityId);
+            }
+        }
+        tierRef.current = tier;
+        group.visible = live.hidden !== true && visibleRef.current(entityId) && tier !== "crowd";
     });
-    return (_jsxs("group", { ref: groupRef, userData: { [POINTER_ENTITY_KEY]: entityId }, onPointerDown: (event) => {
+    useEffect(() => () => {
+        crowd?.delete(entityId);
+        clearCharacterLodTier(entityId);
+    }, [crowd, entityId]);
+    return (_jsxs("group", { ref: groupRef, matrixAutoUpdate: false, userData: { [POINTER_ENTITY_KEY]: entityId }, onPointerDown: (event) => {
             event.stopPropagation();
             if (isLocal)
                 return;
@@ -61,6 +87,7 @@ function ObjectMarker({ object, custom, model, style, }) {
     const ctx = useGameContext();
     const visibleRef = useRenderVisibility();
     const instanceId = object.instanceId;
+    const memoRef = useRef(emptyPoseMemo());
     const [scaleX, scaleY, scaleZ] = objectVisualScale(object.visual);
     const color = object.visual?.color ?? style?.color ?? colorFromId(object.catalogId);
     const opacity = object.visual?.opacity ?? style?.opacity ?? 1;
@@ -71,10 +98,10 @@ function ObjectMarker({ object, custom, model, style, }) {
         const live = ctx.scene.object.get(instanceId);
         if (live === null)
             return;
-        writeEntityPose(group, live);
+        writePoseIfChanged(group, live, memoRef.current);
         group.visible = visibleRef.current(instanceId);
     });
-    return (_jsx("group", { ref: groupRef, userData: { [POINTER_OBJECT_KEY]: instanceId }, children: custom !== undefined && custom !== null ? (_jsx(MeasuredBoundsGroup, { target: "object", measureKey: object.catalogId, children: custom })) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: instanceId, measure: { target: "object", key: object.catalogId } })) : style?.hidden === true ? null : (_jsxs("mesh", { "position-y": 0.5 * scaleY, scale: [scaleX, scaleY, scaleZ], castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx(DefaultSurface, { color: color, transparent: opacity < 1, opacity: opacity })] })) }));
+    return (_jsx("group", { ref: groupRef, matrixAutoUpdate: false, userData: { [POINTER_OBJECT_KEY]: instanceId }, children: custom !== undefined && custom !== null ? (_jsx(MeasuredBoundsGroup, { target: "object", measureKey: object.catalogId, children: custom })) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: instanceId, measure: { target: "object", key: object.catalogId } })) : style?.hidden === true ? null : (_jsxs("mesh", { "position-y": 0.5 * scaleY, scale: [scaleX, scaleY, scaleZ], castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx(DefaultSurface, { color: color, transparent: opacity < 1, opacity: opacity })] })) }));
 }
 function GroundPlane() {
     const geometry = useMemo(() => {
@@ -141,6 +168,7 @@ function WorldEnvironment({ environment: Environment }) {
 }
 function WorldActors({ entitySprites, entityModels, objectModels, objectStyles, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
     const ctx = useGameContext();
+    const scene = useThree((state) => state.scene);
     const entityIds = useSceneEntityIds();
     const objectIds = useSceneObjectIds();
     const document = useLiveEditorDocument(editorLayers ?? EMPTY_DOCUMENT, editorLayers !== undefined);
@@ -151,6 +179,7 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
     const player = usePlayer();
     const targetId = useTarget(player.userId);
     const controlledId = useGameStore((c) => c.player.possession.active(player.userId));
+    const crowdRegistry = useMemo(() => new CharacterCrowdRegistry(), []);
     const handleSelect = (entity) => {
         const relation = ctx.scene.entity.canReceive(entity.id, "damage") === null ? "hostile" : "friendly";
         ctx.scene.entity.setTarget(controlledId, relation === "hostile" || entity.role === "npc" ? entity.id : null);
@@ -176,9 +205,15 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
         }
         return [{ object, model, custom, style, authored: authoredIds.has(instanceId), catalog: ctx.scene.object.catalog(instanceId) }];
     });
-    const grouped = groupStaticObjects(candidates.map((candidate) => ({ ...candidate, custom: candidate.custom !== undefined && candidate.custom !== null })), undefined, batchCache.current);
+    const grouped = groupStaticObjects(candidates.map((candidate) => ({ ...candidate, custom: candidate.custom !== undefined && candidate.custom !== null })), batchCache.current);
     batchCache.current = new Map(grouped.batches.map((batch) => [batch.key, batch]));
+    useStaticObjectBatchProbe(scene, {
+        batches: grouped.batches.length,
+        instances: grouped.batches.reduce((total, batch) => total + batch.objects.length, 0),
+        singles: grouped.singles.length,
+    });
     const candidatesById = new Map(candidates.map((candidate) => [candidate.object.instanceId, candidate]));
+    const crowdModels = new Map();
     const renderSingle = (object) => {
         object = ctx.scene.object.get(object.instanceId) ?? object;
         const candidate = candidatesById.get(object.instanceId);
@@ -199,8 +234,10 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
                 if ((custom === undefined || custom === null) && model === undefined && sprite === undefined) {
                     reportFallbackSeam("entity", "omittedMapping");
                 }
-                return (_jsx(EntityMarker, { entity: entity, custom: custom, model: model, sprite: sprite, isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), onSelect: handleSelect }, entityId));
-            }), grouped.singles.map((candidate) => renderSingle(candidate.object)), grouped.batches.map((batch) => _jsx(StaticObjectModels, { batch: batch, single: renderSingle }, batch.key))] }));
+                if (crowdEligible(model))
+                    crowdModels.set(crowdKindOf(model), model);
+                return (_jsx(EntityMarker, { entity: entity, custom: custom, model: model, sprite: sprite, isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), crowd: crowdRegistry, onSelect: handleSelect }, entityId));
+            }), crowdModels.size > 0 ? _jsx(CharacterCrowd, { models: [...crowdModels.values()], registry: crowdRegistry }) : null, grouped.singles.map((candidate) => renderSingle(candidate.object)), grouped.batches.map((batch) => _jsx(StaticObjectModels, { batch: batch, single: renderSingle }, batch.key))] }));
 }
 export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
     return (_jsxs(_Fragment, { children: [_jsx(WindClock, {}), _jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor, editorLayers: editorLayers })] }));

package/dist/world/entityPose.d.ts

@@ -14,6 +14,23 @@ export interface PoseSource {
 }
 /** @internal */
 export declare function writeEntityPose(target: PoseWritable, source: PoseSource): void;
+/** The pose last written to one marker group, reused across frames. @internal */
+export type PoseMemo = [number, number, number, number];
+/** A marker group that owns its own matrix instead of three recomposing it every frame. @internal */
+export interface MatrixPoseTarget extends PoseWritable {
+    updateMatrix(): void;
+}
+/** A memo that never matches, so the first write to a marker group always lands. @internal */
+export declare function emptyPoseMemo(): PoseMemo;
+/**
+ * Write a marker pose and recompose only when it changed. The marker group runs with
+ * `matrixAutoUpdate=false`, so an idle actor or a parked prop leaves its whole subtree out of the
+ * per-frame world-matrix pass instead of forcing every child to recompose (#2038).
+ * @internal
+ */
+export declare function writePoseIfChanged(target: MatrixPoseTarget, source: PoseSource, memo: PoseMemo): boolean;
+/** {@link writePoseIfChanged} for the interpolated pose in `ctx.sim`, falling back to `live`. @internal */
+export declare function writeRenderPoseIfChanged(target: MatrixPoseTarget, ctx: Pick<GameContext, "sim">, entityId: string, live: PoseSource, scratch: RenderPose, memo: PoseMemo): boolean;
 /** Write the interpolated render pose from `ctx.sim` (falls back to `live` when no history exists). @internal */
 export declare function writeRenderPose(target: PoseWritable, ctx: Pick<GameContext, "sim">, entityId: string, live: PoseSource, scratch: RenderPose): void;
 /** @internal */

package/dist/world/entityPose.js

@@ -3,6 +3,48 @@ export function writeEntityPose(target, source) {
     target.position.set(source.position[0], source.position[1], source.position[2]);
     target.rotation.y = source.rotationY;
 }
+/** A memo that never matches, so the first write to a marker group always lands. @internal */
+export function emptyPoseMemo() {
+    return [Number.NaN, Number.NaN, Number.NaN, Number.NaN];
+}
+/**
+ * Write a marker pose and recompose only when it changed. The marker group runs with
+ * `matrixAutoUpdate=false`, so an idle actor or a parked prop leaves its whole subtree out of the
+ * per-frame world-matrix pass instead of forcing every child to recompose (#2038).
+ * @internal
+ */
+export function writePoseIfChanged(target, source, memo) {
+    const [x, y, z] = source.position;
+    if (memo[0] === x && memo[1] === y && memo[2] === z && memo[3] === source.rotationY)
+        return false;
+    memo[0] = x;
+    memo[1] = y;
+    memo[2] = z;
+    memo[3] = source.rotationY;
+    target.position.set(x, y, z);
+    target.rotation.y = source.rotationY;
+    target.updateMatrix();
+    return true;
+}
+/** {@link writePoseIfChanged} for the interpolated pose in `ctx.sim`, falling back to `live`. @internal */
+export function writeRenderPoseIfChanged(target, ctx, entityId, live, scratch, memo) {
+    if (!ctx.sim.renderPose(entityId, scratch)) {
+        scratch[0] = live.position[0];
+        scratch[1] = live.position[1];
+        scratch[2] = live.position[2];
+        scratch[3] = live.rotationY;
+    }
+    if (memo[0] === scratch[0] && memo[1] === scratch[1] && memo[2] === scratch[2] && memo[3] === scratch[3])
+        return false;
+    memo[0] = scratch[0];
+    memo[1] = scratch[1];
+    memo[2] = scratch[2];
+    memo[3] = scratch[3];
+    target.position.set(scratch[0], scratch[1], scratch[2]);
+    target.rotation.y = scratch[3];
+    target.updateMatrix();
+    return true;
+}
 /** Write the interpolated render pose from `ctx.sim` (falls back to `live` when no history exists). @internal */
 export function writeRenderPose(target, ctx, entityId, live, scratch) {
     if (ctx.sim.renderPose(entityId, scratch)) {

package/dist/world/staticObjectBatches.d.ts

@@ -24,15 +24,43 @@ export declare function canBatchStaticObject(candidate: StaticObjectCandidate):
 export declare function isCompatibleStaticObject(object: SceneObject, model: ModelConfig | undefined, catalog: GameContextObjectEntry | null): boolean;
 /** Stable exclusion snapshot; only compatibility transitions allocate. @internal */
 export declare function incompatibleStaticObjectIds(batch: StaticObjectBatch, get: (id: string) => SceneObject | null, catalog: (id: string) => GameContextObjectEntry | null, previous: readonly string[], fallbackObjects?: Map<string, SceneObject>): readonly string[];
-/** Batch cell edge in metres: one instanced draw per model per cell, culled as a unit. @internal */
-export declare const STATIC_BATCH_CHUNK = 64;
 /** Smallest same-model group worth an instanced draw; below this each prop draws on its own. @internal */
-export declare const STATIC_BATCH_MIN = 3;
-/** Groups compatible authored or `scenery` props, at least {@link STATIC_BATCH_MIN} per spatial cell. @internal */
-export declare function groupStaticObjects(candidates: readonly StaticObjectCandidate[], chunkSize?: number, previous?: ReadonlyMap<string, StaticObjectBatch>): {
+export declare const STATIC_BATCH_MIN = 2;
+/**
+ * Batch cell edge in metres. One InstancedMesh has one bounding sphere, and three frustum-tests it in
+ * the shadow pass too, so a batch that spans the whole city submits every camera-visible instance to
+ * every shadow cascade. A cell keeps that test useful without fragmenting one model per prop.
+ * @internal
+ */
+export declare const STATIC_BATCH_CELL = 128;
+/**
+ * Groups compatible authored or `scenery` props by model inside {@link STATIC_BATCH_CELL} metres, at
+ * least {@link STATIC_BATCH_MIN} of a model. Culling stays per instance: `syncStaticObjectSource`
+ * compacts each batch's drawn range against the visibility predicate every frame, and the cell keeps
+ * the batch's one bounding sphere small enough that three's own frustum test still rejects it in the
+ * shadow pass. Props spread thinner than the minimum in a cell fall back to individual draws.
+ * @internal
+ */
+export declare function groupStaticObjects(candidates: readonly StaticObjectCandidate[], previous?: ReadonlyMap<string, StaticObjectBatch>, cell?: number): {
     batches: StaticObjectBatch[];
     singles: StaticObjectCandidate[];
 };
+/** Marks the instanced draws a static object batch owns so the batching probe can count them. @internal */
+export declare const STATIC_BATCH_MESH_KEY = "jgStaticObjectBatch";
+/** What one frame's static object batching produced. @internal */
+export interface StaticBatchCounts {
+    /** Instanced draws the loaded models actually submitted. */
+    draws: number;
+    /** Distinct instances inside those draws after the visibility predicate compacted them. */
+    drawn: number;
+}
+/**
+ * Sum the tagged draws in the live scene. `drawn` counts each instance once even though one instance
+ * appears in every material source's draw, so it is the number of instances the renderer was asked to
+ * draw this frame — a world-wide batch whose instances leave the view drops it without unmounting.
+ * @internal
+ */
+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 */

package/dist/world/staticObjectBatches.js

@@ -49,12 +49,24 @@ export function incompatibleStaticObjectIds(batch, get, catalog, previous, fallb
         return live !== null && !compatible(live) ? [live.instanceId] : [];
     });
 }
-/** Batch cell edge in metres: one instanced draw per model per cell, culled as a unit. @internal */
-export const STATIC_BATCH_CHUNK = 64;
 /** Smallest same-model group worth an instanced draw; below this each prop draws on its own. @internal */
-export const STATIC_BATCH_MIN = 3;
-/** Groups compatible authored or `scenery` props, at least {@link STATIC_BATCH_MIN} per spatial cell. @internal */
-export function groupStaticObjects(candidates, chunkSize = STATIC_BATCH_CHUNK, previous) {
+export const STATIC_BATCH_MIN = 2;
+/**
+ * Batch cell edge in metres. One InstancedMesh has one bounding sphere, and three frustum-tests it in
+ * the shadow pass too, so a batch that spans the whole city submits every camera-visible instance to
+ * every shadow cascade. A cell keeps that test useful without fragmenting one model per prop.
+ * @internal
+ */
+export const STATIC_BATCH_CELL = 128;
+/**
+ * Groups compatible authored or `scenery` props by model inside {@link STATIC_BATCH_CELL} metres, at
+ * least {@link STATIC_BATCH_MIN} of a model. Culling stays per instance: `syncStaticObjectSource`
+ * compacts each batch's drawn range against the visibility predicate every frame, and the cell keeps
+ * the batch's one bounding sphere small enough that three's own frustum test still rejects it in the
+ * shadow pass. Props spread thinner than the minimum in a cell fall back to individual draws.
+ * @internal
+ */
+export function groupStaticObjects(candidates, previous, cell = STATIC_BATCH_CELL) {
     const groups = new Map();
     const singles = [];
     for (const candidate of candidates) {
@@ -63,7 +75,7 @@ export function groupStaticObjects(candidates, chunkSize = STATIC_BATCH_CHUNK, p
             singles.push(candidate);
             continue;
         }
-        const key = JSON.stringify([object.catalogId, Math.floor(object.position[0] / chunkSize), Math.floor(object.position[2] / chunkSize), model]);
+        const key = JSON.stringify([object.catalogId, Math.floor(object.position[0] / cell), Math.floor(object.position[2] / cell), model]);
         let group = groups.get(key);
         if (group === undefined) {
             group = { batch: { key, model, objects: [] }, candidates: [] };
@@ -84,6 +96,28 @@ export function groupStaticObjects(candidates, chunkSize = STATIC_BATCH_CHUNK, p
     }
     return { batches, singles };
 }
+/** Marks the instanced draws a static object batch owns so the batching probe can count them. @internal */
+export const STATIC_BATCH_MESH_KEY = "jgStaticObjectBatch";
+/**
+ * Sum the tagged draws in the live scene. `drawn` counts each instance once even though one instance
+ * appears in every material source's draw, so it is the number of instances the renderer was asked to
+ * draw this frame — a world-wide batch whose instances leave the view drops it without unmounting.
+ * @internal
+ */
+export function countStaticBatchDraws(scene) {
+    let draws = 0;
+    const drawn = new Set();
+    scene.traverse((node) => {
+        if (node.userData[STATIC_BATCH_MESH_KEY] !== true)
+            return;
+        draws += 1;
+        const ids = node.userData[POINTER_OBJECT_INSTANCES_KEY];
+        if (Array.isArray(ids))
+            for (const id of ids)
+                drawn.add(id);
+    });
+    return { draws, drawn: drawn.size };
+}
 /** Rejects loaded scenes whose behavior cannot be represented by static instanced draws. @internal */
 export function canInstanceStaticScene(scene, clips) {
     if (clips.length > 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.27.0",
+  "version": "0.28.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",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.27.0",
-    "@jgengine/react": "^0.27.0",
-    "@jgengine/ws": "^0.27.0"
+    "@jgengine/core": "^0.28.0",
+    "@jgengine/react": "^0.28.0",
+    "@jgengine/ws": "^0.28.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.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.28.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.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/SKILL.md

@@ -29,6 +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.
 - **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.