@jgengine/shell 0.26.0 → 0.28.0

package/dist/render/decalGeometry.d.ts

@@ -0,0 +1,26 @@
+import type { TerrainHeightSampler } from "../terrain/terrainMath.js";
+/** Inputs for {@link createDecalDrapeGeometry}. */
+export interface DecalDrapeOptions {
+    /** Decal edge length in metres. */
+    size: number;
+    rotationY: number;
+    heightAt: TerrainHeightSampler;
+    /** Height above the sampled ground, metres. */
+    lift: number;
+    /** Grid resolution per axis; defaults to 12 (bounded, decals are small). */
+    segments?: number;
+}
+/** Baked vertex/index buffers for one draped ground decal. */
+export interface DecalDrapeGeometry {
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+}
+/**
+ * A ground decal's draped quad: an `size`² patch rotated by `rotationY`, every vertex lifted onto
+ * the live terrain so a stain follows a curb or a camber instead of floating over it or sinking
+ * through it. Bounded to one small grid — decals are metres, not patches.
+ * @internal
+ */
+export declare function createDecalDrapeGeometry(options: DecalDrapeOptions): DecalDrapeGeometry;

package/dist/render/decalGeometry.js

@@ -0,0 +1,54 @@
+/**
+ * A ground decal's draped quad: an `size`² patch rotated by `rotationY`, every vertex lifted onto
+ * the live terrain so a stain follows a curb or a camber instead of floating over it or sinking
+ * through it. Bounded to one small grid — decals are metres, not patches.
+ * @internal
+ */
+export function createDecalDrapeGeometry(options) {
+    const segments = Math.max(2, Math.min(24, Math.floor(options.segments ?? 12)));
+    const half = options.size / 2;
+    const cos = Math.cos(options.rotationY);
+    const sin = Math.sin(options.rotationY);
+    const cols = segments + 1;
+    const positions = new Float32Array(cols * cols * 3);
+    const normals = new Float32Array(cols * cols * 3);
+    const uvs = new Float32Array(cols * cols * 2);
+    const eps = Math.max(0.05, options.size / segments / 2);
+    for (let iz = 0; iz < cols; iz += 1) {
+        for (let ix = 0; ix < cols; ix += 1) {
+            const lx = -half + (ix / segments) * options.size;
+            const lz = -half + (iz / segments) * options.size;
+            const x = lx * cos + lz * sin;
+            const z = -lx * sin + lz * cos;
+            const index = iz * cols + ix;
+            positions[index * 3] = x;
+            positions[index * 3 + 1] = options.heightAt(x, z) + options.lift;
+            positions[index * 3 + 2] = z;
+            const hx = options.heightAt(x + eps, z) - options.heightAt(x - eps, z);
+            const hz = options.heightAt(x, z + eps) - options.heightAt(x, z - eps);
+            const length = Math.hypot(hx, 2 * eps, hz) || 1;
+            normals[index * 3] = -hx / length;
+            normals[index * 3 + 1] = (2 * eps) / length;
+            normals[index * 3 + 2] = -hz / length;
+            uvs[index * 2] = ix / segments;
+            uvs[index * 2 + 1] = 1 - iz / segments;
+        }
+    }
+    const indices = new Uint32Array(segments * segments * 6);
+    let cursor = 0;
+    for (let iz = 0; iz < segments; iz += 1) {
+        for (let ix = 0; ix < segments; ix += 1) {
+            const a = iz * cols + ix;
+            const b = a + 1;
+            const c = a + cols;
+            const d = c + 1;
+            indices[cursor++] = a;
+            indices[cursor++] = c;
+            indices[cursor++] = b;
+            indices[cursor++] = b;
+            indices[cursor++] = c;
+            indices[cursor++] = d;
+        }
+    }
+    return { positions, normals, uvs, indices };
+}

package/dist/render/decalTexture.d.ts

@@ -0,0 +1,13 @@
+import type { DecalStyle } from "@jgengine/core/world/decalKind";
+/** Row-major RGBA bytes plus their edge length, ready for a `THREE.DataTexture`. */
+export interface DecalTextureData {
+    size: number;
+    data: Uint8Array;
+}
+/**
+ * The deterministic procedural texture behind one decal style. Same style+seed always bakes the
+ * same bytes; the renderer uploads it once as a `DataTexture`, so no scan is pulled and no game
+ * ships stain art it cannot inspect. Alpha is the coverage; colour is the stain itself.
+ * @internal
+ */
+export declare function createDecalTexture(style: DecalStyle, seed: string, size?: number): DecalTextureData;

package/dist/render/decalTexture.js

@@ -0,0 +1,114 @@
+function hash(x, y, seed) {
+    let h = Math.imul(x | 0, 374761393) ^ Math.imul(y | 0, 668265263) ^ Math.imul(seed | 0, 2246822519);
+    h = Math.imul(h ^ (h >>> 13), 1274126177);
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+function smooth(t) {
+    return t * t * (3 - 2 * t);
+}
+function noise(x, y, seed) {
+    const xi = Math.floor(x);
+    const yi = Math.floor(y);
+    const tx = smooth(x - xi);
+    const ty = smooth(y - yi);
+    const a = hash(xi, yi, seed);
+    const b = hash(xi + 1, yi, seed);
+    const c = hash(xi, yi + 1, seed);
+    const d = hash(xi + 1, yi + 1, seed);
+    return (a + (b - a) * tx) * (1 - ty) + (c + (d - c) * tx) * ty;
+}
+function fbm(x, y, seed) {
+    return noise(x, y, seed) * 0.62 + noise(x * 2.1 + 7.3, y * 2.1 - 3.1, seed + 11) * 0.26 + noise(x * 4.3 - 1.7, y * 4.3 + 5.9, seed + 23) * 0.12;
+}
+function seedOf(text) {
+    let h = 2166136261;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+function smoothstep(edge0, edge1, x) {
+    const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0 || 1e-6)));
+    return t * t * (3 - 2 * t);
+}
+/**
+ * The deterministic procedural texture behind one decal style. Same style+seed always bakes the
+ * same bytes; the renderer uploads it once as a `DataTexture`, so no scan is pulled and no game
+ * ships stain art it cannot inspect. Alpha is the coverage; colour is the stain itself.
+ * @internal
+ */
+export function createDecalTexture(style, seed, size = 128) {
+    const seedNumber = seedOf(seed.length > 0 ? seed : style);
+    const data = new Uint8Array(size * size * 4);
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            const u = x / size - 0.5;
+            const v = y / size - 0.5;
+            const r = Math.hypot(u, v) * 2;
+            const n = fbm(u * 5 + 13.1, v * 5 - 7.7, seedNumber);
+            let alpha = 0;
+            let red = 0;
+            let green = 0;
+            let blue = 0;
+            if (style === "dirt") {
+                const grain = fbm(u * 17 + 3.3, v * 17 + 9.1, seedNumber + 5);
+                alpha = smoothstep(0.5, 0.62, n) * (1 - smoothstep(0.55, 1, r)) * (0.55 + grain * 0.45);
+                const shade = 0.75 + grain * 0.5;
+                red = 0.36 * shade;
+                green = 0.29 * shade;
+                blue = 0.19 * shade;
+            }
+            else if (style === "blood") {
+                const splatter = fbm(u * 7 - 2.2, v * 7 + 4.4, seedNumber);
+                const main = smoothstep(0.46, 0.58, splatter) * (1 - smoothstep(0.6, 1, r));
+                // Satellite droplets: 26 seeded points, each a soft dark ring.
+                let drops = 0;
+                for (let i = 0; i < 26; i += 1) {
+                    const a = hash(i, 3, seedNumber) * Math.PI * 2;
+                    const d = 0.08 + hash(i, 7, seedNumber) * 0.42;
+                    const radius = 0.012 + hash(i, 11, seedNumber) * 0.03;
+                    const dist = Math.hypot(u - Math.cos(a) * d, v - Math.sin(a) * d);
+                    drops = Math.max(drops, 1 - smoothstep(radius * 0.6, radius, dist));
+                }
+                alpha = Math.max(main, drops);
+                const shade = 0.8 + splatter * 0.35;
+                red = 0.46 * shade;
+                green = 0.055 * shade;
+                blue = 0.045 * shade;
+            }
+            else if (style === "paint") {
+                const body = smoothstep(0.44, 0.55, n) * (1 - smoothstep(0.7, 1, r));
+                const streak = smoothstep(0.38, 0.52, fbm(u * 22 + 1.7, v * 5 + 8.3, seedNumber + 3)) * smoothstep(0.2, 0.9, v + 0.5) * 0.5;
+                alpha = Math.max(body, streak * (1 - smoothstep(0.5, 0.9, r)));
+                const shade = 0.86 + n * 0.22;
+                red = 0.84 * shade;
+                green = 0.8 * shade;
+                blue = 0.72 * shade;
+            }
+            else {
+                // Cracks: six warped radial lines plus two branches, faded toward the rim.
+                let line = 0;
+                for (let i = 0; i < 8; i += 1) {
+                    const base = (i / 8) * Math.PI * 2 + hash(i, 1, seedNumber) * 0.7;
+                    const wobble = (fbm(u * 9 + i * 3.1, v * 9 - i * 2.3, seedNumber + i) - 0.5) * 0.5;
+                    const angle = Math.atan2(v, u);
+                    const delta = Math.abs(Math.atan2(Math.sin(angle - base - wobble), Math.cos(angle - base - wobble)));
+                    const width = 0.022 + hash(i, 5, seedNumber) * 0.02;
+                    line = Math.max(line, (1 - smoothstep(0, width, delta * Math.max(0.05, r))) * (1 - smoothstep(0.45, 1, r)));
+                }
+                const grit = fbm(u * 30 + 4.1, v * 30 - 2.8, seedNumber + 9) * 0.35;
+                alpha = Math.max(line, grit * smoothstep(0.35, 0.7, n) * (1 - smoothstep(0.6, 1, r)));
+                red = 0.13;
+                green = 0.12;
+                blue = 0.11;
+            }
+            const index = (y * size + x) * 4;
+            data[index] = Math.round(Math.min(1, red) * 255);
+            data[index + 1] = Math.round(Math.min(1, green) * 255);
+            data[index + 2] = Math.round(Math.min(1, blue) * 255);
+            data[index + 3] = Math.round(Math.min(1, alpha) * 255);
+        }
+    }
+    return { size, data };
+}

package/dist/render/materialAsset.js

@@ -6,6 +6,7 @@ import { MATERIAL_TEXTURE_SEMANTICS, validateMaterialAsset, validateMaterialAssi
 import { applyMaterialOverrideToMaterial, MATERIAL_TEXTURE_PROPERTIES, requiresPhysicalMaterial } from "../materialOverride.js";
 import { configureAuthoredSurface } from "./authoredSurfaceMaterial.js";
 import { ownModelMaterial } from "./modelRender.js";
+import { meshMatchesName } from "./modelMeshMerge.js";
 import { useDisposable } from "./useDisposable.js";
 import { detectKtx2Support, materialKtx2Loader } from "./modelLoad.js";
 import { resolveAssetBaseUrl } from "./assetBase.js";
@@ -200,7 +201,7 @@ function materialAssignmentTargets(root, assets, assignments, options = {}) {
         const selected = [];
         root.traverse(node => {
             const mesh = node;
-            if (!mesh.isMesh || (assignment.selector.mesh !== undefined && mesh.name !== assignment.selector.mesh))
+            if (!mesh.isMesh || (assignment.selector.mesh !== undefined && !meshMatchesName(mesh, assignment.selector.mesh)))
                 return;
             const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
             materials.forEach((material, index) => {

package/dist/render/modelLoad.js

@@ -6,6 +6,7 @@ import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.j
 import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
 import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
 import { resolveAssetBaseUrl } from "./assetBase.js";
+import { mergeModelSubMeshes, mergeSkinnedModelParts } from "./modelMeshMerge.js";
 import { applyModelSurface } from "./modelSurface.js";
 /** Model containers already covered by the whole-model fallback probe; not "texture" errors. @internal */
 const MODEL_URL_RE = /\.(glb|gltf)(\?|#|$)/i;
@@ -212,6 +213,8 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
         super.load(url, (gltf) => {
             recordModelTriangles(url, countSceneTriangles(gltf.scene));
             applyModelSurface(gltf.scene);
+            mergeSkinnedModelParts(gltf.scene);
+            mergeModelSubMeshes(gltf.scene, gltf.animations);
             onLoad(gltf);
         }, onProgress, (event) => {
             if (onError === undefined)

package/dist/render/modelMeshMerge.d.ts

@@ -0,0 +1,49 @@
+import * as THREE from "three";
+/**
+ * Turn load-time sub-mesh merging on or off. On (the default) every loaded model whose meshes share a
+ * material collapses to one mesh per material, which is what a game with many instances of a
+ * multi-mesh prop needs; a game that must keep per-mesh nodes (named material slots, node visibility)
+ * turns it off.
+ * @internal
+ */
+export declare function setModelSubMeshMerge(enabled: boolean): void;
+/** The node names a merged mesh absorbed, in the order they were merged. Empty for an unmerged mesh. @internal */
+export declare function mergedMeshNames(mesh: THREE.Object3D): readonly string[];
+/**
+ * Whether a mesh answers to `name`: its own name, or one of the sub-meshes a load-time merge folded
+ * into it. Name-based lookups (material assignment selectors) go through this so a merged model keeps
+ * resolving the names its source meshes had.
+ * @internal
+ */
+export declare function meshMatchesName(mesh: THREE.Object3D, name: string): boolean;
+/** What {@link mergeModelSubMeshes} did to one loaded model. @internal */
+export interface ModelMeshMergeReport {
+    /** Meshes removed from the graph because their geometry joined a same-material sibling. */
+    merged: number;
+    /** Meshes left in place. */
+    kept: number;
+}
+/**
+ * Collapse a freshly loaded model's meshes that share a material into one mesh per material, baking
+ * each mesh's transform relative to `root` into the merged vertices. Runs once per load, so every
+ * instance cloned from the model inherits the lower draw count.
+ *
+ * Skinned meshes, instanced meshes, meshes with morph targets or rigged ancestors, meshes with
+ * children, hidden meshes, mirrored meshes, and every model carrying an animation clip are left
+ * untouched: a clip can move any node in the file, so baking an animated model's transforms would
+ * freeze it.
+ * @internal
+ */
+export declare function mergeModelSubMeshes(root: THREE.Object3D, animations?: readonly THREE.AnimationClip[]): ModelMeshMergeReport;
+/**
+ * Collapse a rigged model's skinned parts that share a skeleton and a material into one skinned mesh,
+ * so one character is one draw and one bone matrix upload instead of one per body part. Vertices move
+ * into bind space (each part's own `bindMatrix` baked in) and skin indices are remapped onto the
+ * union of the parts' bones, which leaves the posed result unchanged. Runs once per load, before any
+ * clone, so every instance inherits the lower part count.
+ *
+ * Parts with a different material, a different attribute layout, morph targets, several materials or
+ * children stay as they are. A model that only has one part is untouched.
+ * @internal
+ */
+export declare function mergeSkinnedModelParts(root: THREE.Object3D): ModelMeshMergeReport;

package/dist/render/modelMeshMerge.js

@@ -0,0 +1,269 @@
+import * as THREE from "three";
+import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
+const MERGED_NAMES_KEY = "jgMergedMeshNames";
+let mergeEnabled = true;
+/**
+ * Turn load-time sub-mesh merging on or off. On (the default) every loaded model whose meshes share a
+ * material collapses to one mesh per material, which is what a game with many instances of a
+ * multi-mesh prop needs; a game that must keep per-mesh nodes (named material slots, node visibility)
+ * turns it off.
+ * @internal
+ */
+export function setModelSubMeshMerge(enabled) {
+    mergeEnabled = enabled;
+}
+/** The node names a merged mesh absorbed, in the order they were merged. Empty for an unmerged mesh. @internal */
+export function mergedMeshNames(mesh) {
+    const names = mesh.userData[MERGED_NAMES_KEY];
+    return Array.isArray(names) ? names : [];
+}
+/**
+ * Whether a mesh answers to `name`: its own name, or one of the sub-meshes a load-time merge folded
+ * into it. Name-based lookups (material assignment selectors) go through this so a merged model keeps
+ * resolving the names its source meshes had.
+ * @internal
+ */
+export function meshMatchesName(mesh, name) {
+    return mesh.name === name || mergedMeshNames(mesh).includes(name);
+}
+function countMeshes(root) {
+    let count = 0;
+    root.traverse((node) => {
+        if (node.isMesh === true)
+            count += 1;
+    });
+    return count;
+}
+/** Skinning, instancing and bone parents are all driven at runtime, so their transforms cannot be baked. */
+function hasRiggedAncestor(mesh, root) {
+    let node = mesh;
+    while (node !== null && node !== root) {
+        if (node.isBone === true)
+            return true;
+        if (node.isSkinnedMesh === true)
+            return true;
+        node = node.parent;
+    }
+    return false;
+}
+/** Attribute layout two geometries must agree on before their vertices can share a draw. */
+function attributeKey(geometry) {
+    const parts = [geometry.index === null ? "plain" : "indexed"];
+    for (const name of Object.keys(geometry.attributes).sort()) {
+        const attribute = geometry.attributes[name];
+        parts.push(`${name}:${attribute.itemSize}:${attribute.normalized === true ? 1 : 0}`);
+    }
+    return parts.join(",");
+}
+function isMergeable(mesh, root) {
+    if (mesh.isSkinnedMesh === true || mesh.isInstancedMesh === true)
+        return false;
+    // A node with children carries them: removing it would orphan them, and merging the children instead
+    // is handled by their own groups.
+    if (mesh.children.length > 0)
+        return false;
+    if (mesh.visible !== true)
+        return false;
+    if (Array.isArray(mesh.material) || mesh.material === undefined || mesh.material === null)
+        return false;
+    const geometry = mesh.geometry;
+    if (geometry === undefined || geometry.attributes.position === undefined)
+        return false;
+    if (Object.keys(geometry.morphAttributes).length > 0)
+        return false;
+    return !hasRiggedAncestor(mesh, root);
+}
+/**
+ * Collapse a freshly loaded model's meshes that share a material into one mesh per material, baking
+ * each mesh's transform relative to `root` into the merged vertices. Runs once per load, so every
+ * instance cloned from the model inherits the lower draw count.
+ *
+ * Skinned meshes, instanced meshes, meshes with morph targets or rigged ancestors, meshes with
+ * children, hidden meshes, mirrored meshes, and every model carrying an animation clip are left
+ * untouched: a clip can move any node in the file, so baking an animated model's transforms would
+ * freeze it.
+ * @internal
+ */
+export function mergeModelSubMeshes(root, animations = []) {
+    if (!mergeEnabled || animations.length > 0)
+        return { merged: 0, kept: countMeshes(root) };
+    root.updateMatrixWorld(true);
+    const rootInverse = root.matrixWorld.clone().invert();
+    const groups = new Map();
+    let kept = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.isMesh !== true)
+            return;
+        if (!isMergeable(mesh, root)) {
+            kept += 1;
+            return;
+        }
+        // A mirrored node renders with flipped winding, which a baked vertex has no way to express.
+        const relative = new THREE.Matrix4().multiplyMatrices(rootInverse, mesh.matrixWorld);
+        if (relative.determinant() < 0) {
+            kept += 1;
+            return;
+        }
+        const material = mesh.material;
+        const key = `${material.uuid}|${attributeKey(mesh.geometry)}`;
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, { material, meshes: [{ mesh, relative }] });
+        else
+            group.meshes.push({ mesh, relative });
+    });
+    let merged = 0;
+    for (const group of groups.values()) {
+        if (group.meshes.length < 2) {
+            kept += group.meshes.length;
+            continue;
+        }
+        const parts = group.meshes.map(({ mesh, relative }) => mesh.geometry.clone().applyMatrix4(relative));
+        const geometry = mergeGeometries(parts, false);
+        for (const part of parts)
+            part.dispose();
+        if (geometry === null) {
+            kept += group.meshes.length;
+            continue;
+        }
+        geometry.computeBoundingBox();
+        geometry.computeBoundingSphere();
+        const first = group.meshes[0].mesh;
+        const mesh = new THREE.Mesh(geometry, group.material);
+        mesh.name = first.name;
+        mesh.renderOrder = first.renderOrder;
+        mesh.frustumCulled = first.frustumCulled;
+        mesh.castShadow = first.castShadow;
+        mesh.receiveShadow = first.receiveShadow;
+        const names = [...new Set(group.meshes.map(({ mesh: source }) => source.name).filter((name) => name.length > 0))];
+        if (names.length > 0)
+            mesh.userData[MERGED_NAMES_KEY] = names;
+        for (const { mesh: source } of group.meshes)
+            source.removeFromParent();
+        root.add(mesh);
+        merged += group.meshes.length - 1;
+        kept += 1;
+    }
+    return { merged, kept };
+}
+function boneSlot(slots, bone, inverse) {
+    const found = slots.findIndex((slot) => slot.bone === bone && slot.inverse.equals(inverse));
+    if (found >= 0)
+        return found;
+    slots.push({ bone, inverse: inverse.clone() });
+    return slots.length - 1;
+}
+function isMergeableSkinnedPart(mesh) {
+    if (mesh.isSkinnedMesh !== true)
+        return false;
+    if (mesh.children.length > 0 || mesh.visible !== true)
+        return false;
+    if (Array.isArray(mesh.material) || mesh.material === undefined || mesh.material === null)
+        return false;
+    const geometry = mesh.geometry;
+    if (geometry.attributes.position === undefined)
+        return false;
+    if (Object.keys(geometry.morphAttributes).length > 0)
+        return false;
+    return geometry.getAttribute("skinIndex") !== undefined && geometry.getAttribute("skinWeight") !== undefined;
+}
+/**
+ * Collapse a rigged model's skinned parts that share a skeleton and a material into one skinned mesh,
+ * so one character is one draw and one bone matrix upload instead of one per body part. Vertices move
+ * into bind space (each part's own `bindMatrix` baked in) and skin indices are remapped onto the
+ * union of the parts' bones, which leaves the posed result unchanged. Runs once per load, before any
+ * clone, so every instance inherits the lower part count.
+ *
+ * Parts with a different material, a different attribute layout, morph targets, several materials or
+ * children stay as they are. A model that only has one part is untouched.
+ * @internal
+ */
+export function mergeSkinnedModelParts(root) {
+    if (!mergeEnabled)
+        return { merged: 0, kept: countMeshes(root) };
+    root.updateMatrixWorld(true);
+    const groups = new Map();
+    let kept = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.isMesh !== true)
+            return;
+        if (!isMergeableSkinnedPart(mesh)) {
+            if (mesh.isSkinnedMesh === true)
+                kept += 1;
+            return;
+        }
+        const skinned = mesh;
+        const bones = skinned.skeleton.bones.map((bone) => bone.uuid).join(",");
+        const material = skinned.material;
+        const key = `${material.uuid}|${attributeKey(skinned.geometry)}|${bones}`;
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, { material, meshes: [skinned] });
+        else
+            group.meshes.push(skinned);
+    });
+    let merged = 0;
+    for (const group of groups.values()) {
+        if (group.meshes.length < 2) {
+            kept += group.meshes.length;
+            continue;
+        }
+        const slots = [];
+        const parts = [];
+        for (const mesh of group.meshes) {
+            const source = mesh.geometry;
+            const part = new THREE.BufferGeometry();
+            for (const [name, attribute] of Object.entries(source.attributes))
+                part.setAttribute(name, attribute.clone());
+            if (source.index !== null)
+                part.setIndex(source.index.clone());
+            part.applyMatrix4(mesh.bindMatrix);
+            const skinIndex = source.getAttribute("skinIndex");
+            const skinWeight = source.getAttribute("skinWeight");
+            const bySkeletonIndex = mesh.skeleton.bones.map((bone, index) => boneSlot(slots, bone, mesh.skeleton.boneInverses[index]));
+            const indices = new Float32Array(skinIndex.count * 4);
+            const weights = new Float32Array(skinWeight.count * 4);
+            for (let vertex = 0; vertex < skinIndex.count; vertex += 1) {
+                for (let channel = 0; channel < 4; channel += 1) {
+                    indices[vertex * 4 + channel] = bySkeletonIndex[skinIndex.getComponent(vertex, channel)] ?? 0;
+                    weights[vertex * 4 + channel] = skinWeight.getComponent(vertex, channel);
+                }
+            }
+            part.setAttribute("skinIndex", new THREE.Float32BufferAttribute(indices, 4));
+            part.setAttribute("skinWeight", new THREE.Float32BufferAttribute(weights, 4));
+            parts.push(part);
+        }
+        const geometry = mergeGeometries(parts, false);
+        for (const part of parts)
+            part.dispose();
+        if (geometry === null) {
+            kept += group.meshes.length;
+            continue;
+        }
+        geometry.computeBoundingBox();
+        geometry.computeBoundingSphere();
+        const first = group.meshes[0];
+        const mesh = new THREE.SkinnedMesh(geometry, group.material);
+        // Bind mode "attached" keeps bindMatrixInverse equal to the mesh's own world matrix, which is what
+        // makes vertices baked out of bind space pose the same wherever the merged node hangs. An explicit
+        // identity bind matrix is required: bind() would otherwise recalculate rest inverses from the
+        // current pose and skin every part against the wrong rest.
+        mesh.bind(new THREE.Skeleton(slots.map((slot) => slot.bone), slots.map((slot) => slot.inverse)), new THREE.Matrix4());
+        mesh.name = first.name;
+        mesh.renderOrder = first.renderOrder;
+        mesh.frustumCulled = first.frustumCulled;
+        mesh.castShadow = first.castShadow;
+        mesh.receiveShadow = first.receiveShadow;
+        const names = [...new Set(group.meshes.map((part) => part.name).filter((name) => name.length > 0))];
+        if (names.length > 0)
+            mesh.userData[MERGED_NAMES_KEY] = names;
+        for (const source of group.meshes)
+            source.removeFromParent();
+        root.add(mesh);
+        merged += group.meshes.length - 1;
+        kept += 1;
+    }
+    return { merged, kept };
+}

package/dist/render/modelWind.d.ts

@@ -0,0 +1,28 @@
+import * as THREE from "three";
+import type { ModelWindConfig } from "@jgengine/core/game/playableGame";
+/** Shared gust clock every foliage material reads; advanced once per frame by `WindClock`. */
+export declare const windClock: {
+    value: number;
+};
+/** Shared gust direction (XZ); a model may override it with its own authored direction. */
+export declare const windDirection: THREE.Vector2;
+/** Resolved sway settings baked into one material. */
+export interface ResolvedModelWind {
+    strength: number;
+    speed: number;
+    height: number;
+    direction: THREE.Vector2;
+}
+/** Fully-defaulted sway settings for a model. @internal */
+export declare function resolveModelWind(wind: ModelWindConfig | false | undefined, fallbackHeight: number): ResolvedModelWind | null;
+/**
+ * Compiles height-ramped wind sway into a standard material's vertex shader. Idempotent per
+ * material; the clock and direction are shared module uniforms, so the whole scene advances with
+ * one write per frame and no per-material bookkeeping.
+ * @capability model-wind sway a foliage model in the shared gust field
+ */
+export declare function applyModelWind(material: THREE.MeshStandardMaterial, wind: ResolvedModelWind): THREE.MeshStandardMaterial;
+/** Applies wind to every standard material under a cloned model. @internal */
+export declare function applyModelWindToScene(root: THREE.Object3D, wind: ModelWindConfig | false | undefined, fallbackHeight?: number): void;
+/** Advances the shared gust clock once per frame; mount one per 3D world. */
+export declare function WindClock(): null;