@jgengine/shell 0.17.0 → 0.18.1

package/dist/scene/cityWindowMaterial.d.ts

@@ -1,12 +1,14 @@
 import * as THREE from "three";
 /**
  * Instanced facade material for city massing walls: a `MeshStandardMaterial` whose fragment stage
- * paints procedural window strips on the side faces of every instanced unit box — floor bands from
- * the district's real `floorHeight`, window columns on a fixed pitch, and a per-cell hash that
- * dims/lights individual windows so no two facades read identical. Ground floors (plus any buried
- * foundation, via the `instanceGroundOffset` attribute) stay solid wall so street level reads as
- * storefront/lobby rather than floating glass. Same `onBeforeCompile` idiom as the grass/terrain
- * materials; instance colors keep tinting the wall exactly like the plain massing material.
+ * paints a real facade on the side faces of every instanced unit box — floor bands from the
+ * district's `floorHeight`, spandrels between floors, framed panes with mullions, a per-cell hash
+ * that lights a minority of windows (emissive), and a ground floor of plinth, storefront glazing
+ * and fascia so street level never repeats floor 30. Two instanced attributes drive it:
+ * `instanceGroundOffset` (buried foundation to skip) and `instanceFacade` (`x` = per-building seed,
+ * `y` = facade kind — 0 punched openings, 1 curtain wall, 2 open parking deck). Same
+ * `onBeforeCompile` idiom as the grass/terrain materials; instance colors keep tinting the wall
+ * exactly like the plain massing material.
  * @internal — created by `CityRenderer` for the banded-piece InstancedMesh.
  */
 export declare function createCityWindowMaterial(options: {

package/dist/scene/cityWindowMaterial.js

@@ -1,12 +1,14 @@
 import * as THREE from "three";
 /**
  * Instanced facade material for city massing walls: a `MeshStandardMaterial` whose fragment stage
- * paints procedural window strips on the side faces of every instanced unit box — floor bands from
- * the district's real `floorHeight`, window columns on a fixed pitch, and a per-cell hash that
- * dims/lights individual windows so no two facades read identical. Ground floors (plus any buried
- * foundation, via the `instanceGroundOffset` attribute) stay solid wall so street level reads as
- * storefront/lobby rather than floating glass. Same `onBeforeCompile` idiom as the grass/terrain
- * materials; instance colors keep tinting the wall exactly like the plain massing material.
+ * paints a real facade on the side faces of every instanced unit box — floor bands from the
+ * district's `floorHeight`, spandrels between floors, framed panes with mullions, a per-cell hash
+ * that lights a minority of windows (emissive), and a ground floor of plinth, storefront glazing
+ * and fascia so street level never repeats floor 30. Two instanced attributes drive it:
+ * `instanceGroundOffset` (buried foundation to skip) and `instanceFacade` (`x` = per-building seed,
+ * `y` = facade kind — 0 punched openings, 1 curtain wall, 2 open parking deck). Same
+ * `onBeforeCompile` idiom as the grass/terrain materials; instance colors keep tinting the wall
+ * exactly like the plain massing material.
  * @internal — created by `CityRenderer` for the banded-piece InstancedMesh.
  */
 export function createCityWindowMaterial(options) {
@@ -25,10 +27,12 @@ export function createCityWindowMaterial(options) {
             .replace("#include <common>", `
 #include <common>
 attribute float instanceGroundOffset;
+attribute vec2 instanceFacade;
 varying vec3 vCityLocal;
 varying vec3 vCityScale;
 varying vec3 vCityNormal;
 varying float vCityGround;
+varying vec2 vCityFacade;
 `)
             .replace("#include <begin_vertex>", `
 #include <begin_vertex>
@@ -36,6 +40,7 @@ vCityLocal = position;
 vCityScale = vec3(length(instanceMatrix[0].xyz), length(instanceMatrix[1].xyz), length(instanceMatrix[2].xyz));
 vCityNormal = normal;
 vCityGround = instanceGroundOffset;
+vCityFacade = instanceFacade;
 `);
         shader.fragmentShader = shader.fragmentShader
             .replace("#include <common>", `
@@ -46,6 +51,8 @@ varying vec3 vCityLocal;
 varying vec3 vCityScale;
 varying vec3 vCityNormal;
 varying float vCityGround;
+varying vec2 vCityFacade;
+float cityLit = 0.0;
 float cityHash(vec2 cell) {
   return fract(sin(dot(cell, vec2(127.1, 311.7))) * 43758.5453);
 }
@@ -55,25 +62,77 @@ float cityHash(vec2 cell) {
 {
   // Side faces only — roofs and undersides stay plain wall.
   if (abs(vCityNormal.y) < 0.5) {
-    float along = abs(vCityNormal.x) > 0.5 ? (vCityLocal.z + 0.5) * vCityScale.z : (vCityLocal.x + 0.5) * vCityScale.x;
-    float faceWidth = abs(vCityNormal.x) > 0.5 ? vCityScale.z : vCityScale.x;
+    bool sideX = abs(vCityNormal.x) > 0.5;
+    float along = sideX ? (vCityLocal.z + 0.5) * vCityScale.z : (vCityLocal.x + 0.5) * vCityScale.x;
+    float faceWidth = sideX ? vCityScale.z : vCityScale.x;
     float up = (vCityLocal.y + 0.5) * vCityScale.y - vCityGround;
-    float pitch = 2.4;
-    float floorT = fract(up / uFloorHeight);
-    float colT = fract(along / pitch);
-    float floorIndex = floor(up / uFloorHeight);
-    float colIndex = floor(along / pitch);
-    bool window = up > uFloorHeight * 1.05 && floorT > 0.32 && floorT < 0.78 && colT > 0.2 && colT < 0.8
-      && along > 0.7 && along < faceWidth - 0.7;
-    if (window) {
-      float cell = cityHash(vec2(floorIndex, colIndex) + vec2(vCityScale.x, vCityScale.z));
-      vec3 pane = uWindowColor * mix(0.55, 1.25, cell);
-      diffuseColor.rgb = mix(diffuseColor.rgb, pane, 0.88);
+    float fh = uFloorHeight;
+    float seed = vCityFacade.x;
+    float kind = vCityFacade.y;
+    float face = (sideX ? 2.0 : 0.0) + (vCityNormal.x + vCityNormal.z > 0.0 ? 1.0 : 0.0);
+    vec3 wall = diffuseColor.rgb;
+    float floorT = fract(up / fh);
+    float floorIndex = floor(up / fh);
+    // The facade is a procedural stripe pattern with no mip chain, so once a floor band shrinks
+    // toward a pixel it aliases into speckled static. Measure the on-screen footprint of one metre
+    // of facade and dissolve the detail into its own average before that happens.
+    float facadeFootprint = fwidth(up) + fwidth(along);
+    float detail = 1.0 - smoothstep(fh * 0.08, fh * 0.45, facadeFootprint);
+    if (kind > 1.5) {
+      // Open parking deck: shadowed slots between column bays, solid spandrel below each level.
+      float bay = fract(along / 6.0);
+      bool slot = up > fh * 0.55 && floorT > 0.22 && floorT < 0.82
+        && along > 1.4 && along < faceWidth - 1.4 && bay > 0.14;
+      diffuseColor.rgb = slot ? wall * 0.16 : wall * (floorT < 0.18 ? 0.86 : 1.0);
+    } else if (up > fh * 1.02) {
+      float curtain = step(0.5, kind);
+      float pitch = mix(2.45, 1.75, curtain);
+      float glassW = mix(0.46, 0.7, curtain);
+      float margin = mix(0.9, 0.55, curtain);
+      float sillT = mix(0.36, 0.24, curtain);
+      float headT = mix(0.8, 0.87, curtain);
+      float colIndex = floor(along / pitch);
+      float colC = abs(fract(along / pitch) - 0.5) * 2.0;
+      bool inBand = along > margin && along < faceWidth - margin;
+      if (inBand && floorT > sillT && floorT < headT && colC < glassW) {
+        float cell = cityHash(vec2(floorIndex, colIndex) + vec2(seed * 41.0, face * 7.0));
+        float lit = step(0.9, cell);
+        vec3 pane = uWindowColor * mix(0.34, 0.86, cell);
+        pane = mix(pane, vec3(1.0, 0.9, 0.7), lit * 0.5);
+        // Pane frame + a transom across tall curtain-wall bays: the grid that reads as glazing.
+        float frame = step(glassW - 0.14, colC) + curtain * step(abs(floorT - (sillT + headT) * 0.5), 0.022);
+        diffuseColor.rgb = mix(pane, wall * mix(0.7, 0.5, curtain), clamp(frame, 0.0, 1.0));
+        cityLit = lit * (1.0 - clamp(frame, 0.0, 1.0)) * 0.3;
+      } else if (inBand && (floorT <= sillT || floorT >= headT)) {
+        diffuseColor.rgb = wall * mix(0.9, 0.78, curtain);
+        // Sill lip under each opening catches the light and breaks the flat band.
+        if (colC < glassW && floorT > sillT - 0.055) diffuseColor.rgb = wall * mix(1.08, 0.9, curtain);
+      }
+    } else {
+      // Ground floor: plinth, pier-and-glass shopfront, fascia band under the first slab.
+      if (up < 0.55) {
+        diffuseColor.rgb = wall * 0.62;
+      } else if (faceWidth > 5.0) {
+        float pier = abs(fract(along / 3.1) - 0.5) * 2.0;
+        bool store = up > 0.75 && up < fh * 0.74 && pier < 0.78
+          && along > 1.1 && along < faceWidth - 1.1;
+        if (store) {
+          diffuseColor.rgb = uWindowColor * 0.17;
+          cityLit = 0.1;
+        } else if (up > fh * 0.78 && up < fh * 0.96) {
+          diffuseColor.rgb = wall * 0.75;
+        }
+      }
     }
-    // A thin darker plinth line right above grade grounds the facade.
-    if (up > 0.0 && up < 0.35) diffuseColor.rgb *= 0.8;
+    vec3 distant = mix(wall, uWindowColor * 0.5, 0.42);
+    diffuseColor.rgb = mix(distant, diffuseColor.rgb, detail);
+    cityLit *= detail;
   }
 }
+`)
+            .replace("#include <emissivemap_fragment>", `
+#include <emissivemap_fragment>
+totalEmissiveRadiance += mix(uWindowColor, vec3(1.0, 0.86, 0.6), 0.6) * cityLit;
 `);
     };
     material.customProgramCacheKey = () => `jgengine-city-windows`;

package/dist/settings/appliedSettings.d.ts

@@ -1,5 +1,6 @@
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
 import { type GraphicsQuality, type SettingsStore } from "@jgengine/core/settings/settingsModel";
+import { type GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
 import { type TouchJoystickVariant, type TouchStyle } from "@jgengine/core/input/touchScheme";
 import type { AudioEngine } from "../audio/audioEngine.js";
 /** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
@@ -9,11 +10,12 @@ export declare function useTouchStyle(store: SettingsStore, fallback: TouchStyle
 /** Shell-internal: binds the SettingsStore joystick-variant choice (fixed vs floating) to the touch renderer. @internal */
 export declare function useTouchJoystickVariant(store: SettingsStore): TouchJoystickVariant;
 export declare function useSettingsRevision(store: SettingsStore): number;
-export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean): {
+export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean, overrides?: Partial<Record<GraphicsQuality, Partial<GraphicsProfile>>>): {
     shadows: boolean;
     dpr: number;
     uiScale: number;
     quality: GraphicsQuality;
+    profile: GraphicsProfile;
 };
 export declare function AudioSettingsBridge({ store, engine, buses, }: {
     store: SettingsStore;

package/dist/settings/appliedSettings.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 import { busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { resolveGraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANTS, TOUCH_STYLES, } from "@jgengine/core/input/touchScheme";
 /** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
 export const TOUCH_STYLE_AUTO = "auto";
@@ -26,16 +27,18 @@ export function useSettingsRevision(store) {
     const getVersion = useCallback(() => versionRef.current, []);
     return useSyncExternalStore(subscribe, getVersion, getVersion);
 }
-export function useGraphicsSettings(store, shadowsDefault) {
+export function useGraphicsSettings(store, shadowsDefault, overrides) {
     useSettingsRevision(store);
     const rawQuality = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
     const quality = GRAPHICS_QUALITY_DPR[rawQuality] !== undefined ? rawQuality : "high";
+    const profile = resolveGraphicsProfile(quality, overrides?.[quality]);
     const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
     return {
         shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
-        dpr: GRAPHICS_QUALITY_DPR[quality],
+        dpr: profile.renderScale,
         uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
         quality,
+        profile,
     };
 }
 export function AudioSettingsBridge({ store, engine, buses, }) {

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 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,37 @@
-import { useEffect } from "react";
+import { useEffect, useState, useCallback } from "react";
 import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
 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 = [];
         void multiplayer.backend.transport
             .joinServer({ gameId: multiplayer.gameId })
             .then((joined) => {
+            if (!joined.ok) {
+                if (!disposed) {
+                    setFailureReason(joined.reason);
+                    setStatus("failed");
+                }
+                return;
+            }
             if (disposed) {
                 void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId });
                 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 +96,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)
@@ -94,5 +113,6 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
                 void multiplayer.backend.transport.leaveServer({ serverId }).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 };
+/**
+ * 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;