@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -0,0 +1,334 @@
+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.`)
+    );
+}

package/src/engine/graphics3/prefab/prefab_instantiate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Spawn a prefab as entities under `root`, in bulk.
+ *
+ * **What a model is in an ECS.** Each node of the prefab becomes an entity: named, attached to
+ * its parent's entity by a `TransformAttachment` carrying the node's rest pose, holding a world
+ * `Transform64` composed from the root's, drawing through a `ShadedGeometry` where the node
+ * carries geometry, and declaring `GPUStateAuthority` — with a zero flags word — where a clip or a
+ * skin may later hand the node to the GPU, so that the hand-over is a bit write and never a
+ * component add. Node 0 is `root` itself, the caller's entity, whose `Transform64` is the
+ * placement.
+ *
+ * **Parents before children, and the transform last.** Entities are built in the prefab's node
+ * order, which puts every parent's entity there before its children's, so
+ * `TransformAttachmentSystem` binds each one on the spot rather than parking it. The `Transform64`
+ * is the last component added to each entity, so every system whose dependencies include it —
+ * and they all do — links once, seeing the entity complete.
+ *
+ * Every entity is the root's for its lifetime (`ParentEntity`) and, unless told otherwise,
+ * transient to serialization: a save holds the model's placement, not sixty joints of derived
+ * state.
+ *
+ * @param {Prefab} prefab
+ * @param {EntityComponentDataset} dataset
+ * @param {number} root an entity carrying a `Transform64`
+ * @param {object} [options]
+ * @param {boolean} [options.transient] whether the spawned entities are skipped by serialization;
+ * true unless said otherwise
+ * @returns {PrefabInstance}
+ */
+export function prefab_instantiate(prefab: Prefab, dataset: EntityComponentDataset, root: number, { transient }?: {
+    transient?: boolean;
+}): PrefabInstance;
+/**
+ * Remove every entity an instance spawned. The root is the caller's and stays.
+ *
+ * Children before parents, so that no parent's removal has to reach down and detach a child
+ * that is about to go anyway.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {PrefabInstance} instance
+ */
+export function prefab_instance_destroy(dataset: EntityComponentDataset, instance: PrefabInstance): void;
+export type Prefab = import("./Prefab.js").Prefab;
+export type EntityComponentDataset = import("../../ecs/EntityComponentDataset.js").EntityComponentDataset;
+import { PrefabInstance } from "./PrefabInstance.js";
+//# sourceMappingURL=prefab_instantiate.d.ts.map

package/src/engine/graphics3/prefab/prefab_instantiate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefab_instantiate.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_instantiate.js"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,2CARW,MAAM,WACN,sBAAsB,QACtB,MAAM;IAEY,SAAS,GAA3B,OAAO;IAEL,cAAc,CAgJ1B;AAED;;;;;;;;GAQG;AACH,iDAHW,sBAAsB,YACtB,cAAc,QAWxB;qBApNY,OAAO,aAAa,EAAE,MAAM;qCAC5B,OAAO,qCAAqC,EAAE,sBAAsB;+BAJlD,qBAAqB"}

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

@@ -0,0 +1,230 @@
+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 { SerializationMetadata } from "../../ecs/components/SerializationMetadata.js";
+import { GPUStateAuthority } from "../../ecs/gpu/GPUStateAuthority.js";
+import { Name } from "../../ecs/name/Name.js";
+import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
+import { TransformAttachment } from "../../ecs/transform-attachment/TransformAttachment.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { DrawMode } from "../../graphics/ecs/mesh-v2/DrawMode.js";
+import { ShadedGeometry } from "../../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import { PrefabInstance } from "./PrefabInstance.js";
+
+/**
+ * @typedef {import("./Prefab.js").Prefab} Prefab
+ * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ */
+
+/**
+ * Every component type an instance may attach. Registered once per dataset, before the first
+ * entity is built, because registering a type rebuilds the dataset's occupancy and a spawn of
+ * thousands of entities must not do that per component.
+ *
+ * @type {Function[]}
+ */
+const COMPONENT_TYPES = [
+    Transform64,
+    TransformAttachment,
+    Name,
+    ShadedGeometry,
+    GPUStateAuthority,
+    ParentEntity,
+    SerializationMetadata,
+];
+
+/**
+ * Spawn a prefab as entities under `root`, in bulk.
+ *
+ * **What a model is in an ECS.** Each node of the prefab becomes an entity: named, attached to
+ * its parent's entity by a `TransformAttachment` carrying the node's rest pose, holding a world
+ * `Transform64` composed from the root's, drawing through a `ShadedGeometry` where the node
+ * carries geometry, and declaring `GPUStateAuthority` — with a zero flags word — where a clip or a
+ * skin may later hand the node to the GPU, so that the hand-over is a bit write and never a
+ * component add. Node 0 is `root` itself, the caller's entity, whose `Transform64` is the
+ * placement.
+ *
+ * **Parents before children, and the transform last.** Entities are built in the prefab's node
+ * order, which puts every parent's entity there before its children's, so
+ * `TransformAttachmentSystem` binds each one on the spot rather than parking it. The `Transform64`
+ * is the last component added to each entity, so every system whose dependencies include it —
+ * and they all do — links once, seeing the entity complete.
+ *
+ * Every entity is the root's for its lifetime (`ParentEntity`) and, unless told otherwise,
+ * transient to serialization: a save holds the model's placement, not sixty joints of derived
+ * state.
+ *
+ * @param {Prefab} prefab
+ * @param {EntityComponentDataset} dataset
+ * @param {number} root an entity carrying a `Transform64`
+ * @param {object} [options]
+ * @param {boolean} [options.transient] whether the spawned entities are skipped by serialization;
+ * true unless said otherwise
+ * @returns {PrefabInstance}
+ */
+export function prefab_instantiate(prefab, dataset, root, { transient = true } = {}) {
+    assert.defined(prefab, 'prefab');
+    assert.equal(prefab.isPrefab, true, 'prefab.isPrefab !== true');
+    assert.defined(dataset, 'dataset');
+    assert.equal(dataset.isEntityComponentDataset, true, 'dataset.isEntityComponentDataset !== true');
+    assert.isNonNegativeInteger(root, 'root');
+    assert.ok(dataset.entityExists(root), `root entity ${root} does not exist`);
+
+    dataset.registerManyComponentTypes(COMPONENT_TYPES);
+
+    // Component indices resolved once: an add by index skips the class lookup and the guard that
+    // formats a component into an error message, and there are six or seven adds per entity.
+    const TRANSFORM = dataset.computeComponentTypeIndex(Transform64);
+    const ATTACHMENT = dataset.computeComponentTypeIndex(TransformAttachment);
+    const NAME = dataset.computeComponentTypeIndex(Name);
+    const GEOMETRY = dataset.computeComponentTypeIndex(ShadedGeometry);
+    const AUTHORITY = dataset.computeComponentTypeIndex(GPUStateAuthority);
+    const PARENT = dataset.computeComponentTypeIndex(ParentEntity);
+    const METADATA = dataset.computeComponentTypeIndex(SerializationMetadata);
+
+    const root_transform = dataset.getComponent(root, Transform64);
+
+    assert.defined(root_transform, `root entity ${root} carries no Transform64 to place the model by`);
+
+    const node_count = prefab.node_count;
+
+    const entities = new Int32Array(node_count);
+
+    entities[0] = root;
+
+    // Ids from the dataset's own occupancy, walking forward: `createEntity` scans from bit zero
+    // every time, which is quadratic over a spawn of this size.
+    const occupancy = dataset.entityOccupancy;
+
+    let cursor = 0;
+
+    for (let i = 1; i < node_count; i++) {
+        const entity = occupancy.nextClearBit(cursor);
+
+        dataset.createEntitySpecific(entity);
+
+        entities[i] = entity;
+        cursor = entity + 1;
+    }
+
+    const parent = prefab.parent;
+    const names = prefab.name;
+    const locals = prefab.local;
+    const worlds = prefab.world;
+    const animated = prefab.animated;
+
+    /**
+     * @type {Map<number, import("./Prefab.js").PrefabPrimitive>}
+     */
+    const primitive_of = new Map();
+
+    for (const primitive of prefab.primitives) {
+        primitive_of.set(primitive.node, primitive);
+    }
+
+    // One lifetime component for the whole instance: it names the root and nothing else, it is
+    // immutable while attached, and sixty copies of one number are sixty allocations for nothing.
+    const owner = ParentEntity.from(root);
+
+    for (let i = 1; i < node_count; i++) {
+        const entity = entities[i];
+
+        if (transient) {
+            dataset.addComponentToEntityByIndex(entity, METADATA, SerializationMetadata.Transient);
+        }
+
+        dataset.addComponentToEntityByIndex(entity, PARENT, owner);
+
+        const name = names[i];
+
+        if (name !== "") {
+            dataset.addComponentToEntityByIndex(entity, NAME, new Name(name));
+        }
+
+        if (animated[i] !== 0) {
+            dataset.addComponentToEntityByIndex(entity, AUTHORITY, new GPUStateAuthority());
+        }
+
+        const primitive = primitive_of.get(i);
+
+        if (primitive !== undefined) {
+            const geometry = ShadedGeometry.from(primitive.geometry, primitive.material, DrawMode.Triangles);
+
+            if (primitive.skin !== -1) {
+                geometry.setFlag(ShadedGeometryFlags.Skinned);
+            }
+
+            dataset.addComponentToEntityByIndex(entity, GEOMETRY, geometry);
+        }
+
+        const attachment = new TransformAttachment();
+
+        attachment.parent = entities[parent[i]];
+        attachment.transform.copy(locals[i]);
+
+        // The world is composed below, from the same chain the attachment system would compose
+        // it from, so the system is told not to compose it again at link: a decomposition per
+        // entity, and an announcement nothing is listening for yet. It still follows every move
+        // of the parent from then on.
+        attachment.immediate = false;
+
+        dataset.addComponentToEntityByIndex(entity, ATTACHMENT, attachment);
+
+        // Composed here rather than left to the attachment system, so that a dataset with no
+        // systems — a preview, a spec — holds every world too.
+        const world = new Transform64();
+
+        m4_multiply(world, root_transform, worlds[i]);
+        world.updateComponents();
+
+        dataset.addComponentToEntityByIndex(entity, TRANSFORM, world);
+    }
+
+    const instance = new PrefabInstance();
+
+    instance.prefab = prefab;
+    instance.root = root;
+    instance.entities = entities;
+    instance.mesh_entities = Int32Array.from(prefab.primitives, primitive => entities[primitive.node]);
+
+    instance.skins = prefab.skins.map(skin => Skin.from({
+        name: skin.name,
+        joints: Array.from(skin.joints, joint => entities[joint]),
+        inverse_bind_matrices: skin.inverse_bind_matrices,
+        meshes: Array.from(skin.meshes, mesh => entities[mesh]),
+    }));
+
+    instance.clips = prefab.clips.map(clip => ShadeAnimationClip.from({
+        name: clip.name,
+        channels: clip.channels.map(channel => ShadeAnimationChannel.from({
+            target: entities[channel.target],
+            property: channel.property,
+            curves: channel.curves,
+        })),
+    }));
+
+    return instance;
+}
+
+/**
+ * Remove every entity an instance spawned. The root is the caller's and stays.
+ *
+ * Children before parents, so that no parent's removal has to reach down and detach a child
+ * that is about to go anyway.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {PrefabInstance} instance
+ */
+export function prefab_instance_destroy(dataset, instance) {
+    assert.defined(dataset, 'dataset');
+    assert.defined(instance, 'instance');
+
+    const entities = instance.entities;
+
+    for (let i = entities.length - 1; i >= 1; i--) {
+        dataset.removeEntity(entities[i]);
+    }
+}

package/src/engine/graphics3/prefab/prefab_normalize_skin_frames.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @typedef {object} PrefabSkinFrameReport
+ * @property {number} frame_defect how far the skin is from being deformable in *any* frame; zero
+ * when it is fine
+ * @property {number} absorbed how far from rigid the largest correction was — for a violation,
+ * the number the soup was made of
+ * @property {number} corrected meshes moved
+ * @property {number} unchanged meshes already right
+ * @property {number} residual the worst `|mesh.world − bind|` left afterwards
+ * @property {number[]} obstructed corrected mesh nodes that have children, which inherit a
+ * transform nobody asked for
+ */
+/**
+ * Put every skin's meshes into the frame the skin deforms in, once, on the prefab.
+ *
+ * The skinning pass writes each clone's vertices in `inverse(mesh.global)` space and the
+ * rasterizer re-applies `mesh.global`, so `mesh.global` is the *frame* a skinned mesh's vertices
+ * live in — and the pass gets there by folding `inverse(mesh.global) × joint.global ×
+ * inverse_bind` into a dual quaternion, which carries a rotation and a translation and nothing
+ * else. glTF says a skinned mesh's node transform is ignored, so the frame is the engine's to
+ * choose, and the one that is guaranteed to fold rigidly is the skin's own bind transform,
+ * `joint.global × inverse_bind` at rest ({@link prefab_skin_bind_transform}). After this the fold
+ * is the joint's displacement from bind, rigid whenever the clip rotates and translates and does
+ * not scale. `SKINNING_FRAME_PLAN.md` is the whole argument.
+ *
+ * Done here rather than on registration because the correction is placement-invariant and
+ * idempotent: it is a property of the asset, so it belongs to the compiled model and not to each
+ * of its placements. A file whose inverse-bind matrices already agree with its node transforms is
+ * not touched. A skin whose own bind frame does not fold — a rest pose carrying a non-uniform
+ * scale or a shear — is reported and left as the asset had it.
+ *
+ * The correction goes on the mesh node's **local** transform, and its descendants' worlds are
+ * recomposed, so the prefab's {@link Prefab.world} stays consistent with its {@link Prefab.local}.
+ *
+ * @param {Prefab} prefab
+ * @returns {PrefabSkinFrameReport[]} one report per skin
+ */
+export function prefab_normalize_skin_frames(prefab: Prefab): PrefabSkinFrameReport[];
+export type PrefabSkinFrameReport = {
+    /**
+     * how far the skin is from being deformable in *any* frame; zero
+     * when it is fine
+     */
+    frame_defect: number;
+    /**
+     * how far from rigid the largest correction was — for a violation,
+     * the number the soup was made of
+     */
+    absorbed: number;
+    /**
+     * meshes moved
+     */
+    corrected: number;
+    /**
+     * meshes already right
+     */
+    unchanged: number;
+    /**
+     * the worst `|mesh.world − bind|` left afterwards
+     */
+    residual: number;
+    /**
+     * corrected mesh nodes that have children, which inherit a
+     * transform nobody asked for
+     */
+    obstructed: number[];
+};
+export type Prefab = import("./Prefab.js").Prefab;
+export type Skin = import("../../../shade/renderer/animation/Skin.js").Skin;
+//# sourceMappingURL=prefab_normalize_skin_frames.d.ts.map

package/src/engine/graphics3/prefab/prefab_normalize_skin_frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefab_normalize_skin_frames.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_normalize_skin_frames.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qDAHW,MAAM,GACJ,qBAAqB,EAAE,CAOnC;;;;;;kBAzCa,MAAM;;;;;cAEN,MAAM;;;;eAEN,MAAM;;;;eACN,MAAM;;;;cACN,MAAM;;;;;gBACN,MAAM,EAAE;;qBA9BT,OAAO,aAAa,EAAE,MAAM;mBAC5B,OAAO,2CAA2C,EAAE,IAAI"}