@woosh/meep-engine 3.43.0 → 3.44.0

package/src/shade/renderer/animation/GPUAnimationManager.d.ts

@@ -16,9 +16,9 @@
  *
  * Usage:
  *  1. (Once at setup) Either low-level (`add_curve`, `add_track`,
- *     `add_skin`, `add_clip`) or high-level (`register_skin`,
- *     `register_clip` against the CPU data classes {@link Skin} /
- *     {@link ShadeAnimationClip}).
+ *     `add_skin`, `add_clip`) or high-level (`register_skin` over joint
+ *     entities and their inverse binds, with `bind_skin_mesh` per mesh;
+ *     `register_clip` against {@link ShadeAnimationClip}).
  *  2. (Once) {@link start} per clip to begin GPU-driven playback —
  *     the {@link shader_animation_tick} pass advances `time` each
  *     frame thereafter. CPU-driven prototypes can instead call
@@ -330,24 +330,51 @@ export class GPUAnimationManager {
         }>;
     }): number;
     /**
-     * High-level skin registration: consumes a {@link Skin} whose joints and meshes are
-     * **entities**, allocates a GPU skin record, and binds every mesh entity through the
-     * skinning context.
+     * High-level skin registration: joints as **entities**, and the inverse bind of each. One call
+     * is one hold on the skin, given back by {@link unregister_skin}; meshes deform against it
+     * through {@link bind_skin_mesh}.
+     *
+     * **A skin is registered once, however many meshes describe it.** A body and its hair are bound
+     * to one skeleton the same way and each carry the description; a second registration with the
+     * same joint entities, in the same order, under the same inverse binds is answered with the
+     * first one's id, whether or not it passes the same arrays — so the skeleton's matrices are made
+     * once a frame. The arrays are read-only from here on: they are what later registrations are
+     * compared against.
      *
      * **Eventual consistency.** The `skin_id` is allocated and returned synchronously, and the
      * skin's joints take their rows at once, so {@link get_skin_matrix_offset} and
      * {@link unregister_skin} work from here on. If any joint's entity has not taken its
-     * transforms row yet (see `GPUSceneRows.acquire`), the joints name no node, and the meshes
-     * are not bound, until the next {@link update} that sees every joint there. Until then the
-     * skin's matrices are not written, and its meshes draw undeformed, as they were modelled.
+     * transforms row yet (see `GPUSceneRows.acquire`), the joints name no node, and no mesh is
+     * bound, until the next {@link update} that sees every joint there. Until then the skin's
+     * matrices are not written, and its meshes draw undeformed, as they were modelled.
      *
      * The frame a skin's meshes are deformed in is the prefab's business, fixed once at compile
      * (`prefab_normalize_skin_frames`); nothing about it is decided here.
      *
-     * @param {Skin} skin joints and meshes as entities
+     * @param {ArrayLike<number>} joints entities, in the order the meshes' joint indices address them
+     * @param {Float32Array} inverse_bind_matrices `joints.length` × 16, column-major
      * @returns {number} skin id (index into the `animation_skins` table)
      */
-    register_skin(skin: Skin): number;
+    register_skin(joints: ArrayLike<number>, inverse_bind_matrices: Float32Array): number;
+    /**
+     * Deform a mesh entity against a skin {@link register_skin} issued. The mesh is bound in the
+     * skinning context as soon as the skin's joints are named — now, or at the {@link update} that
+     * names them — so it is never deformed by matrices nobody has written. The clone a binding
+     * deforms is made when the entity's mesh row is written, before or after, and the binding
+     * follows.
+     *
+     * One skin per mesh: {@link unbind_skin_mesh} first to move it.
+     *
+     * @param {number} entity
+     * @param {number} skin_id
+     */
+    bind_skin_mesh(entity: number, skin_id: number): void;
+    /**
+     * Stop deforming a mesh. Safe on a mesh bound to nothing.
+     *
+     * @param {number} entity
+     */
+    unbind_skin_mesh(entity: number): void;
     /**
      * High-level clip registration: consumes a {@link ShadeAnimationClip} whose channels target
      * **entities**, uploads curves and tracks, and creates the GPU clip record.
@@ -400,8 +427,13 @@ export class GPUAnimationManager {
      * hole fits too — so a spawn/despawn loop over a fixed cast costs what the cast costs, not
      * what the loop has run.
      *
-     * Tolerates the skin still being pending. Safe to call repeatedly on the same id: the
-     * second call finds the row unoccupied and removes nothing.
+     * **A skin from {@link register_skin} is held once per registration**, and this gives one hold
+     * back: the skin goes with the last. So it is one call per registration — a stray second call
+     * gives back a hold some other mesh is counting on.
+     *
+     * Tolerates the skin still being pending. A skin from {@link add_skin} goes on the first call,
+     * and calling again on its id is safe: the second call finds the row unoccupied and removes
+     * nothing.
      *
      * @param {number} skin_id
      */
@@ -491,6 +523,5 @@ export type GPURecordWriter = import("../buffer/table/serde/generate_record_writ
 export type ShadeGPUCommandContext = import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
 export type GPUSceneContext = import("../scene/GPUSceneContext.js").GPUSceneContext;
 export type ShadeAnimationClip = import("./ShadeAnimationClip.js").ShadeAnimationClip;
-export type Skin = import("./Skin.js").Skin;
 import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
 //# sourceMappingURL=GPUAnimationManager.d.ts.map

package/src/shade/renderer/animation/GPUAnimationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}

package/src/shade/renderer/animation/GPUAnimationManager.js

@@ -1,4 +1,7 @@
 import { assert } from "../../../core/assert.js";
+import { computeIntegerArrayHash } from "../../../core/collection/array/computeIntegerArrayHash.js";
+import { computeHashFloatArray } from "../../../core/math/hash/computeHashFloatArray.js";
+import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
 import { FrameGraph } from "../../../engine/graphics/render/frame_graph/FrameGraph.js";
 import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
 import { GPU_DATABASE_NULL } from "../buffer/table/GPU_DATABASE_NULL.js";
@@ -50,7 +53,6 @@ import {
  * @typedef {import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
  * @typedef {import("../scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
  * @typedef {import("./ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
- * @typedef {import("./Skin.js").Skin} Skin
  */
 
 /**
@@ -207,6 +209,117 @@ const POSE_ACCUMULATOR_INITIAL_CAPACITY = 256;
  */
 const MAX_DT_SECONDS = 1 / 15;
 
+/**
+ * A skin registered through {@link GPUAnimationManager#register_skin}: what it was registered with,
+ * how many registrations hold it, and the meshes bound to it.
+ */
+class RegisteredSkin {
+    /**
+     * @type {number}
+     */
+    skin_id = -1;
+
+    /**
+     * {@link skin_content_hash} of {@link joints} and {@link inverse_bind_matrices}.
+     *
+     * @type {number}
+     */
+    hash = 0;
+
+    /**
+     * The joint entities, as the first registration gave them. Read-only from then on.
+     *
+     * @type {ArrayLike<number>}
+     */
+    joints = [];
+
+    /**
+     * Read-only from registration on, like {@link joints}.
+     *
+     * @type {Float32Array}
+     */
+    inverse_bind_matrices = new Float32Array(0);
+
+    /**
+     * The first row of the skin's run of joints.
+     *
+     * @type {number}
+     */
+    joints_first = 0;
+
+    /**
+     * How many registrations are holding the skin; the last {@link GPUAnimationManager#unregister_skin}
+     * frees it.
+     *
+     * @type {number}
+     */
+    holds = 0;
+
+    /**
+     * Whether every joint's node is named. Until then the skin's matrices are not written, and no
+     * mesh is bound to it.
+     *
+     * @type {boolean}
+     */
+    named = false;
+
+    /**
+     * The mesh entities bound to the skin, bound in the skinning context once it is {@link named}.
+     *
+     * @type {number[]}
+     */
+    meshes = [];
+}
+
+/**
+ * What two registrations of one skin share: the joint entities in order and the inverse binds.
+ *
+ * @param {ArrayLike<number>} joints
+ * @param {Float32Array} inverse_bind_matrices
+ * @returns {number}
+ */
+function skin_content_hash(joints, inverse_bind_matrices) {
+    return hash_mix2(
+        computeIntegerArrayHash(joints, 0, joints.length),
+        computeHashFloatArray(inverse_bind_matrices)
+    );
+}
+
+/**
+ * @param {RegisteredSkin} skin
+ * @param {ArrayLike<number>} joints
+ * @param {Float32Array} inverse_bind_matrices
+ * @returns {boolean} whether `skin` was registered with these joints and inverse binds
+ */
+function skin_content_equals(skin, joints, inverse_bind_matrices) {
+    const own = skin.joints;
+    const count = own.length;
+
+    if (joints.length !== count) {
+        return false;
+    }
+
+    for (let i = 0; i < count; i++) {
+        if (own[i] !== joints[i]) {
+            return false;
+        }
+    }
+
+    const matrices = skin.inverse_bind_matrices;
+
+    if (matrices === inverse_bind_matrices) {
+        return true;
+    }
+
+    for (let i = 0; i < matrices.length; i++) {
+        if (matrices[i] !== inverse_bind_matrices[i]) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
 /**
  * Top-level coordinator for GPU-resident animation.
  *
@@ -225,9 +338,9 @@ const MAX_DT_SECONDS = 1 / 15;
  *
  * Usage:
  *  1. (Once at setup) Either low-level (`add_curve`, `add_track`,
- *     `add_skin`, `add_clip`) or high-level (`register_skin`,
- *     `register_clip` against the CPU data classes {@link Skin} /
- *     {@link ShadeAnimationClip}).
+ *     `add_skin`, `add_clip`) or high-level (`register_skin` over joint
+ *     entities and their inverse binds, with `bind_skin_mesh` per mesh;
+ *     `register_clip` against {@link ShadeAnimationClip}).
  *  2. (Once) {@link start} per clip to begin GPU-driven playback —
  *     the {@link shader_animation_tick} pass advances `time` each
  *     frame thereafter. CPU-driven prototypes can instead call
@@ -454,19 +567,32 @@ export class GPUAnimationManager {
      * to it only when {@link update} names the nodes: until then its matrices are not written,
      * and a mesh deformed by them would read zeros or another skin's last pose.
      *
-     * Each entry: `skin_id`; the CPU {@link Skin}, whose `joints` are the entities whose rows
-     * become the nodes and whose `meshes` are bound then; `joints_first`, the first row of the
-     * skin's joints; and `joint_count`, how many rows the run has.
-     *
-     * @type {Array<{
-     *     skin_id: number,
-     *     skin: Skin,
-     *     joints_first: number,
-     *     joint_count: number,
-     * }>}
+     * @type {RegisteredSkin[]}
      */
     #pending_skins = [];
 
+    /**
+     * Every skin registered via {@link register_skin}, by id.
+     *
+     * @type {Map<number, RegisteredSkin>}
+     */
+    #registered_skins = new Map();
+
+    /**
+     * The same skins by content: {@link skin_content_hash} to every registered skin with that hash.
+     * A bucket is a list because a hash is not an identity.
+     *
+     * @type {Map<number, RegisteredSkin[]>}
+     */
+    #skins_by_content = new Map();
+
+    /**
+     * The skin each mesh entity is bound to through {@link bind_skin_mesh}.
+     *
+     * @type {Map<number, number>}
+     */
+    #skin_of_mesh = new Map();
+
     /**
      * Clips registered via {@link register_clip} whose bindings
      * haven't been added yet because one or more channel
@@ -1029,78 +1155,164 @@ export class GPUAnimationManager {
     }
 
     /**
-     * High-level skin registration: consumes a {@link Skin} whose joints and meshes are
-     * **entities**, allocates a GPU skin record, and binds every mesh entity through the
-     * skinning context.
+     * High-level skin registration: joints as **entities**, and the inverse bind of each. One call
+     * is one hold on the skin, given back by {@link unregister_skin}; meshes deform against it
+     * through {@link bind_skin_mesh}.
+     *
+     * **A skin is registered once, however many meshes describe it.** A body and its hair are bound
+     * to one skeleton the same way and each carry the description; a second registration with the
+     * same joint entities, in the same order, under the same inverse binds is answered with the
+     * first one's id, whether or not it passes the same arrays — so the skeleton's matrices are made
+     * once a frame. The arrays are read-only from here on: they are what later registrations are
+     * compared against.
      *
      * **Eventual consistency.** The `skin_id` is allocated and returned synchronously, and the
      * skin's joints take their rows at once, so {@link get_skin_matrix_offset} and
      * {@link unregister_skin} work from here on. If any joint's entity has not taken its
-     * transforms row yet (see `GPUSceneRows.acquire`), the joints name no node, and the meshes
-     * are not bound, until the next {@link update} that sees every joint there. Until then the
-     * skin's matrices are not written, and its meshes draw undeformed, as they were modelled.
+     * transforms row yet (see `GPUSceneRows.acquire`), the joints name no node, and no mesh is
+     * bound, until the next {@link update} that sees every joint there. Until then the skin's
+     * matrices are not written, and its meshes draw undeformed, as they were modelled.
      *
      * The frame a skin's meshes are deformed in is the prefab's business, fixed once at compile
      * (`prefab_normalize_skin_frames`); nothing about it is decided here.
      *
-     * @param {Skin} skin joints and meshes as entities
+     * @param {ArrayLike<number>} joints entities, in the order the meshes' joint indices address them
+     * @param {Float32Array} inverse_bind_matrices `joints.length` × 16, column-major
      * @returns {number} skin id (index into the `animation_skins` table)
      */
-    register_skin(skin) {
-        assert.defined(skin, 'skin');
-        assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
-        assert.greaterThanOrEqual(skin.joints.length, 1, 'skin must have at least one joint');
-        assert.greaterThanOrEqual(skin.meshes.length, 1, 'skin.meshes must contain at least one mesh');
+    register_skin(joints, inverse_bind_matrices) {
+        assert.defined(joints, 'joints');
+        assert.greaterThanOrEqual(joints.length, 1, 'skin must have at least one joint');
+        assert.defined(inverse_bind_matrices, 'inverse_bind_matrices');
+        assert.equal(
+            inverse_bind_matrices.length, joints.length * 16,
+            'inverse_bind_matrices.length !== joints.length * 16'
+        );
+
+        const hash = skin_content_hash(joints, inverse_bind_matrices);
+
+        let bucket = this.#skins_by_content.get(hash);
 
-        for (let i = 0; i < skin.meshes.length; i++) {
-            assert.isNonNegativeInteger(skin.meshes[i], `skin.meshes[${i}]`);
+        if (bucket === undefined) {
+            bucket = [];
+
+            this.#skins_by_content.set(hash, bucket);
+        } else {
+            for (let i = 0; i < bucket.length; i++) {
+                const registered = bucket[i];
+
+                if (skin_content_equals(registered, joints, inverse_bind_matrices)) {
+                    registered.holds++;
+
+                    return registered.skin_id;
+                }
+            }
         }
 
-        const complete = this.#joint_rows_ready(skin);
+        const skin = new RegisteredSkin();
+
+        skin.hash = hash;
+        skin.joints = joints;
+        skin.inverse_bind_matrices = inverse_bind_matrices;
+        skin.holds = 1;
+        skin.named = this.#joint_rows_ready(joints);
 
         // The joints take their rows now, named nodes and all if every joint is there already.
-        const joints_first = this.#add_joints(this.#skin_joints(skin, complete));
-        const joint_count = skin.joints.length;
+        skin.joints_first = this.#add_joints(this.#skin_joints(skin, skin.named));
+
+        skin.skin_id = this.#database.get('animation_skins').add({
+            joints_first: skin.joints_first,
+            joint_count: joints.length,
+        });
 
-        const skin_id = this.#database.get('animation_skins').add({ joints_first, joint_count });
+        bucket.push(skin);
 
-        if (complete) {
-            this.#bind_meshes(skin, skin_id);
-        } else {
+        this.#registered_skins.set(skin.skin_id, skin);
+
+        if (!skin.named) {
             // the next update() that sees every joint's row names the nodes and binds the meshes
-            this.#pending_skins.push({ skin_id, skin, joints_first, joint_count });
+            this.#pending_skins.push(skin);
         }
 
-        return skin_id;
+        return skin.skin_id;
     }
 
     /**
-     * Bind every mesh entity of `skin` into the skinning context. The clone a binding deforms is
-     * made when the entity's mesh row is written — before or after this — and the binding
+     * Deform a mesh entity against a skin {@link register_skin} issued. The mesh is bound in the
+     * skinning context as soon as the skin's joints are named — now, or at the {@link update} that
+     * names them — so it is never deformed by matrices nobody has written. The clone a binding
+     * deforms is made when the entity's mesh row is written, before or after, and the binding
      * follows.
      *
-     * @param {Skin} skin
+     * One skin per mesh: {@link unbind_skin_mesh} first to move it.
+     *
+     * @param {number} entity
      * @param {number} skin_id
      */
-    #bind_meshes(skin, skin_id) {
+    bind_skin_mesh(entity, skin_id) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.isNonNegativeInteger(skin_id, 'skin_id');
+
+        const skin = this.#registered_skins.get(skin_id);
+
+        assert.defined(skin, 'skin_id was not issued by register_skin, or has been freed');
+        assert.equal(this.#skin_of_mesh.has(entity), false, 'the mesh is bound to a skin already; unbind it first');
+
+        this.#skin_of_mesh.set(entity, skin_id);
+
+        skin.meshes.push(entity);
+
+        if (skin.named) {
+            this.#scene_context.skinning.bind(entity, skin_id);
+        }
+    }
+
+    /**
+     * Stop deforming a mesh. Safe on a mesh bound to nothing.
+     *
+     * @param {number} entity
+     */
+    unbind_skin_mesh(entity) {
+        const skin_id = this.#skin_of_mesh.get(entity);
+
+        if (skin_id === undefined) {
+            return;
+        }
+
+        this.#skin_of_mesh.delete(entity);
+
+        const meshes = this.#registered_skins.get(skin_id).meshes;
+        const index = meshes.indexOf(entity);
+
+        meshes[index] = meshes[meshes.length - 1];
+        meshes.pop();
+
+        this.#scene_context.skinning.unbind(entity);
+    }
+
+    /**
+     * Bind every mesh of `skin` into the skinning context, now that its joints are named.
+     *
+     * @param {RegisteredSkin} skin
+     */
+    #bind_meshes(skin) {
         const skinning = this.#scene_context.skinning;
         const meshes = skin.meshes;
 
         for (let i = 0; i < meshes.length; i++) {
-            skinning.bind(meshes[i], skin_id);
+            skinning.bind(meshes[i], skin.skin_id);
         }
     }
 
     /**
-     * Whether every joint entity of `skin` holds its transforms row. All or nothing: a skin
-     * whose joints were only partly named would deform with some of its matrices missing.
+     * Whether every joint entity holds its transforms row. All or nothing: a skin whose joints
+     * were only partly named would deform with some of its matrices missing.
      *
-     * @param {Skin} skin
+     * @param {ArrayLike<number>} joints
      * @returns {boolean}
      */
-    #joint_rows_ready(skin) {
+    #joint_rows_ready(joints) {
         const rows = this.#scene_context.rows;
-        const joints = skin.joints;
 
         for (let i = 0; i < joints.length; i++) {
             assert.isNonNegativeInteger(joints[i], `skin.joints[${i}]`);
@@ -1117,7 +1329,7 @@ export class GPUAnimationManager {
      * The joint records of `skin`: each joint's inverse bind, and its node — the joint entity's
      * transforms row when `with_nodes`, {@link GPU_DATABASE_NULL} otherwise.
      *
-     * @param {Skin} skin
+     * @param {RegisteredSkin} skin
      * @param {boolean} with_nodes
      * @returns {Array<{node: number, inverse_bind: Float32Array}>}
      */
@@ -1146,32 +1358,29 @@ export class GPUAnimationManager {
      * Only each joint's `node` is written, and only that word is uploaded: the inverse bind went
      * in at registration.
      *
-     * @param {{skin_id: number, skin: Skin, joints_first: number, joint_count: number}} pending
+     * @param {RegisteredSkin} skin
      * @returns {boolean}
      */
-    #try_complete_skin(pending) {
-        const skin = pending.skin;
-
-        if (!this.#joint_rows_ready(skin)) {
+    #try_complete_skin(skin) {
+        if (!this.#joint_rows_ready(skin.joints)) {
             return false;
         }
 
         const joints_table = this.#database.get('animation_skin_joints');
         const entities = skin.joints;
 
-        // the run was cut to the skin as it registered; a joint added since has no row in it
-        assert.equal(entities.length, pending.joint_count, 'skin.joints changed after register_skin');
-
         for (let i = 0; i < entities.length; i++) {
-            joints_table.set_fields(pending.joints_first + i, { node: row_of_entity(entities[i]) }, SKIN_JOINT_NODE_WRITER);
+            joints_table.set_fields(skin.joints_first + i, { node: row_of_entity(entities[i]) }, SKIN_JOINT_NODE_WRITER);
         }
 
-        this.#bind_meshes(skin, pending.skin_id);
+        skin.named = true;
+
+        this.#bind_meshes(skin);
 
         // The joints' matrices are written from the next prep on, and "previous" over their rows
         // holds whatever was there before — zeros, or the last pose of a skin that had them — so
         // it is seeded, as it is for a run just handed out.
-        this.#skin_matrix_seed_runs.push([pending.joints_first, pending.joint_count]);
+        this.#skin_matrix_seed_runs.push([skin.joints_first, entities.length]);
 
         return true;
     }
@@ -1670,18 +1879,27 @@ export class GPUAnimationManager {
      * hole fits too — so a spawn/despawn loop over a fixed cast costs what the cast costs, not
      * what the loop has run.
      *
-     * Tolerates the skin still being pending. Safe to call repeatedly on the same id: the
-     * second call finds the row unoccupied and removes nothing.
+     * **A skin from {@link register_skin} is held once per registration**, and this gives one hold
+     * back: the skin goes with the last. So it is one call per registration — a stray second call
+     * gives back a hold some other mesh is counting on.
+     *
+     * Tolerates the skin still being pending. A skin from {@link add_skin} goes on the first call,
+     * and calling again on its id is safe: the second call finds the row unoccupied and removes
+     * nothing.
      *
      * @param {number} skin_id
      */
     unregister_skin(skin_id) {
         assert.isNonNegativeInteger(skin_id, 'skin_id');
 
-        for (let i = this.#pending_skins.length - 1; i >= 0; i--) {
-            if (this.#pending_skins[i].skin_id === skin_id) {
-                this.#pending_skins.splice(i, 1);
+        const registered = this.#registered_skins.get(skin_id);
+
+        if (registered !== undefined) {
+            if (--registered.holds > 0) {
+                return;
             }
+
+            this.#forget_registered_skin(registered);
         }
 
         // Tear down skinning bindings first so the skinning
@@ -1706,6 +1924,40 @@ export class GPUAnimationManager {
         skins_table.remove(skin_id);
     }
 
+    /**
+     * The last hold on a registered skin is gone: it leaves the content index, the pending list and
+     * its meshes' records. Its row and bindings go with {@link unregister_skin}.
+     *
+     * @param {RegisteredSkin} skin
+     */
+    #forget_registered_skin(skin) {
+        this.#registered_skins.delete(skin.skin_id);
+
+        const bucket = this.#skins_by_content.get(skin.hash);
+        const index = bucket.indexOf(skin);
+
+        bucket[index] = bucket[bucket.length - 1];
+        bucket.pop();
+
+        if (bucket.length === 0) {
+            this.#skins_by_content.delete(skin.hash);
+        }
+
+        const pending = this.#pending_skins.indexOf(skin);
+
+        if (pending !== -1) {
+            this.#pending_skins.splice(pending, 1);
+        }
+
+        const meshes = skin.meshes;
+
+        for (let i = 0; i < meshes.length; i++) {
+            this.#skin_of_mesh.delete(meshes[i]);
+        }
+
+        meshes.length = 0;
+    }
+
     /**
      * Drop every queued seed run starting at `first_row`: the run of a skin being given back,
      * queued when it was handed out, and again if its joints have been named since.

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.d.ts

@@ -142,6 +142,11 @@ export class GPUMeshSkinningContext {
      * registrations (which would otherwise try to look up the freed
      * skin's matrix offset on the next bindings upload and assert).
      *
+     * **A mesh bound before its clone exists is forgotten too.** It has no binding record yet, only
+     * its skin, and keeping that skin past this call would leave the entity naming a freed id: the
+     * next skin to take the id would deform it, and binding it to a skin of its own would be refused
+     * as a rebind.
+     *
      * @param {number} skin_id
      */
     unbind_all_by_skin(skin_id: number): void;

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshSkinningContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js"],"names":[],"mappings":"AAmFA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAgNI;;;;;;;OAOG;IACH,sEAPW;QACV,UAAgB,EAAE,kBAAkB,CAAC;QACrC,iBAAuB,EAAE,mBAAmB,CAAC;QAC7C,aAAmB,EAAE,eAAe,CAAC;QACrC,MAAY,YAAY;KACrB,EAcH;IAED;;;;;;OAMG;IACH,iCAEC;IAED;;;;;;;OAOG;IACH,yCAEC;IAED;;;;;;OAMG;IACH,2BAEC;IAED;;;;;OAKG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,wCAEC;IAED;;;;;;;;;;;;OAYG;IACH,qBAJW,MAAM,YACN,eAAe,GACb,mBAAmB,CAqB/B;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,mBAAmB,GAAC,SAAS,CAMzC;IAED;;;;;;;;;;OAUG;IACH,aAHW,MAAM,WACN,MAAM,QAwBhB;IAED;;;;;;;OAOG;IACH,oBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;OAUG;IACH,eAFW,MAAM,QAYhB;IAED;;;;;;;;OAQG;IACH,4BAFW,MAAM,QAUhB;IA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFW,MAAM,QAqBhB;IAuBD;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAJW,sBAAsB,GACpB,OAAO,CA+NnB;IAmXD;;;;;;;OAOG;IACH,gBA+BC;;CACJ;qCA/xCY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;kCACnE,OAAO,2BAA2B,EAAE,mBAAmB"}
+{"version":3,"file":"GPUMeshSkinningContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js"],"names":[],"mappings":"AAmFA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAgNI;;;;;;;OAOG;IACH,sEAPW;QACV,UAAgB,EAAE,kBAAkB,CAAC;QACrC,iBAAuB,EAAE,mBAAmB,CAAC;QAC7C,aAAmB,EAAE,eAAe,CAAC;QACrC,MAAY,YAAY;KACrB,EAcH;IAED;;;;;;OAMG;IACH,iCAEC;IAED;;;;;;;OAOG;IACH,yCAEC;IAED;;;;;;OAMG;IACH,2BAEC;IAED;;;;;OAKG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,wCAEC;IAED;;;;;;;;;;;;OAYG;IACH,qBAJW,MAAM,YACN,eAAe,GACb,mBAAmB,CAqB/B;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,mBAAmB,GAAC,SAAS,CAMzC;IAED;;;;;;;;;;OAUG;IACH,aAHW,MAAM,WACN,MAAM,QAwBhB;IAED;;;;;;;OAOG;IACH,oBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;OAUG;IACH,eAFW,MAAM,QAYhB;IAED;;;;;;;;;;;;;OAaG;IACH,4BAFW,MAAM,QAehB;IA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFW,MAAM,QAqBhB;IAuBD;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAJW,sBAAsB,GACpB,OAAO,CA+NnB;IAmXD;;;;;;;OAOG;IACH,gBA+BC;;CACJ;qCAzyCY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;kCACnE,OAAO,2BAA2B,EAAE,mBAAmB"}