@jgengine/shell 0.19.0 → 0.21.0

package/dist/world/WorldParticles.js

@@ -1,91 +1,183 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useRef, useState } from "react";
+import { devtools } from "@jgengine/core/devtools/devtools";
 import { createParticleSystem } from "@jgengine/core/vfx/particles";
 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 per-effect particle pool a graphics tier allows: the requested `max`
- * clamped to the tier cap, so lower tiers degrade density instead of dropping
- * effects entirely.
- */
+/** The requested visual pool clamped to the graphics tier. */
 export function resolveParticleBudget(quality, requested, particleCap) {
-    const cap = Math.max(1, Math.floor(particleCap ?? QUALITY_POOL_CAP[quality]));
-    return Math.max(1, Math.min(requested ?? cap, cap));
+    const rawCap = particleCap ?? QUALITY_POOL_CAP[quality];
+    const cap = Number.isFinite(rawCap) ? Math.max(1, Math.floor(rawCap)) : QUALITY_POOL_CAP[quality];
+    return Number.isFinite(requested) ? Math.max(1, Math.floor(Math.min(requested, cap))) : cap;
 }
 const MAX_CONCURRENT_BURSTS = 32;
-/**
- * Whether a spec change touches something the JSX reads (blending, static offset,
- * follow binding) and therefore needs a React re-render — config-only retunes are
- * applied imperatively to the live system and must stay render-free.
- *
- * @internal WorldParticles render-boundary helper, exported for its regression test.
- */
+const ZERO = [0, 0, 0];
+/** @internal Config retunes stay imperative; output changes require React rendering. */
 export function specNeedsRender(prev, next) {
-    if (prev.blending !== next.blending || prev.follow !== next.follow)
+    if (prev.blending !== next.blending || prev.follow !== next.follow || prev.space !== next.space)
         return true;
-    const a = prev.offset;
-    const b = next.offset;
+    if (prev.render?.shape !== next.render?.shape || prev.render?.stretch !== next.render?.stretch)
+        return true;
+    const a = prev.offset, b = next.offset;
     if (a === b)
         return false;
     if (a === undefined || b === undefined)
         return true;
     return a[0] !== b[0] || a[1] !== b[1] || a[2] !== b[2];
 }
-/**
- * Renders `ctx.particles` — the game-reachable particle seam. Standing emitters
- * become persistent `ParticleField`s (recreated only when their pool size changes,
- * retuned in place otherwise), `follow` emitters track their entity's live pose
- * each frame, and drained bursts become transient systems reaped once empty.
- * Auto-mounted by the player shell; pools are capped by graphics quality via
- * {@link resolveParticleBudget}.
- *
- * @internal
- */
-export function WorldParticles({ quality, particleCap }) {
+/** @internal Transform a simulation vector through a followed yaw and origin. */
+export function transformParticleVector(point, origin, yaw, inverse = false, out = [0, 0, 0]) {
+    const c = Math.cos(yaw), s = Math.sin(yaw);
+    const x = inverse ? point[0] - origin[0] : point[0];
+    const y = inverse ? point[1] - origin[1] : point[1];
+    const z = inverse ? point[2] - origin[2] : point[2];
+    out[0] = inverse ? c * x - s * z : origin[0] + c * x + s * z;
+    out[1] = inverse ? y : origin[1] + y;
+    out[2] = inverse ? s * x + c * z : origin[2] - s * x + c * z;
+    return out;
+}
+/** @internal Cosmetic catch-up follows game time, with bounded work after suspension. */
+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 }) {
     const ctx = useGameContext();
     const emittersRef = useRef(new Map());
     const burstsRef = useRef([]);
+    const previousTime = useRef(ctx.time.now());
+    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);
+    function pose(spec) {
+        const offset = spec.offset ?? [0, 0, 0];
+        const entity = spec.follow === undefined ? undefined : ctx.scene.entity.get(spec.follow);
+        if (entity === undefined || entity === null)
+            return { position: offset, yaw: 0, found: spec.follow === undefined };
+        if (spec.space === "local")
+            return { position: transformParticleVector(offset, entity.position, entity.rotationY), yaw: entity.rotationY, found: true };
+        return { position: [entity.position[0] + offset[0], entity.position[1] + offset[1], entity.position[2] + offset[2]], yaw: 0, found: true };
+    }
+    function syncPose(instance) {
+        const resolved = pose(instance.spec);
+        instance.pose = resolved;
+        if (instance.spec.space === "local" && resolved.found) {
+            instance.group?.position.set(...resolved.position);
+            if (instance.group !== null)
+                instance.group.rotation.y = resolved.yaw;
+        }
+        else if (instance.spec.space !== "local") {
+            const base = instance.spec.follow === undefined ? instance.spec.config.position ?? [0, 0, 0] : [0, 0, 0];
+            instance.system.configure({ position: [resolved.position[0] + base[0], resolved.position[1] + base[1], resolved.position[2] + base[2]] });
+        }
+        if (resolved.found && instance.spec.active !== false)
+            instance.system.start();
+        else
+            instance.system.stop();
+    }
+    function collisionFor(spec, frozenPose) {
+        return (from, to) => {
+            const current = spec();
+            const local = current.space === "local";
+            const resolved = frozenPose ?? emittersRef.current.get(current.id)?.pose ?? pose(current);
+            const start = local ? transformParticleVector(from, resolved.position, resolved.yaw) : from;
+            const end = local ? transformParticleVector(to, resolved.position, resolved.yaw) : to;
+            const direction = [end[0] - start[0], end[1] - start[1], end[2] - start[2]];
+            const maxDistance = Math.hypot(...direction);
+            if (maxDistance === 0)
+                return null;
+            const hit = ctx.scene.raycast({ origin: start, direction, maxDistance,
+                filter: { entities: false, objects: true, terrain: true, walls: true } });
+            if (hit === null)
+                return null;
+            return { position: local ? transformParticleVector(hit.point, resolved.position, resolved.yaw, true) : hit.point,
+                normal: local ? transformParticleVector(hit.normal, [0, 0, 0], resolved.yaw, true) : hit.normal };
+        };
+    }
+    function accelerationFor(spec, frozenPose) {
+        const worldScratch = [0, 0, 0];
+        const forceScratch = [0, 0, 0];
+        return (position, _velocity, out) => {
+            const current = spec();
+            const influence = current.environment;
+            if (influence === undefined) {
+                out[0] = out[1] = out[2] = 0;
+                return out;
+            }
+            const resolved = frozenPose ?? emittersRef.current.get(current.id)?.pose ?? pose(current);
+            const local = current.space === "local";
+            const world = local ? transformParticleVector(position, resolved.position, resolved.yaw, false, worldScratch) : position;
+            const force = ctx.environment.accelerationAt(world, ctx.time.now(), influence.windResponse ?? 0, influence.maxAcceleration ?? 100, influence.mask ?? 0xffffffff, forceScratch);
+            const result = local ? transformParticleVector(force, ZERO, resolved.yaw, true, forceScratch) : force;
+            out[0] = result[0];
+            out[1] = result[1];
+            out[2] = result[2];
+            return out;
+        };
+    }
     useEffect(() => {
         const emitters = emittersRef.current;
         function sync() {
             let changed = false;
-            const specs = ctx.particles.emitters();
             const liveIds = new Set();
-            for (const spec of specs) {
+            for (const spec of ctx.particles.emitters()) {
                 liveIds.add(spec.id);
                 const poolMax = resolveParticleBudget(quality, spec.config.max, particleCap);
                 const current = emitters.get(spec.id);
                 if (current === undefined || current.poolMax !== poolMax) {
-                    emitters.set(spec.id, {
-                        spec,
-                        poolMax,
-                        system: createParticleSystem({ ...spec.config, max: poolMax, seed: spec.id }),
-                    });
+                    const next = { spec, poolMax, group: current?.group ?? null, pose: pose(spec),
+                        system: createParticleSystem({ ...spec.config, max: poolMax, seed: spec.config.seed ?? spec.id }, { collision: collisionFor(() => next.spec), acceleration: accelerationFor(() => next.spec) }) };
+                    if (current !== undefined) {
+                        next.system.restore(current.system.snapshot());
+                        next.system.configure({ ...spec.config, max: poolMax, seed: spec.config.seed ?? spec.id }, true);
+                    }
+                    timing.current.poolsCreated++;
+                    if (current !== undefined)
+                        timing.current.poolsRetired++;
+                    emitters.set(spec.id, next);
+                    syncPose(next);
                     changed = true;
                 }
                 else if (current.spec !== spec) {
                     if (specNeedsRender(current.spec, spec))
                         changed = true;
-                    current.system.configure({ ...spec.config, max: poolMax });
+                    current.system.configure({ ...spec.config, max: poolMax, seed: spec.config.seed ?? spec.id }, true);
                     current.spec = spec;
+                    syncPose(current);
                 }
             }
             for (const id of emitters.keys()) {
                 if (liveIds.has(id))
                     continue;
                 emitters.delete(id);
+                timing.current.poolsRetired++;
                 changed = true;
             }
             for (const burst of ctx.particles.drainBursts()) {
+                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 system = createParticleSystem({ ...burst.config, max: poolMax, seed: burst.seq });
+                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) });
+                if (spec.space !== "local") {
+                    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);
-                burstsRef.current.push({ seq: burst.seq, system, blending: burst.blending ?? "additive" });
-                if (burstsRef.current.length > MAX_CONCURRENT_BURSTS)
+                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 });
+                if (burstsRef.current.length > MAX_CONCURRENT_BURSTS) {
                     burstsRef.current.shift();
+                    timing.current.poolsRetired++;
+                }
                 changed = true;
             }
             if (changed)
@@ -93,36 +185,92 @@ export function WorldParticles({ quality, particleCap }) {
         }
         sync();
         const off = ctx.particles.subscribe(sync);
+        return off;
+    }, [ctx, quality, particleCap]);
+    useEffect(() => {
+        if (!diagnostics)
+            return;
+        return devtools.probes.register("particles", () => {
+            let count = 0, capacity = 0, renderBufferBytes = 0;
+            const read = (system) => {
+                const buffers = system.buffers();
+                count += system.count();
+                capacity += buffers.positions.length / 3;
+                renderBufferBytes += buffers.positions.byteLength + buffers.previousPositions.byteLength + buffers.velocities.byteLength + buffers.sizes.byteLength + buffers.colors.byteLength + buffers.alphas.byteLength + buffers.ids.byteLength;
+            };
+            for (const instance of emittersRef.current.values())
+                read(instance.system);
+            for (const burst of burstsRef.current)
+                read(burst.system);
+            const sample = timing.current, fields = resources.current;
+            return { scope: "WorldParticles", emitters: emittersRef.current.size, bursts: burstsRef.current.length, count, capacity, renderBufferBytes,
+                poolsCreated: sample.poolsCreated, poolsRetired: sample.poolsRetired,
+                updateSamples: sample.updateSamples, lastUpdateMs: sample.lastUpdateMs, maxUpdateMs: sample.maxUpdateMs,
+                avgUpdateMs: sample.updateSamples === 0 ? 0 : sample.totalUpdateMs / sample.updateSamples,
+                droppedCatchupSeconds: sample.droppedCatchupSeconds,
+                resources: { ...fields, avgUploadMsPerField: fields.uploadSamples === 0 ? 0 : fields.totalUploadMs / fields.uploadSamples } };
+        });
+    }, [ctx, diagnostics]);
+    useEffect(() => {
+        previousTime.current = ctx.time.now();
         return () => {
-            off();
-            emitters.clear();
+            timing.current.poolsRetired += emittersRef.current.size + burstsRef.current.length;
+            emittersRef.current.clear();
             burstsRef.current = [];
         };
-    }, [ctx, quality, particleCap]);
+    }, [ctx]);
     useFrame(() => {
+        const started = diagnostics ? performance.now() : 0;
+        const gameTime = ctx.time.now();
+        const dt = resolveParticleDelta(previousTime.current, gameTime);
+        if (diagnostics)
+            timing.current.droppedCatchupSeconds += Math.max(0, gameTime - previousTime.current - dt);
+        previousTime.current = gameTime;
+        const impacts = [];
+        const collect = (id, system, effect, origin, yaw = 0) => {
+            const events = system.drainEvents();
+            for (const event of events) {
+                if (origin !== undefined) {
+                    event.position = transformParticleVector(event.position, origin, yaw);
+                    event.velocity = transformParticleVector(event.velocity, [0, 0, 0], yaw);
+                    if (event.normal !== undefined)
+                        event.normal = transformParticleVector(event.normal, [0, 0, 0], yaw);
+                }
+                if (effect !== undefined && event.type === "collision" && impacts.length < 16)
+                    impacts.push({ effect, event });
+            }
+            ctx.particles.reportEvents(id, events);
+        };
         for (const instance of emittersRef.current.values()) {
-            const follow = instance.spec.follow;
-            if (follow === undefined)
-                continue;
-            const entity = ctx.scene.entity.get(follow);
-            if (entity === null || entity === undefined)
-                continue;
-            const offset = instance.spec.offset ?? [0, 0, 0];
-            instance.system.configure({
-                position: [
-                    entity.position[0] + offset[0],
-                    entity.position[1] + offset[1],
-                    entity.position[2] + offset[2],
-                ],
-            });
+            syncPose(instance);
+            instance.system.update(dt);
+            const resolved = instance.spec.space === "local" ? instance.pose : undefined;
+            collect(instance.spec.id, instance.system, instance.spec.collisionEffect, resolved?.position, resolved?.yaw);
+        }
+        let finished = false;
+        for (const burst of burstsRef.current) {
+            burst.system.update(dt);
+            collect(`burst:${burst.seq}`, burst.system, burst.collisionEffect, burst.position, burst.rotationY);
+            if (burst.system.count() === 0) {
+                finished = true;
+                timing.current.poolsRetired++;
+            }
         }
-        const finished = burstsRef.current.filter((burst) => burst.system.count() === 0);
-        if (finished.length > 0) {
+        if (finished) {
             burstsRef.current = burstsRef.current.filter((burst) => burst.system.count() > 0);
             setGeneration((n) => n + 1);
         }
+        for (const { effect, event } of impacts) {
+            const { collision: _, ...config } = effect.config;
+            ctx.particles.burst({ ...config, position: event.position, rate: 0, deathEvents: false }, effect.count, effect.blending, { render: effect.render });
+        }
+        if (diagnostics) {
+            const elapsed = performance.now() - started, sample = timing.current;
+            sample.lastUpdateMs = elapsed;
+            sample.totalUpdateMs += elapsed;
+            sample.maxUpdateMs = Math.max(sample.maxUpdateMs, elapsed);
+            sample.updateSamples++;
+        }
     });
-    return (_jsxs(_Fragment, { children: [Array.from(emittersRef.current.values()).map((instance) => (_jsx("group", { position: instance.spec.follow === undefined && instance.spec.offset !== undefined
-                    ? instance.spec.offset
-                    : [0, 0, 0], children: _jsx(ParticleField, { system: instance.system, blending: instance.spec.blending ?? "normal" }) }, instance.spec.id))), burstsRef.current.map((burst) => (_jsx(ParticleField, { system: burst.system, blending: burst.blending }, burst.seq)))] }));
+    return _jsxs(_Fragment, { children: [Array.from(emittersRef.current.values()).map((instance) => _jsx("group", { ref: (group) => { instance.group = group; }, children: _jsx(ParticleField, { system: instance.system, advance: false, blending: instance.spec.blending ?? "normal", render: instance.spec.render, metrics: diagnostics ? resources.current : undefined }) }, instance.spec.id)), burstsRef.current.map((burst) => _jsx("group", { position: burst.position, rotation: [0, burst.rotationY, 0], children: _jsx(ParticleField, { system: burst.system, advance: false, blending: burst.blending, render: burst.render, metrics: diagnostics ? resources.current : undefined }) }, burst.seq))] });
 }

package/dist/world/WorldScene.d.ts

@@ -1,10 +1,11 @@
 import { type ComponentType, type ReactNode } from "react";
+import { type EditorDocument } from "@jgengine/core/editor/index";
 import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import { type SceneObject } from "@jgengine/core/scene/objectStore";
 import type { EntitySpriteConfig, ModelConfig, ObjectStyle } from "@jgengine/core/game/playableGame";
 import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
-export declare function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }: {
+export declare function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }: {
     entitySprites: Record<string, EntitySpriteConfig> | undefined;
     entityModels: Record<string, string | ModelConfig> | undefined;
     objectModels: Record<string, string | ModelConfig> | undefined;
@@ -15,6 +16,7 @@ export declare function WorldView({ entitySprites, entityModels, objectModels, o
     renderObject: ((object: SceneObject) => ReactNode) | undefined;
     selectedIds: ReadonlySet<string>;
     hideLocalActor: boolean;
+    editorLayers?: EditorDocument | undefined;
 }): import("react").JSX.Element;
 export declare function RemotePlayers({ rows, presenceInterpolationMs }: {
     rows: PresencePoseRow[];

package/dist/world/WorldScene.js

@@ -1,7 +1,14 @@
 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 { 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 { groupStaticObjects } from "./staticObjectBatches.js";
 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";
@@ -12,11 +19,12 @@ import { DefaultSurface, detailMaps } from "../render/defaultSurface.js";
 import { useDisposable } from "../render/useDisposable.js";
 import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
-import { resolveModel, resolveEntityModel, tryResolveCatalogModel } from "../render/resolveModel.js";
+import { resolveEntityModel, resolveObjectModel } from "../render/resolveModel.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
 import { writeEntityPose, writeRenderPose } 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, }) {
@@ -130,10 +138,15 @@ function WorldEnvironment({ environment: Environment }) {
     reportFallbackSeam("ground", "noScene");
     return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx(RockField, {})] }));
 }
-function WorldActors({ entitySprites, entityModels, objectModels, objectStyles, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {
+function WorldActors({ entitySprites, entityModels, objectModels, objectStyles, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
     const ctx = useGameContext();
     const entityIds = useSceneEntityIds();
     const objectIds = useSceneObjectIds();
+    const document = useLiveEditorDocument(editorLayers ?? EMPTY_DOCUMENT, editorLayers !== undefined);
+    const materialMarkers = useMemo(() => new Map(document.markers.map((marker) => [marker.id, marker])), [document]);
+    const authoredIds = useMemo(() => new Set(resolveAuthoredObjects(document).map((object) => object.instanceId)), [document]);
+    const batchCache = useRef(new Map());
+    const modelCache = useMemo(() => new Map(), [objectModels, assets]);
     const player = usePlayer();
     const targetId = useTarget(player.userId);
     const controlledId = useGameStore((c) => c.player.possession.active(player.userId));
@@ -148,6 +161,29 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
     useEffect(() => {
         endFallbackPass();
     });
+    const candidates = objectIds.flatMap((instanceId) => {
+        const object = ctx.scene.object.get(instanceId);
+        if (object === null)
+            return [];
+        const custom = renderObject?.(object);
+        const model = modelWithAuthoredNodeVisibility(modelWithAuthoredMaterials(resolveObjectModel(object, objectModels, assets, modelCache), { materialAssets: document.materialAssets, markers: materialMarkers.has(object.instanceId) ? [materialMarkers.get(object.instanceId)] : [] }, object.instanceId), materialMarkers.get(object.instanceId));
+        const style = objectStyles?.[object.catalogId];
+        // Reaching the primitive box means no model resolved. A present-but-unresolved objectModels
+        // key implies its asset pack is not pulled; an absent key is an omitted (often intended) mapping.
+        if ((custom === undefined || custom === null) && model === undefined && style?.hidden !== true) {
+            reportFallbackSeam("object", objectModels?.[object.catalogId] === undefined ? "omittedMapping" : "unpulledPack");
+        }
+        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 })), 24, batchCache.current);
+    batchCache.current = new Map(grouped.batches.map((batch) => [batch.key, batch]));
+    const candidatesById = new Map(candidates.map((candidate) => [candidate.object.instanceId, candidate]));
+    const renderSingle = (object) => {
+        object = ctx.scene.object.get(object.instanceId) ?? object;
+        const candidate = candidatesById.get(object.instanceId);
+        const model = modelWithAuthoredNodeVisibility(modelWithAuthoredMaterials(resolveObjectModel(object, objectModels, assets, modelCache), { materialAssets: document.materialAssets, markers: materialMarkers.has(object.instanceId) ? [materialMarkers.get(object.instanceId)] : [] }, object.instanceId), materialMarkers.get(object.instanceId));
+        return _jsx(ObjectMarker, { object: object, custom: object === candidate.object ? candidate.custom : renderObject?.(object), model: model, style: objectStyles?.[object.catalogId] }, object.instanceId);
+    };
     return (_jsxs(_Fragment, { children: [entityIds.map((entityId) => {
                 const entity = ctx.scene.entity.get(entityId);
                 if (entity === null || entity.name === WORLD_ITEM_ENTITY_NAME)
@@ -163,31 +199,10 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
                     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));
-            }), objectIds.map((instanceId) => {
-                const object = ctx.scene.object.get(instanceId);
-                if (object === null)
-                    return null;
-                const custom = renderObject?.(object);
-                const resolved = resolveModel(objectModels?.[object.catalogId], assets, {
-                    seam: "objectModels",
-                    key: object.catalogId,
-                }) ?? tryResolveCatalogModel(object.catalogId, assets);
-                // An authored per-placement animation override (marker.meta.animation → SceneObject.animation,
-                // #1276) wins over catalog resolution's default "auto"; absent, the resolved config is untouched.
-                const model = resolved !== undefined && object.animation !== undefined
-                    ? { ...resolved, animation: object.animation }
-                    : resolved;
-                const style = objectStyles?.[object.catalogId];
-                // Reaching the primitive box means no model resolved. A present-but-unresolved objectModels
-                // key implies its asset pack is not pulled; an absent key is an omitted (often intended) mapping.
-                if ((custom === undefined || custom === null) && model === undefined && style?.hidden !== true) {
-                    reportFallbackSeam("object", objectModels?.[object.catalogId] === undefined ? "omittedMapping" : "unpulledPack");
-                }
-                return (_jsx(ObjectMarker, { object: object, custom: custom, model: model, style: style }, instanceId));
-            })] }));
+            }), 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, }) {
-    return (_jsxs(_Fragment, { children: [_jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor })] }));
+export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
+    return (_jsxs(_Fragment, { children: [_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 })] }));
 }
 export function RemotePlayers({ rows, presenceInterpolationMs = 100 }) {
     const groups = useRef(new Map());

package/dist/world/staticObjectBatches.d.ts

@@ -0,0 +1,35 @@
+import * as THREE from "three";
+import type { ModelConfig, ObjectStyle } from "@jgengine/core/game/playableGame";
+import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { GameContextObjectEntry } from "@jgengine/core/runtime/gameContext";
+import type { ScatterModelSource } from "../scatter/scatterModels.js";
+/** @internal */
+export interface StaticObjectCandidate {
+    object: SceneObject;
+    model?: ModelConfig;
+    authored: boolean;
+    custom: boolean;
+    catalog: GameContextObjectEntry | null;
+    style?: ObjectStyle | undefined;
+}
+/** @internal */
+export interface StaticObjectBatch {
+    key: string;
+    model: ModelConfig;
+    objects: SceneObject[];
+}
+/** The same compatibility gate is used when live placements change after grouping. @internal */
+export declare function canBatchStaticObject(candidate: StaticObjectCandidate): boolean;
+/** Checks a live placement without constructing a grouping candidate. @internal */
+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[];
+/** Groups compatible authored props above eight placements per spatial cell. @internal */
+export declare function groupStaticObjects(candidates: readonly StaticObjectCandidate[], chunkSize?: number, previous?: ReadonlyMap<string, StaticObjectBatch>): {
+    batches: StaticObjectBatch[];
+    singles: StaticObjectCandidate[];
+};
+/** 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;