@woosh/meep-engine 3.23.0 → 3.24.0

package/src/engine/physics/cloth/ecs/cloth_write_back_rig.js

@@ -1,115 +1,58 @@
-import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
-import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
-import {
-    TRANSFORM64_ROTATION_OFFSET,
-    TRANSFORM64_TRANSLATION_OFFSET
-} from "../../../ecs/transform/Transform64.js";
-import { cloth_reconstruct_pose } from "./cloth_reconstruct_pose.js";
-import { cloth_write_local_pose } from "./cloth_write_back.js";
-
-/**
- * # Putting the answer back onto a skinned model's joints — §11.2
- *
- * The same reconstruction the entity path uses, written onto `Node3D`s instead
- * of onto entities. **Cloth moves joints; it does not produce vertices** — the
- * mapping from a simulated joint to a render vertex already exists in this
- * engine and it is the skin, so the existing skinning pass does the rest,
- * including bounds refresh and BLAS refit that a bespoke vertex-deformation
- * path would have to reimplement.
- *
- * ## `transform_local` is the output, and `transform_global` is written too
- *
- * `transform_local` is a joint's own truth and the handle §11.2 names. It is
- * also *passive*: a `Node3D` does not track its components, and nothing
- * downstream sees a change until `updateMatrices` runs — which recurses into
- * every descendant, so calling it on the anchor would recompose the whole
- * character every fixed step to move a cape.
- *
- * So this pass composes the cloth subtree's `transform_global` itself, which
- * costs nothing because the pose is already in hand, and bumps each joint's
- * version through `needsUpdate` so the renderer uploads the row. Nothing above
- * the anchor is touched and nothing below the garment is walked.
- *
- * `transform_global` is derived, so writing it is only ever a shortcut for the
- * recomposition it saves — and it is a *correct* shortcut only because this
- * pass has the anchor's world pose and the whole chain under it. Anything that
- * moves the anchor without telling cloth invalidates it, which is the same
- * contract every consumer of a derived transform already has.
- *
- * ## What is not here
- *
- * No announcement, and no pruned boundary. The entity path has both because its
- * subtree is an entity hierarchy with other things hanging off it; a proxy's
- * joint list is closed by construction, and a socket parented to a cape joint
- * follows it through the ordinary node hierarchy.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * Write one cloth's solved pose onto the joints it drives.
- *
- * @param {ClothInstance} instance
- * @param {Transform64} anchor the anchor joint's **world** pose, evaluated by
- *   the caller — see `ClothSystem` for why it is not read off the node
- * @returns {void}
- */
-export function cloth_write_back_rig(instance, anchor) {
-    cloth_reconstruct_pose(instance);
-
-    const node_count = instance.node_count;
-
-    const blended = instance.blended_position;
-    const reconstructed = instance.blended_rotation;
-
-    const ax = anchor[TRANSFORM64_TRANSLATION_OFFSET];
-    const ay = anchor[TRANSFORM64_TRANSLATION_OFFSET + 1];
-    const az = anchor[TRANSFORM64_TRANSLATION_OFFSET + 2];
-
-    const aqx = anchor[TRANSFORM64_ROTATION_OFFSET];
-    const aqy = anchor[TRANSFORM64_ROTATION_OFFSET + 1];
-    const aqz = anchor[TRANSFORM64_ROTATION_OFFSET + 2];
-    const aqw = anchor[TRANSFORM64_ROTATION_OFFSET + 3];
-
-    const parent = instance.node_parent;
-    const node_joint = instance.node_joint;
-
-    for (let node = 1; node < node_count; node++) {
-        const joint = node_joint[node];
-
-        if (joint === undefined || joint === null) {
-            continue;
-        }
-
-        cloth_write_local_pose(joint.transform_local, instance, node, parent[node]);
-
-        const global = joint.transform_global;
-
-        const n = node * 3;
-
-        v3_quaternion_apply(
-            global, TRANSFORM64_TRANSLATION_OFFSET,
-            blended[n], blended[n + 1], blended[n + 2],
-            aqx, aqy, aqz, aqw
-        );
-
-        global[TRANSFORM64_TRANSLATION_OFFSET] += ax;
-        global[TRANSFORM64_TRANSLATION_OFFSET + 1] += ay;
-        global[TRANSFORM64_TRANSLATION_OFFSET + 2] += az;
-
-        quat3_multiply(
-            global, TRANSFORM64_ROTATION_OFFSET,
-            aqx, aqy, aqz, aqw,
-            reconstructed[node * 4], reconstructed[node * 4 + 1],
-            reconstructed[node * 4 + 2], reconstructed[node * 4 + 3]
-        );
-
-        global.updateMatrix();
-
-        // The version is what the renderer compares against to decide whether
-        // to upload the row, so a joint whose transform changed and whose
-        // version did not is a joint that moved nowhere.
-        joint.needsUpdate = true;
-    }
-}
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../../../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { cloth_reconstruct_pose } from "./cloth_reconstruct_pose.js";
+import { cloth_write_local_pose } from "./cloth_write_back.js";
+
+/**
+ * # Putting the answer back onto a skinned model's joints — §11.2
+ *
+ * The same reconstruction the entity path uses, written onto the joint entities' offsets.
+ * **Cloth moves joints; it does not produce vertices** — the mapping from a simulated joint to a
+ * render vertex already exists in this engine and it is the skin, so the existing skinning pass
+ * does the rest, including bounds refresh and BLAS refit that a bespoke vertex-deformation path
+ * would have to reimplement.
+ *
+ * ## The offset is the output
+ *
+ * A joint's `TransformAttachment` offset is its own truth and the handle §11.2 names: it is what
+ * the joint's row holds, and the GPU composes the world from it under the anchor's animated
+ * row. Writing it is announced on the joint, which is what carries it to the row — the model
+ * marks the row on that announcement — and what lets the attachment system recompose the CPU's
+ * copy of the world below it. That copy is composed under the anchor as the CPU knows it, which
+ * for a GPU-driven anchor is its rest pose: what the simulation may read about a cape joint is
+ * its offset, or an exact evaluation, never that composed world.
+ *
+ * Nothing above the anchor is touched: the anchor is the character's, animated by its clips,
+ * and this pass hangs a cape from it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Write the reconstructed pose onto the rig's joints.
+ *
+ * @param {ClothInstance} instance
+ * @param {EntityComponentDataset} ecd
+ */
+export function cloth_write_back_rig(instance, ecd) {
+    cloth_reconstruct_pose(instance);
+
+    const node_count = instance.node_count;
+
+    const parent = instance.node_parent;
+    const node_joint = instance.node_joint;
+    const node_attachment = instance.node_attachment;
+
+    for (let node = 1; node < node_count; node++) {
+        const joint = node_joint[node];
+        const attachment = node_attachment[node];
+
+        if (attachment === undefined || attachment === null || !ecd.entityExists(joint)) {
+            continue;
+        }
+
+        cloth_write_local_pose(attachment.transform, instance, node, parent[node]);
+
+        ecd.sendEvent(joint, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
+    }
+}

package/src/engine/physics/cloth/playground/README.md

@@ -12,7 +12,7 @@ free port if 5173 is busy — the terminal says which.)
 | [`index.html`](./index.html) | **the solver, M0.** `cloth_step` over a `ClothState`, no ECS at all. |
 | [`rig.html`](./rig.html) | **the entity subtree, M1.** A real `EntityManager`, real entities, `ClothSystem` walking and writing back. |
 | [`collide.html`](./collide.html) | **collision, M2.** The solver again, with a packed collider table in the argument list. |
-| [`garment.html`](./garment.html) | **skinned garments, M3, and self-collision, M4.** A `Node3D` skeleton, a `Skin`, and a `Cloth` + `ClothRig` driving some of its joints. |
+| [`garment.html`](./garment.html) | **skinned garments, M3, and self-collision, M4.** A skeleton of entities, a `Skin`, and a `Cloth` + `ClothRig` driving some of its joints. |
 
 Both are at
 `http://localhost:5173/src/engine/physics/cloth/playground/<page>`.
@@ -260,14 +260,14 @@ does not fire in a hidden pane, so a driver calls `step_once` itself.
 ## What it is
 
 `rig.html` is a `Cloth` over an entity subtree; this is a `Cloth` + a `ClothRig`
-over a skinned model's **joints**. Every point on screen is a
-`Node3D.transform_global` — a joint of a `Skin`, not an entity — and it is where
-it is because the solver wrote its `transform_local` and this page composed the
-chain.
+over a skinned model's **joints**. Every point on screen is a joint's
+`Transform64` — an entity of the skeleton's prefab instance, named by a `Skin` —
+and it is where it is because the solver wrote its attachment's local transform
+and the attachment system composed the chain.
 
 `ClothSystem#models` takes a stub rather than a `MeshSystem` for the reason the
 field exists: a `MeshSystem` needs a graphics engine, a scene and a loader, and a
-garment's joints are a `Node3D` tree that needs none of the three. The stub
+garment's joints are a prefab instance that needs none of the three. The stub
 answers exactly the one method the system calls.
 
 ## The garments
@@ -279,7 +279,7 @@ answers exactly the one method the system calls.
 - **coat tails** — three strips of nine in denim, which is the library entry that
   spends its two levers on particles rather than iterations.
 - **ponytail** — one chain of twelve off the neck. The rig path is the entity
-  path with `Node3D`s in it, and a single chain is where that is most obviously
+  path over a skin's joints, and a single chain is where that is most obviously
   true.
 - **loincloth** — seven strips of five off the pelvis, and the one preset that
   spends most of its time against the leg colliders.
@@ -287,10 +287,10 @@ answers exactly the one method the system calls.
 ## The motion drives the character, and only the character
 
 The buttons write the **character's own bones**. The garment's joints are
-cloth's, and the seed says so: it claims `TransformAuthority.CPU` on every one of
-them, because a joint a clip drives is under GPU authority and its
-`transform_local` is not read by anything. Two writers of one row is the race the
-authority enum exists to prevent, and the claim is where a garment whose joints
+cloth's, and the seed says so: it revokes the GPU's authority over the attachment
+of every one of them, because a joint a clip drives is the GPU's and its local
+transform is not read by anything. Two writers of one row is the race the
+authority flags exist to prevent, and the claim is where a garment whose joints
 are *also* keyed shows up as an authoring error.
 
 **sprint** is §7 P7's own profile: a square wave in velocity, integrated. Written

package/src/engine/physics/cloth/playground/garment_build.d.ts

@@ -74,5 +74,4 @@ export type GarmentScene = {
 import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
 import { ClothSystem } from "../ecs/ClothSystem.js";
 import { ClothColliderSystem } from "../ecs/ClothColliderSystem.js";
-import { Node3D } from "../../../../shade/renderer/scene/Node3D.js";
 //# sourceMappingURL=garment_build.d.ts.map

package/src/engine/physics/cloth/playground/garment_build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"garment_build.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/garment_build.js"],"names":[],"mappings":"AA2FA;;;GAGG;AACH,6FAHW,MAAM,GACJ,QAAQ,YAAY,CAAC,CA4EjC;AA8JD;;;;;;GAMG;AACH,8CAHW,MAAM,GACJ,IAAI,CA0BhB;AAhVD;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;IAqCE;;SAjDY,sBAAsB;WACtB,WAAW;eACX,mBAAmB;YACnB,MAAM;;;;UACN,MAAM;YACN,MAAM;;;;UACN,MAAM,EAAE;;;;WACR,MAAM,EAAE;;;;;UAER,MAAM,EAAE,EAAE;;uCA7Ce,wCAAwC;4BAcnD,uBAAuB;oCAHf,+BAA+B;uBAZ5C,4CAA4C"}
+{"version":3,"file":"garment_build.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/garment_build.js"],"names":[],"mappings":"AA8FA;;;GAGG;AACH,6FAHW,MAAM,GACJ,QAAQ,YAAY,CAAC,CA6EjC;AAiKD;;;;;;GAMG;AACH,8CAHW,MAAM,GACJ,IAAI,CAyBhB;AAnVD;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;IAqCE;;SAjDY,sBAAsB;WACtB,WAAW;eACX,mBAAmB;YACnB,MAAM;;;;;;;;;UAGN,QAAQ;;;;WACR,QAAQ;;;;;UAER,MAAM,EAAE,EAAE;;uCA7Ce,wCAAwC;4BAcnD,uBAAuB;oCAHf,+BAA+B"}

package/src/engine/physics/cloth/playground/garment_build.js

@@ -1,7 +1,10 @@
 import { CapsuleShape3D } from "../../../../core/geom/3d/shape/CapsuleShape3D.js";
 import { SphereShape3D } from "../../../../core/geom/3d/shape/SphereShape3D.js";
 import { Skin } from "../../../../shade/renderer/animation/Skin.js";
-import { Node3D } from "../../../../shade/renderer/scene/Node3D.js";
+import { SceneBundle } from "../../../../shade/renderer/loader/SceneBundle.js";
+import { SceneNode } from "../../../../shade/renderer/loader/SceneNode.js";
+import { prefab_compile } from "../../../graphics3/prefab/prefab_compile.js";
+import { prefab_instantiate } from "../../../graphics3/prefab/prefab_instantiate.js";
 import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
 import { EntityManager } from "../../../ecs/EntityManager.js";
 import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
@@ -72,8 +75,8 @@ export const GARMENT_PRESETS = [
     {
         id: 'ponytail',
         label: 'ponytail — 1 × 12',
-        blurb: 'One chain, deep. The rig path is the entity path with Node3Ds in it, and a single '
-            + 'chain is where that is most obviously true.',
+        blurb: 'One chain, deep. The rig path is the entity path, and a single chain is where that '
+            + 'is most obviously true.',
         strips: 1,
         links: 12,
         dynamics: 'HAIR'
@@ -114,9 +117,8 @@ export async function build_garment({ preset, dynamics, links, spacing, collide,
 
     const entry = GARMENT_PRESETS.find(p => p.id === preset) ?? GARMENT_PRESETS[0];
 
-    const skeleton = build_skeleton(entry, links, spacing);
-
-    const { proxy, error } = cloth_proxy_from_joints(skeleton.skin, skeleton.garment_names, {
+        const skeleton = build_skeleton(ecd, entry, links, spacing);
+    const { proxy, error } = cloth_proxy_from_joints(skeleton.prefab, skeleton.skin, skeleton.garment_names, {
         name: entry.label
     });
 
@@ -143,7 +145,9 @@ export async function build_garment({ preset, dynamics, links, spacing, collide,
 
     ecd.addComponentToEntity(entity, Cloth.from(fabric, { flags: ClothFlags.NeverSleep }));
 
-    cloth.models = { instance_of: () => ({ skins: [skeleton.skin] }) };
+    // the one method `ClothSystem` calls on a model provider: the instance whose skins address the
+    // joints as entities
+    cloth.models = { instance_of: () => skeleton.instance };
 
     if (collide) {
         add_body_colliders(ecd, skeleton);
@@ -152,11 +156,11 @@ export async function build_garment({ preset, dynamics, links, spacing, collide,
     // One step so the seed runs and the bind pose is on the joints.
     cloth.fixedUpdate(1 / 60);
 
-    const bind = skeleton.joint.map(node => [
-        node.transform_global.translation[0],
-        node.transform_global.translation[1],
-        node.transform_global.translation[2]
-    ]);
+    const bind = skeleton.joint.map(entity => {
+        const t = ecd.getComponent(entity, Transform64).translation;
+
+        return [t[0], t[1], t[2]];
+    });
 
     return {
         ecd,
@@ -173,38 +177,26 @@ export async function build_garment({ preset, dynamics, links, spacing, collide,
  * A character: pelvis, spine, shoulders, two legs, and the garment's own strips
  * hanging from whichever bone the preset says.
  *
+ * @param {EntityComponentDataset} ecd the page's dataset, which the character becomes entities of
  * @param {object} entry
  * @param {number} links
  * @param {number} spacing
- * @returns {object}
+ * @returns {object} the bones and the garment's joints as entities, the prefab and its instance
  * @private
  */
-function build_skeleton(entry, links, spacing) {
-    /** @type {Node3D[]} */
-    const joints = [];
+function build_skeleton(ecd, entry, links, spacing) {
+    // the character as a loader would describe it: nodes in pre-order, every one a joint of the skin
+    const bundle = new SceneBundle();
 
     /**
      * @param {string} name
-     * @param {Node3D|null} parent
+     * @param {number} parent
      * @param {number[]} offset
-     * @returns {Node3D}
+     * @returns {number} the node's index
      */
-    const bone = (name, parent, offset) => {
-        const node = new Node3D();
-
-        node.name = name;
-        node.transform_local.setTranslation(offset[0], offset[1], offset[2]);
-
-        if (parent !== null) {
-            parent.addChild(node);
-        }
-
-        joints.push(node);
+    const bone = (name, parent, offset) => bundle.add_node(SceneNode.from({ name, parent, translation: offset }));
 
-        return node;
-    };
-
-    const root = bone('root', null, [0, 0, 0]);
+    const root = bone('root', -1, [0, 0, 0]);
     const pelvis = bone('pelvis', root, [0, 0.95, 0]);
     const spine = bone('spine', pelvis, [0, 0.22, 0]);
     const chest = bone('chest', spine, [0, 0.2, 0]);
@@ -218,15 +210,13 @@ function build_skeleton(entry, links, spacing) {
     bone('knee_l', left_leg, [0, -0.42, 0]);
     bone('knee_r', right_leg, [0, -0.42, 0]);
 
-    const character = joints.slice();
+    const character_count = bundle.nodes.length;
 
     // The garment hangs from the chest for a cape and from the pelvis for a
     // loincloth, which is the difference between the two presets.
     const from = entry.id === 'loincloth' ? pelvis : (entry.id === 'ponytail' ? neck : chest);
 
     const garment_names = [];
-    const garment = [];
-
     const strips = entry.strips;
 
     for (let s = 0; s < strips; s++) {
@@ -235,8 +225,10 @@ function build_skeleton(entry, links, spacing) {
         let parent = from;
 
         for (let i = 0; i < links; i++) {
-            const node = bone(
-                `garment_${s}_${i}`,
+            const name = `garment_${s}_${i}`;
+
+            parent = bone(
+                name,
                 parent,
                 i === 0
                     // The first link carries the strip sideways and behind, so
@@ -252,25 +244,40 @@ function build_skeleton(entry, links, spacing) {
                     : [0, -spacing, -spacing * 0.05]
             );
 
-            garment_names.push(node.name);
-            garment.push(node);
-
-            parent = node;
+            garment_names.push(name);
         }
     }
 
-    root.updateMatrices();
+    const joints = bundle.nodes.map((_node, index) => index);
+
+    bundle.skins = [Skin.from({
+        joints,
+        inverse_bind_matrices: new Float32Array(joints.length * 16)
+    })];
+
+    const prefab = prefab_compile(bundle);
+
+    // the character is entities of the page's dataset, under a placement standing at the origin;
+    // the attachment system composes every joint's world from there, the way a rig's would
+    const placement = ecd.createEntity();
+    const placement_transform = new Transform64();
+
+    placement_transform.updateMatrix();
+
+    ecd.addComponentToEntity(placement, placement_transform);
+
+    const instance = prefab_instantiate(prefab, ecd, placement);
 
     return {
-        root,
-        pelvis,
-        bone: character,
-        joint: garment,
+        prefab,
+        instance,
+        placement,
+        root: instance.entity_of('root'),
+        pelvis: instance.entity_of('pelvis'),
+        bone: bundle.nodes.slice(0, character_count).map(node => instance.entity_of(node.name)),
+        joint: garment_names.map(name => instance.entity_of(name)),
         garment_names,
-        skin: Skin.from({
-            joints,
-            inverse_bind_matrices: new Float32Array(joints.length * 16)
-        })
+        skin: prefab.skins[0]
     };
 }
 
@@ -278,7 +285,7 @@ function build_skeleton(entry, links, spacing) {
  * Capsules on the character's own bones, opted into cloth the way any collider
  * is: a `ClothCollider` beside an existing `(Collider, Transform64)`.
  *
- * They are entities rather than nodes because that is what a `ClothCollider`
+ * They are entities of their own because that is what a `ClothCollider`
  * is — §3.5's "the `RigidBody`-analogue" — and because a character's collision
  * capsules are authored as entities in a real scene too. The page keeps their
  * transforms in step with the bones by hand, which is what a rig would do.
@@ -288,7 +295,7 @@ function build_skeleton(entry, links, spacing) {
  * @private
  */
 function add_body_colliders(ecd, skeleton) {
-    const by_name = new Map(skeleton.bone.map(node => [node.name, node]));
+    const instance = skeleton.instance;
 
     const parts = [
         { bone: 'spine', shape: CapsuleShape3D.from(0.13, 0.3), offset: [0, 0.1, 0] },
@@ -300,9 +307,9 @@ function add_body_colliders(ecd, skeleton) {
     skeleton.body = [];
 
     for (const part of parts) {
-        const node = by_name.get(part.bone);
+        const node = instance.entity_of(part.bone);
 
-        if (node === undefined) {
+        if (node === -1) {
             continue;
         }
 
@@ -340,9 +347,8 @@ export function garment_sync_colliders(scene) {
     }
 
     for (const part of body) {
-        const node = part.node;
-
-        const t = node.transform_global;
+        // the bone's world, as the attachment system composed it
+        const t = scene.ecd.getComponent(part.node, Transform64);
 
         part.transform.setTranslation(
             t.translation[0] + part.offset[0],

package/src/engine/physics/cloth/playground/garment_main.js

@@ -2,6 +2,9 @@ import { Cloth } from "../ecs/Cloth.js";
 import { CLOTH_DYNAMICS_BY_NAME } from "../ecs/cloth_dynamics_library.js";
 import { PlaygroundCamera, project } from "./cloth_playground_draw.js";
 import { GARMENT_PRESETS, build_garment, garment_sync_colliders } from "./garment_build.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../../../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
 
 /**
  * # Skinned garments playground — M3
@@ -11,9 +14,9 @@ import { GARMENT_PRESETS, build_garment, garment_sync_colliders } from "./garmen
  *
  * The rig page (`rig.html`) is a `Cloth` over an entity subtree; this is a
  * `Cloth` + a `ClothRig` over a skinned model's **joints**. Every point on
- * screen is a `Node3D.transform_global` — a joint of a `Skin`, not an entity —
- * and it is where it is because the solver wrote its `transform_local` and this
- * page composed the chain.
+ * screen is a joint's world `Transform64` — an entity of the character's prefab
+ * instance — and it is where it is because the solver wrote the joint's own
+ * offset and the attachment system composed the chain.
  *
  * What it exists to show, because these are claims about a hierarchy rather
  * than about an array:
@@ -122,35 +125,43 @@ function step_once() {
  * the race it exists to prevent.
  */
 function drive_character() {
-    const root = scene.root;
-    const pelvis = scene.pelvis;
+    const ecd = scene.ecd;
+
+    // the bones' own offsets, under their parents: what a rig's animation would write
+    const root = ecd.getComponent(scene.root, TransformAttachment).transform;
+    const pelvis = ecd.getComponent(scene.pelvis, TransformAttachment).transform;
 
     if (control.motion === 'still') {
-        root.transform_local.setTranslation(0, 0, 0);
-        root.transform_local.setRotation(0, 0, 0, 1);
-        pelvis.transform_local.setTranslation(0, 0.95, 0);
+        root.setTranslation(0, 0, 0);
+        root.setRotation(0, 0, 0, 1);
+        pelvis.setTranslation(0, 0.95, 0);
     } else if (control.motion === 'walk') {
-        root.transform_local.setTranslation(0, 0, Math.sin(time * 1.6) * 0.9);
-        root.transform_local.setRotation(0, 0, 0, 1);
-        pelvis.transform_local.setTranslation(0, 0.95 + Math.sin(time * 6.4) * 0.02, 0);
+        root.setTranslation(0, 0, Math.sin(time * 1.6) * 0.9);
+        root.setRotation(0, 0, 0, 1);
+        pelvis.setTranslation(0, 0.95 + Math.sin(time * 6.4) * 0.02, 0);
     } else if (control.motion === 'turn') {
         const angle = time * 1.9;
 
-        root.transform_local.setTranslation(0, 0, 0);
-        root.transform_local.setRotation(0, Math.sin(angle * 0.5), 0, Math.cos(angle * 0.5));
-        pelvis.transform_local.setTranslation(0, 0.95, 0);
+        root.setTranslation(0, 0, 0);
+        root.setRotation(0, Math.sin(angle * 0.5), 0, Math.cos(angle * 0.5));
+        pelvis.setTranslation(0, 0.95, 0);
     } else {
         // §7 P7's own profile: a **square wave in velocity**, integrated rather
         // than written as a position — a position that resets is a nine-metre
         // discontinuity, which is a teleport (§7 P6) wearing a sprint's clothes.
         sprint_z += (Math.floor(time) % 2 === 0 ? 9 : -9) * FIXED_STEP;
 
-        root.transform_local.setTranslation(0, 0, sprint_z);
-        root.transform_local.setRotation(0, 0, 0, 1);
-        pelvis.transform_local.setTranslation(0, 0.95, 0);
+        root.setTranslation(0, 0, sprint_z);
+        root.setRotation(0, 0, 0, 1);
+        pelvis.setTranslation(0, 0.95, 0);
     }
 
-    root.updateMatrices();
+    root.updateMatrix();
+    pelvis.updateMatrix();
+
+    // announced, so the attachment system composes the chain below each
+    ecd.sendEvent(scene.root, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
+    ecd.sendEvent(scene.pelvis, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
 }
 
 // ------------------------------------------------------------------- draw
@@ -183,18 +194,35 @@ function draw() {
 }
 
 /**
- * @param {Node3D} node
+ * @param {number} node an entity of the character
  * @param {Float64Array} out
  * @param {number} width
  * @param {number} height
  * @returns {number} depth
  */
 function project_node(node, out, width, height) {
-    const t = node.transform_global.translation;
+    const t = scene.ecd.getComponent(node, Transform64).translation;
 
     return project(out, camera, t[0], t[1], t[2], width, height);
 }
 
+/**
+ * The bone an entity hangs from, or -1 at the top of the character — the placement above the
+ * root is not a bone.
+ *
+ * @param {number} node
+ * @returns {number}
+ */
+function parent_of(node) {
+    const attachment = scene.ecd.getComponent(node, TransformAttachment);
+
+    if (attachment === undefined || attachment.parent === scene.placement) {
+        return -1;
+    }
+
+    return attachment.parent;
+}
+
 function draw_ground(width, height) {
     context.save();
     context.strokeStyle = '#1d222a';
@@ -227,11 +255,13 @@ function draw_body(width, height) {
     context.lineWidth = Math.max(2, width / 500);
 
     for (const node of scene.bone) {
-        if (node.parent === null) {
+        const parent = parent_of(node);
+
+        if (parent === -1) {
             continue;
         }
 
-        project_node(node.parent, SCREEN, width, height);
+        project_node(parent, SCREEN, width, height);
         project_node(node, OTHER, width, height);
 
         context.beginPath();
@@ -257,17 +287,13 @@ function draw_bind(width, height) {
     const joint = scene.joint;
 
     for (let i = 0; i < joint.length; i++) {
-        const node = joint[i];
-
-        const parent_index = joint.indexOf(node.parent);
+                const node = joint[i];
+        const parent = parent_of(node);
+        const parent_index = joint.indexOf(parent);
 
         const from = parent_index >= 0
             ? bind[parent_index]
-            : [
-                node.parent.transform_global.translation[0],
-                node.parent.transform_global.translation[1],
-                node.parent.transform_global.translation[2]
-            ];
+            : Array.from(scene.ecd.getComponent(parent, Transform64).translation);
 
         project(SCREEN, camera, from[0], from[1], from[2], width, height);
         project(OTHER, camera, bind[i][0], bind[i][1], bind[i][2], width, height);
@@ -287,7 +313,7 @@ function draw_garment(width, height) {
     context.lineWidth = Math.max(1.5, width / 700);
 
     for (const node of scene.joint) {
-        project_node(node.parent, SCREEN, width, height);
+        project_node(parent_of(node), SCREEN, width, height);
         project_node(node, OTHER, width, height);
 
         context.beginPath();
@@ -313,7 +339,7 @@ function draw_garment(width, height) {
  * Each joint's reconstructed orientation, as an axis triple. A particle has no
  * orientation, so this is §11.1's swing — the minimal rotation from the link's
  * bind direction to its simulated one, and the reason the rig path can write a
- * `transform_local` at all.
+ * offset of its own at all.
  */
 function draw_frames(width, height) {
     const axes = [
@@ -328,7 +354,7 @@ function draw_frames(width, height) {
     context.lineWidth = 1;
 
     for (const node of scene.joint) {
-        const t = node.transform_global;
+        const t = scene.ecd.getComponent(node, Transform64);
 
         project(SCREEN, camera, t.translation[0], t.translation[1], t.translation[2], width, height);