@woosh/meep-engine 3.42.0 → 3.44.0

package/editor/prototypeEditorShell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prototypeEditorShell.d.ts","sourceRoot":"","sources":["../../editor/prototypeEditorShell.js"],"names":[],"mappings":"AAuLA;;;;;GAKG;AACH,2BAFU,QAAQ;IAAC,MAAM,SAAS;IAAC,MAAM,SAAS;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,UAAS;CAAC,CAAC,CAEzD"}
+{"version":3,"file":"prototypeEditorShell.d.ts","sourceRoot":"","sources":["../../editor/prototypeEditorShell.js"],"names":[],"mappings":"AAyLA;;;;;GAKG;AACH,2BAFU,QAAQ;IAAC,MAAM,SAAS;IAAC,MAAM,SAAS;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,UAAS;CAAC,CAAC,CAEzD"}

package/editor/prototypeEditorShell.js

@@ -32,6 +32,7 @@ import {
 import {
     ShadedGeometrySystem
 } from "../src/engine/graphics3/ShadedGeometrySystem.js";
+import { MeshSkinSystem } from "../src/engine/graphics3/MeshSkinSystem.js";
 import { GPUParticleEmitterSystem } from "../src/engine/graphics3/GPUParticleEmitterSystem.js";
 import { enableEditor } from "./enableEditor.js";
 
@@ -96,9 +97,10 @@ async function addGraphicsSystems(engine) {
 
     await em.addSystem(meshes);
 
-    // a model with neither skin nor clip becomes entities, and its primitives are drawn by the
-    // system that owns primitives (D47)
+    // a model becomes entities: its primitives are drawn by the system that owns primitives
+    // (D47), and the skinned ones deformed by the system that owns skins
     await em.addSystem(new ShadedGeometrySystem(engine.graphics, EngineHarness.shadeScene(engine)));
+    await em.addSystem(new MeshSkinSystem(engine.graphics, EngineHarness.shadeScene(engine)));
 
     /*
      One outline pass and both of its sources, because the editor offers a `Highlight` editor and

package/package.json

@@ -1,96 +1,91 @@
-{
-  "name": "@woosh/meep-engine",
-  "license": "SEE LICENSE IN LICENSE",
-  "productName": "Meep",
-  "homepage": "https://meep.company-named.com/",
-  "description": "Advanced 3D game engine",
-  "type": "module",
-  "author": "Alexander Goldring",
-  "version": "3.42.0",
-  "exports": {
-    "./build/*": "./build/*",
-    "./src/*": "./src/*",
-    "./editor/*": "./editor/*",
-    "./samples/*": "./samples/*",
-    "./*.md": "./*.md",
-    "./package.json": "./package.json"
-  },
-  "sideEffects": [
-    "**/*.css",
-    "**/*.scss"
-  ],
-  "scripts": {
-    "test:ci": "node scripts/check-types.mjs && vitest run --coverage --reporter=default --reporter=junit --outputFile=junit.xml",
-    "build-module": "rollup -c rollup.config.js",
-    "publish-npm": "npm publish",
-    "generate-types": "tsc --project tsconfig.types.json",
-    "check-types": "node scripts/check-types.mjs",
-    "test": "vitest run",
-    "test:extended": "vitest run --mode extended",
-    "test:all": "vitest run --mode all",
-    "dev": "vite"
-  },
-  "browserslist": [
-    "last 2 chrome version",
-    "last 2 firefox version",
-    "last 2 safari version"
-  ],
-  "files": [
-    "build",
-    "src",
-    "editor",
-    "samples",
-    "package.json",
-    "README.md",
-    "!src/**/*.spec.js",
-    "!samples/**/*.spec.js",
-    "!editor/**/*.spec.js",
-    "!src/**/__fixtures__/**",
-    "!src/shade/renderer/texture/noise/stbn/images/**"
-  ],
-  "dependencies": {
-    "opentype.js": "1.3.4",
-    "robust-predicates": "3.0.3"
-  },
-  "peerDependencies": {
-    "dat.gui": ">=0.7.0"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "29.0.3",
-    "@rollup/plugin-node-resolve": "16.0.3",
-    "@rollup/plugin-strip": "3.0.4",
-    "@rollup/plugin-terser": "1.0.0",
-    "@vitest/coverage-v8": "^5.0.0",
-    "@webgpu/types": "0.1.72",
-    "jsdom": "^30.0.1",
-    "rollup": "4.63.1",
-    "typescript": "5.4.5",
-    "vite": "^8.2.2",
-    "vitest": "^5.0.0",
-    "web-tree-sitter": "^0.27.0"
-  },
-  "keywords": [
-    "game-engine",
-    "gamedev",
-    "ecs",
-    "entity-component-system",
-    "data-oriented",
-    "zero-allocation",
-    "modular",
-    "tree-shaking",
-    "3d",
-    "webgpu",
-    "webaudio",
-    "particles",
-    "bvh",
-    "behavior-tree",
-    "inverse-kinematics",
-    "fabrik",
-    "clustered-lighting",
-    "color-management",
-    "typescript"
-  ],
-  "engines": {
-    "node": ">=24"
-  }
-}
+{
+  "name": "@woosh/meep-engine",
+  "license": "SEE LICENSE IN LICENSE",
+  "productName": "Meep",
+  "homepage": "https://meep.company-named.com/",
+  "description": "Advanced 3D game engine",
+  "type": "module",
+  "author": "Alexander Goldring",
+  "version": "3.44.0",
+  "exports": {
+    "./build/*": "./build/*",
+    "./src/*": "./src/*",
+    "./editor/*": "./editor/*",
+    "./samples/*": "./samples/*",
+    "./*.md": "./*.md",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
+  "scripts": {
+    "test:ci": "node scripts/check-types.mjs && vitest run --coverage --reporter=default --reporter=junit --outputFile=junit.xml",
+    "build-module": "rollup -c rollup.config.js",
+    "publish-npm": "npm publish",
+    "generate-types": "tsc --project tsconfig.types.json",
+    "check-types": "node scripts/check-types.mjs",
+    "test": "vitest run",
+    "test:extended": "vitest run --mode extended",
+    "test:all": "vitest run --mode all",
+    "dev": "vite"
+  },
+  "browserslist": [
+    "last 2 chrome version",
+    "last 2 firefox version",
+    "last 2 safari version"
+  ],
+  "files": [
+    "build",
+    "src",
+    "editor",
+    "samples",
+    "package.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "opentype.js": "1.3.4",
+    "robust-predicates": "3.0.3"
+  },
+  "peerDependencies": {
+    "dat.gui": ">=0.7.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "29.0.3",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-strip": "3.0.4",
+    "@rollup/plugin-terser": "1.0.0",
+    "@vitest/coverage-v8": "^5.0.0",
+    "@webgpu/types": "0.1.72",
+    "jsdom": "^30.0.1",
+    "rollup": "4.63.1",
+    "typescript": "5.4.5",
+    "vite": "^8.2.2",
+    "vitest": "^5.0.0",
+    "web-tree-sitter": "^0.27.0"
+  },
+  "keywords": [
+    "game-engine",
+    "gamedev",
+    "ecs",
+    "entity-component-system",
+    "data-oriented",
+    "zero-allocation",
+    "modular",
+    "tree-shaking",
+    "3d",
+    "webgpu",
+    "webaudio",
+    "particles",
+    "bvh",
+    "behavior-tree",
+    "inverse-kinematics",
+    "fabrik",
+    "clustered-lighting",
+    "color-management",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=24"
+  }
+}

package/src/engine/Clock.d.ts

@@ -52,6 +52,21 @@ declare class Clock {
      * @returns {number} in seconds
      */
     getDelta(): number;
+    /**
+     * {@link getDelta}, measured to a given moment instead of to now - an animation frame's
+     * timestamp, so that the simulation shown by a frame is the simulation at that frame's time and
+     * not at whenever the code reading the clock happened to run.
+     *
+     * Only a moment between the clock's last reading and now can be measured to; anything else is
+     * measured to now. A frame's timestamp is when the frame began, so it can sit behind a reading
+     * taken earlier in that frame (a resume() from an input handler). And it is only on this
+     * clock's timeline where the environment keeps its promise that it is - jsdom stamps frames
+     * 1.5 s behind `performance.now()`, a `Date.now()` polyfill decades ahead - and measured to
+     * those, the clock froze or leapt.
+     * @param {number} time in seconds, on the {@link current_time_in_seconds} timeline
+     * @returns {number} in seconds
+     */
+    getDeltaAt(time: number): number;
     /**
      *
      * @returns {number} in seconds

package/src/engine/Clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../../src/engine/Clock.js"],"names":[],"mappings":";AAcA;;GAEG;AACH;IAEI;;;;OAIG;IACH,0BAAsB;IAEtB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAoB;IAGpB;;;;;;OAMG;IACH,gBAHU,IAAI,CAGM;IAMpB;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,yBAEC;IAED,cAIC;IAED,aAEC;IAED,cAeC;IAED;;;OAGG;IACH,YAFa,MAAM,CAOlB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAOlB;IAED;;;;OAIG;IACH,kBAFY,MAAM,CAIjB;IAED,cAGC;CACJ;iBA1IgB,4BAA4B"}
+{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../../src/engine/Clock.js"],"names":[],"mappings":";AAcA;;GAEG;AACH;IAEI;;;;OAIG;IACH,0BAAsB;IAEtB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAoB;IAGpB;;;;;;OAMG;IACH,gBAHU,IAAI,CAGM;IAMpB;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,yBAEC;IAED,cAIC;IAED,aAEC;IAED,cAeC;IAED;;;OAGG;IACH,YAFa,MAAM,CAIlB;IAED;;;;;;;;;;;;;OAaG;IACH,iBAHW,MAAM,GACJ,MAAM,CAalB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAOlB;IAED;;;;OAIG;IACH,kBAFY,MAAM,CAIjB;IAED,cAGC;CACJ;iBAlKgB,4BAA4B"}

package/src/engine/Clock.js

@@ -4,9 +4,9 @@ import { current_time_in_seconds } from "../core/time/current_time_in_seconds.js
 /**
  *
  * @param {Clock} clock
+ * @param {number} now in seconds, on the {@link current_time_in_seconds} timeline
  */
-function updateElapsedTime(clock) {
-    const now = current_time_in_seconds();
+function updateElapsedTime(clock, now) {
     const delta = (now - clock.__lastMeasurement) * clock.speed;
     clock.__lastMeasurement = now;
     clock.elapsedTime += delta;
@@ -98,7 +98,7 @@ class Clock {
 
         this.__isRunning = false;
         //update time
-        updateElapsedTime(this);
+        updateElapsedTime(this, current_time_in_seconds());
     }
 
     /**
@@ -106,7 +106,31 @@ class Clock {
      * @returns {number} in seconds
      */
     getDelta() {
-        const elapsedTime = this.updateElapsedTime();
+        return this.getDeltaAt(current_time_in_seconds());
+    }
+
+    /**
+     * {@link getDelta}, measured to a given moment instead of to now - an animation frame's
+     * timestamp, so that the simulation shown by a frame is the simulation at that frame's time and
+     * not at whenever the code reading the clock happened to run.
+     *
+     * Only a moment between the clock's last reading and now can be measured to; anything else is
+     * measured to now. A frame's timestamp is when the frame began, so it can sit behind a reading
+     * taken earlier in that frame (a resume() from an input handler). And it is only on this
+     * clock's timeline where the environment keeps its promise that it is - jsdom stamps frames
+     * 1.5 s behind `performance.now()`, a `Date.now()` polyfill decades ahead - and measured to
+     * those, the clock froze or leapt.
+     * @param {number} time in seconds, on the {@link current_time_in_seconds} timeline
+     * @returns {number} in seconds
+     */
+    getDeltaAt(time) {
+        if (this.__isRunning) {
+            const now = current_time_in_seconds();
+
+            updateElapsedTime(this, time >= this.__lastMeasurement && time <= now ? time : now);
+        }
+
+        const elapsedTime = this.elapsedTime;
         const delta = elapsedTime - this.timeAtDelta;
         this.timeAtDelta = elapsedTime;
         return delta;
@@ -118,7 +142,7 @@ class Clock {
      */
     updateElapsedTime() {
         if (this.__isRunning) {
-            updateElapsedTime(this);
+            updateElapsedTime(this, current_time_in_seconds());
         }
         return this.elapsedTime;
     }

package/src/engine/Engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAqCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IAiGI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OAiPjB;IAtSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;;MAKC;IA8BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBA2GC;IAqBD;;OAEG;IACH,sBAgEC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BAt5B8B,+BAA+B;wBAWtC,wBAAwB;0BArBtB,0CAA0C;wCAeN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BAtBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BAUxE,0BAA0B;+BArBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAvC4B,sCAAsC;sBA4B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BAFhC,kCAAkC;8BAClC,kCAAkC;sBAb1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAqCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IA4FI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OAiPjB;IAtSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;;MAKC;IA8BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBA0GC;IAoBD;;OAEG;IACH,sBA+DC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BA94B8B,+BAA+B;wBAWtC,wBAAwB;0BArBtB,0CAA0C;wCAeN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BAtBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BAUxE,0BAA0B;+BArBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAvC4B,sCAAsC;sBA4B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BAFhC,kCAAkC;8BAClC,kCAAkC;sBAb1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}

package/src/engine/Engine.js

@@ -86,11 +86,6 @@ class Engine {
      */
     #last_render_simulation_time = 0;
 
-    /**
-     * Handle of the pending render-loop frame, `-1` when the loop is not running
-     * @type {number}
-     */
-    #animation_frame_handle = -1;
 
     /**
      * Handle of the pending "pause the simulation, this outage is taking a while" timer, `-1` when none
@@ -699,14 +694,14 @@ class Engine {
              scene's speed modifiers (see SceneManager), so a paused game holds its particles still
              and a slowed one slows them. A wall-clock measurement would do neither.
 
-             `updateElapsedTime` advances the clock and reads it without touching the anchor
-             `getDelta` keeps, so this does not consume the delta the entity manager's tick is
-             about to be handed.
+             Read, not advanced: a frame draws right after the ticker advanced the clock to the
+             frame's timestamp (see Ticker#onFrame), so this is the simulation time of the frame.
+             Advancing it here would step the renderer by however long that tick took to run.
 
              Moved only when a frame is actually drawn, so simulation time that passes while
              rendering is off is caught up by the next frame rather than lost.
             */
-            const simulation_time = this.ticker.clock.updateElapsedTime();
+            const simulation_time = this.ticker.clock.getElapsedTime();
             const time_delta_seconds = simulation_time - this.#last_render_simulation_time;
 
             this.#last_render_simulation_time = simulation_time;
@@ -781,10 +776,9 @@ class Engine {
 
             this.#last_frame_timestamp = performance.now();
 
-            /**
-             * Starting the engine
-             */
-            this.#animation_frame_handle = requestAnimationFrame(this.#animation_frame);
+            // Drawn from the ticker's frame, after that frame's tick. A render loop of its own drew
+            // each frame before the tick, i.e. the simulation as of whenever the previous tick ran.
+            this.ticker.onFrame.add(this.#animation_frame);
 
             //start simulation
             this.ticker.start({ maxTimeout: 200 });
@@ -835,13 +829,12 @@ class Engine {
     }
 
     /**
-     * Fired every animation frame via {@link requestAnimationFrame}
+     * Fired every animation frame via {@link Ticker#onFrame}
      */
     #animation_frame = () => {
 
         const t0 = this.#last_frame_timestamp;
         const t1 = performance.now();
-        this.#animation_frame_handle = requestAnimationFrame(this.#animation_frame);
         this.render();
 
         const frame_delay = (t1 - t0) / 1000;
@@ -865,10 +858,9 @@ class Engine {
         // running, which would abort the whole teardown below
         this.ticker.stop();
 
-        // and the render loop, which re-requests itself every frame and would
-        // otherwise keep calling render() on a torn-down engine forever
-        cancelAnimationFrame(this.#animation_frame_handle);
-        this.#animation_frame_handle = -1;
+        // which also ends the render loop, as it draws from the ticker's frames. Unsubscribed too,
+        // so a restart does not draw twice per frame
+        this.ticker.onFrame.remove(this.#animation_frame);
 
         // the input devices the constructor started. The gamepad one polls on its own animation
         // frame loop, so left alone it outlives the engine the same way the render loop would;

package/src/engine/graphics/ecs/mesh-v2/MeshSkin.d.ts

@@ -0,0 +1,57 @@
+/**
+ * How the geometry on this entity deforms: the joints its vertices are weighted to, as entities,
+ * and where each joint stood when the mesh was bound to it.
+ *
+ * **It describes the mesh, so it lives on the mesh entity.** The geometry's per-vertex joint indices
+ * index {@link joints}, and an inverse bind belongs to the pair (this mesh, that joint) — one joint
+ * can bind with different matrices in different skins. The joints are entities like any other: a
+ * clip, IK, a ragdoll or a cloth moves them, and the skin follows.
+ *
+ * The geometry beside it says it draws a deformed clone (`ShadedGeometryFlags.Skinned`); without
+ * that it draws the shared source and nothing would deform. `MeshSkinSystem` deforms it; a model
+ * loaded by `MeshSystem` carries one on each skinned primitive, and code builds one the same way.
+ *
+ * **Replaced, never edited.** A skin is registered once with the joints and matrices it has then;
+ * to change either, take the component off and put another on. Meshes of one model that share a
+ * skeleton and bind it the same way — a body and its hair — share one registration on the GPU,
+ * whether or not they share the arrays.
+ *
+ * **Not saved**, for the reason {@link ShadedGeometry} is not: the joint indices address the vertex
+ * attribute of a geometry no save holds, so whatever builds the geometry builds its skin.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MeshSkin {
+    /**
+     * @param {Int32Array} joints entities
+     * @param {Float32Array} inverse_bind_matrices `joints.length` × 16
+     * @returns {MeshSkin}
+     */
+    static from(joints: Int32Array, inverse_bind_matrices: Float32Array): MeshSkin;
+    /**
+     * The joints, as entities, in the order the geometry's per-vertex joint indices address them.
+     * Read-only once the component is on an entity.
+     *
+     * @type {Int32Array}
+     */
+    joints: Int32Array;
+    /**
+     * `joints.length` × 16 column-major matrices, flat: joint `j`'s at `[j * 16, j * 16 + 16)`, taking
+     * a vertex from the mesh's frame into the joint's at bind. Read-only, and shared — a model's
+     * placements all hold the one array their prefab compiled.
+     *
+     * @type {Float32Array}
+     */
+    inverse_bind_matrices: Float32Array;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isMeshSkin: boolean;
+}
+export namespace MeshSkin {
+    let typeName: string;
+    let serializable: boolean;
+}
+//# sourceMappingURL=MeshSkin.d.ts.map

package/src/engine/graphics/ecs/mesh-v2/MeshSkin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshSkin.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/MeshSkin.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAkBI;;;;OAIG;IACH,oBAJW,UAAU,yBACV,YAAY,GACV,QAAQ,CAiBpB;IArCD;;;;;OAKG;IACH,QAFU,UAAU,CAEO;IAE3B;;;;;;OAMG;IACH,uBAFU,YAAY,CAEsB;IAyBhD;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B;;kBAUS,MAAM;sBAMN,OAAO"}

package/src/engine/graphics/ecs/mesh-v2/MeshSkin.js

@@ -0,0 +1,84 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * How the geometry on this entity deforms: the joints its vertices are weighted to, as entities,
+ * and where each joint stood when the mesh was bound to it.
+ *
+ * **It describes the mesh, so it lives on the mesh entity.** The geometry's per-vertex joint indices
+ * index {@link joints}, and an inverse bind belongs to the pair (this mesh, that joint) — one joint
+ * can bind with different matrices in different skins. The joints are entities like any other: a
+ * clip, IK, a ragdoll or a cloth moves them, and the skin follows.
+ *
+ * The geometry beside it says it draws a deformed clone (`ShadedGeometryFlags.Skinned`); without
+ * that it draws the shared source and nothing would deform. `MeshSkinSystem` deforms it; a model
+ * loaded by `MeshSystem` carries one on each skinned primitive, and code builds one the same way.
+ *
+ * **Replaced, never edited.** A skin is registered once with the joints and matrices it has then;
+ * to change either, take the component off and put another on. Meshes of one model that share a
+ * skeleton and bind it the same way — a body and its hair — share one registration on the GPU,
+ * whether or not they share the arrays.
+ *
+ * **Not saved**, for the reason {@link ShadedGeometry} is not: the joint indices address the vertex
+ * attribute of a geometry no save holds, so whatever builds the geometry builds its skin.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MeshSkin {
+    /**
+     * The joints, as entities, in the order the geometry's per-vertex joint indices address them.
+     * Read-only once the component is on an entity.
+     *
+     * @type {Int32Array}
+     */
+    joints = new Int32Array(0);
+
+    /**
+     * `joints.length` × 16 column-major matrices, flat: joint `j`'s at `[j * 16, j * 16 + 16)`, taking
+     * a vertex from the mesh's frame into the joint's at bind. Read-only, and shared — a model's
+     * placements all hold the one array their prefab compiled.
+     *
+     * @type {Float32Array}
+     */
+    inverse_bind_matrices = new Float32Array(0);
+
+    /**
+     * @param {Int32Array} joints entities
+     * @param {Float32Array} inverse_bind_matrices `joints.length` × 16
+     * @returns {MeshSkin}
+     */
+    static from(joints, inverse_bind_matrices) {
+        assert.equal(joints instanceof Int32Array, true, 'joints must be an Int32Array of entities');
+        assert.greaterThanOrEqual(joints.length, 1, 'a skin has at least one joint');
+        assert.equal(inverse_bind_matrices instanceof Float32Array, true, 'inverse_bind_matrices must be a Float32Array');
+        assert.equal(
+            inverse_bind_matrices.length, joints.length * 16,
+            'inverse_bind_matrices.length !== joints.length * 16'
+        );
+
+        const r = new MeshSkin();
+
+        r.joints = joints;
+        r.inverse_bind_matrices = inverse_bind_matrices;
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+MeshSkin.prototype.isMeshSkin = true;
+
+/**
+ * @readonly
+ * @type {string}
+ */
+MeshSkin.typeName = "MeshSkin";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+MeshSkin.serializable = false;

package/src/engine/graphics3/AnimationGraphSystem.d.ts

@@ -2,6 +2,10 @@
  * Drives every entity's {@link AnimationGraphController}: runs its clock, and tells the renderer
  * what its clips weigh and where they are playing.
  *
+ * **The clips are the entity's {@link AnimationClips}.** An entity is driven while it carries both
+ * components, whoever put them there — a model `MeshSystem` loaded, or a rig built in code. New
+ * clips are a new component, which this system sees as the entity leaving and coming back.
+ *
  * **It is the CPU that plays the animation and the GPU that draws it.** Shade can advance a clip
  * itself, and this never asks it to — `AnimationClipFlags.Playing` is left clear and every audible
  * clip's time is written down each frame from the controller's own clock. That is I-4: the pose
@@ -10,33 +14,38 @@
  *
  * **Nothing here is culled.** The legacy system skipped entities smaller than 32 px², which let
  * camera framing decide whether a footstep effect or an ability release ever happened. The clock and
- * its notifications are gameplay and run for every entity whose model has arrived; what may be
+ * its notifications are gameplay and run for every entity whose clips have arrived; what may be
  * culled is drawing, and drawing is Shade's to cull.
  */
 export class AnimationGraphSystem extends System<any> {
     /**
      * @param {GraphicsEngine} graphics
-     * @param {MeshSystem} meshes
+     * @param {Scene} scene
      */
-    constructor(graphics: GraphicsEngine, meshes: MeshSystem);
-    dependencies: (typeof SGMesh | typeof AnimationGraphController)[];
+    constructor(graphics: GraphicsEngine, scene: Scene);
+    dependencies: (typeof AnimationGraphController | typeof AnimationClips)[];
     components_used: ResourceAccessSpecification<typeof AnimationGraphController>[];
     /**
+     * Only noted here: the graph is bound to the clips by the next {@link update}. A link can happen
+     * anywhere the components are added — inside a model's spawn, for one `MeshSystem` loads — and a
+     * graph naming a clip the entity has not got throws, which belongs in this system's tick and not
+     * in whoever added the component.
+     *
      * @param {AnimationGraphController} controller
-     * @param {SGMesh} model
+     * @param {AnimationClips} clips
      * @param {number} entity
      */
-    link(controller: AnimationGraphController, model: SGMesh, entity: number): void;
+    link(controller: AnimationGraphController, clips: AnimationClips, entity: number): void;
     /**
-     * What the entity's model is playing, in the form the CPU pose evaluator takes: one entry per
-     * clip **this graph names**, at the weight and the time the renderer has been given.
+     * What the entity is playing, in the form the CPU pose evaluator takes: one entry per clip
+     * **this graph names**, at the weight and the time the renderer has been given.
      *
      * **The clips the graph does not name are not here, because they are not registered** (D37).
      * The GPU's accumulator marks a joint dirty for every bound clip that writes to it, weight and
      * all — so a bound clip at weight zero resolves the joints only it drives to zero rather than
      * leaving them at rest. The answer is not to hand those clips to the evaluator so it can make
      * the same mistake; it is not to bind them. What the graph never names, nothing plays, and the
-     * joints it alone would have driven stay where the model rests.
+     * joints it alone would have driven stay where they rest.
      *
      * A clip the graph names but is not currently playing **is** here, at weight zero, because it is
      * bound and the accumulator does see it.
@@ -47,21 +56,22 @@ export class AnimationGraphSystem extends System<any> {
      * @param {PosePlayback[]} target appended to
      * @param {number} entity
      * @returns {boolean} whether this system is driving the entity — `false` for one with no
-     * {@link AnimationGraphController}, and for one whose model has not arrived
+     * {@link AnimationGraphController} or no {@link AnimationClips}, and for one whose clips arrived
+     * since the last update
      */
     write_pose_playbacks(target: PosePlayback[], entity: number): boolean;
     /**
      * @param {AnimationGraphController} controller
-     * @param {SGMesh} model
+     * @param {AnimationClips} clips
      * @param {number} entity
      */
-    unlink(controller: AnimationGraphController, model: SGMesh, entity: number): void;
+    unlink(controller: AnimationGraphController, clips: AnimationClips, entity: number): void;
     shutdown(entityManager: any): Promise<void>;
     #private;
 }
 import { System } from "../ecs/System.js";
-import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
 import { AnimationGraphController } from "./animation/AnimationGraphController.js";
+import { AnimationClips } from "./animation/AnimationClips.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
 import { PosePlayback } from "../../shade/renderer/animation/pose/PosePlayback.js";
 //# sourceMappingURL=AnimationGraphSystem.d.ts.map

package/src/engine/graphics3/AnimationGraphSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationGraphSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/AnimationGraphSystem.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;GAcG;AACH;IAmBI;;;OAGG;IACH,0DAgBC;IAPG,kEAAsD;IAItD,gFAEC;IAGL;;;;OAIG;IACH,iBAJW,wBAAwB,SACxB,MAAM,UACN,MAAM,QAahB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,6BALW,YAAY,EAAE,UACd,MAAM,GACJ,OAAO,CA+CnB;IAED;;;;OAIG;IACH,mBAJW,wBAAwB,SACxB,MAAM,UACN,MAAM,QAYhB;IAED,4CAQC;;CA4JJ;uBA5UsB,kBAAkB;uBAClB,6CAA6C;yCAC3B,yCAAyC;4CAJtC,iDAAiD;6BAChE,qDAAqD"}
+{"version":3,"file":"AnimationGraphSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/AnimationGraphSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAkBI;;;OAGG;IACH,oDAgBC;IAPG,0EAA8D;IAI9D,gFAEC;IAGL;;;;;;;;;OASG;IACH,iBAJW,wBAAwB,SACxB,cAAc,UACd,MAAM,QAchB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,6BANW,YAAY,EAAE,UACd,MAAM,GACJ,OAAO,CAgDnB;IAED;;;;OAIG;IACH,mBAJW,wBAAwB,SACxB,cAAc,UACd,MAAM,QAYhB;IAED,4CAQC;;CAkJJ;uBAzUsB,kBAAkB;yCAEA,yCAAyC;+BADnD,+BAA+B;4CAHlB,iDAAiD;6BAChE,qDAAqD"}