@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -0,0 +1,210 @@
+import { assert } from "../../../core/assert.js";
+import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { m4_rigidity_defect } from "../../../core/geom/3d/mat4/m4_rigidity_defect.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { prefab_skin_bind_transform, prefab_skin_frame_defect } from "./prefab_skin_frame.js";
+
+/**
+ * @typedef {import("./Prefab.js").Prefab} Prefab
+ * @typedef {import("../../../shade/renderer/animation/Skin.js").Skin} Skin
+ */
+
+/**
+ * How far from the bind transform a mesh node may sit and still be left alone, and how large a
+ * residual counts as landed. A `Transform64` recomposes its matrix from TRS components, and the
+ * correction is applied through that round trip, so the frame arrives with rounding on it; this
+ * is far above the rounding and far below anything that shows.
+ *
+ * @type {number}
+ */
+const TOLERANCE = 1e-4;
+
+const IDENTITY = new Float64Array([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1,
+]);
+
+/**
+ * @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) {
+    assert.defined(prefab, 'prefab');
+    assert.equal(prefab.isPrefab, true, 'prefab.isPrefab !== true');
+
+    return prefab.skins.map(skin => normalize_skin(prefab, skin));
+}
+
+/**
+ * @param {Prefab} prefab
+ * @param {Skin} skin
+ * @returns {PrefabSkinFrameReport}
+ */
+function normalize_skin(prefab, skin) {
+    const report = {
+        frame_defect: 0,
+        absorbed: 0,
+        corrected: 0,
+        unchanged: 0,
+        residual: 0,
+        obstructed: [],
+    };
+
+    const bind = new Float64Array(16);
+
+    prefab_skin_bind_transform(bind, prefab, skin);
+
+    report.frame_defect = prefab_skin_frame_defect(prefab, skin, bind);
+
+    if (!(report.frame_defect <= TOLERANCE)) {
+        // `!(x <= t)` rather than `x > t` so that a NaN — a singular joint matrix — lands here too
+        return report;
+    }
+
+    const inverse_world = new Float64Array(16);
+    const correction_matrix = new Float64Array(16);
+    const correction = new Transform64();
+
+    for (const mesh of skin.meshes) {
+        const world = prefab.world[mesh];
+
+        if (!m4_invert(inverse_world, world)) {
+            // a mesh node with no inverse is not a frame either; the skinning pass inverts this
+            report.residual = Infinity;
+
+            continue;
+        }
+
+        m4_multiply(correction_matrix, inverse_world, bind);
+
+        const absorbed = m4_rigidity_defect(correction_matrix);
+
+        report.absorbed = Math.max(report.absorbed, absorbed);
+
+        if (matrix_distance(correction_matrix, IDENTITY) <= TOLERANCE) {
+            report.unchanged++;
+
+            continue;
+        }
+
+        correction.fromMatrix(correction_matrix);
+
+        prefab.local[mesh].multiply(correction);
+
+        recompose_subtree(prefab, mesh);
+
+        report.corrected++;
+        report.residual = Math.max(report.residual, matrix_distance(prefab.world[mesh], bind));
+
+        if (has_children(prefab, mesh)) {
+            report.obstructed.push(mesh);
+        }
+    }
+
+    return report;
+}
+
+/**
+ * Recompose the world of `node` and of every node under it from their locals. Children follow
+ * their parents in index order, so one forward pass from `node` is enough.
+ *
+ * @param {Prefab} prefab
+ * @param {number} node
+ */
+function recompose_subtree(prefab, node) {
+    const parent = prefab.parent;
+    const world = prefab.world;
+    const local = prefab.local;
+
+    /**
+     * @type {Set<number>}
+     */
+    const inside = new Set([node]);
+
+    m4_multiply(world[node], world[parent[node]], local[node]);
+
+    for (let i = node + 1; i < prefab.node_count; i++) {
+        const p = parent[i];
+
+        if (!inside.has(p)) {
+            continue;
+        }
+
+        inside.add(i);
+
+        m4_multiply(world[i], world[p], local[i]);
+    }
+}
+
+/**
+ * @param {Prefab} prefab
+ * @param {number} node
+ * @returns {boolean}
+ */
+function has_children(prefab, node) {
+    const parent = prefab.parent;
+
+    for (let i = node + 1; i < prefab.node_count; i++) {
+        if (parent[i] === node) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * @param {ArrayLike<number>} a
+ * @param {ArrayLike<number>} b
+ * @returns {number}
+ */
+function matrix_distance(a, b) {
+    let worst = 0;
+
+    for (let i = 0; i < 16; i++) {
+        const difference = Math.abs(a[i] - b[i]);
+
+        if (difference > worst) {
+            worst = difference;
+        }
+    }
+
+    return worst;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * @typedef {import("./Prefab.js").Prefab} Prefab
+ * @typedef {import("./PrefabInstance.js").PrefabInstance} PrefabInstance
+ * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../register_instance_animation.js").InstanceAnimationRegistration} InstanceAnimationRegistration
+ */
+/**
+ * Put a model into a scene that has no systems: a playground, a preview, a tool.
+ *
+ * A game does this in two systems — `MeshSystem` spawns the prefab under the entity that wears
+ * it, and `ShadedGeometrySystem` takes a mesh row for every primitive as its component appears.
+ * A scene bound to a bare dataset has neither, so this does the same by hand, in one call: a root
+ * entity carrying `placement`, the prefab spawned under it, a `transforms` row acquired for every
+ * entity of the instance, a `meshes` row attached for every primitive (over a clone of its geometry
+ * where the primitive is skinned), and the instance's skins and clips registered with the
+ * animation manager — unless told otherwise.
+ *
+ * @param {GPUSceneContext} scene_context the scene's context — its rows are where the instance goes
+ * @param {EntityComponentDataset} dataset the dataset the scene is bound to
+ * @param {Prefab} prefab the model, compiled once
+ * @param {Transform64} placement where the model's root goes; copied
+ * @param {object} [options]
+ * @param {boolean} [options.register_animation] whether the instance's skins and clips are
+ *        registered; off leaves a skinned primitive's clone undeformed
+ * @param {boolean} [options.skinned] whether skinned primitives take a row at all; a preview that
+ *        registers no skin has nothing to pose them with and leaves them out
+ * @returns {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null, drawn: number}}
+ *          `drawn` is how many primitives took a row
+ */
+export function prefab_place(scene_context: GPUSceneContext, dataset: EntityComponentDataset, prefab: Prefab, placement: Transform64, { register_animation, skinned }?: {
+    register_animation?: boolean;
+    skinned?: boolean;
+}): {
+    root: number;
+    instance: PrefabInstance;
+    animation: InstanceAnimationRegistration | null;
+    drawn: number;
+};
+/**
+ * Take a placed model out again: its rows given back, its animation unregistered, its entities
+ * removed — the root included, since {@link prefab_place} made it.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {EntityComponentDataset} dataset
+ * @param {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null}} placed
+ *        what {@link prefab_place} answered
+ */
+export function prefab_unplace(scene_context: GPUSceneContext, dataset: EntityComponentDataset, placed: {
+    root: number;
+    instance: PrefabInstance;
+    animation: InstanceAnimationRegistration | null;
+}): void;
+export type Prefab = import("./Prefab.js").Prefab;
+export type PrefabInstance = import("./PrefabInstance.js").PrefabInstance;
+export type EntityComponentDataset = import("../../ecs/EntityComponentDataset.js").EntityComponentDataset;
+export type GPUSceneContext = import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
+export type InstanceAnimationRegistration = import("../register_instance_animation.js").InstanceAnimationRegistration;
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+//# sourceMappingURL=prefab_place.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prefab_place.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_place.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAZW,eAAe,WACf,sBAAsB,UACtB,MAAM,aACN,WAAW;IAEO,kBAAkB,GAApC,OAAO;IAEW,OAAO,GAAzB,OAAO;IAEL;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,6BAA6B,GAAC,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAyDlH;AAED;;;;;;;;GAQG;AACH,8CALW,eAAe,WACf,sBAAsB,UACtB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,6BAA6B,GAAC,IAAI,CAAA;CAAC,QA6BjG;qBAzHY,OAAO,aAAa,EAAE,MAAM;6BAC5B,OAAO,qBAAqB,EAAE,cAAc;qCAC5C,OAAO,qCAAqC,EAAE,sBAAsB;8BACpE,OAAO,kDAAkD,EAAE,eAAe;4CAC1E,OAAO,mCAAmC,EAAE,6BAA6B;4BAX1D,oCAAoC"}

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

@@ -0,0 +1,130 @@
+import { assert } from "../../../core/assert.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { ShadedGeometry } from "../../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import { register_instance_animation, unregister_instance_animation } from "../register_instance_animation.js";
+import { prefab_instance_destroy, prefab_instantiate } from "./prefab_instantiate.js";
+
+/**
+ * @typedef {import("./Prefab.js").Prefab} Prefab
+ * @typedef {import("./PrefabInstance.js").PrefabInstance} PrefabInstance
+ * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../register_instance_animation.js").InstanceAnimationRegistration} InstanceAnimationRegistration
+ */
+
+/**
+ * Put a model into a scene that has no systems: a playground, a preview, a tool.
+ *
+ * A game does this in two systems — `MeshSystem` spawns the prefab under the entity that wears
+ * it, and `ShadedGeometrySystem` takes a mesh row for every primitive as its component appears.
+ * A scene bound to a bare dataset has neither, so this does the same by hand, in one call: a root
+ * entity carrying `placement`, the prefab spawned under it, a `transforms` row acquired for every
+ * entity of the instance, a `meshes` row attached for every primitive (over a clone of its geometry
+ * where the primitive is skinned), and the instance's skins and clips registered with the
+ * animation manager — unless told otherwise.
+ *
+ * @param {GPUSceneContext} scene_context the scene's context — its rows are where the instance goes
+ * @param {EntityComponentDataset} dataset the dataset the scene is bound to
+ * @param {Prefab} prefab the model, compiled once
+ * @param {Transform64} placement where the model's root goes; copied
+ * @param {object} [options]
+ * @param {boolean} [options.register_animation] whether the instance's skins and clips are
+ *        registered; off leaves a skinned primitive's clone undeformed
+ * @param {boolean} [options.skinned] whether skinned primitives take a row at all; a preview that
+ *        registers no skin has nothing to pose them with and leaves them out
+ * @returns {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null, drawn: number}}
+ *          `drawn` is how many primitives took a row
+ */
+export function prefab_place(scene_context, dataset, prefab, placement, { register_animation = true, skinned = true } = {}) {
+    assert.defined(scene_context, 'scene_context');
+    assert.defined(dataset, 'dataset');
+    assert.equal(dataset.isEntityComponentDataset, true, 'dataset.isEntityComponentDataset !== true');
+    assert.defined(prefab, 'prefab');
+    assert.equal(prefab.isPrefab, true, 'prefab.isPrefab !== true');
+    assert.defined(placement, 'placement');
+    assert.isBoolean(register_animation, 'register_animation');
+    assert.isBoolean(skinned, 'skinned');
+
+    // a fresh dataset knows no component types; the prefab registers its own, and the root is
+    // placed before the prefab is spawned
+    dataset.registerManyComponentTypes([Transform64]);
+
+    const root = dataset.createEntity();
+    const transform = new Transform64();
+
+    transform.copy(placement);
+    transform.updateMatrix();
+
+    dataset.addComponentToEntity(root, transform);
+
+    const instance = prefab_instantiate(prefab, dataset, root);
+
+    const rows = scene_context.rows;
+    const entities = instance.entities;
+
+    for (let i = 0; i < entities.length; i++) {
+        rows.acquire(entities[i]);
+    }
+
+    const mesh_entities = instance.mesh_entities;
+
+    let drawn = 0;
+
+    for (let i = 0; i < mesh_entities.length; i++) {
+        const entity = mesh_entities[i];
+        const geometry = dataset.getComponent(entity, ShadedGeometry);
+        const is_skinned = geometry.getFlag(ShadedGeometryFlags.Skinned);
+
+        if (is_skinned && !skinned) {
+            continue;
+        }
+
+        rows.attach_mesh(entity, geometry.geometry, geometry.material, is_skinned);
+
+        drawn++;
+    }
+
+    const animation = register_animation
+        ? register_instance_animation(scene_context, instance)
+        : null;
+
+    return { root, instance, animation, drawn };
+}
+
+/**
+ * Take a placed model out again: its rows given back, its animation unregistered, its entities
+ * removed — the root included, since {@link prefab_place} made it.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {EntityComponentDataset} dataset
+ * @param {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null}} placed
+ *        what {@link prefab_place} answered
+ */
+export function prefab_unplace(scene_context, dataset, placed) {
+    assert.defined(scene_context, 'scene_context');
+    assert.defined(dataset, 'dataset');
+    assert.defined(placed, 'placed');
+
+    if (placed.animation !== null) {
+        unregister_instance_animation(placed.animation);
+    }
+
+    const rows = scene_context.rows;
+    const instance = placed.instance;
+    const mesh_entities = instance.mesh_entities;
+
+    for (let i = 0; i < mesh_entities.length; i++) {
+        // safe on a skinned primitive that took no row
+        rows.detach_mesh(mesh_entities[i]);
+    }
+
+    const entities = instance.entities;
+
+    for (let i = 0; i < entities.length; i++) {
+        rows.release(entities[i]);
+    }
+
+    prefab_instance_destroy(dataset, instance);
+    dataset.removeEntity(placed.root);
+}

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

@@ -0,0 +1,60 @@
+/**
+ * @typedef {import("./Prefab.js").Prefab} Prefab
+ * @typedef {import("../../../shade/renderer/animation/Skin.js").Skin} Skin
+ * @typedef {import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("../../../shade/renderer/animation/ShadeAnimationChannel.js").ShadeAnimationChannel} ShadeAnimationChannel
+ */
+/**
+ * @typedef {object} PrefabSkinScaleConflict
+ * @property {ShadeAnimationChannel} channel the scaling channel
+ * @property {number} node the node it scales
+ * @property {boolean} uniform whether the scale is the same on every axis
+ * @property {number} joints_reached how many of the skin's joints sit under the node
+ * @property {boolean} reaches_mesh whether any of the skin's meshes sit under the node
+ */
+/**
+ * The scale channels of `clip` that reach some of a skin's joints and meshes but not all of them.
+ *
+ * The frame {@link prefab_normalize_skin_frames} chooses is fixed at compile, and it is sound
+ * because the joints and the mesh share their scaling ancestors. A scale that reaches only some
+ * of them — a joint's own scale, a scale on a bone above half the skeleton — breaks that every
+ * frame it plays, on the GPU, where nothing can see it: the scale enters the joint matrices and
+ * not the frame they are folded against, and a dual quaternion cannot carry it. A scale on the
+ * character's root reaches the mesh and every joint and cancels; a scale on a node the skin has
+ * nothing to do with reaches nothing.
+ *
+ * The same question `skin_clip_scale_conflicts` asked of a node tree, asked of parent indices.
+ *
+ * @param {Prefab} prefab
+ * @param {Skin} skin joints and meshes as node indices
+ * @param {ShadeAnimationClip} clip channels targeting node indices
+ * @returns {PrefabSkinScaleConflict[]}
+ */
+export function prefab_skin_clip_scale_conflicts(prefab: Prefab, skin: Skin, clip: ShadeAnimationClip): PrefabSkinScaleConflict[];
+export type Prefab = import("./Prefab.js").Prefab;
+export type Skin = import("../../../shade/renderer/animation/Skin.js").Skin;
+export type ShadeAnimationClip = import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip;
+export type ShadeAnimationChannel = import("../../../shade/renderer/animation/ShadeAnimationChannel.js").ShadeAnimationChannel;
+export type PrefabSkinScaleConflict = {
+    /**
+     * the scaling channel
+     */
+    channel: ShadeAnimationChannel;
+    /**
+     * the node it scales
+     */
+    node: number;
+    /**
+     * whether the scale is the same on every axis
+     */
+    uniform: boolean;
+    /**
+     * how many of the skin's joints sit under the node
+     */
+    joints_reached: number;
+    /**
+     * whether any of the skin's meshes sit under the node
+     */
+    reaches_mesh: boolean;
+};
+//# sourceMappingURL=prefab_skin_clip_scale_conflicts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prefab_skin_clip_scale_conflicts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_skin_clip_scale_conflicts.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,yDALW,MAAM,QACN,IAAI,QACJ,kBAAkB,GAChB,uBAAuB,EAAE,CAqDrC;qBApFY,OAAO,aAAa,EAAE,MAAM;mBAC5B,OAAO,2CAA2C,EAAE,IAAI;iCACxD,OAAO,yDAAyD,EAAE,kBAAkB;oCACpF,OAAO,4DAA4D,EAAE,qBAAqB;;;;;aAKzF,qBAAqB;;;;UACrB,MAAM;;;;aACN,OAAO;;;;oBACP,MAAM;;;;kBACN,OAAO"}

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

@@ -0,0 +1,128 @@
+import { assert } from "../../../core/assert.js";
+import { clip_scale_channels } from "../../../shade/renderer/animation/skin_clip_scale_conflicts.js";
+
+/**
+ * @typedef {import("./Prefab.js").Prefab} Prefab
+ * @typedef {import("../../../shade/renderer/animation/Skin.js").Skin} Skin
+ * @typedef {import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("../../../shade/renderer/animation/ShadeAnimationChannel.js").ShadeAnimationChannel} ShadeAnimationChannel
+ */
+
+/**
+ * @typedef {object} PrefabSkinScaleConflict
+ * @property {ShadeAnimationChannel} channel the scaling channel
+ * @property {number} node the node it scales
+ * @property {boolean} uniform whether the scale is the same on every axis
+ * @property {number} joints_reached how many of the skin's joints sit under the node
+ * @property {boolean} reaches_mesh whether any of the skin's meshes sit under the node
+ */
+
+/**
+ * The scale channels of `clip` that reach some of a skin's joints and meshes but not all of them.
+ *
+ * The frame {@link prefab_normalize_skin_frames} chooses is fixed at compile, and it is sound
+ * because the joints and the mesh share their scaling ancestors. A scale that reaches only some
+ * of them — a joint's own scale, a scale on a bone above half the skeleton — breaks that every
+ * frame it plays, on the GPU, where nothing can see it: the scale enters the joint matrices and
+ * not the frame they are folded against, and a dual quaternion cannot carry it. A scale on the
+ * character's root reaches the mesh and every joint and cancels; a scale on a node the skin has
+ * nothing to do with reaches nothing.
+ *
+ * The same question `skin_clip_scale_conflicts` asked of a node tree, asked of parent indices.
+ *
+ * @param {Prefab} prefab
+ * @param {Skin} skin joints and meshes as node indices
+ * @param {ShadeAnimationClip} clip channels targeting node indices
+ * @returns {PrefabSkinScaleConflict[]}
+ */
+export function prefab_skin_clip_scale_conflicts(prefab, skin, clip) {
+    assert.defined(prefab, 'prefab');
+    assert.equal(prefab.isPrefab, true, 'prefab.isPrefab !== true');
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+    assert.defined(clip, 'clip');
+
+    const scaling = clip_scale_channels(clip);
+
+    const conflicts = [];
+
+    if (scaling.length === 0) {
+        return conflicts;
+    }
+
+    const joints = new Set(skin.joints);
+    const meshes = new Set(skin.meshes);
+
+    for (const channel of scaling) {
+        const target = channel.target;
+
+        let joints_reached = 0;
+        let meshes_reached = 0;
+
+        for (const node of subtree(prefab, target)) {
+            if (joints.has(node)) {
+                joints_reached++;
+            }
+
+            if (meshes.has(node)) {
+                meshes_reached++;
+            }
+        }
+
+        const reaches_everything = joints_reached === joints.size && meshes_reached === meshes.size;
+        const reaches_nothing = joints_reached === 0 && meshes_reached === 0;
+
+        if (reaches_everything || reaches_nothing) {
+            continue;
+        }
+
+        conflicts.push({
+            channel,
+            node: target,
+            uniform: is_uniform(channel),
+            joints_reached,
+            reaches_mesh: meshes_reached > 0,
+        });
+    }
+
+    return conflicts;
+}
+
+/**
+ * `node` and every node under it. Children follow their parents in index order, so a forward
+ * pass from `node` with a membership set finds them all.
+ *
+ * @param {Prefab} prefab
+ * @param {number} node
+ * @returns {number[]}
+ */
+function subtree(prefab, node) {
+    const parent = prefab.parent;
+    const inside = new Set([node]);
+    const found = [node];
+
+    for (let i = node + 1; i < prefab.node_count; i++) {
+        if (inside.has(parent[i])) {
+            inside.add(i);
+            found.push(i);
+        }
+    }
+
+    return found;
+}
+
+/**
+ * @param {ShadeAnimationChannel} channel
+ * @returns {boolean}
+ */
+function is_uniform(channel) {
+    const { x, y, z } = channel.curves;
+
+    if (x === undefined || y === undefined || z === undefined) {
+        // an axis left unanimated keeps whatever the node's own scale holds while the others move,
+        // which is a non-uniform scale however uniform the curves that are there
+        return false;
+    }
+
+    return (x === y || x.equals(y)) && (x === z || x.equals(z));
+}

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

@@ -0,0 +1,40 @@
+/**
+ * A joint's skinning matrix at the prefab's rest pose: the joint's world under the root, times
+ * its inverse-bind matrix. What the skin matrix prep pass computes on the GPU from the row's
+ * `global`, computed here from the prefab's own composition.
+ *
+ * @param {Float64Array} out
+ * @param {Prefab} prefab
+ * @param {Skin} skin joints as node indices
+ * @param {number} joint_index
+ * @returns {Float64Array} `out`
+ */
+export function prefab_skin_joint_matrix(out: Float64Array, prefab: Prefab, skin: Skin, joint_index: number): Float64Array;
+/**
+ * The frame a skin's meshes are deformed in: its first joint's skinning matrix at rest. For a
+ * skin whose rest pose is rigid every joint gives the same answer, and the first is as good as any.
+ *
+ * @param {Float64Array} out
+ * @param {Prefab} prefab
+ * @param {Skin} skin
+ * @returns {Float64Array} `out`
+ */
+export function prefab_skin_bind_transform(out: Float64Array, prefab: Prefab, skin: Skin): Float64Array;
+/**
+ * How far a skin is from being deformable in `frame`: the worst rigidity defect of
+ * `inverse(frame) × joint.world × inverse_bind` over its joints, at rest. Zero for a skin that
+ * folds rigidly, `Infinity` for a frame with no inverse or a joint that reflects.
+ *
+ * A reflection scores perfectly on orthonormality, which is why it is caught by its determinant
+ * rather than by the defect: a dual quaternion would answer it with a rotation, silently, which is
+ * precisely the class of failure this exists to end.
+ *
+ * @param {Prefab} prefab
+ * @param {Skin} skin
+ * @param {ArrayLike<number>} frame
+ * @returns {number}
+ */
+export function prefab_skin_frame_defect(prefab: Prefab, skin: Skin, frame: ArrayLike<number>): number;
+export type Prefab = import("./Prefab.js").Prefab;
+export type Skin = import("../../../shade/renderer/animation/Skin.js").Skin;
+//# sourceMappingURL=prefab_skin_frame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prefab_skin_frame.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_skin_frame.js"],"names":[],"mappings":"AAcA;;;;;;;;;;GAUG;AACH,8CANW,YAAY,UACZ,MAAM,QACN,IAAI,eACJ,MAAM,GACJ,YAAY,CAqBxB;AAED;;;;;;;;GAQG;AACH,gDALW,YAAY,UACZ,MAAM,QACN,IAAI,GACF,YAAY,CAMxB;AAED;;;;;;;;;;;;;GAaG;AACH,iDALW,MAAM,QACN,IAAI,SACJ,UAAU,MAAM,CAAC,GACf,MAAM,CA8BlB;qBAjGY,OAAO,aAAa,EAAE,MAAM;mBAC5B,OAAO,2CAA2C,EAAE,IAAI"}