@woosh/meep-engine 3.52.0 → 3.54.0

package/src/engine/graphics3/prefab/prefab_compile.js

@@ -1,334 +1,369 @@
-import { assert } from "../../../core/assert.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-import { ShadeAnimationChannel } from "../../../shade/renderer/animation/ShadeAnimationChannel.js";
-import { ShadeAnimationClip } from "../../../shade/renderer/animation/ShadeAnimationClip.js";
-import { Skin } from "../../../shade/renderer/animation/Skin.js";
-import { Transform64 } from "../../ecs/transform/Transform64.js";
-import { Prefab, PrefabPrimitive } from "./Prefab.js";
-import { prefab_normalize_skin_frames } from "./prefab_normalize_skin_frames.js";
-import { prefab_skin_clip_scale_conflicts } from "./prefab_skin_clip_scale_conflicts.js";
-
-/**
- * @typedef {import("../../../shade/renderer/loader/SceneBundle.js").SceneBundle} SceneBundle
- * @typedef {import("../../../shade/renderer/loader/SceneNode.js").SceneNode} SceneNode
- */
-
-/**
- * The root's world, and every node's until it is composed.
- *
- * @type {Float64Array}
- */
-const IDENTITY = new Float64Array([
-    1, 0, 0, 0,
-    0, 1, 0, 0,
-    0, 0, 1, 0,
-    0, 0, 0, 1,
-]);
-
-/**
- * Whether a root can be folded into the prefab's root: it carries nothing an entity would be
- * spawned for. glTF gives every scene one of these, so folding it is one entity fewer per
- * placement; a root that is posed, named, drawn or animated is kept.
- *
- * @param {SceneNode} node
- * @param {number} index the node's index in the bundle
- * @param {Set<number>} referenced indices of the nodes a skin or a clip names
- * @returns {boolean}
- */
-function foldable(node, index, referenced) {
-    return node.parent === -1
-        && node.name === ""
-        && node.geometry === null
-        && node.local.isIdentity()
-        && !referenced.has(index);
-}
-
-/**
- * Compile what a loader produced into a {@link Prefab}.
- *
- * The bundle is read and never written: it is the loader's, shared by every placement of the
- * model and by whatever else reads it. Geometry, materials, inverse-bind matrices and curves are
- * referenced, not copied.
- *
- * The bundle's nodes are in pre-order, so one forward pass indexes them with every parent below
- * its children and composes each world from its parent's. Skins and clips are re-addressed from
- * the bundle's indices to the prefab's; nothing about them changes otherwise. Then, once per model
- * rather than once per placement, each skin's meshes are put into the frame the skin deforms in
- * ({@link prefab_normalize_skin_frames}) and each clip that scales something is checked against
- * each skin ({@link prefab_skin_clip_scale_conflicts}), both reported the way the animation
- * manager used to report them on registration.
- *
- * @param {SceneBundle} bundle
- * @returns {Prefab}
- */
-export function prefab_compile(bundle) {
-    assert.defined(bundle, 'bundle');
-    assert.equal(bundle.isSceneBundle, true, 'bundle.isSceneBundle !== true');
-
-    const nodes = bundle.nodes;
-
-    const referenced = new Set();
-
-    for (const skin of bundle.skins) {
-        for (const joint of skin.joints) {
-            referenced.add(joint);
-        }
-
-        for (const mesh of skin.meshes) {
-            referenced.add(mesh);
-        }
-    }
-
-    for (const clip of bundle.clips) {
-        for (const channel of clip.channels) {
-            referenced.add(channel.target);
-        }
-    }
-
-    const prefab = new Prefab();
-
-    /**
-     * The prefab index of each bundle node; a folded root's is the prefab's root.
-     *
-     * @type {Int32Array}
-     */
-    const index_of = new Int32Array(nodes.length).fill(-1);
-
-    const parents = [-1];
-    const names = [""];
-    const locals = [new Transform64()];
-    const worlds = [new Float64Array(IDENTITY)];
-
-    for (let i = 0; i < nodes.length; i++) {
-        const node = nodes[i];
-
-        assert.equal(node.parent < i, true, `bundle node ${i} names parent ${node.parent}: the bundle is not in pre-order`);
-
-        if (foldable(node, i, referenced)) {
-            index_of[i] = 0;
-
-            continue;
-        }
-
-        const parent = node.parent === -1 ? 0 : index_of[node.parent];
-        const index = parents.length;
-
-        index_of[i] = index;
-
-        parents.push(parent);
-        names.push(node.name);
-
-        const local = new Transform64();
-
-        local.copy(node.local);
-        local.updateMatrix();
-
-        locals.push(local);
-
-        const world = new Float64Array(16);
-
-        m4_multiply(world, worlds[parent], local);
-
-        worlds.push(world);
-
-        if (node.geometry !== null) {
-            const primitive = new PrefabPrimitive();
-
-            primitive.node = index;
-            primitive.geometry = node.geometry;
-            primitive.material = node.material;
-
-            prefab.primitives.push(primitive);
-        }
-    }
-
-    prefab.node_count = parents.length;
-    prefab.parent = Int32Array.from(parents);
-    prefab.name = names;
-    prefab.local = locals;
-    prefab.world = worlds;
-    prefab.animated = new Uint8Array(parents.length);
-    prefab.index_names();
-
-    /**
-     * @param {number} node an index into the bundle's nodes
-     * @param {string} what
-     * @returns {number} the prefab's index for it
-     */
-    function resolve(node, what) {
-        assert.isNonNegativeInteger(node, `${what}: a node is named by its index in the bundle`);
-        assert.lessThan(node, nodes.length, `${what} names node ${node}, and the bundle has ${nodes.length}`);
-
-        return index_of[node];
-    }
-
-    prefab.skins = bundle.skins.map((skin, s) => {
-        const joints = skin.joints.map((joint, j) => resolve(joint, `skin ${s} joint ${j}`));
-        const meshes = skin.meshes.map((mesh, m) => resolve(mesh, `skin ${s} mesh ${m}`));
-
-        for (const joint of joints) {
-            prefab.animated[joint] = 1;
-        }
-
-        for (const mesh of meshes) {
-            const primitive = prefab.primitives.find(primitive => primitive.node === mesh);
-
-            assert.defined(primitive, `skin ${s} deforms node ${mesh}, which carries no geometry`);
-
-            primitive.skin = s;
-        }
-
-        return Skin.from({
-            name: skin.name,
-            joints,
-            inverse_bind_matrices: skin.inverse_bind_matrices,
-            meshes,
-        });
-    });
-
-    prefab.clips = bundle.clips.map((clip, c) => ShadeAnimationClip.from({
-        name: clip.name,
-        channels: clip.channels.map((channel, ch) => {
-            const target = resolve(channel.target, `clip ${c} channel ${ch}`);
-
-            prefab.animated[target] = 1;
-
-            return ShadeAnimationChannel.from({
-                target,
-                property: channel.property,
-                curves: channel.curves,
-            });
-        }),
-    }));
-
-    /*
-     A node under an animated one is animated too: once a clip takes the joint, the GPU composes
-     the joint's world and every world below it, so the instance has to be able to say so on each
-     of those entities without adding a component mid-game. Pre-order puts every parent before
-     its children, so one pass carries the mark all the way down.
-    */
-    const animated = prefab.animated;
-    const parent_of = prefab.parent;
-
-    for (let i = 1; i < animated.length; i++) {
-        if (animated[parent_of[i]] === 1) {
-            animated[i] = 1;
-        }
-    }
-
-    const reports = prefab_normalize_skin_frames(prefab);
-
-    for (let s = 0; s < reports.length; s++) {
-        report_frame(prefab, prefab.skins[s], reports[s]);
-    }
-
-    for (const clip of prefab.clips) {
-        for (const skin of prefab.skins) {
-            report_scale_conflicts(prefab, skin, clip);
-        }
-    }
-
-    return prefab;
-}
-
-/**
- * The name a person would recognise a skin by: its own, or its first mesh's.
- *
- * @param {Prefab} prefab
- * @param {Skin} skin
- * @returns {string}
- */
-function skin_label(prefab, skin) {
-    if (skin.name !== '') {
-        return skin.name;
-    }
-
-    const mesh = skin.meshes[0];
-
-    return mesh === undefined ? '<unnamed>' : (prefab.name[mesh] || '<unnamed>');
-}
-
-/**
- * Say what {@link prefab_normalize_skin_frames} found, on the console, the way registration
- * used to: an asset that renders wrong should say which asset and by how much, once, where it
- * was compiled, rather than reaching a person as a screenshot of soup.
- *
- * @param {Prefab} prefab
- * @param {Skin} skin
- * @param {object} report
- */
-function report_frame(prefab, skin, report) {
-    const label = skin_label(prefab, skin);
-
-    if (report.frame_defect > 0.001) {
-        console.error(
-            `skin '${label}': no frame can deform it — `
-            + `inverse(frame) × joint.global × inverse_bind is ${report.frame_defect.toFixed(4)} `
-            + `away from rigid at its own bind pose, and a dual quaternion carries a rotation and `
-            + `a translation and nothing else. The rest pose has a non-uniform scale or a shear `
-            + `in it. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §4.`
-        );
-
-        return;
-    }
-
-    if (report.residual > 0.001) {
-        console.error(
-            `skin '${label}': its mesh frame did not land — ${report.residual.toFixed(6)} `
-            + `left over. A correction carrying shear does not survive a Transform64's TRS `
-            + `components. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §3.`
-        );
-
-        return;
-    }
-
-    for (const mesh of report.obstructed) {
-        console.warn(
-            `skin '${label}': mesh node '${prefab.name[mesh]}' carries the skin's frame now, and `
-            + `its child nodes inherit it. Sockets belong on bones.`
-        );
-    }
-
-    if (report.corrected > 0) {
-        // verbose rather than a warning: this is a legal asset shape, and a crowd of them would
-        // otherwise be a crowd of log lines
-        console.debug(
-            `skin '${label}': ${report.corrected} mesh frame(s) moved onto the skin's bind `
-            + `transform, absorbing ${report.absorbed.toFixed(4)} of non-rigidity the skinning `
-            + `pass could not have carried.`
-        );
-    }
-}
-
-/**
- * Say so when a clip scales a skin's joints out from under the frame it is deformed in. Nothing
- * is refused: the clip is legal animation and the skin is a legal skin, and it is their
- * combination the skinning pass cannot carry.
- *
- * @param {Prefab} prefab
- * @param {Skin} skin
- * @param {ShadeAnimationClip} clip
- */
-function report_scale_conflicts(prefab, skin, clip) {
-    const conflicts = prefab_skin_clip_scale_conflicts(prefab, skin, clip);
-
-    if (conflicts.length === 0) {
-        return;
-    }
-
-    const nodes = conflicts.map(conflict => prefab.name[conflict.node] || '<unnamed>').join(', ');
-
-    const uniform = conflicts.every(conflict => conflict.uniform);
-
-    console.error(
-        `clip '${clip.name}' scales ${conflicts.length} node(s) of skin '${skin_label(prefab, skin)}' — `
-        + `${nodes} — which reach its joints but not its mesh, so the scale enters the joint `
-        + `matrices and not the frame they are folded against. A dual quaternion cannot carry `
-        + `it and no choice of frame fixes it: the deformation will be wrong while this clip `
-        + `plays. `
-        + (uniform
-            ? `The scale is uniform, which SKINNING_FRAME_PLAN.md §4 has a design for.`
-            : `The scale is non-uniform, which no dual quaternion holds — §4's linear-blend `
-            + `path or an import-time refusal.`)
-    );
-}
+import { assert } from "../../../core/assert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { FoliageWindJoint } from "../../../shade/renderer/animation/foliage/FoliageWindJoint.js";
+import { FoliageWindRig } from "../../../shade/renderer/animation/foliage/FoliageWindRig.js";
+import { ShadeAnimationChannel } from "../../../shade/renderer/animation/ShadeAnimationChannel.js";
+import { ShadeAnimationClip } from "../../../shade/renderer/animation/ShadeAnimationClip.js";
+import { Skin } from "../../../shade/renderer/animation/Skin.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { Prefab, PrefabPrimitive } from "./Prefab.js";
+import { prefab_normalize_skin_frames } from "./prefab_normalize_skin_frames.js";
+import { prefab_skin_clip_scale_conflicts } from "./prefab_skin_clip_scale_conflicts.js";
+
+/**
+ * @typedef {import("../../../shade/renderer/loader/SceneBundle.js").SceneBundle} SceneBundle
+ * @typedef {import("../../../shade/renderer/loader/SceneNode.js").SceneNode} SceneNode
+ */
+
+/**
+ * The root's world, and every node's until it is composed.
+ *
+ * @type {Float64Array}
+ */
+const IDENTITY = new Float64Array([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1,
+]);
+
+/**
+ * Whether a root can be folded into the prefab's root: it carries nothing an entity would be
+ * spawned for. glTF gives every scene one of these, so folding it is one entity fewer per
+ * placement; a root that is posed, named, drawn or animated is kept.
+ *
+ * @param {SceneNode} node
+ * @param {number} index the node's index in the bundle
+ * @param {Set<number>} referenced indices of the nodes a skin or a clip names
+ * @returns {boolean}
+ */
+function foldable(node, index, referenced) {
+    return node.parent === -1
+        && node.name === ""
+        && node.geometry === null
+        && node.local.isIdentity()
+        && !referenced.has(index);
+}
+
+/**
+ * Compile what a loader produced into a {@link Prefab}.
+ *
+ * The bundle is read and never written: it is the loader's, shared by every placement of the
+ * model and by whatever else reads it. Geometry, materials, inverse-bind matrices and curves are
+ * referenced, not copied.
+ *
+ * The bundle's nodes are in pre-order, so one forward pass indexes them with every parent below
+ * its children and composes each world from its parent's. Skins and clips are re-addressed from
+ * the bundle's indices to the prefab's; nothing about them changes otherwise. Then, once per model
+ * rather than once per placement, each skin's meshes are put into the frame the skin deforms in
+ * ({@link prefab_normalize_skin_frames}) and each clip that scales something is checked against
+ * each skin ({@link prefab_skin_clip_scale_conflicts}), both reported the way the animation
+ * manager used to report them on registration.
+ *
+ * @param {SceneBundle} bundle
+ * @returns {Prefab}
+ */
+export function prefab_compile(bundle) {
+    assert.defined(bundle, 'bundle');
+    assert.equal(bundle.isSceneBundle, true, 'bundle.isSceneBundle !== true');
+
+    const nodes = bundle.nodes;
+
+    const referenced = new Set();
+
+    for (const skin of bundle.skins) {
+        for (const joint of skin.joints) {
+            referenced.add(joint);
+        }
+
+        for (const mesh of skin.meshes) {
+            referenced.add(mesh);
+        }
+    }
+
+    for (const clip of bundle.clips) {
+        for (const channel of clip.channels) {
+            referenced.add(channel.target);
+        }
+    }
+
+    for (const rig of bundle.foliage_rigs) {
+        referenced.add(rig.root);
+        for (const joint of rig.joints) {
+            referenced.add(joint.target);
+        }
+    }
+
+    const prefab = new Prefab();
+
+    /**
+     * The prefab index of each bundle node; a folded root's is the prefab's root.
+     *
+     * @type {Int32Array}
+     */
+    const index_of = new Int32Array(nodes.length).fill(-1);
+
+    const parents = [-1];
+    const names = [""];
+    const locals = [new Transform64()];
+    const worlds = [new Float64Array(IDENTITY)];
+
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+
+        assert.equal(node.parent < i, true, `bundle node ${i} names parent ${node.parent}: the bundle is not in pre-order`);
+
+        if (foldable(node, i, referenced)) {
+            index_of[i] = 0;
+
+            continue;
+        }
+
+        const parent = node.parent === -1 ? 0 : index_of[node.parent];
+        const index = parents.length;
+
+        index_of[i] = index;
+
+        parents.push(parent);
+        names.push(node.name);
+
+        const local = new Transform64();
+
+        local.copy(node.local);
+        local.updateMatrix();
+
+        locals.push(local);
+
+        const world = new Float64Array(16);
+
+        m4_multiply(world, worlds[parent], local);
+
+        worlds.push(world);
+
+        if (node.geometry !== null) {
+            const primitive = new PrefabPrimitive();
+
+            primitive.node = index;
+            primitive.geometry = node.geometry;
+            primitive.material = node.material;
+
+            prefab.primitives.push(primitive);
+        }
+    }
+
+    prefab.node_count = parents.length;
+    prefab.parent = Int32Array.from(parents);
+    prefab.name = names;
+    prefab.local = locals;
+    prefab.world = worlds;
+    prefab.animated = new Uint8Array(parents.length);
+    prefab.index_names();
+
+    /**
+     * @param {number} node an index into the bundle's nodes
+     * @param {string} what
+     * @returns {number} the prefab's index for it
+     */
+    function resolve(node, what) {
+        assert.isNonNegativeInteger(node, `${what}: a node is named by its index in the bundle`);
+        assert.lessThan(node, nodes.length, `${what} names node ${node}, and the bundle has ${nodes.length}`);
+
+        return index_of[node];
+    }
+
+    prefab.skins = bundle.skins.map((skin, s) => {
+        const joints = skin.joints.map((joint, j) => resolve(joint, `skin ${s} joint ${j}`));
+        const meshes = skin.meshes.map((mesh, m) => resolve(mesh, `skin ${s} mesh ${m}`));
+
+        for (const joint of joints) {
+            prefab.animated[joint] = 1;
+        }
+
+        for (const mesh of meshes) {
+            const primitive = prefab.primitives.find(primitive => primitive.node === mesh);
+
+            assert.defined(primitive, `skin ${s} deforms node ${mesh}, which carries no geometry`);
+
+            primitive.skin = s;
+        }
+
+        return Skin.from({
+            name: skin.name,
+            joints,
+            inverse_bind_matrices: skin.inverse_bind_matrices,
+            meshes,
+        });
+    });
+
+    prefab.clips = bundle.clips.map((clip, c) => ShadeAnimationClip.from({
+        name: clip.name,
+        channels: clip.channels.map((channel, ch) => {
+            const target = resolve(channel.target, `clip ${c} channel ${ch}`);
+
+            prefab.animated[target] = 1;
+
+            return ShadeAnimationChannel.from({
+                target,
+                property: channel.property,
+                curves: channel.curves,
+            });
+        }),
+    }));
+
+    prefab.foliage_rigs = bundle.foliage_rigs.map((rig, r) => {
+        const root = resolve(rig.root, `foliage_rig ${r} root`);
+
+        return FoliageWindRig.from({
+            name: rig.name,
+            root,
+            weight: rig.weight,
+            joints: rig.joints.map((joint, j) => {
+                const target = resolve(joint.target, `foliage_rig ${r} joint ${j}`);
+
+                prefab.animated[target] = 1;
+
+                return FoliageWindJoint.from({
+                    target,
+                    branch_axis: joint.branch_axis,
+                    compliance: joint.compliance,
+                    natural_frequency: joint.natural_frequency,
+                    damping_ratio: joint.damping_ratio,
+                    max_angle: joint.max_angle,
+                    turbulence: joint.turbulence,
+                    phase_offset: joint.phase_offset,
+                });
+            }),
+        });
+    });
+
+    /*
+     A node under an animated one is animated too: once a clip takes the joint, the GPU composes
+     the joint's world and every world below it, so the instance has to be able to say so on each
+     of those entities without adding a component mid-game. Pre-order puts every parent before
+     its children, so one pass carries the mark all the way down.
+    */
+    const animated = prefab.animated;
+    const parent_of = prefab.parent;
+
+    for (let i = 1; i < animated.length; i++) {
+        if (animated[parent_of[i]] === 1) {
+            animated[i] = 1;
+        }
+    }
+
+    const reports = prefab_normalize_skin_frames(prefab);
+
+    for (let s = 0; s < reports.length; s++) {
+        report_frame(prefab, prefab.skins[s], reports[s]);
+    }
+
+    for (const clip of prefab.clips) {
+        for (const skin of prefab.skins) {
+            report_scale_conflicts(prefab, skin, clip);
+        }
+    }
+
+    return prefab;
+}
+
+/**
+ * The name a person would recognise a skin by: its own, or its first mesh's.
+ *
+ * @param {Prefab} prefab
+ * @param {Skin} skin
+ * @returns {string}
+ */
+function skin_label(prefab, skin) {
+    if (skin.name !== '') {
+        return skin.name;
+    }
+
+    const mesh = skin.meshes[0];
+
+    return mesh === undefined ? '<unnamed>' : (prefab.name[mesh] || '<unnamed>');
+}
+
+/**
+ * Say what {@link prefab_normalize_skin_frames} found, on the console, the way registration
+ * used to: an asset that renders wrong should say which asset and by how much, once, where it
+ * was compiled, rather than reaching a person as a screenshot of soup.
+ *
+ * @param {Prefab} prefab
+ * @param {Skin} skin
+ * @param {object} report
+ */
+function report_frame(prefab, skin, report) {
+    const label = skin_label(prefab, skin);
+
+    if (report.frame_defect > 0.001) {
+        console.error(
+            `skin '${label}': no frame can deform it — `
+            + `inverse(frame) × joint.global × inverse_bind is ${report.frame_defect.toFixed(4)} `
+            + `away from rigid at its own bind pose, and a dual quaternion carries a rotation and `
+            + `a translation and nothing else. The rest pose has a non-uniform scale or a shear `
+            + `in it. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §4.`
+        );
+
+        return;
+    }
+
+    if (report.residual > 0.001) {
+        console.error(
+            `skin '${label}': its mesh frame did not land — ${report.residual.toFixed(6)} `
+            + `left over. A correction carrying shear does not survive a Transform64's TRS `
+            + `components. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §3.`
+        );
+
+        return;
+    }
+
+    for (const mesh of report.obstructed) {
+        console.warn(
+            `skin '${label}': mesh node '${prefab.name[mesh]}' carries the skin's frame now, and `
+            + `its child nodes inherit it. Sockets belong on bones.`
+        );
+    }
+
+    if (report.corrected > 0) {
+        // verbose rather than a warning: this is a legal asset shape, and a crowd of them would
+        // otherwise be a crowd of log lines
+        console.debug(
+            `skin '${label}': ${report.corrected} mesh frame(s) moved onto the skin's bind `
+            + `transform, absorbing ${report.absorbed.toFixed(4)} of non-rigidity the skinning `
+            + `pass could not have carried.`
+        );
+    }
+}
+
+/**
+ * Say so when a clip scales a skin's joints out from under the frame it is deformed in. Nothing
+ * is refused: the clip is legal animation and the skin is a legal skin, and it is their
+ * combination the skinning pass cannot carry.
+ *
+ * @param {Prefab} prefab
+ * @param {Skin} skin
+ * @param {ShadeAnimationClip} clip
+ */
+function report_scale_conflicts(prefab, skin, clip) {
+    const conflicts = prefab_skin_clip_scale_conflicts(prefab, skin, clip);
+
+    if (conflicts.length === 0) {
+        return;
+    }
+
+    const nodes = conflicts.map(conflict => prefab.name[conflict.node] || '<unnamed>').join(', ');
+
+    const uniform = conflicts.every(conflict => conflict.uniform);
+
+    console.error(
+        `clip '${clip.name}' scales ${conflicts.length} node(s) of skin '${skin_label(prefab, skin)}' — `
+        + `${nodes} — which reach its joints but not its mesh, so the scale enters the joint `
+        + `matrices and not the frame they are folded against. A dual quaternion cannot carry `
+        + `it and no choice of frame fixes it: the deformation will be wrong while this clip `
+        + `plays. `
+        + (uniform
+            ? `The scale is uniform, which SKINNING_FRAME_PLAN.md §4 has a design for.`
+            : `The scale is non-uniform, which no dual quaternion holds — §4's linear-blend `
+            + `path or an import-time refusal.`)
+    );
+}