@jgengine/shell 0.10.0 → 0.11.0

package/dist/postfx/PostProcessing.js

@@ -1,9 +1,10 @@
 import { useFrame, useThree } from "@react-three/fiber";
-import { useEffect, useMemo } from "react";
+import { useEffect, useRef } from "react";
 import * as THREE from "three";
 import { EffectComposer, RenderPass, UnrealBloomPass } from "three-stdlib";
 import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
 import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
+import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { createGradePass } from "./gradeShader.js";
 const TONE_MAPPING = {
     aces: THREE.ACESFilmicToneMapping,
@@ -13,6 +14,23 @@ const TONE_MAPPING = {
     linear: THREE.LinearToneMapping,
     none: THREE.NoToneMapping,
 };
+function disposeGraph(built) {
+    for (const pass of built.composer.passes)
+        pass.dispose();
+    if (built.dof !== null) {
+        built.dof.renderTargetDepth.dispose();
+        built.dof.materialDepth.dispose();
+        built.dof.materialBokeh.dispose();
+        built.dof.fsQuad.dispose();
+    }
+    built.composer.dispose();
+}
+function syncSize(built, width, height, pixelRatio) {
+    built.composer.setPixelRatio(pixelRatio);
+    built.composer.setSize(width, height);
+    if (built.dof !== null)
+        built.dof.renderTargetDepth.setSize(width * pixelRatio, height * pixelRatio);
+}
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
@@ -24,7 +42,8 @@ export function PostProcessing({ config }) {
     const scene = useThree((s) => s.scene);
     const camera = useThree((s) => s.camera);
     const size = useThree((s) => s.size);
-    const built = useMemo(() => {
+    const builtRef = useRef(null);
+    useEffect(() => {
         const width = Math.max(1, size.width);
         const height = Math.max(1, size.height);
         const target = new THREE.WebGLRenderTarget(width, height, {
@@ -49,14 +68,30 @@ export function PostProcessing({ config }) {
             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 (config.dof !== undefined && config.dof !== false) {
+            const d = config.dof;
+            dof = new BokehPass(scene, camera, {
+                focus: d.focus ?? 18,
+                aperture: d.aperture ?? 0.00025,
+                maxblur: d.maxBlur ?? 0.01,
+            });
+            composer.addPass(dof);
+        }
         composer.addPass(new OutputPass());
         let grade = null;
         if (config.grade !== false) {
             grade = createGradePass(config.grade ?? {});
             composer.addPass(grade);
         }
-        return { composer, grade };
-    }, [gl, scene, camera, config, size.width, size.height]);
+        const graph = { composer, grade, dof };
+        syncSize(graph, width, height, gl.getPixelRatio());
+        builtRef.current = graph;
+        return () => {
+            disposeGraph(graph);
+            builtRef.current = null;
+        };
+    }, [gl, scene, camera, config]);
     useEffect(() => {
         const prevTone = gl.toneMapping;
         const prevExposure = gl.toneMappingExposure;
@@ -68,12 +103,15 @@ export function PostProcessing({ config }) {
         };
     }, [gl, config.toneMapping, config.exposure]);
     useEffect(() => {
-        const { composer } = built;
-        composer.setPixelRatio(gl.getPixelRatio());
-        composer.setSize(size.width, size.height);
-        return () => composer.dispose();
-    }, [built, gl, size.width, size.height]);
+        const built = builtRef.current;
+        if (built === null)
+            return;
+        syncSize(built, Math.max(1, size.width), Math.max(1, size.height), gl.getPixelRatio());
+    }, [gl, size.width, size.height]);
     useFrame((_, delta) => {
+        const built = builtRef.current;
+        if (built === null)
+            return;
         if (built.grade !== null)
             built.grade.uniforms.uTime.value += delta;
         built.composer.render(delta);

package/dist/postfx/gradeShader.js

@@ -6,6 +6,7 @@ const DEFAULT_GAMMA = 0.96;
 const DEFAULT_SATURATION = 1.12;
 const DEFAULT_VIGNETTE = 0.2;
 const DEFAULT_GRAIN = 0.012;
+const DEFAULT_CHROMA = 0;
 const fragmentShader = /* glsl */ `
   uniform sampler2D tDiffuse;
   uniform vec3 uLift;
@@ -14,6 +15,7 @@ const fragmentShader = /* glsl */ `
   uniform float uSaturation;
   uniform float uVignette;
   uniform float uGrain;
+  uniform float uChroma;
   uniform float uTime;
   varying vec2 vUv;
 
@@ -22,7 +24,12 @@ const fragmentShader = /* glsl */ `
   }
 
   void main() {
-    vec3 c = texture2D(tDiffuse, vUv).rgb;
+    vec2 dir = vUv - 0.5;
+    // Chromatic aberration: split RGB along the radial direction, growing toward the edges.
+    vec2 shift = uChroma > 0.0 ? dir * uChroma * dot(dir, dir) * 4.0 : vec2(0.0);
+    vec3 c = uChroma > 0.0
+      ? vec3(texture2D(tDiffuse, vUv + shift).r, texture2D(tDiffuse, vUv).g, texture2D(tDiffuse, vUv - shift).b)
+      : texture2D(tDiffuse, vUv).rgb;
     c = c + uLift;
     c = c * uGain;
     c = pow(max(c, 0.0), vec3(uGamma));
@@ -56,6 +63,7 @@ export function createGradePass(config = {}) {
             uSaturation: { value: config.saturation ?? DEFAULT_SATURATION },
             uVignette: { value: config.vignette ?? DEFAULT_VIGNETTE },
             uGrain: { value: config.grain ?? DEFAULT_GRAIN },
+            uChroma: { value: config.chromaticAberration ?? DEFAULT_CHROMA },
             uTime: { value: 0 },
         },
         vertexShader,

package/dist/registry.d.ts

@@ -1,9 +1,10 @@
 import type { ComponentType, ReactNode } from "react";
-import type { PlayableGame as EnginePlayableGame } from "@jgengine/core/game/playableGame";
+import type { PlayableGame as EnginePlayableGame, WorldOverlayProps } from "@jgengine/core/game/playableGame";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { ViewmodelProps } from "./camera/GameFirstPersonCamera.js";
 export type RenderEntity = (entity: SceneEntity) => ReactNode;
 export type RenderObject = (object: SceneObject) => ReactNode;
-export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject>;
+export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps>>;
 export type GameRegistry = Record<string, () => Promise<PlayableGame>>;
 export declare function resolveGameLoader(registry: GameRegistry, gameId: string, fallbackGameId?: string): (() => Promise<PlayableGame>) | undefined;

package/dist/render/EnvironmentLighting.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sets a neutral, network-free image-based-lighting environment on the scene so every
+ * `MeshStandardMaterial` — models and un-modeled primitive fallbacks alike — picks up soft
+ * reflections and fill instead of rendering dead-flat. A game's own sky/lighting still layers on
+ * top; this only supplies the reflective ambient the shell never had. Opt out with `look: "flat"`.
+ * @internal shell-internal default lighting; games never import it.
+ */
+export declare function EnvironmentLighting({ intensity }: {
+    intensity?: number;
+}): null;

package/dist/render/EnvironmentLighting.js

@@ -0,0 +1,34 @@
+import { useThree } from "@react-three/fiber";
+import { useEffect } from "react";
+import * as THREE from "three";
+import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
+/**
+ * Sets a neutral, network-free image-based-lighting environment on the scene so every
+ * `MeshStandardMaterial` — models and un-modeled primitive fallbacks alike — picks up soft
+ * reflections and fill instead of rendering dead-flat. A game's own sky/lighting still layers on
+ * top; this only supplies the reflective ambient the shell never had. Opt out with `look: "flat"`.
+ * @internal shell-internal default lighting; games never import it.
+ */
+export function EnvironmentLighting({ intensity = 0.28 }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    useEffect(() => {
+        const pmrem = new THREE.PMREMGenerator(gl);
+        const room = new RoomEnvironment();
+        const target = pmrem.fromScene(room, 0.04);
+        const previous = scene.environment;
+        scene.environment = target.texture;
+        const sceneWithIntensity = scene;
+        const previousIntensity = sceneWithIntensity.environmentIntensity;
+        sceneWithIntensity.environmentIntensity = intensity;
+        room.dispose?.();
+        pmrem.dispose();
+        return () => {
+            target.dispose();
+            scene.environment = previous;
+            if (previousIntensity !== undefined)
+                sceneWithIntensity.environmentIntensity = previousIntensity;
+        };
+    }, [gl, scene, intensity]);
+    return null;
+}

package/dist/render/SceneLighting.d.ts

@@ -0,0 +1,7 @@
+import type { BackdropConfig, LightingConfig } from "@jgengine/core/game/playableGame";
+export declare function ConfiguredLighting({ lighting }: {
+    lighting: LightingConfig;
+}): import("react").JSX.Element;
+export declare function BackdropFog({ fog }: {
+    fog: BackdropConfig["fog"];
+}): import("react").JSX.Element | null;

package/dist/render/SceneLighting.js

@@ -0,0 +1,18 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
+function DirectionalShadowLight({ entry }) {
+    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 }));
+}
+export function ConfiguredLighting({ 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)))] }));
+}
+export function BackdropFog({ fog }) {
+    if (fog === undefined)
+        return null;
+    return fog.density !== undefined ? (_jsx("fogExp2", { attach: "fog", args: [fog.color ?? DEFAULT_BACKDROP_FOG_COLOR, fog.density] })) : (_jsx("fog", { attach: "fog", args: [fog.color ?? DEFAULT_BACKDROP_FOG_COLOR, fog.near ?? 10, fog.far ?? 200] }));
+}

package/dist/render/SceneModels.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import type { EntitySpriteConfig, ModelConfig } from "@jgengine/core/game/playableGame";
+export declare function EntitySprite({ sprite }: {
+    sprite: EntitySpriteConfig;
+}): import("react").JSX.Element;
+export declare function IsolatedEntityModel({ model, instanceId, fallback, }: {
+    model: ModelConfig;
+    instanceId?: string;
+    fallback?: ReactNode;
+}): import("react").JSX.Element;
+export declare function EntityModel({ model, instanceId }: {
+    model: ModelConfig;
+    instanceId?: string;
+}): import("react").JSX.Element;

package/dist/render/SceneModels.js

@@ -0,0 +1,337 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { resolveOneShotClip } from "@jgengine/core/game/modelAnimation";
+import { useGameContext } from "@jgengine/react/provider";
+import { sharedGltfLoader } from "./modelLoad.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);
+    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 }) }));
+}
+class ModelFallbackBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+export function IsolatedEntityModel({ model, instanceId, fallback, }) {
+    return (_jsx(ModelFallbackBoundary, { fallback: fallback ?? null, children: _jsx(Suspense, { fallback: null, children: _jsx(EntityModel, { model: model, instanceId: instanceId }) }) }));
+}
+function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
+    const gltf = useLoader(sharedGltfLoader, model.url);
+    const weaponScene = useMemo(() => cloneModelScene(gltf.scene), [gltf]);
+    const px = position?.[0] ?? 0;
+    const py = position?.[1] ?? 0;
+    const pz = position?.[2] ?? 0;
+    const rx = rotation?.[0] ?? 0;
+    const ry = rotation?.[1] ?? 0;
+    const rz = rotation?.[2] ?? 0;
+    const s = scale ?? 1;
+    useEffect(() => {
+        const bone = rig.getObjectByName(slot);
+        if (bone === undefined) {
+            if (typeof console !== "undefined") {
+                console.warn(`[jgengine] entityModels attachment: bone/slot "${slot}" not found on the rig`);
+            }
+            return;
+        }
+        weaponScene.position.set(px, py, pz);
+        weaponScene.rotation.set(rx, ry, rz);
+        weaponScene.scale.setScalar(s);
+        bone.add(weaponScene);
+        return () => {
+            bone.remove(weaponScene);
+        };
+    }, [rig, weaponScene, slot, px, py, pz, rx, ry, rz, s]);
+    useEffect(() => () => disposeClonedMaterials(weaponScene), [weaponScene]);
+    return null;
+}
+/** Renders a static kit-of-parts child at a fixed local offset under the parent model — no bone/rig lookup, unlike `BoneAttachment`. The nested `EntityModel` still applies its own `dims`/anchor centering, so scale/pivot sanity carries over per part. */
+function ModelPartGroup({ model, position, rotation, scale, }) {
+    return (_jsx("group", { position: position ?? [0, 0, 0], rotation: rotation ?? [0, 0, 0], scale: scale ?? 1, children: _jsx(EntityModel, { model: model }) }));
+}
+function ModelMaterialMapsApplier({ scene, maps }) {
+    const entries = useMemo(() => {
+        const record = {};
+        if (maps.color !== undefined)
+            record.color = maps.color;
+        if (maps.normal !== undefined)
+            record.normal = maps.normal;
+        if (maps.roughness !== undefined)
+            record.roughness = maps.roughness;
+        if (maps.ao !== undefined)
+            record.ao = maps.ao;
+        return record;
+    }, [maps.color, maps.normal, maps.roughness, maps.ao]);
+    const textures = useTexture(entries);
+    useEffect(() => {
+        if (textures.color !== undefined)
+            textures.color.colorSpace = THREE.SRGBColorSpace;
+        applyMaterialOverride(scene, {}, { clone: false, textures });
+    }, [scene, textures]);
+    return null;
+}
+export function EntityModel({ model, instanceId }) {
+    const gltf = useLoader(sharedGltfLoader, model.url);
+    const ctx = useGameContext();
+    const material = model.material;
+    const baseY = model.y ?? 0;
+    const dims = model.dims;
+    const scene = useMemo(() => {
+        const cloned = cloneModelScene(gltf.scene);
+        if (material !== undefined)
+            applyMaterialOverride(cloned, material, { clone: false });
+        return cloned;
+    }, [gltf, material]);
+    const measured = useMemo(() => {
+        if (model.targetHeight === undefined)
+            return null;
+        const box = new THREE.Box3().setFromObject(scene);
+        const height = box.max.y - box.min.y;
+        if (!Number.isFinite(height) || height <= 0)
+            return null;
+        return {
+            normalize: model.targetHeight / height,
+            minY: box.min.y,
+            centerX: (box.min.x + box.max.x) / 2,
+            centerZ: (box.min.z + box.max.z) / 2,
+        };
+    }, [scene, model.targetHeight]);
+    const scale = (model.scale ?? 1) * (measured?.normalize ?? 1);
+    const centered = (model.anchor ?? "center") === "center" && dims !== undefined;
+    const position = measured !== null
+        ? [-scale * measured.centerX, baseY - scale * measured.minY, -scale * measured.centerZ]
+        : centered
+            ? [-scale * dims.center.x, baseY - scale * dims.minY, -scale * dims.center.z]
+            : [0, baseY, 0];
+    useEffect(() => () => {
+        disposeClonedMaterials(scene);
+    }, [scene]);
+    const animation = model.animation;
+    const mixerRef = useRef(null);
+    const animationPausedRef = useRef(false);
+    const stateActionsRef = useRef(null);
+    const states = animation?.states;
+    const oneShots = animation?.oneShots;
+    const oneShotPlayRef = useRef(null);
+    const activeOneShotRef = useRef(null);
+    useEffect(() => {
+        if (animation === undefined || gltf.animations.length === 0) {
+            mixerRef.current = null;
+            stateActionsRef.current = null;
+            return;
+        }
+        const mixer = new THREE.AnimationMixer(scene);
+        if (states !== undefined) {
+            const clipFor = (name) => THREE.AnimationClip.findByName(gltf.animations, name) ?? gltf.animations[0];
+            const actions = {
+                idle: mixer.clipAction(clipFor(states.idle)),
+                walk: mixer.clipAction(clipFor(states.walk)),
+                ...(states.run === undefined ? {} : { run: mixer.clipAction(clipFor(states.run)) }),
+            };
+            for (const action of Object.values(actions)) {
+                action.setLoop(THREE.LoopRepeat, Infinity);
+                action.timeScale = animation.timeScale ?? 1;
+                action.enabled = true;
+            }
+            actions.idle.play();
+            mixer.update(0);
+            mixerRef.current = mixer;
+            stateActionsRef.current = { actions, active: "idle", lastPos: null, smoothedSpeed: 0 };
+            animationPausedRef.current = false;
+            let onOneShotFinished = null;
+            if (oneShots !== undefined) {
+                const clipNames = new Set();
+                for (const spec of Object.values(oneShots)) {
+                    if (typeof spec === "string")
+                        clipNames.add(spec);
+                    else
+                        for (const name of spec)
+                            clipNames.add(name);
+                }
+                const oneShotActions = new Map();
+                for (const name of clipNames) {
+                    const found = THREE.AnimationClip.findByName(gltf.animations, name);
+                    if (found === null)
+                        continue;
+                    const oneShotAction = mixer.clipAction(found);
+                    oneShotAction.setLoop(THREE.LoopOnce, 1);
+                    oneShotAction.enabled = true;
+                    oneShotActions.set(name, oneShotAction);
+                }
+                onOneShotFinished = ({ action }) => {
+                    const active = activeOneShotRef.current;
+                    if (active === null || action !== active.action || active.isDeath)
+                        return;
+                    const machine = stateActionsRef.current;
+                    const back = machine?.actions[machine.active];
+                    action.fadeOut(0.15);
+                    if (back !== undefined)
+                        back.reset().fadeIn(0.15).play();
+                    activeOneShotRef.current = null;
+                };
+                mixer.addEventListener("finished", onOneShotFinished);
+                oneShotPlayRef.current = (event) => {
+                    const active = activeOneShotRef.current;
+                    if (active !== null && active.isDeath)
+                        return;
+                    const clipName = resolveOneShotClip(oneShots, event, Math.random());
+                    if (clipName === null)
+                        return;
+                    const oneShotAction = oneShotActions.get(clipName);
+                    if (oneShotAction === undefined)
+                        return;
+                    const machine = stateActionsRef.current;
+                    machine?.actions[machine.active]?.fadeOut(0.1);
+                    if (active !== null && active.action !== oneShotAction)
+                        active.action.stop();
+                    oneShotAction.clampWhenFinished = event === "death";
+                    oneShotAction.reset().fadeIn(0.1).play();
+                    activeOneShotRef.current = { action: oneShotAction, isDeath: event === "death" };
+                };
+            }
+            return () => {
+                if (onOneShotFinished !== null)
+                    mixer.removeEventListener("finished", onOneShotFinished);
+                oneShotPlayRef.current = null;
+                activeOneShotRef.current = null;
+                mixer.stopAllAction();
+                mixerRef.current = null;
+                stateActionsRef.current = null;
+            };
+        }
+        const clip = (animation.clip !== undefined ? THREE.AnimationClip.findByName(gltf.animations, animation.clip) : undefined) ??
+            gltf.animations[0];
+        const action = mixer.clipAction(clip);
+        action.setLoop(animation.loop === false ? THREE.LoopOnce : THREE.LoopRepeat, Infinity);
+        action.clampWhenFinished = animation.loop === false;
+        action.timeScale = animation.timeScale ?? 1;
+        action.enabled = true;
+        action.paused = animation.paused === true;
+        action.play();
+        if (animation.time !== undefined)
+            action.time = animation.time;
+        mixer.update(0);
+        mixerRef.current = mixer;
+        animationPausedRef.current = animation.paused === true;
+        return () => {
+            mixer.stopAllAction();
+            mixerRef.current = null;
+        };
+    }, [
+        scene,
+        gltf,
+        animation?.clip,
+        animation?.loop,
+        animation?.timeScale,
+        animation?.paused,
+        animation?.time,
+        states,
+        oneShots,
+    ]);
+    useEffect(() => {
+        if (instanceId === undefined || oneShots === undefined)
+            return;
+        const fire = (event) => oneShotPlayRef.current?.(event);
+        const offAnimation = ctx.game.events.on("entity.animation", (event) => {
+            if (event.instanceId === instanceId)
+                fire(event.event);
+        });
+        const offHit = ctx.game.events.on("combat.hitReaction", (event) => {
+            if (event.instanceId === instanceId)
+                fire("hit");
+        });
+        const offDied = ctx.game.events.on("entity.died", (event) => {
+            if (event.instanceId === instanceId)
+                fire("death");
+        });
+        return () => {
+            offAnimation();
+            offHit();
+            offDied();
+        };
+    }, [ctx, instanceId, oneShots]);
+    const paintCanvasRef = useRef(null);
+    const paintDrawnCountRef = useRef(0);
+    const paintVersionRef = useRef(-1);
+    const materialCacheRef = useRef(null);
+    useEffect(() => () => {
+        if (paintCanvasRef.current !== null) {
+            disposePaintCanvas(paintCanvasRef.current);
+            paintCanvasRef.current = null;
+        }
+        paintDrawnCountRef.current = 0;
+        paintVersionRef.current = -1;
+        materialCacheRef.current = null;
+    }, [scene]);
+    useFrame((_state, delta) => {
+        const stateMachine = stateActionsRef.current;
+        if (stateMachine !== null && states !== undefined && instanceId !== undefined && delta > 0) {
+            const entity = ctx.scene.entity.get(instanceId);
+            if (entity !== null) {
+                const [x, , z] = entity.position;
+                if (stateMachine.lastPos !== null) {
+                    const instantSpeed = Math.hypot(x - stateMachine.lastPos[0], z - stateMachine.lastPos[2]) / delta;
+                    stateMachine.smoothedSpeed +=
+                        (instantSpeed - stateMachine.smoothedSpeed) * Math.min(1, delta * 12);
+                }
+                stateMachine.lastPos = [x, entity.position[1], z];
+                const walkSpeed = states.walkSpeed ?? 0.5;
+                const runSpeed = states.runSpeed ?? 6;
+                const next = stateMachine.smoothedSpeed < walkSpeed
+                    ? "idle"
+                    : stateMachine.actions.run !== undefined && stateMachine.smoothedSpeed >= runSpeed
+                        ? "run"
+                        : "walk";
+                if (next !== stateMachine.active) {
+                    if (activeOneShotRef.current === null) {
+                        const fade = states.fadeSec ?? 0.2;
+                        const from = stateMachine.actions[stateMachine.active];
+                        const to = stateMachine.actions[next];
+                        if (from !== undefined && to !== undefined) {
+                            to.reset().fadeIn(fade).play();
+                            from.fadeOut(fade);
+                        }
+                    }
+                    stateMachine.active = next;
+                }
+            }
+        }
+        if (mixerRef.current !== null && !animationPausedRef.current)
+            mixerRef.current.update(delta);
+        if (instanceId === undefined)
+            return;
+        const paint = ctx.scene.entity.paint;
+        const version = paint.version(instanceId);
+        if (version === paintVersionRef.current)
+            return;
+        paintVersionRef.current = version;
+        const strokes = paint.strokes(instanceId);
+        const cache = cacheStandardMaterials(scene, materialCacheRef.current);
+        materialCacheRef.current = cache;
+        if (paintCanvasRef.current === null) {
+            if (strokes.length === 0)
+                return;
+            const seed = cache.materials[0];
+            if (seed === undefined)
+                return;
+            const paintCanvas = createPaintCanvas(seed);
+            paintCanvasRef.current = paintCanvas;
+            applyPaintTextureToMaterials(cache.materials, paintCanvas);
+        }
+        paintDrawnCountRef.current = syncPaintCanvas(paintCanvasRef.current, cache.seedColor, strokes, paintDrawnCountRef.current);
+    });
+    return (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), material?.maps !== undefined ? _jsx(ModelMaterialMapsApplier, { scene: scene, maps: material.maps }) : null, (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }, `${attachment.slot}-${index}`))), (model.parts ?? []).map((part, index) => typeof part.model === "string" ? null : (_jsx(ModelPartGroup, { model: part.model, position: part.position, rotation: part.rotation, scale: part.scale }, index)))] }));
+}

package/dist/render/defaultSurface.d.ts

@@ -0,0 +1,29 @@
+import { type ThreeElements } from "@react-three/fiber";
+import * as THREE from "three";
+/**
+ * Shared, lazily-built procedural detail maps (a subtle tangent-space normal map plus a
+ * roughness-variation map) used by every un-modeled primitive so a flat colored box reads as a
+ * surface, not plastic. Pure JS `DataTexture` — no canvas/DOM, so it imports safely under `bun test`.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export declare function detailMaps(): {
+    normal: THREE.DataTexture;
+    roughness: THREE.DataTexture;
+};
+/**
+ * Props for {@link DefaultSurface}: a required base `color` plus optional PBR overrides.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export interface DefaultSurfaceProps extends Omit<ThreeElements["meshStandardMaterial"], "args" | "normalMap" | "roughnessMap"> {
+    color: THREE.ColorRepresentation;
+    roughness?: number;
+    metalness?: number;
+    detail?: boolean;
+}
+/**
+ * The upgraded default material for un-modeled entities/objects: tuned PBR roughness/metalness plus
+ * the shared procedural detail maps, so primitive fallbacks catch light and image-based reflections
+ * instead of reading as flat plastic. Drop-in replacement for a bare `<meshStandardMaterial color>`.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export declare function DefaultSurface({ color, roughness, metalness, detail, ...rest }: DefaultSurfaceProps): import("react").JSX.Element;