@jgengine/shell 0.18.0 → 0.19.0

package/dist/structures/buildingSurface.js

@@ -0,0 +1,134 @@
+import { useEffect, useMemo, useState } from "react";
+import * as THREE from "three";
+const SURFACE_ROLES = ["color", "normal", "roughness", "ao", "metalness"];
+/** True when the surface names at least one map URL, so the batch needs the textured path. */
+export function surfaceHasMaps(surface) {
+    if (surface?.maps === undefined)
+        return false;
+    return SURFACE_ROLES.some((role) => surface.maps?.[role] !== undefined);
+}
+/** A stable key for bucketing instances that share one surface (same colour, maps, tiling, and response). */
+export function surfaceKey(surface) {
+    if (surface === undefined)
+        return "";
+    const repeat = surface.repeat === undefined ? 1 : surface.repeat;
+    const maps = surface.maps === undefined ? "" : SURFACE_ROLES.map((role) => surface.maps?.[role] ?? "").join(",");
+    const tiling = typeof repeat === "number" ? String(repeat) : repeat.join("x");
+    return `${surface.color ?? ""}|${maps}|${tiling}|${surface.roughness ?? ""}|${surface.metalness ?? ""}`;
+}
+function repeatOf(surface) {
+    const repeat = surface.repeat ?? 1;
+    return typeof repeat === "number" ? [repeat, repeat] : [repeat[0], repeat[1]];
+}
+const textureLoader = new THREE.TextureLoader();
+const loads = new Map();
+/** One shared decode per URL; a missing file (a pack without `ao.jpg`) resolves to null instead of failing the batch. */
+function loadSurfaceTexture(url) {
+    let pending = loads.get(url);
+    if (pending === undefined) {
+        pending = new Promise((resolve) => {
+            textureLoader.load(url, (texture) => resolve(texture), undefined, () => resolve(null));
+        });
+        loads.set(url, pending);
+    }
+    return pending;
+}
+/**
+ * Loads a surface's PBR maps and returns per-caller clones configured to tile `repeat` times per
+ * slot, or `undefined` until the first map arrives so the batch draws its flat colour meanwhile.
+ * Clones share the decoded image, so two kinds using one map at different repeats cost one
+ * download. Maps whose file is missing are skipped rather than failing the whole surface.
+ * @internal
+ */
+export function useBuildingSurfaceTextures(surface) {
+    const maps = surface?.maps;
+    const color = maps?.color;
+    const normal = maps?.normal;
+    const roughness = maps?.roughness;
+    const ao = maps?.ao;
+    const metalness = maps?.metalness;
+    const urls = useMemo(() => {
+        const record = {};
+        if (color !== undefined)
+            record.color = color;
+        if (normal !== undefined)
+            record.normal = normal;
+        if (roughness !== undefined)
+            record.roughness = roughness;
+        if (ao !== undefined)
+            record.ao = ao;
+        if (metalness !== undefined)
+            record.metalness = metalness;
+        return record;
+    }, [color, normal, roughness, ao, metalness]);
+    const [loaded, setLoaded] = useState(undefined);
+    useEffect(() => {
+        const entries = Object.entries(urls);
+        if (entries.length === 0) {
+            setLoaded(undefined);
+            return;
+        }
+        let cancelled = false;
+        Promise.all(entries.map(([role, url]) => loadSurfaceTexture(url).then((texture) => [role, texture]))).then((results) => {
+            if (cancelled)
+                return;
+            const record = {};
+            for (const [role, texture] of results)
+                if (texture !== null)
+                    record[role] = texture;
+            setLoaded(Object.keys(record).length === 0 ? undefined : record);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [urls]);
+    const [repeatX, repeatY] = surface === undefined ? [1, 1] : repeatOf(surface);
+    const textures = useMemo(() => {
+        if (loaded === undefined)
+            return undefined;
+        const out = {};
+        for (const role of SURFACE_ROLES) {
+            const source = loaded[role];
+            if (source === undefined)
+                continue;
+            const texture = source.clone();
+            texture.wrapS = THREE.RepeatWrapping;
+            texture.wrapT = THREE.RepeatWrapping;
+            texture.repeat.set(repeatX, repeatY);
+            texture.colorSpace = role === "color" ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+            texture.needsUpdate = true;
+            out[role] = texture;
+        }
+        return out;
+    }, [loaded, repeatX, repeatY]);
+    useEffect(() => () => {
+        if (textures === undefined)
+            return;
+        for (const role of SURFACE_ROLES)
+            textures[role]?.dispose();
+    }, [textures]);
+    return textures;
+}
+/** Applies a surface's colour, response, and loaded maps onto a standard or physical material in place. @internal */
+export function applyBuildingSurface(material, surface, textures) {
+    if (surface.color !== undefined)
+        material.color.set(surface.color);
+    if (surface.roughness !== undefined)
+        material.roughness = surface.roughness;
+    if (surface.metalness !== undefined)
+        material.metalness = surface.metalness;
+    if (textures !== undefined) {
+        if (textures.color !== undefined)
+            material.map = textures.color;
+        if (textures.normal !== undefined)
+            material.normalMap = textures.normal;
+        if (textures.roughness !== undefined)
+            material.roughnessMap = textures.roughness;
+        if (textures.ao !== undefined)
+            material.aoMap = textures.ao;
+        if (textures.metalness !== undefined)
+            material.metalnessMap = textures.metalness;
+        material.needsUpdate = true;
+    }
+    return material;
+}

package/dist/terrain/terrainDetailMaterial.js

@@ -48,6 +48,8 @@ export function createTerrainDetailMaterial(detail, textures) {
         uRockColor: { value: new THREE.Color(detail.rockColor) },
         uSandColor: { value: new THREE.Color(detail.sandColor) },
         uSnowColor: { value: new THREE.Color(detail.snowColor) },
+        uSweepDry: { value: new THREE.Vector3(...detail.sweeps.dry) },
+        uSweepWet: { value: new THREE.Vector3(...detail.sweeps.wet) },
         uRockSlopeStart: { value: detail.rockSlopeStart },
         uSnowHeight: { value: detail.snowHeight },
         uWaterLevel: { value: detail.waterLevel },
@@ -126,6 +128,8 @@ varying vec3 vJgWorldNormal;
 uniform vec3 uRockColor;
 uniform vec3 uSandColor;
 uniform vec3 uSnowColor;
+uniform vec3 uSweepDry;
+uniform vec3 uSweepWet;
 uniform float uRockSlopeStart;
 uniform float uSnowHeight;
 uniform float uWaterLevel;
@@ -149,9 +153,9 @@ float jgFleck = jgVNoise(jgWp / max(0.05, uDetailScale * 0.024));
 float jgFleckMid = jgVNoise(jgWp / max(0.12, uDetailScale * 0.07) + vec2(51.3, 7.9));
 vec3 jgBase = diffuseColor.rgb;
 jgBase *= mix(1.0 - 0.2 * uStrength, 1.0 + 0.16 * uStrength, jgFine);
-// Meadow patchwork: hue-shifted sun-dried sweeps and cooler lush pockets, not just darker spots.
-jgBase = mix(jgBase, jgBase * vec3(1.14, 1.05, 0.76), smoothstep(0.5, 0.8, jgMacro) * 0.55 * uStrength);
-jgBase = mix(jgBase, jgBase * vec3(0.78, 1.0, 0.86), smoothstep(0.52, 0.85, jgPatch) * 0.5 * uStrength);
+// Biome patchwork: hue-shifted dry sweeps and cooler wet pockets, tinted per-world via detail.sweeps.
+jgBase = mix(jgBase, jgBase * uSweepDry, smoothstep(0.5, 0.8, jgMacro) * 0.55 * uStrength);
+jgBase = mix(jgBase, jgBase * uSweepWet, smoothstep(0.52, 0.85, jgPatch) * 0.5 * uStrength);
 // Rolling large-scale light/dark sweeps keep far hills from flattening into one tone.
 jgBase *= 1.0 + (jgFbm(jgWp / (uMacroScale * 2.3) + vec2(9.1, 73.4)) - 0.5) * 0.22 * uStrength;
 jgBase *= 1.0 + (jgFleck - 0.5) * 0.48 * uStrength * jgNear;

package/dist/useShellMultiplayerSync.d.ts

@@ -1,9 +1,16 @@
 import { type Dispatch, type SetStateAction } from "react";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
-import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
+import { type PresencePoseRow } from "@jgengine/core/runtime/transport";
+import { type AuthoritativeFrameHandler } from "./worldSync.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
 /** Joins the multiplayer server for the live context and wires presence, feed relay, and chat sync until teardown. */
 export declare function useShellMultiplayerSync(ctx: GameContext | null, multiplayer: ShellMultiplayer | null, playable: PlayableGame, serverIdRef: {
     current: string | null;
-}, setRemotePlayers: Dispatch<SetStateAction<PresencePoseRow[]>>): void;
+}, setRemotePlayers: Dispatch<SetStateAction<PresencePoseRow[]>>, authoritativeFrameRef?: {
+    current: AuthoritativeFrameHandler | null;
+}): {
+    status: "joining" | "joined" | "failed";
+    failureReason: string | null;
+    retry: () => void;
+};

package/dist/useShellMultiplayerSync.js

@@ -1,23 +1,39 @@
-import { useEffect } from "react";
+import { useEffect, useState, useCallback } from "react";
 import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { createTransportSessionId } from "@jgengine/core/runtime/transport";
 import { attachWorldSync } from "./worldSync.js";
 /** Joins the multiplayer server for the live context and wires presence, feed relay, and chat sync until teardown. */
-export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef, setRemotePlayers) {
+export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef, setRemotePlayers, authoritativeFrameRef) {
+    const [status, setStatus] = useState("joining");
+    const [failureReason, setFailureReason] = useState(null);
+    const [attempt, setAttempt] = useState(0);
+    const retry = useCallback(() => setAttempt((value) => value + 1), []);
     useEffect(() => {
         if (ctx === null || multiplayer === null)
             return;
+        setStatus("joining");
+        setFailureReason(null);
         let disposed = false;
         const cleanups = [];
+        const sessionId = createTransportSessionId();
         void multiplayer.backend.transport
-            .joinServer({ gameId: multiplayer.gameId })
+            .joinServer({ gameId: multiplayer.gameId, sessionId })
             .then((joined) => {
+            if (!joined.ok) {
+                if (!disposed) {
+                    setFailureReason(joined.reason);
+                    setStatus("failed");
+                }
+                return;
+            }
             if (disposed) {
-                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId });
+                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId, sessionId }).catch(() => undefined);
                 return;
             }
             serverIdRef.current = joined.serverId;
+            setStatus("joined");
             if (isServerAuthoritative(playable.game.multiplayer) && multiplayer.backend.feeds !== undefined) {
-                cleanups.push(attachWorldSync(multiplayer.backend.feeds, joined.serverId, ctx));
+                cleanups.push(attachWorldSync(multiplayer.backend.feeds, joined.serverId, ctx, (revision) => authoritativeFrameRef?.current?.(revision)));
             }
             cleanups.push(multiplayer.backend.presenceSync.subscribe(joined.serverId, (rows) => {
                 setRemotePlayers(rows.filter((row) => row.userId !== multiplayer.userId));
@@ -82,7 +98,12 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
                 }
             }
         })
-            .catch(() => undefined);
+            .catch((error) => {
+            if (!disposed) {
+                setFailureReason(error instanceof Error ? error.message : "Connection failed");
+                setStatus("failed");
+            }
+        });
         return () => {
             disposed = true;
             for (const cleanup of cleanups)
@@ -91,8 +112,9 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
             serverIdRef.current = null;
             setRemotePlayers([]);
             if (serverId !== null) {
-                void multiplayer.backend.transport.leaveServer({ serverId }).catch(() => undefined);
+                void multiplayer.backend.transport.leaveServer({ serverId, sessionId }).catch(() => undefined);
             }
         };
-    }, [ctx, multiplayer, playable]);
+    }, [ctx, multiplayer, playable, attempt]);
+    return { status: multiplayer === null ? "joined" : status, failureReason, retry };
 }

package/dist/visibility/CullingProvider.d.ts

@@ -14,8 +14,9 @@ export declare function useRenderVisibility(): MutableRefObject<VisiblePredicate
  * conservative preload margin) are never submitted to the renderer, without unmounting them or
  * touching gameplay. UI, sky, terrain, and environment live outside this subtree and are unaffected.
  */
-export declare function CullingProvider({ config, children }: {
+export declare function CullingProvider({ config, drawDistance, children }: {
     config: VisibilityConfig | undefined;
+    drawDistance?: number;
     children: ReactNode;
 }): ReactNode;
 export {};

package/dist/visibility/CullingProvider.js

@@ -110,12 +110,17 @@ function viewFromCamera(camera) {
  * conservative preload margin) are never submitted to the renderer, without unmounting them or
  * touching gameplay. UI, sky, terrain, and environment live outside this subtree and are unaffected.
  */
-export function CullingProvider({ config, children }) {
+export function CullingProvider({ config, drawDistance, children }) {
     const ctx = useGameContext();
     const enabled = config?.enabled !== false;
     const predicateRef = useRef(ALWAYS_VISIBLE);
     const camera = useThree((state) => state.camera);
-    const driver = useMemo(() => (enabled ? buildSystem(ctx, config) : null), [ctx, config, enabled]);
+    const resolvedConfig = useMemo(() => {
+        if (drawDistance === undefined)
+            return config;
+        return { ...config, culling: { ...config?.culling, defaultMaxRenderDistance: config?.culling?.defaultMaxRenderDistance ?? drawDistance } };
+    }, [config, drawDistance]);
+    const driver = useMemo(() => (enabled ? buildSystem(ctx, resolvedConfig) : null), [ctx, resolvedConfig, enabled]);
     useFrame(() => {
         if (driver === null) {
             predicateRef.current = ALWAYS_VISIBLE;

package/dist/world/GridWorldScene.js

@@ -3,6 +3,7 @@ import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { resolveGridInstances } from "@jgengine/core/world/gridInstances";
 import { useDisposable } from "../render/useDisposable.js";
+import { TileLayerRenderer } from "./TileLayerRenderer.js";
 function isGridWorldFeature(feature) {
     return (feature.kind === "biomes" || feature.kind === "voxel" || feature.kind === "plots" || feature.kind === "tilemap");
 }
@@ -12,6 +13,9 @@ function isGridWorldFeature(feature) {
  * `cells`, following the same direct-buffer pattern as `InstancedBodies`.
  */
 export function GridWorldScene({ feature }) {
+    if (feature.kind === "tilemap" && feature.tileSet !== undefined) {
+        return _jsx(TileLayerRenderer, { config: feature });
+    }
     const instances = useMemo(() => (isGridWorldFeature(feature) ? resolveGridInstances(feature) : []), [feature]);
     const meshRef = useRef(null);
     const geometry = useDisposable(() => new THREE.BoxGeometry(1, 1, 1), []);

package/dist/world/TileLayerRenderer.d.ts

@@ -0,0 +1,9 @@
+import type { TilemapWorldConfig } from "@jgengine/core/world/features";
+/** Inputs for the instanced textured tile-layer renderer. */
+export interface TileLayerRendererProps {
+    config: TilemapWorldConfig;
+    parallax?: readonly [number, number];
+    pixelated?: boolean;
+}
+/** Renders a tilemap as one instanced quad mesh with atlas UV rectangles. */
+export declare function TileLayerRenderer({ config, parallax, pixelated }: TileLayerRendererProps): import("react").JSX.Element | null;

package/dist/world/TileLayerRenderer.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame, useLoader, useThree } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { sortingOrder } from "@jgengine/core/render/sprite2d";
+import { useDisposable } from "../render/useDisposable.js";
+import { resolveTileLayerInstances } from "./tileLayerInstances.js";
+/** Renders a tilemap as one instanced quad mesh with atlas UV rectangles. */
+export function TileLayerRenderer({ config, parallax = [1, 1], pixelated = true }) {
+    const tileSet = config.tileSet;
+    const { camera } = useThree();
+    const texture = useLoader(THREE.TextureLoader, tileSet?.atlas.image ?? "");
+    const instances = useMemo(() => resolveTileLayerInstances(config), [config]);
+    const meshRef = useRef(null);
+    const geometry = useDisposable(() => new THREE.PlaneGeometry(1, 1).rotateX(-Math.PI / 2), []);
+    const uvOffset = useMemo(() => new THREE.InstancedBufferAttribute(new Float32Array(Math.max(instances.length, 1) * 2), 2), [instances.length]);
+    const uvScale = useMemo(() => new THREE.InstancedBufferAttribute(new Float32Array(Math.max(instances.length, 1) * 2), 2), [instances.length]);
+    const material = useDisposable(() => {
+        const mat = new THREE.MeshBasicMaterial({ map: texture, transparent: true, alphaTest: 0.08, depthWrite: false });
+        mat.onBeforeCompile = (shader) => {
+            shader.vertexShader = shader.vertexShader.replace("#include <common>", "#include <common>\nattribute vec2 tileUvOffset;\nattribute vec2 tileUvScale;").replace("#include <uv_vertex>", "#include <uv_vertex>\n#ifdef USE_MAP\n  vMapUv = vMapUv * tileUvScale + tileUvOffset;\n#endif");
+        };
+        mat.customProgramCacheKey = () => "jgengine-tile-layer";
+        return mat;
+    }, [texture]);
+    useEffect(() => {
+        texture.colorSpace = THREE.SRGBColorSpace;
+        texture.magFilter = pixelated ? THREE.NearestFilter : THREE.LinearFilter;
+        texture.minFilter = pixelated ? THREE.NearestFilter : THREE.LinearMipmapLinearFilter;
+        texture.needsUpdate = true;
+    }, [texture, pixelated]);
+    useEffect(() => {
+        geometry.setAttribute("tileUvOffset", uvOffset);
+        geometry.setAttribute("tileUvScale", uvScale);
+    }, [geometry, uvOffset, uvScale]);
+    const matrix = useMemo(() => new THREE.Matrix4(), []);
+    useFrame(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        mesh.position.set(-camera.position.x * (1 - parallax[0]), 0, camera.position.z * (1 - parallax[1]));
+    });
+    useEffect(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        mesh.count = instances.length;
+        const array = mesh.instanceMatrix.array;
+        const offset = uvOffset.array;
+        const scale = uvScale.array;
+        for (let i = 0; i < instances.length; i += 1) {
+            const instance = instances[i];
+            matrix.makeTranslation(instance.x, 0, instance.z).toArray(array, i * 16);
+            offset.set(instance.uvOffset, i * 2);
+            scale.set(instance.uvScale, i * 2);
+        }
+        mesh.instanceMatrix.needsUpdate = true;
+        uvOffset.needsUpdate = true;
+        uvScale.needsUpdate = true;
+    }, [instances, matrix, uvOffset, uvScale]);
+    if (tileSet === undefined || instances.length === 0)
+        return null;
+    return _jsx("instancedMesh", { ref: meshRef, args: [geometry, material, instances.length], renderOrder: sortingOrder(["ground", "objects", "effects"], config.sortingLayer ?? "ground", 0), frustumCulled: false });
+}

package/dist/world/WorldParticles.d.ts

@@ -0,0 +1,31 @@
+import { type ReactElement } from "react";
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+import type { ParticleEmitterSpec } from "@jgengine/core/vfx/particleDirector";
+/**
+ * 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.
+ */
+export declare function resolveParticleBudget(quality: GraphicsQuality, requested: number | undefined, particleCap?: number): number;
+/**
+ * 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.
+ */
+export declare function specNeedsRender(prev: ParticleEmitterSpec, next: ParticleEmitterSpec): boolean;
+/**
+ * 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 declare function WorldParticles({ quality, particleCap }: {
+    quality: GraphicsQuality;
+    particleCap?: number;
+}): ReactElement;

package/dist/world/WorldParticles.js

@@ -0,0 +1,128 @@
+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 { 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.
+ */
+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 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.
+ */
+export function specNeedsRender(prev, next) {
+    if (prev.blending !== next.blending || prev.follow !== next.follow)
+        return true;
+    const a = prev.offset;
+    const 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 }) {
+    const ctx = useGameContext();
+    const emittersRef = useRef(new Map());
+    const burstsRef = useRef([]);
+    const [, setGeneration] = useState(0);
+    useEffect(() => {
+        const emitters = emittersRef.current;
+        function sync() {
+            let changed = false;
+            const specs = ctx.particles.emitters();
+            const liveIds = new Set();
+            for (const spec of specs) {
+                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 }),
+                    });
+                    changed = true;
+                }
+                else if (current.spec !== spec) {
+                    if (specNeedsRender(current.spec, spec))
+                        changed = true;
+                    current.system.configure({ ...spec.config, max: poolMax });
+                    current.spec = spec;
+                }
+            }
+            for (const id of emitters.keys()) {
+                if (liveIds.has(id))
+                    continue;
+                emitters.delete(id);
+                changed = true;
+            }
+            for (const burst of ctx.particles.drainBursts()) {
+                const poolMax = resolveParticleBudget(quality, Math.min(burst.count, burst.config.max ?? burst.count), particleCap);
+                const system = createParticleSystem({ ...burst.config, max: poolMax, seed: burst.seq });
+                system.emit(burst.count);
+                burstsRef.current.push({ seq: burst.seq, system, blending: burst.blending ?? "additive" });
+                if (burstsRef.current.length > MAX_CONCURRENT_BURSTS)
+                    burstsRef.current.shift();
+                changed = true;
+            }
+            if (changed)
+                setGeneration((n) => n + 1);
+        }
+        sync();
+        const off = ctx.particles.subscribe(sync);
+        return () => {
+            off();
+            emitters.clear();
+            burstsRef.current = [];
+        };
+    }, [ctx, quality, particleCap]);
+    useFrame(() => {
+        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],
+                ],
+            });
+        }
+        const finished = burstsRef.current.filter((burst) => burst.system.count() === 0);
+        if (finished.length > 0) {
+            burstsRef.current = burstsRef.current.filter((burst) => burst.system.count() > 0);
+            setGeneration((n) => n + 1);
+        }
+    });
+    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)))] }));
+}

package/dist/world/WorldScene.d.ts

@@ -16,6 +16,7 @@ export declare function WorldView({ entitySprites, entityModels, objectModels, o
     selectedIds: ReadonlySet<string>;
     hideLocalActor: boolean;
 }): import("react").JSX.Element;
-export declare function RemotePlayers({ rows }: {
+export declare function RemotePlayers({ rows, presenceInterpolationMs }: {
     rows: PresencePoseRow[];
+    presenceInterpolationMs?: number;
 }): import("react").JSX.Element;

package/dist/world/WorldScene.js

@@ -14,7 +14,8 @@ import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
 import { resolveModel, resolveEntityModel, tryResolveCatalogModel } from "../render/resolveModel.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
-import { writeEntityPose } from "./entityPose.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 GROUND_SIZE = 160;
 const GROUND_SEGMENTS = 80;
@@ -26,6 +27,7 @@ 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 scratchRef = useRef([0, 0, 0, 0]);
     useFrame(() => {
         const group = groupRef.current;
         if (group === null)
@@ -33,7 +35,7 @@ function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, select
         const live = ctx.scene.entity.get(entityId);
         if (live === null)
             return;
-        writeEntityPose(group, live);
+        writeRenderPose(group, ctx, entityId, live, scratchRef.current);
         group.visible = live.hidden !== true && visibleRef.current(entityId);
     });
     return (_jsxs("group", { ref: groupRef, userData: { [POINTER_ENTITY_KEY]: entityId }, onPointerDown: (event) => {
@@ -187,6 +189,46 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
 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 RemotePlayers({ rows }) {
-    return (_jsx(_Fragment, { children: rows.map((row) => (_jsxs("group", { position: [row.position.x, row.position.y, row.position.z], "rotation-y": row.rotationY, children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: colorFromId(row.userId) })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] }, row.userId))) }));
+export function RemotePlayers({ rows, presenceInterpolationMs = 100 }) {
+    const groups = useRef(new Map());
+    const buffers = useRef(new Map());
+    const rowsRef = useRef(rows);
+    rowsRef.current = rows;
+    useEffect(() => {
+        const active = new Set(rows.map((row) => row.userId));
+        for (const row of rows) {
+            let buffer = buffers.current.get(row.userId);
+            if (buffer === undefined) {
+                buffer = createSnapshotBuffer({ delayMs: presenceInterpolationMs, capacity: 16 });
+                buffers.current.set(row.userId, buffer);
+            }
+            else {
+                buffer.retune({ delayMs: presenceInterpolationMs });
+            }
+            buffer.push(row.lastSeenAt, row);
+        }
+        for (const userId of buffers.current.keys()) {
+            if (!active.has(userId))
+                buffers.current.delete(userId);
+        }
+    }, [rows, presenceInterpolationMs]);
+    useFrame(({ clock }) => {
+        const now = clock.getElapsedTime() * 1000;
+        for (const [userId, buffer] of buffers.current) {
+            const group = groups.current.get(userId);
+            const sample = buffer.sampleAt(now);
+            if (group === undefined || sample === null)
+                continue;
+            const before = sample.before;
+            const after = sample.after;
+            group.position.set(before.position.x + (after.position.x - before.position.x) * sample.alpha, before.position.y + (after.position.y - before.position.y) * sample.alpha, before.position.z + (after.position.z - before.position.z) * sample.alpha);
+            group.rotation.y = before.rotationY + (after.rotationY - before.rotationY) * sample.alpha;
+        }
+    });
+    return (_jsx(_Fragment, { children: rows.map((row) => (_jsxs("group", { ref: (group) => {
+                if (group === null)
+                    groups.current.delete(row.userId);
+                else
+                    groups.current.set(row.userId, group);
+            }, children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: colorFromId(row.userId) })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] }, row.userId))) }));
 }

package/dist/world/entityPose.d.ts

@@ -1,3 +1,5 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { RenderPose } from "@jgengine/core/runtime/poseInterpolation";
 export interface PoseWritable {
     position: {
         set(x: number, y: number, z: number): void;
@@ -12,5 +14,7 @@ export interface PoseSource {
 }
 /** @internal */
 export declare function writeEntityPose(target: PoseWritable, source: PoseSource): void;
+/** 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 */
 export declare function posesEqual(a: PoseSource, b: PoseSource): boolean;