@jgengine/shell 0.19.0 → 0.21.0

package/dist/render/SceneModels.js

@@ -1,20 +1,25 @@
 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 { useFrame, useLoader, useThree } from "@react-three/fiber";
+import { Component, Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility";
 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 { detectKtx2Support, sharedGltfLoader } from "./modelLoad.js";
+import { modelAssetRequests } from "./modelAssets.js";
 import { measureLocalBounds, reportMeasuredBounds } from "./measureBounds.js";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
-import { useModelAnimation } from "./useModelAnimation.js";
+import { useModelInstance } from "./useModelInstance.js";
+import { applyMaterialAssignments, useModelMaterialTextures, MaterialTextureLoader, validateMaterialAssignmentTargets } from "./materialAsset.js";
 import { useFootIk } from "./useFootIk.js";
+import { resolveRigNode } from "./rigNode.js";
 import { PartMotionRig } from "./PartMotion.js";
+import { syncSpriteFrame } from "./spriteRender.js";
 import { applyMaterialOverride } from "../materialOverride.js";
-import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeClonedMaterials, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
+import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeModelScene, ownModelMaterial, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
 export function EntitySprite({ sprite }) {
+    const invalidate = useThree((state) => state.invalidate);
     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]);
@@ -28,7 +33,11 @@ export function EntitySprite({ sprite }) {
     useEffect(() => {
         if (player !== null && animation !== undefined)
             player.play(animation);
-    }, [player, animation]);
+        const frame = player?.frame();
+        if (frame !== undefined && sprite.clip !== undefined)
+            syncSpriteFrame(map, frame, sprite.clip.atlas.size);
+        invalidate();
+    }, [player, animation, map, sprite.clip, invalidate]);
     useFrame((_state, delta) => {
         if (player === null || sprite.clip === undefined)
             return;
@@ -36,10 +45,7 @@ export function EntitySprite({ sprite }) {
         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;
+        syncSpriteFrame(map, frame, sprite.clip.atlas.size);
     });
     useEffect(() => {
         if (player === null) {
@@ -97,13 +103,14 @@ function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
     const rz = rotation?.[2] ?? 0;
     const s = scale ?? 1;
     useEffect(() => {
-        const bone = rig.getObjectByName(slot);
-        if (bone === undefined) {
+        const resolved = resolveRigNode(rig, slot);
+        if (resolved.node === undefined) {
             if (typeof console !== "undefined") {
-                console.warn(`[jgengine] entityModels attachment: bone/slot "${slot}" not found on the rig`);
+                console.warn(`[jgengine] entityModels attachment: ${resolved.diagnostic.message}`);
             }
             return;
         }
+        const bone = resolved.node;
         weaponScene.position.set(px, py, pz);
         weaponScene.rotation.set(rx, ry, rz);
         weaponScene.scale.setScalar(s);
@@ -112,80 +119,47 @@ function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
             bone.remove(weaponScene);
         };
     }, [rig, weaponScene, slot, px, py, pz, rx, ry, rz, s]);
-    useEffect(() => () => disposeClonedMaterials(weaponScene), [weaponScene]);
+    useEffect(() => () => disposeModelScene(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(IsolatedModelPart, { model: model, 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;
-        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.metalness, maps.emissive, maps.height]);
-    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, measure, }) {
-    const gltf = useLoader(sharedGltfLoader, model.url);
+    parseModelHiddenNodes(model.hiddenNodes);
+    const renderer = useThree(state => state.gl);
+    if (renderer.isWebGLRenderer)
+        detectKtx2Support(renderer);
+    const assets = modelAssetRequests(model);
+    for (const url of assets.models)
+        useLoader.preload(sharedGltfLoader, url);
     // Optional, not required: measured bounds and paint strokes are live-world extras, and a model
     // that threw without a running game could not be inspected outside one — which is how a broken
     // composition stayed undiagnosable in `EntityPreview` (#1588).
     const ctx = useOptionalGameContext();
     const material = model.material;
+    const materialAssetKey = JSON.stringify((model.materialAssets ?? []).filter(asset => model.materialAssignments?.some(assignment => assignment.materialId === asset.id)));
+    const materialAssets = useMemo(() => (model.materialAssets ?? []).filter(asset => model.materialAssignments?.some(assignment => assignment.materialId === asset.id)), [materialAssetKey]);
+    const materialAssignments = model.materialAssignments;
+    const assignmentSource = useLoader(sharedGltfLoader, materialAssignments?.length ? [model.url] : [])[0]?.scene;
+    const assignmentKey = JSON.stringify(materialAssignments);
+    useMemo(() => {
+        if (assignmentSource !== undefined)
+            validateMaterialAssignmentTargets(assignmentSource, materialAssets, materialAssignments, { baseAlphaMode: material?.alphaMode });
+    }, [assignmentSource, materialAssets, assignmentKey, material?.alphaMode]);
+    for (const urls of assets.textureGroups)
+        useLoader.preload(MaterialTextureLoader, urls);
+    const materialTextures = useModelMaterialTextures(model);
     const baseY = model.y ?? 0;
     const dims = model.dims;
-    const shadows = model.shadows;
-    const scene = useMemo(() => {
-        const cloned = cloneModelScene(gltf.scene, { shadows });
+    const configure = useCallback((content) => {
         if (material !== undefined)
-            applyMaterialOverride(cloned, material, { clone: false });
-        return cloned;
-    }, [gltf, material, shadows]);
-    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]);
+            applyMaterialOverride(content, material, { clone: false, textures: materialTextures.global, ownMaterial: replacement => ownModelMaterial(content, replacement) });
+        if (materialAssignments !== undefined)
+            applyMaterialAssignments(content, materialAssets ?? [], materialAssignments, materialTextures.assets);
+    }, [material, materialTextures, materialAssets, materialAssignments]);
+    const { scene, scale, position } = useModelInstance(model, { instanceId, configure });
     // A model without index-measured dims can't drive the fitted-collider path, so report the live
     // measurement (the primitive mounts with only this uniform scale + position) instead of letting
     // the kind fall back to a fixed-size box. Index dims keep priority — skip when they exist.
@@ -193,7 +167,8 @@ export function EntityModel({ model, instanceId, measure, }) {
     const measureKey = measure?.key;
     const dimsMaxY = dims?.maxY;
     const [positionX, positionY, positionZ] = position;
-    useEffect(() => {
+    // Measure before the instance hook's passive animation effects can move imported root nodes.
+    useLayoutEffect(() => {
         if (ctx === null || measureTarget === undefined || measureKey === undefined || dimsMaxY !== undefined)
             return;
         const raw = measureLocalBounds(scene);
@@ -207,7 +182,7 @@ export function EntityModel({ model, instanceId, measure, }) {
     }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey, dimsMaxY]);
     // Runs with or without index dims: the loaded geometry upgrades whatever box the kind resolved
     // (fitted or measured) to a hitbox that raycasts the model's own triangles.
-    useEffect(() => {
+    useLayoutEffect(() => {
         if (ctx === null || measureTarget === undefined || measureKey === undefined)
             return;
         const triangles = measureLocalCollisionTriangles(scene, {
@@ -217,7 +192,6 @@ export function EntityModel({ model, instanceId, measure, }) {
         if (triangles !== null)
             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, baseY);
     const paintCanvasRef = useRef(null);
     const paintDrawnCountRef = useRef(0);
@@ -255,7 +229,7 @@ export function EntityModel({ model, instanceId, measure, }) {
         }
         paintDrawnCountRef.current = syncPaintCanvas(paintCanvasRef.current, cache.seedColor, strokes, paintDrawnCountRef.current);
     });
-    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), material?.maps !== undefined ? (_jsx(IsolatedModelPart, { model: model, children: _jsx(ModelMaterialMapsApplier, { scene: scene, maps: material.maps }) })) : null, (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(IsolatedModelPart, { model: attachment.model, children: _jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }) }, `${attachment.slot}-${index}`)))] }));
+    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(IsolatedModelPart, { model: attachment.model, children: _jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }) }, `${attachment.slot}-${index}`)))] }));
     const parts = model.parts ?? [];
     // Any role-tagged part switches the composition onto the procedural part-motion rig:
     // root bob/flinch/topple plus per-role limb swing, driven from the entity's live state.

package/dist/render/authoredSurfaceMaterial.d.ts

@@ -0,0 +1,43 @@
+import * as THREE from "three";
+import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
+import { type MaterialOverrideTextures } from "../materialOverride.js";
+/** Serializable PBR settings for an authored primitive surface. Map roles use the model-material contract. */
+export interface AuthoredSurfaceConfig extends Omit<ModelMaterialOverride, "anisotropy" | "normalScale"> {
+    /** Physical metres per texture tile on unit boxes/cylinders, including instance and parent scale. Omit to retain authored UVs. */
+    repeatMetres?: number;
+    /** Texture sampler policy on owned clones; defaults to repeat on both axes and anisotropy 1. */
+    wrapping?: "repeat" | "clamp" | "mirror";
+    anisotropy?: number;
+    /** Physical directional highlight strength [0,1]; `anisotropy` remains the legacy texture sampler setting. */
+    surfaceAnisotropy?: number;
+    normalScale?: readonly [number, number];
+    /** Normalized [0,1] height maps displace in local shape units (Three defaults: scale 1, bias 0). */
+    displacementScale?: number;
+    displacementBias?: number;
+    transparent?: boolean;
+    opacity?: number;
+    depthWrite?: boolean;
+}
+/** Primitive UV layout whose physical dimensions drive `repeatMetres`. */
+export type SurfaceShape = "box" | "cylinder";
+/** Stable material identity, independent of object/map property insertion order. @internal */
+export declare function authoredSurfaceKey(config: AuthoredSurfaceConfig): string;
+/** Configure owned map clones without changing textures retained in a loader cache. @internal */
+export declare function authoredSurfaceTextures(entries: Record<string, string>, sources: readonly THREE.Texture[], config?: AuthoredSurfaceConfig): MaterialOverrideTextures;
+/** Apply PBR settings and optional metre UVs to an owned standard material. @internal */
+export declare function configureAuthoredSurface(material: THREE.MeshStandardMaterial, config: AuthoredSurfaceConfig, textures: MaterialOverrideTextures, shape: SurfaceShape): void;
+/**
+ * Load declared surface-map roles and own the material/map clones (cached textures remain untouched).
+ * Colour, emissive, sheen-colour and specular-colour maps are sRGB; numeric maps are linear. Cylinder side metres use the RMS ellipse circumference approximation.
+ * Static batches and custom meshes share this lifecycle.
+ * @capability authored-surface-material render declared PBR maps with colour-space handling and metre-scale box/cylinder UVs
+ */
+export declare function useAuthoredSurfaceMaterial(config: AuthoredSurfaceConfig, shape?: SurfaceShape): THREE.MeshStandardMaterial;
+/**
+ * Mount an owned PBR surface material on a mesh.
+ * @capability authored-surface-material mount an owned PBR surface material on a mesh
+ */
+export declare function AuthoredSurfaceMaterial({ surface, shape }: {
+    surface: AuthoredSurfaceConfig;
+    shape?: SurfaceShape;
+}): import("react").JSX.Element;

package/dist/render/authoredSurfaceMaterial.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLoader } from "@react-three/fiber";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { MATERIAL_TEXTURE_SEMANTICS } from "@jgengine/core/material/materialAsset";
+import { applyMaterialOverrideToMaterial, requiresPhysicalMaterial } from "../materialOverride.js";
+import { modelMapEntries } from "./modelAssets.js";
+import { useDisposable } from "./useDisposable.js";
+/** Stable material identity, independent of object/map property insertion order. @internal */
+export function authoredSurfaceKey(config) {
+    return JSON.stringify(Object.entries({ ...config, maps: modelMapEntries(config.maps ?? {}) }).sort(([a], [b]) => a.localeCompare(b)));
+}
+/** Configure owned map clones without changing textures retained in a loader cache. @internal */
+export function authoredSurfaceTextures(entries, sources, config = {}) {
+    const wrapping = config.wrapping === "clamp" ? THREE.ClampToEdgeWrapping : config.wrapping === "mirror" ? THREE.MirroredRepeatWrapping : THREE.RepeatWrapping;
+    return Object.fromEntries(Object.keys(entries).map((role, index) => {
+        const texture = sources[index].clone();
+        texture.colorSpace = MATERIAL_TEXTURE_SEMANTICS[role]?.colorSpace === "srgb" ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+        texture.wrapS = wrapping;
+        texture.wrapT = wrapping;
+        texture.anisotropy = config.anisotropy ?? 1;
+        texture.needsUpdate = true;
+        return [role, texture];
+    }));
+}
+/** Apply PBR settings and optional metre UVs to an owned standard material. @internal */
+export function configureAuthoredSurface(material, config, textures, shape) {
+    const tile = config.repeatMetres;
+    if (tile !== undefined && (!Number.isFinite(tile) || tile <= 0))
+        throw new Error("repeatMetres must be finite and positive");
+    if (config.normalScale?.some(value => !Number.isFinite(value)))
+        throw new Error("normalScale must be finite");
+    if (config.anisotropy !== undefined && (!Number.isFinite(config.anisotropy) || config.anisotropy < 1))
+        throw new Error("anisotropy must be finite and >= 1");
+    if ([config.displacementScale, config.displacementBias].some(value => value !== undefined && !Number.isFinite(value)))
+        throw new Error("displacement settings must be finite");
+    const { anisotropy: _samplerAnisotropy, surfaceAnisotropy, ...surface } = config;
+    if (requiresPhysicalMaterial({ ...surface, normalScale: surface.normalScale === undefined ? undefined : [...surface.normalScale], anisotropy: surfaceAnisotropy }, textures) && !material.isMeshPhysicalMaterial)
+        throw new Error("Physical authored surface settings require MeshPhysicalMaterial");
+    applyMaterialOverrideToMaterial(material, { ...surface, normalScale: surface.normalScale === undefined ? undefined : [...surface.normalScale], anisotropy: surfaceAnisotropy }, false, textures);
+    if (config.displacementScale !== undefined)
+        material.displacementScale = config.displacementScale;
+    if (config.displacementBias !== undefined)
+        material.displacementBias = config.displacementBias;
+    if (config.transparent !== undefined)
+        material.transparent = config.transparent;
+    if (config.opacity !== undefined)
+        material.opacity = config.opacity;
+    if (config.depthWrite !== undefined)
+        material.depthWrite = config.depthWrite;
+    if (config.normalScale !== undefined)
+        material.normalScale.set(...config.normalScale);
+    if (tile === undefined)
+        return;
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey();
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        shader.vertexShader = shader.vertexShader.replace("#include <uv_vertex>", `#include <uv_vertex>
+mat4 surfaceTransform = modelMatrix;
+#ifdef USE_INSTANCING
+ surfaceTransform = modelMatrix * instanceMatrix;
+#endif
+vec3 surfaceExtent = vec3(length(surfaceTransform[0].xyz), length(surfaceTransform[1].xyz), length(surfaceTransform[2].xyz));
+vec2 surfaceRepeat = ${shape === "box"
+            ? "abs(normal.x) > 0.5 ? surfaceExtent.zy : abs(normal.y) > 0.5 ? surfaceExtent.xz : surfaceExtent.xy"
+            : "abs(normal.y) > 0.5 ? surfaceExtent.xz * 2.0 : vec2(6.28318530718 * sqrt((surfaceExtent.x * surfaceExtent.x + surfaceExtent.z * surfaceExtent.z) * 0.5), surfaceExtent.y)"};
+surfaceRepeat /= ${tile.toExponential(8)};
+${Object.entries({ MAP: "vMapUv", NORMALMAP: "vNormalMapUv", ROUGHNESSMAP: "vRoughnessMapUv", AOMAP: "vAoMapUv", METALNESSMAP: "vMetalnessMapUv", EMISSIVEMAP: "vEmissiveMapUv", DISPLACEMENTMAP: "vDisplacementMapUv", ALPHAMAP: "vAlphaMapUv", SHEENCOLORMAP: "vSheenColorMapUv", SHEENROUGHNESSMAP: "vSheenRoughnessMapUv", ANISOTROPYMAP: "vAnisotropyMapUv", CLEARCOATMAP: "vClearcoatMapUv", CLEARCOATROUGHNESSMAP: "vClearcoatRoughnessMapUv", CLEARCOATNORMALMAP: "vClearcoatNormalMapUv", SPECULARINTENSITYMAP: "vSpecularIntensityMapUv", SPECULARCOLORMAP: "vSpecularColorMapUv", TRANSMISSIONMAP: "vTransmissionMapUv", THICKNESSMAP: "vThicknessMapUv", IRIDESCENCEMAP: "vIridescenceMapUv", IRIDESCENCETHICKNESSMAP: "vIridescenceThicknessMapUv" }).map(([role, name]) => {
+            return `#ifdef USE_${role}\n ${name} *= surfaceRepeat;\n#endif`;
+        }).join("\n")}`);
+    };
+    material.customProgramCacheKey = () => `${previousKey}|authored-surface:${shape}:${tile}`;
+}
+/**
+ * Load declared surface-map roles and own the material/map clones (cached textures remain untouched).
+ * Colour, emissive, sheen-colour and specular-colour maps are sRGB; numeric maps are linear. Cylinder side metres use the RMS ellipse circumference approximation.
+ * Static batches and custom meshes share this lifecycle.
+ * @capability authored-surface-material render declared PBR maps with colour-space handling and metre-scale box/cylinder UVs
+ */
+export function useAuthoredSurfaceMaterial(config, shape = "box") {
+    const key = authoredSurfaceKey(config);
+    const entries = useMemo(() => modelMapEntries(config.maps ?? {}), [key]);
+    const loaded = useLoader(THREE.TextureLoader, Object.values(entries));
+    const resources = useDisposable(() => {
+        const textures = authoredSurfaceTextures(entries, loaded, config);
+        const { anisotropy: _samplerAnisotropy, surfaceAnisotropy, ...surface } = config;
+        const material = requiresPhysicalMaterial({ ...surface, normalScale: surface.normalScale === undefined ? undefined : [...surface.normalScale], anisotropy: surfaceAnisotropy }, textures) ? new THREE.MeshPhysicalMaterial() : new THREE.MeshStandardMaterial();
+        try {
+            configureAuthoredSurface(material, config, textures, shape);
+        }
+        catch (error) {
+            material.dispose();
+            Object.values(textures).forEach(texture => texture.dispose());
+            throw error;
+        }
+        return [material, ...Object.values(textures)];
+    }, [key, entries, loaded, shape]);
+    return resources[0];
+}
+/**
+ * Mount an owned PBR surface material on a mesh.
+ * @capability authored-surface-material mount an owned PBR surface material on a mesh
+ */
+export function AuthoredSurfaceMaterial({ surface, shape = "box" }) {
+    const material = useAuthoredSurfaceMaterial(surface, shape);
+    return _jsx("primitive", { object: material, attach: "material" });
+}

package/dist/render/materialAppearanceSignals.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from "three";
+import { type MaterialAppearanceBaseline, type MaterialAppearancePolicy, type MaterialAppearanceResponse } from "@jgengine/core/material/appearanceSignals";
+import type { EnvironmentSample } from "@jgengine/core/world/envField";
+/** Immutable resolved baseline for one caller-owned assigned material, including its original card exposure. */
+export interface RenderMaterialAppearanceBaseline extends MaterialAppearanceBaseline {
+    cardBacklightExposure: number;
+}
+/**
+ * Capture once after assignment; recapture after an authored change. Never capture an already wet material.
+ * @capability material-appearance-signals capture immutable resolved dry values from one owned assigned material
+ */
+export declare function captureMaterialAppearanceBaseline(material: THREE.MeshStandardMaterial): RenderMaterialAppearanceBaseline;
+/**
+ * Apply one sample to an already owned material. Imported/cache materials must be cloned before use.
+ * Allocates no textures or materials; clearcoat/sheen require an existing physical material and opt-in policy.
+ * @capability material-appearance-signals update one owned material from wetness and local card exposure without global lighting edits
+ */
+export declare function applyMaterialAppearanceSignals(material: THREE.MeshStandardMaterial, baseline: MaterialAppearanceBaseline, sample: EnvironmentSample, policy?: MaterialAppearancePolicy): MaterialAppearanceResponse;
+/**
+ * Restore the dry baseline when removing an appearance binding; maps and unrelated imported features remain borrowed.
+ * @capability material-appearance-signals restore dry material response when removing an environment appearance binding
+ */
+export declare function restoreMaterialAppearanceBaseline(material: THREE.MeshStandardMaterial, baseline: RenderMaterialAppearanceBaseline): void;

package/dist/render/materialAppearanceSignals.js

@@ -0,0 +1,58 @@
+import * as THREE from "three";
+import { resolveMaterialAppearance } from "@jgengine/core/material/appearanceSignals";
+import { setHairCardLightExposure } from "./materialAsset.js";
+/**
+ * Capture once after assignment; recapture after an authored change. Never capture an already wet material.
+ * @capability material-appearance-signals capture immutable resolved dry values from one owned assigned material
+ */
+export function captureMaterialAppearanceBaseline(material) {
+    const physical = material;
+    return Object.freeze({
+        roughness: material.roughness,
+        colorLinear: Object.freeze([material.color.r, material.color.g, material.color.b]),
+        ...(physical.isMeshPhysicalMaterial ? { sheen: physical.sheen, clearcoat: physical.clearcoat, clearcoatRoughness: physical.clearcoatRoughness } : {}),
+        cardBacklightExposure: material.userData.jgHairLightExposure ?? 1,
+    });
+}
+/**
+ * Apply one sample to an already owned material. Imported/cache materials must be cloned before use.
+ * Allocates no textures or materials; clearcoat/sheen require an existing physical material and opt-in policy.
+ * @capability material-appearance-signals update one owned material from wetness and local card exposure without global lighting edits
+ */
+export function applyMaterialAppearanceSignals(material, baseline, sample, policy = {}) {
+    if ((policy.wetness?.sheen !== undefined || policy.wetness?.clearcoat !== undefined) && !material.isMeshPhysicalMaterial)
+        throw new TypeError("Wet sheen or clearcoat requires an owned MeshPhysicalMaterial; declare the capability when assigning it.");
+    const response = resolveMaterialAppearance(sample, baseline, policy);
+    const physical = material;
+    if (response.surface.roughness !== undefined)
+        material.roughness = response.surface.roughness;
+    if (response.colorLinear !== undefined)
+        material.color.setRGB(...response.colorLinear, THREE.LinearSRGBColorSpace);
+    if (response.surface.sheen !== undefined)
+        physical.sheen = response.surface.sheen;
+    if (response.surface.clearcoat !== undefined)
+        physical.clearcoat = response.surface.clearcoat;
+    if (response.surface.clearcoatRoughness !== undefined)
+        physical.clearcoatRoughness = response.surface.clearcoatRoughness;
+    if (response.backlightExposure !== undefined)
+        setHairCardLightExposure(material, response.backlightExposure);
+    return response;
+}
+/**
+ * Restore the dry baseline when removing an appearance binding; maps and unrelated imported features remain borrowed.
+ * @capability material-appearance-signals restore dry material response when removing an environment appearance binding
+ */
+export function restoreMaterialAppearanceBaseline(material, baseline) {
+    if ((baseline.sheen !== undefined || baseline.clearcoat !== undefined) && !material.isMeshPhysicalMaterial)
+        throw new TypeError("The appearance baseline belongs to a physical material.");
+    material.roughness = baseline.roughness;
+    material.color.setRGB(...baseline.colorLinear, THREE.LinearSRGBColorSpace);
+    const physical = material;
+    if (baseline.sheen !== undefined)
+        physical.sheen = baseline.sheen;
+    if (baseline.clearcoat !== undefined)
+        physical.clearcoat = baseline.clearcoat;
+    if (baseline.clearcoatRoughness !== undefined)
+        physical.clearcoatRoughness = baseline.clearcoatRoughness;
+    setHairCardLightExposure(material, baseline.cardBacklightExposure);
+}

package/dist/render/materialAsset.d.ts

@@ -0,0 +1,98 @@
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import * as THREE from "three";
+import { type MaterialAsset, type MaterialAssignment, type MaterialAssignmentValidationOptions, type MaterialSurfaceParameters, type MaterialTextureMetadata, type MaterialTextureRole } from "@jgengine/core/material/materialAsset";
+import { type MaterialOverrideTextures } from "../materialOverride.js";
+import { type SurfaceShape } from "./authoredSurfaceMaterial.js";
+/** Shares the model transcoder and loader cache while loading native authored images normally. @internal */
+export declare class MaterialTextureLoader extends THREE.Loader<THREE.Texture> {
+    load(url: string, onLoad?: (texture: THREE.Texture) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): void;
+}
+/**
+ * Validate and configure an owned texture view while retaining the loader's immutable source.
+ * @capability material-texture-metadata configure owned map views with semantic color space, packed channels, UV transforms and sampling
+ */
+export declare function configureMaterialTexture(role: MaterialTextureRole, metadata: MaterialTextureMetadata, source: THREE.Texture): THREE.Texture;
+/**
+ * Physical defaults adapt a declared construction; explicit authored parameters remain authoritative.
+ * @capability material-assets resolve fabric and hair construction into sparse physical appearance parameters
+ */
+export declare function materialAssetSurface(asset: MaterialAsset, overrides?: MaterialSurfaceParameters): MaterialSurfaceParameters;
+/**
+ * Apply one reusable material's parameters, map views and construction to an imported PBR slot.
+ * @capability material-assets clone and configure an imported PBR slot while retaining its omitted physical features and maps
+ */
+export declare function applyMaterialAsset(material: THREE.Material, asset: MaterialAsset, textures?: MaterialOverrideTextures, overrides?: MaterialSurfaceParameters): THREE.MeshStandardMaterial;
+/** Read-only target validation policy; source coverage can reflect an earlier all-slot override. */
+export interface MaterialAssignmentTargetOptions extends MaterialAssignmentValidationOptions {
+    /** Coverage applied to every imported slot before named assignments; never mutates the source. */
+    baseAlphaMode?: MaterialSurfaceParameters["alphaMode"];
+}
+/**
+ * Check selectors, PBR slots, UVs and construction prerequisites before allocating material or texture views.
+ * Optional role restrictions apply only to referenced assets; imported maps remain untouched.
+ * @capability material-slot-selection preflight native model assignments without allocating or changing imported resources
+ */
+export declare function validateMaterialAssignmentTargets(root: THREE.Object3D, assets: readonly MaterialAsset[], assignments: readonly MaterialAssignment[], options?: MaterialAssignmentTargetOptions): void;
+/**
+ * Apply intersecting mesh/slot selectors without changing omitted imported slots. Returns caller-owned replacements; model clones register them only after success.
+ * @capability material-assets assign reusable physical assets to independent imported model slots
+ */
+export declare function applyMaterialAssignments(root: THREE.Object3D, assets: readonly MaterialAsset[], assignments: readonly MaterialAssignment[], textures?: ReadonlyMap<string, MaterialOverrideTextures>): THREE.Material[];
+/** Reusable primitive surface options; physical metre UVs reuse the instanced surface renderer. */
+export interface MaterialAssetSurfaceOptions {
+    shape?: SurfaceShape;
+    repeatMetres?: number;
+    overrides?: MaterialSurfaceParameters;
+}
+/**
+ * Load map views, own their cleanup and build the same physical shader used by model assignments.
+ * @capability material-assets own a serializable material asset's textures and runtime physical shader for a custom renderer
+ */
+export declare function useMaterialAssetMaterial(asset: MaterialAsset, options?: MaterialAssetSurfaceOptions): THREE.MeshStandardMaterial;
+/**
+ * Mount a serializable material asset on an authored primitive, sharing model-slot rendering and owned resource cleanup.
+ * @capability material-assets render authored physical surfaces, woven detail and approximate hair-card appearance
+ */
+export declare function MaterialAssetSurface({ asset, ...options }: {
+    asset: MaterialAsset;
+} & MaterialAssetSurfaceOptions): import("react").JSX.Element;
+/**
+ * Estimate texture allocation from loaded dimensions/mips and report pass/coverage risks. Compressed maps count actual mip bytes; uncompressed bytes bound texture views that may share uploads. This does not measure pixel overdraw.
+ * @capability material-resource-metrics inspect loaded texture byte bounds and physical, coverage and transmission participation
+ */
+export declare function materialResourceMetrics(materials: readonly THREE.Material[]): {
+    materials: number;
+    textures: number;
+    textureBytes: number;
+    unknownTextureSizes: number;
+    blendedMaterials: number;
+    maskedMaterials: number;
+    transmissionMaterials: number;
+    doubleSidedMaterials: number;
+    physicalMaterials: number;
+};
+/** Runtime imported-slot inventory for precise authoring selectors; indices address the mesh material array. */
+export interface ModelMaterialSlotInfo {
+    mesh: string;
+    slot: string;
+    slotIndex: number;
+    materialType: string;
+    uvSets: number[];
+    tangents: boolean;
+    physical: boolean;
+}
+/**
+ * Inspect imported names, local slot indices and directional/map prerequisites without mutating the source.
+ * @capability material-slots discover exact imported mesh and material selectors with UV and tangent prerequisites
+ */
+export declare function inspectModelMaterialSlots(root: THREE.Object3D): ModelMaterialSlotInfo[];
+/** Loaded, owned map views for one model configuration. Loader sources and imported maps remain borrowed. @internal */
+export declare function useModelMaterialTextures(model: Pick<ModelConfig, "material" | "materialAssets" | "materialAssignments">): {
+    global: MaterialOverrideTextures;
+    assets: ReadonlyMap<string, MaterialOverrideTextures>;
+};
+/**
+ * Gate the existing thin-sheet hair-card scatter by sampled local light exposure, without changing scene exposure.
+ * @capability material-appearance-signals apply sampled local exposure to the hair-card backlight approximation without global lighting edits
+ */
+export declare function setHairCardLightExposure(material: THREE.Material, exposure: number): void;