@jgengine/shell 0.17.0 → 0.18.1

package/dist/postfx/PostProcessing.js

@@ -63,14 +63,11 @@ function syncSize(built, width, height, pixelRatio) {
  * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
- * `quality` (the player's graphics-quality setting) gates the passes whose cost
- * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
- * the whole scene for depth/normals and runs a multi-sample full-screen pass,
- * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
- * SMAA, tone mapping, and grade stay on every tier (SMAA is the cheap edge fix
- * for alpha-tested foliage that MSAA samples alone leave crawling).
+ * `stages` (resolved from the player's graphics profile) controls expensive passes
+ * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
+ * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages.
  */
-export function PostProcessing({ config, quality = "high" }) {
+export function PostProcessing({ config, quality = "high", stages }) {
     const gl = useThree((s) => s.gl);
     const scene = useThree((s) => s.scene);
     const camera = useThree((s) => s.camera);
@@ -87,8 +84,8 @@ export function PostProcessing({ config, quality = "high" }) {
         });
         const composer = new EffectComposer(gl, target);
         composer.addPass(new RenderPass(scene, camera));
-        const heavyPasses = quality === "high";
-        if (heavyPasses && config.ao !== undefined && config.ao !== false) {
+        const resolvedStages = stages ?? { ao: quality === "high", bloom: true, dof: quality === "high", smaa: true };
+        if (resolvedStages.ao && config.ao !== undefined && config.ao !== false) {
             const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
             ao.blendIntensity = config.ao.blend ?? 1;
             ao.updateGtaoMaterial({
@@ -96,26 +93,26 @@ export function PostProcessing({ config, quality = "high" }) {
                 distanceExponent: 1,
                 thickness: config.ao.distanceFalloff ?? 3.6,
                 scale: config.ao.intensity ?? 2.4,
-                samples: 16,
+                samples: quality === "high" ? 16 : 8,
             });
             composer.addPass(ao);
         }
-        if (config.bloom !== false) {
+        if (resolvedStages.bloom && config.bloom !== false) {
             const b = config.bloom ?? {};
             composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), b.strength ?? 0.32, b.radius ?? 0.55, b.threshold ?? 0.85));
         }
         let dof = null;
-        if (heavyPasses && config.dof !== undefined && config.dof !== false) {
+        if (resolvedStages.dof && config.dof !== undefined && config.dof !== false) {
             const d = config.dof;
             dof = new OverlayAwareBokehPass(scene, camera, {
                 focus: d.focus ?? 18,
-                aperture: d.aperture ?? 0.00025,
+                aperture: d.aperture ?? (quality === "high" ? 0.00025 : 0.00012),
                 maxblur: d.maxBlur ?? 0.01,
             });
             composer.addPass(dof);
         }
         // SMAA must run before OutputPass (linear-sRGB). Default on for post chains.
-        if (aa === "smaa") {
+        if (resolvedStages.smaa && aa === "smaa") {
             composer.addPass(new SMAAPass());
         }
         composer.addPass(new OutputPass());
@@ -131,7 +128,28 @@ export function PostProcessing({ config, quality = "high" }) {
             disposeGraph(graph);
             builtRef.current = null;
         };
-    }, [gl, scene, camera, config, quality]);
+    }, [gl, scene, camera, config, quality, stages]);
+    useEffect(() => {
+        const lut = config.grade !== undefined && config.grade !== false ? config.grade.lut : undefined;
+        const grade = builtRef.current?.grade;
+        if (lut === undefined || grade === null || grade === undefined)
+            return;
+        let cancelled = false;
+        const loader = new THREE.TextureLoader();
+        loader.loadAsync(lut.url).then((texture) => {
+            if (cancelled) {
+                texture.dispose();
+                return;
+            }
+            texture.colorSpace = THREE.SRGBColorSpace;
+            texture.minFilter = THREE.NearestFilter;
+            texture.magFilter = THREE.NearestFilter;
+            texture.generateMipmaps = false;
+            grade.uniforms.uLut.value = texture;
+            grade.uniforms.uLutSize.value = lut.size ?? 32;
+        }).catch(() => undefined);
+        return () => { cancelled = true; };
+    }, [config.grade]);
     useEffect(() => {
         const prevTone = gl.toneMapping;
         const prevExposure = gl.toneMappingExposure;

package/dist/postfx/gradeShader.js

@@ -17,12 +17,22 @@ const fragmentShader = /* glsl */ `
   uniform float uGrain;
   uniform float uChroma;
   uniform float uTime;
+  uniform sampler2D uLut;
+  uniform float uLutSize;
   varying vec2 vUv;
 
   float hash(vec2 p) {
     return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453);
   }
 
+  vec3 sampleLut(vec3 color) {
+    float size = max(uLutSize, 2.0);
+    vec3 c = clamp(color, 0.0, 1.0) * (size - 1.0);
+    float blue = floor(c.b);
+    vec2 uv = vec2((blue * size + c.r + 0.5) / (size * size), (c.g + 0.5) / size);
+    return texture2D(uLut, uv).rgb;
+  }
+
   void main() {
     vec2 dir = vUv - 0.5;
     // Chromatic aberration: split RGB along the radial direction, growing toward the edges.
@@ -35,6 +45,7 @@ const fragmentShader = /* glsl */ `
     c = pow(max(c, 0.0), vec3(uGamma));
     float luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
     c = mix(vec3(luma), c, uSaturation);
+    if (uLutSize > 1.0) c = sampleLut(c);
     vec2 d = vUv - 0.5;
     float vig = 1.0 - uVignette * smoothstep(0.6, 0.95, dot(d, d) * 2.2);
     c *= vig;
@@ -65,6 +76,8 @@ export function createGradePass(config = {}) {
             uGrain: { value: config.grain ?? DEFAULT_GRAIN },
             uChroma: { value: config.chromaticAberration ?? DEFAULT_CHROMA },
             uTime: { value: 0 },
+            uLut: { value: null },
+            uLutSize: { value: 0 },
         },
         vertexShader,
         fragmentShader,

package/dist/render/CascadedShadows.d.ts

@@ -1,3 +1,4 @@
+import * as THREE from "three";
 import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame";
 /**
  * Cascaded shadow maps for one directional light — outdoor scenes keep shadows past a
@@ -11,3 +12,13 @@ import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame
 export declare function CascadedShadows({ entry }: {
     entry: DirectionalLightingConfig;
 }): null;
+/** Structural slice of CSM so the patcher is testable without a renderer. */
+export interface CsmMaterialSetup {
+    setupMaterial(material: THREE.Material): void;
+}
+/**
+ * Run CSM's `setupMaterial` over every unpatched standard material in the scene,
+ * chaining rather than clobbering a material's own `onBeforeCompile`. Called every
+ * frame (WeakSet-guarded) so streamed meshes never render lit by all cascades at once.
+ */
+export declare function patchSceneMaterials(scene: THREE.Scene, csm: CsmMaterialSetup, patched: WeakSet<THREE.Material>): void;

package/dist/render/CascadedShadows.js

@@ -19,7 +19,6 @@ export function CascadedShadows({ entry }) {
     const scene = useThree((s) => s.scene);
     const csmRef = useRef(null);
     const patchedRef = useRef(new WeakSet());
-    const frameRef = useRef(0);
     useEffect(() => {
         const cascades = Math.max(2, Math.min(4, Math.floor(entry.cascades ?? 3)));
         const lightDirection = new THREE.Vector3(-entry.position[0], -entry.position[1], -entry.position[2]);
@@ -47,7 +46,6 @@ export function CascadedShadows({ entry }) {
         patchedRef.current = new WeakSet();
         patchSceneMaterials(scene, csm, patchedRef.current);
         csmRef.current = csm;
-        frameRef.current = 0;
         return () => {
             csm.dispose();
             csmRef.current = null;
@@ -71,16 +69,19 @@ export function CascadedShadows({ entry }) {
         if (csm === null)
             return;
         csm.camera = camera;
-        frameRef.current += 1;
-        // Async model mounts need setupMaterial — re-scan every 30 frames after the first.
-        if (frameRef.current === 1 || frameRef.current % 30 === 0) {
-            patchSceneMaterials(scene, csm, patchedRef.current);
-        }
+        // Every frame: a mesh that renders before setupMaterial receives all cascade
+        // lights at once (a cascades× sun) — the WeakSet keeps the traverse cheap.
+        patchSceneMaterials(scene, csm, patchedRef.current);
         csm.update();
     });
     return null;
 }
-function patchSceneMaterials(scene, csm, patched) {
+/**
+ * Run CSM's `setupMaterial` over every unpatched standard material in the scene,
+ * chaining rather than clobbering a material's own `onBeforeCompile`. Called every
+ * frame (WeakSet-guarded) so streamed meshes never render lit by all cascades at once.
+ */
+export function patchSceneMaterials(scene, csm, patched) {
     scene.traverse((obj) => {
         const mesh = obj;
         if (!mesh.isMesh)
@@ -89,7 +90,17 @@ function patchSceneMaterials(scene, csm, patched) {
         for (const mat of materials) {
             if (!isStandardMaterial(mat) || patched.has(mat))
                 continue;
+            const prior = mat.onBeforeCompile;
             csm.setupMaterial(mat);
+            const csmHook = mat.onBeforeCompile;
+            if (prior !== THREE.Material.prototype.onBeforeCompile && prior !== csmHook) {
+                // setupMaterial assigns onBeforeCompile, which would drop a material's own
+                // shader surgery (rim light, detail maps) — run both, the material's first.
+                mat.onBeforeCompile = function (shader, renderer) {
+                    prior.call(this, shader, renderer);
+                    csmHook.call(this, shader, renderer);
+                };
+            }
             patched.add(mat);
         }
     });

package/dist/render/EnvironmentLighting.d.ts

@@ -1,5 +1,8 @@
+import type { EnvironmentSource } from "@jgengine/core/render/environment";
 /** @internal Props for shell {@link EnvironmentLighting}. */
 export interface EnvironmentLightingProps {
+    /** Optional authored environment map; absent or `gradient` uses the procedural probe. */
+    source?: EnvironmentSource;
     /** IBL intensity. Default 0.35. */
     intensity?: number;
     /** Upper-hemisphere tint for the procedural sky probe. Default cool daylight. */
@@ -23,4 +26,4 @@ export interface EnvironmentLightingProps {
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export declare function EnvironmentLighting({ intensity, skyColor, groundColor, sunDirection, sunColor, }: EnvironmentLightingProps): null;
+export declare function EnvironmentLighting({ source, intensity, skyColor, groundColor, sunDirection, sunColor, }: EnvironmentLightingProps): null;

package/dist/render/EnvironmentLighting.js

@@ -1,6 +1,8 @@
 import { useThree } from "@react-three/fiber";
 import { useEffect } from "react";
 import * as THREE from "three";
+import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
+import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
 /**
  * Image-based lighting from a procedural sky/ground probe (not three's stock
  * RoomEnvironment gray studio box). Metals and dielectrics pick up sky color and
@@ -10,27 +12,61 @@ import * as THREE from "three";
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export function EnvironmentLighting({ intensity = 0.35, skyColor = "#87b5e0", groundColor = "#3d4a38", sunDirection, sunColor = "#fff2d6", }) {
+export function EnvironmentLighting({ source, intensity = 0.35, skyColor = "#87b5e0", groundColor = "#3d4a38", sunDirection, sunColor = "#fff2d6", }) {
     const gl = useThree((state) => state.gl);
     const scene = useThree((state) => state.scene);
     useEffect(() => {
         const pmrem = new THREE.PMREMGenerator(gl);
-        const probe = buildSkyProbeScene({ skyColor, groundColor, sunDirection, sunColor });
-        const target = pmrem.fromScene(probe, 0.04);
+        let target;
+        let loadedTexture;
+        let cancelled = false;
+        const effective = source?.kind === "gradient" ? source : undefined;
+        const apply = (next, rotation) => {
+            if (cancelled) {
+                next.dispose();
+                return;
+            }
+            target = next;
+            scene.environment = next.texture;
+            if (rotation !== undefined)
+                scene.environmentRotation = new THREE.Euler(0, rotation, 0);
+        };
         const previous = scene.environment;
-        scene.environment = target.texture;
+        const previousRotation = scene.environmentRotation;
+        if (source?.kind === "hdri") {
+            const Loader = /\.exr(?:$|\?)/i.test(source.url) ? EXRLoader : RGBELoader;
+            new Loader().loadAsync(source.url).then((texture) => {
+                loadedTexture = texture;
+                texture.mapping = THREE.EquirectangularReflectionMapping;
+                apply(pmrem.fromEquirectangular(texture), source.rotation);
+            }).catch(() => undefined);
+        }
+        else if (source?.kind === "cube") {
+            new THREE.CubeTextureLoader().loadAsync(source.urls).then((texture) => {
+                loadedTexture = texture;
+                apply(pmrem.fromCubemap(texture));
+            }).catch(() => undefined);
+        }
+        else {
+            const probe = buildSkyProbeScene({ skyColor: effective?.sky ?? skyColor, groundColor: effective?.ground ?? groundColor, sunDirection, sunColor: effective?.sun ?? sunColor });
+            apply(pmrem.fromScene(probe, 0.04));
+            disposeScene(probe);
+        }
         const sceneWithIntensity = scene;
         const previousIntensity = sceneWithIntensity.environmentIntensity;
-        sceneWithIntensity.environmentIntensity = intensity;
-        disposeScene(probe);
-        pmrem.dispose();
+        sceneWithIntensity.environmentIntensity = source?.intensity ?? intensity;
         return () => {
-            target.dispose();
+            cancelled = true;
+            pmrem.dispose();
+            target?.dispose();
+            loadedTexture?.dispose();
             scene.environment = previous;
+            if (previousRotation !== undefined)
+                scene.environmentRotation = previousRotation;
             if (previousIntensity !== undefined)
                 sceneWithIntensity.environmentIntensity = previousIntensity;
         };
-    }, [gl, scene, intensity, skyColor, groundColor, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
+    }, [gl, scene, source, intensity, skyColor, groundColor, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
     return null;
 }
 function buildSkyProbeScene(options) {

package/dist/render/SceneLighting.d.ts

@@ -1,6 +1,20 @@
-import type { BackdropConfig, LightingConfig } from "@jgengine/core/game/playableGame";
-export declare function ConfiguredLighting({ lighting }: {
+import type { DirectionalLight } from "three";
+import type { BackdropConfig, LightingConfig, PointLightingConfig } from "@jgengine/core/game/playableGame";
+import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+/** Default cap for combined dynamic point and spot lights. */
+export declare const POINT_LIGHT_BUDGET = 8;
+/** @internal Clamp point lights for the runtime budget. */
+export declare function resolvePointLightBudget(entries: readonly PointLightingConfig[] | undefined): readonly PointLightingConfig[];
+/**
+ * Refresh a directional light's shadow projection after its frustum bounds change.
+ * R3F pierced `shadow-camera-*` props write the bounds but never call
+ * `updateProjectionMatrix()`, so depth renders with the stale default ~10×10 box
+ * and `shadowCameraSize` is silently inert.
+ */
+export declare function syncShadowProjection(light: DirectionalLight): void;
+export declare function ConfiguredLighting({ lighting, profile }: {
     lighting: LightingConfig;
+    profile?: GraphicsProfile;
 }): import("react").JSX.Element;
 export declare function BackdropFog({ fog }: {
     fog: BackdropConfig["fog"];

package/dist/render/SceneLighting.js

@@ -1,22 +1,72 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef } from "react";
 import { CascadedShadows } from "./CascadedShadows.js";
 const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
+/** Default cap for combined dynamic point and spot lights. */
+export const POINT_LIGHT_BUDGET = 8;
+/** @internal Clamp point lights for the runtime budget. */
+export function resolvePointLightBudget(entries) {
+    if (entries === undefined || entries.length <= POINT_LIGHT_BUDGET)
+        return entries ?? [];
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(`[jgengine:lighting] ${entries.length} point lights requested — clamped to budget ${POINT_LIGHT_BUDGET}`);
+    }
+    return entries.slice(0, POINT_LIGHT_BUDGET);
+}
+function resolveDynamicLights(lighting) {
+    const point = lighting.point ?? [];
+    const spot = lighting.spot ?? [];
+    const budget = Math.max(0, Math.floor(lighting.maxDynamicLights ?? POINT_LIGHT_BUDGET));
+    if (point.length + spot.length <= budget)
+        return { point, spot };
+    if (typeof console !== "undefined" && typeof console.warn === "function")
+        console.warn(`[jgengine:lighting] ${point.length + spot.length} dynamic lights requested — clamped to budget ${budget}`);
+    return { point: point.slice(0, budget), spot: spot.slice(0, Math.max(0, budget - point.length)) };
+}
 function usesCascades(entry) {
     return (entry.castShadow ?? false) && (entry.cascades ?? 1) > 1;
 }
-function DirectionalShadowLight({ entry }) {
-    if (usesCascades(entry)) {
-        return _jsx(CascadedShadows, { entry: entry });
+function DirectionalShadowLight({ entry, profile }) {
+    const resolved = profile === undefined ? entry : { ...entry, shadowMapSize: entry.shadowMapSize ?? profile.shadowMapSize, cascades: entry.cascades ?? profile.cascades };
+    if (usesCascades(resolved)) {
+        return _jsx(CascadedShadows, { entry: resolved });
     }
+    return _jsx(SingleShadowLight, { entry: resolved });
+}
+/**
+ * Refresh a directional light's shadow projection after its frustum bounds change.
+ * R3F pierced `shadow-camera-*` props write the bounds but never call
+ * `updateProjectionMatrix()`, so depth renders with the stale default ~10×10 box
+ * and `shadowCameraSize` is silently inert.
+ */
+export function syncShadowProjection(light) {
+    light.shadow.camera.updateProjectionMatrix();
+}
+function SingleShadowLight({ entry }) {
+    const lightRef = useRef(null);
     const size = entry.shadowCameraSize ?? 40;
-    return (_jsx("directionalLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": entry.shadowMapSize ?? 1024, "shadow-mapSize-height": entry.shadowMapSize ?? 1024, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": Math.max(200, size * 6), "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02 }));
+    const far = Math.max(200, size * 6);
+    const mapSize = entry.shadowMapSize ?? 1024;
+    useLayoutEffect(() => {
+        if (lightRef.current !== null)
+            syncShadowProjection(lightRef.current);
+    }, [size, far]);
+    useLayoutEffect(() => {
+        const light = lightRef.current;
+        if (light === null || light.shadow.map === null)
+            return;
+        light.shadow.map.dispose();
+        light.shadow.map = null;
+    }, [mapSize]);
+    return (_jsx("directionalLight", { ref: lightRef, position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": mapSize, "shadow-mapSize-height": mapSize, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": far, "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02 }));
 }
-export function ConfiguredLighting({ lighting }) {
+export function ConfiguredLighting({ lighting, profile }) {
+    const dynamic = resolveDynamicLights(lighting);
     return (_jsxs(_Fragment, { children: [lighting.ambient !== undefined ? (_jsx("ambientLight", { color: lighting.ambient.color, intensity: lighting.ambient.intensity ?? 0.55 })) : null, lighting.hemisphere !== undefined ? (_jsx("hemisphereLight", { args: [
                     lighting.hemisphere.skyColor ?? "#bfe3ff",
                     lighting.hemisphere.groundColor ?? "#4c6b34",
                     lighting.hemisphere.intensity ?? 0.55,
-                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry }, index)))] }));
+                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry, profile: profile }, index))), dynamic.point.map((entry, index) => (_jsx("pointLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, castShadow: entry.castShadow ?? false }, index))), dynamic.spot.map((entry, index) => (_jsx("spotLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, angle: entry.angle ?? Math.PI / 6, penumbra: entry.penumbra ?? 0, castShadow: entry.castShadow ?? false, "target-position": [...(entry.target ?? [0, 0, 0])] }, index)))] }));
 }
 export function BackdropFog({ fog }) {
     if (fog === undefined)

package/dist/render/SceneModels.js

@@ -3,23 +3,51 @@ import { useFrame, useLoader } from "@react-three/fiber";
 import { useTexture } from "@react-three/drei";
 import { Component, Suspense, useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { createSpriteClipPlayer } from "@jgengine/core/render/sprite2d";
 import { reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
 import { useOptionalGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "./modelLoad.js";
 import { measureLocalBounds, reportMeasuredBounds } from "./measureBounds.js";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
 import { useModelAnimation } from "./useModelAnimation.js";
+import { useFootIk } from "./useFootIk.js";
 import { PartMotionRig } from "./PartMotion.js";
 import { applyMaterialOverride } from "../materialOverride.js";
 import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeClonedMaterials, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
 export function EntitySprite({ sprite }) {
-    const texture = useLoader(THREE.TextureLoader, sprite.url);
+    const texture = useLoader(THREE.TextureLoader, sprite.clip?.atlas.image ?? sprite.url);
+    const map = useMemo(() => texture.clone(), [texture]);
+    const player = useMemo(() => (sprite.clip === undefined ? null : createSpriteClipPlayer(sprite.clip.atlas)), [sprite.clip]);
+    const animation = sprite.clip?.animation;
     useEffect(() => {
-        texture.colorSpace = THREE.SRGBColorSpace;
-        texture.anisotropy = 4;
-        texture.needsUpdate = true;
-    }, [texture]);
-    return (_jsx("sprite", { "position-y": sprite.y, scale: [sprite.width, sprite.height, 1], children: _jsx("spriteMaterial", { map: texture, transparent: true, alphaTest: 0.08, depthWrite: false }) }));
+        map.colorSpace = THREE.SRGBColorSpace;
+        map.anisotropy = 4;
+        map.needsUpdate = true;
+        return () => map.dispose();
+    }, [map]);
+    useEffect(() => {
+        if (player !== null && animation !== undefined)
+            player.play(animation);
+    }, [player, animation]);
+    useFrame((_state, delta) => {
+        if (player === null || sprite.clip === undefined)
+            return;
+        player.advance(delta);
+        const frame = player.frame();
+        if (frame === undefined)
+            return;
+        const [atlasWidth, atlasHeight] = sprite.clip.atlas.size;
+        map.repeat.set(frame.w / atlasWidth, frame.h / atlasHeight);
+        map.offset.set(frame.x / atlasWidth, 1 - (frame.y + frame.h) / atlasHeight);
+        map.needsUpdate = true;
+    });
+    useEffect(() => {
+        if (player === null) {
+            map.repeat.set(1, 1);
+            map.offset.set(0, 0);
+        }
+    }, [map, player]);
+    return (_jsx("sprite", { "position-y": sprite.y, scale: [sprite.width, sprite.height, 1], children: _jsx("spriteMaterial", { map: map, transparent: true, alphaTest: 0.08, depthWrite: false }) }));
 }
 /**
  * Catches a render throw from a model subtree and swaps in `fallback` — but never silently: the
@@ -102,8 +130,14 @@ function ModelMaterialMapsApplier({ scene, maps }) {
             record.roughness = maps.roughness;
         if (maps.ao !== undefined)
             record.ao = maps.ao;
+        if (maps.metalness !== undefined)
+            record.metalness = maps.metalness;
+        if (maps.emissive !== undefined)
+            record.emissive = maps.emissive;
+        if (maps.height !== undefined)
+            record.height = maps.height;
         return record;
-    }, [maps.color, maps.normal, maps.roughness, maps.ao]);
+    }, [maps.color, maps.normal, maps.roughness, maps.ao, maps.metalness, maps.emissive, maps.height]);
     const textures = useTexture(entries);
     useEffect(() => {
         if (textures.color !== undefined)
@@ -121,12 +155,13 @@ export function EntityModel({ model, instanceId, measure, }) {
     const material = model.material;
     const baseY = model.y ?? 0;
     const dims = model.dims;
+    const shadows = model.shadows;
     const scene = useMemo(() => {
-        const cloned = cloneModelScene(gltf.scene);
+        const cloned = cloneModelScene(gltf.scene, { shadows });
         if (material !== undefined)
             applyMaterialOverride(cloned, material, { clone: false });
         return cloned;
-    }, [gltf, material]);
+    }, [gltf, material, shadows]);
     const measured = useMemo(() => {
         if (model.targetHeight === undefined)
             return null;
@@ -183,6 +218,7 @@ export function EntityModel({ model, instanceId, measure, }) {
             reportMeasuredCollisionMesh(ctx, measureTarget, measureKey, triangles);
     }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey]);
     useModelAnimation(scene, gltf.animations, model.animation, instanceId);
+    useFootIk(scene, model.ik, ctx, instanceId);
     const paintCanvasRef = useRef(null);
     const paintDrawnCountRef = useRef(0);
     const paintVersionRef = useRef(-1);

package/dist/render/modelLoad.d.ts

@@ -1,3 +1,4 @@
+import * as THREE from "three";
 import { GLTFLoader, type GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { type AssetLoadDiagnosis } from "@jgengine/core/scene/assetDiagnostics";
 /**
@@ -72,6 +73,15 @@ export declare function clearModelLoadFallbacks(): void;
 export declare class DiagnosticGLTFLoader extends GLTFLoader {
     load(url: string, onLoad: (gltf: GLTF) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: unknown) => void): void;
 }
+/** CDN-backed decoder configuration for compressed model and texture assets. */
+export interface ModelLoaderConfig {
+    dracoDecoderPath?: string;
+    ktx2TranscoderPath?: string;
+}
+/** Configures shared Draco and KTX2 loaders. Repeated calls with the same paths are no-ops. */
+export declare function configureModelLoaders(options?: ModelLoaderConfig): Readonly<Required<ModelLoaderConfig>>;
+/** Detects GPU support for the configured KTX2 transcoder after a renderer exists. */
+export declare function detectKtx2Support(renderer: THREE.WebGLRenderer): void;
 /**
  * How long the shared GLB loader has been idle, in ms — `0` while any model is still
  * in flight. A capture host reads this to wait for streaming to finish instead of

package/dist/render/modelLoad.js

@@ -1,5 +1,7 @@
 import * as THREE from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { DRACOLoader } from "three/examples/jsm/loaders/DRACOLoader.js";
+import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
 import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
 import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
 import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
@@ -157,6 +159,31 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
         });
     }
 }
+const DEFAULT_DRACO_DECODER_PATH = "https://cdn.jsdelivr.net/npm/three@0.182.0/examples/jsm/libs/draco/";
+const DEFAULT_KTX2_TRANSCODER_PATH = "https://cdn.jsdelivr.net/npm/three@0.182.0/examples/jsm/libs/basis/";
+let configuredModelLoaders;
+let ktx2Loader;
+/** Configures shared Draco and KTX2 loaders. Repeated calls with the same paths are no-ops. */
+export function configureModelLoaders(options = {}) {
+    const next = {
+        dracoDecoderPath: options.dracoDecoderPath ?? DEFAULT_DRACO_DECODER_PATH,
+        ktx2TranscoderPath: options.ktx2TranscoderPath ?? DEFAULT_KTX2_TRANSCODER_PATH,
+    };
+    if (configuredModelLoaders?.dracoDecoderPath === next.dracoDecoderPath && configuredModelLoaders.ktx2TranscoderPath === next.ktx2TranscoderPath) {
+        return configuredModelLoaders;
+    }
+    const draco = new DRACOLoader().setDecoderPath(next.dracoDecoderPath);
+    ktx2Loader = new KTX2Loader().setTranscoderPath(next.ktx2TranscoderPath);
+    sharedGltfLoader.setDRACOLoader(draco);
+    sharedGltfLoader.setKTX2Loader(ktx2Loader);
+    configuredModelLoaders = next;
+    return configuredModelLoaders;
+}
+/** Detects GPU support for the configured KTX2 transcoder after a renderer exists. */
+export function detectKtx2Support(renderer) {
+    configureModelLoaders();
+    ktx2Loader?.detectSupport(renderer);
+}
 // LoadingManager reports queue transitions, not per-item events: `onStart` fires when the
 // queue goes busy and `onLoad` when it drains (errors included, via itemEnd), so a flag plus
 // a drain timestamp is the whole state.
@@ -187,3 +214,4 @@ export function modelLoadIdleMs() {
 /** Shared GLTF loader used by shell entity/object model mounts. @internal */
 export const sharedGltfLoader = new DiagnosticGLTFLoader(modelLoadingManager);
 sharedGltfLoader.setMeshoptDecoder(MeshoptDecoder);
+configureModelLoaders();

package/dist/render/modelRender.d.ts

@@ -1,9 +1,12 @@
 import * as THREE from "three";
 import type { PaintStroke } from "@jgengine/core/scene/paintLayer";
 export declare const PAINT_TEXTURE_SIZE = 512;
+/** Shadow participation applied to every mesh of a cloned model; mirrors `ModelConfig.shadows`. */
+export type ModelShadowMode = "cast" | "receive" | "both" | "none";
 /** @internal */
 export declare function cloneModelScene(source: THREE.Object3D, options?: {
     cloneMaterials?: boolean;
+    shadows?: ModelShadowMode;
 }): THREE.Object3D;
 /** @internal */
 export declare function disposeClonedMaterials(root: THREE.Object3D): void;

package/dist/render/modelRender.js

@@ -4,12 +4,16 @@ export const PAINT_TEXTURE_SIZE = 512;
 /** @internal */
 export function cloneModelScene(source, options) {
     const clone = cloneSkinned(source);
-    if (options?.cloneMaterials === false)
-        return clone;
+    const shadows = options?.shadows ?? "both";
+    const cloneMaterials = options?.cloneMaterials !== false;
     clone.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
+        mesh.castShadow = shadows === "cast" || shadows === "both";
+        mesh.receiveShadow = shadows === "receive" || shadows === "both";
+        if (!cloneMaterials)
+            return;
         mesh.material = Array.isArray(mesh.material)
             ? mesh.material.map((material) => material.clone())
             : mesh.material.clone();

package/dist/render/testFixtures/proceduralSpriteAtlas.d.ts

@@ -0,0 +1,15 @@
+import type { SpriteAtlas } from "@jgengine/core/assets/spriteAtlas";
+type DrawingContext = Pick<CanvasRenderingContext2D, "clearRect" | "fillRect" | "beginPath" | "arc" | "fill"> & {
+    fillStyle: string | CanvasGradient | CanvasPattern;
+};
+type CanvasFixture = {
+    width: number;
+    height: number;
+    getContext(contextId: "2d"): DrawingContext | null;
+    toDataURL(): string;
+};
+/** Draw the deterministic two-frame atlas used by shell sprite-clip captures and tests.
+ * @internal
+ */
+export declare function drawProceduralSpriteAtlas(canvas: CanvasFixture): SpriteAtlas;
+export {};