reze-engine 0.54.16 → 0.55.0

package/dist/overlay.js

@@ -0,0 +1,806 @@
+// The data behind the overlay pass: what an overlay primitive IS, the unit
+// wireframes the pass draws, and the three builders that turn a posed model into
+// a list of them.
+//
+// The builders are pure — (model, physics, options) -> OverlayPrimitive[] — so a
+// host can call them itself, print the result, diff two poses, or hand a list
+// straight to setOverlay without the engine's live layers in the way. The pass
+// is one caller of them.
+//
+// Everything they emit is WORLD space, root transform included, so a list is
+// meaningful on its own.
+import { Quat, Vec3 } from "./math";
+import { RigidbodyShape, RigidbodyType } from "./physics/types";
+export const OVERLAY_SHAPES = [
+    "line",
+    "dashedLine",
+    "axes",
+    "circle",
+    "dot",
+    "link",
+    "sphere",
+    "box",
+    "capsule",
+    "solidSphere",
+    "solidBox",
+    "solidCapsule",
+];
+/** The shapes that are solid geometry rather than stroked outlines. They draw
+ *  through their own pipeline: no depth write, no culling, so a translucent
+ *  volume reads as a volume and never hides the rig behind it. */
+export const OVERLAY_SOLID_SHAPES = new Set([
+    "solidSphere",
+    "solidBox",
+    "solidCapsule",
+]);
+/** Floats per instance in the pass's instance stream. */
+export const OVERLAY_INSTANCE_FLOATS = 16;
+/** Interleaved pos(3), dir(3), caps(2), side(1), t(1), mode(1) per vertex. */
+export const OVERLAY_VERTEX_FLOATS = 11;
+/** Radius of the marker's solid centre, as a fraction of the ring's. */
+const DOT_RADIUS = 0.42;
+/** Segments in a marker's ring and centre. They are small, always face the
+ *  camera, and there are only a few hundred, so smoothness is nearly free. */
+const MARKER_SEG = 48;
+/** Segments around a sphere's great circles and a capsule's rings. */
+const RING_SEG = 32;
+/** Segments in one half-circle of a capsule cap (ring → pole → ring). */
+const CAP_SEG = 16;
+/** Dashes in a dashed unit line. */
+const DASHES = 7;
+/** Builds every unit wireframe back to back in one line-list vertex buffer. */
+export function buildOverlayShapes() {
+    const v = [];
+    const ranges = {};
+    // Placement mode for the shape being emitted — see `placeWorld` in the shader.
+    let b = 0;
+    // A stroked segment: 6 vertices carrying each endpoint, the offset to the
+    // other, both cap signs, which side of the quad it is on, and its parameter
+    // along the segment. c0/c1 are the capsule cap signs — see the shader.
+    const seg = (p0, p1, c0 = 0, c1 = 0) => {
+        const dx = p1[0] - p0[0], dy = p1[1] - p0[1], dz = p1[2] - p0[2];
+        // prettier-ignore
+        v.push(p0[0], p0[1], p0[2], dx, dy, dz, c0, c1, -1, 0, b, p0[0], p0[1], p0[2], dx, dy, dz, c0, c1, 1, 0, b, p1[0], p1[1], p1[2], -dx, -dy, -dz, c1, c0, -1, 1, b, p0[0], p0[1], p0[2], dx, dy, dz, c0, c1, 1, 0, b, p1[0], p1[1], p1[2], -dx, -dy, -dz, c1, c0, 1, 1, b, p1[0], p1[1], p1[2], -dx, -dy, -dz, c1, c0, -1, 1, b);
+    };
+    // A filled triangle, for the shapes that are geometry rather than strokes.
+    const tri = (p0, p1, p2) => {
+        for (const p of [p0, p1, p2])
+            v.push(p[0], p[1], p[2], 0, 0, 0, 0, 0, 0, 0, b);
+    };
+    // A filled triangle whose vertices carry their own cap signs — the solid
+    // capsule needs it, since one quad of its wall straddles both hemispheres.
+    const triC = (p0, c0, p1, c1, p2, c2) => {
+        v.push(p0[0], p0[1], p0[2], 0, 0, 0, c0, 0, 0, 0, b);
+        v.push(p1[0], p1[1], p1[2], 0, 0, 0, c1, 0, 0, 0, b);
+        v.push(p2[0], p2[1], p2[2], 0, 0, 0, c2, 0, 0, 0, b);
+    };
+    // One rim vertex of the marker's ring: a direction, and which rim it is on.
+    const rim = (d, side) => {
+        v.push(d[0], d[1], d[2], 0, 0, 0, 0, 0, side, 0, b);
+    };
+    const open = (shape) => {
+        ranges[shape] = { first: v.length / OVERLAY_VERTEX_FLOATS, count: 0 };
+    };
+    const close = (shape) => {
+        ranges[shape].count = v.length / OVERLAY_VERTEX_FLOATS - ranges[shape].first;
+    };
+    // line — origin to +Y. scale.y is its length; point it with the rotation.
+    open("line");
+    seg([0, 0, 0], [0, 1, 0]);
+    close("line");
+    // dashedLine — the same run, broken up. A dash is geometry here rather than a
+    // fragment test, which is what a line pass can express without a shader for it.
+    open("dashedLine");
+    for (let i = 0; i < DASHES; i++) {
+        const a = i / DASHES;
+        const b = (i + 0.5) / DASHES;
+        seg([0, a, 0], [0, b, 0]);
+    }
+    close("dashedLine");
+    // axes — a cross through the origin, one segment per axis, ±scale.
+    open("axes");
+    seg([-1, 0, 0], [1, 0, 0]);
+    seg([0, -1, 0], [0, 1, 0]);
+    seg([0, 0, -1], [0, 0, 1]);
+    close("axes");
+    // circle — the bone marker's ring, facing the camera. Triangles between an
+    // inner and an outer rim, which the shader offsets radially in SCREEN space:
+    // the radius is world, the stroke is the same pixel width as the links, and
+    // the two meet without a step. `side` names the rim, -1 inner and +1 outer.
+    b = 4;
+    open("circle");
+    for (let i = 0; i < MARKER_SEG; i++) {
+        const a0 = (i / MARKER_SEG) * Math.PI * 2;
+        const a1 = ((i + 1) / MARKER_SEG) * Math.PI * 2;
+        const d0 = [Math.cos(a0), Math.sin(a0), 0];
+        const d1 = [Math.cos(a1), Math.sin(a1), 0];
+        rim(d0, -1);
+        rim(d0, 1);
+        rim(d1, 1);
+        rim(d0, -1);
+        rim(d1, 1);
+        rim(d1, -1);
+    }
+    close("circle");
+    // dot — the marker's solid centre. A plain camera-facing fan: mode 3, NOT the
+    // ring's 4, whose radial offset is undefined at a fan's centre vertex.
+    b = 3;
+    open("dot");
+    for (let i = 0; i < MARKER_SEG; i++) {
+        const a0 = (i / MARKER_SEG) * Math.PI * 2;
+        const a1 = ((i + 1) / MARKER_SEG) * Math.PI * 2;
+        tri([0, 0, 0], [Math.cos(a0), Math.sin(a0), 0], [Math.cos(a1), Math.sin(a1), 0]);
+    }
+    close("dot");
+    b = 2;
+    // link — the two lines from a marker's edge to its child. scale.x is the
+    // half-width at the base (the marker's radius), scale.y the distance to the
+    // child, and the rotation points +Y at it. Single segments, so there are no
+    // joins: the stroke can be as thick as it likes.
+    open("link");
+    seg([-1, 0, 0], [0, 1, 0]);
+    seg([1, 0, 0], [0, 1, 0]);
+    close("link");
+    b = 0;
+    // sphere — three great circles of radius 1.
+    open("sphere");
+    for (let plane = 0; plane < 3; plane++) {
+        for (let i = 0; i < RING_SEG; i++) {
+            const a0 = (i / RING_SEG) * Math.PI * 2;
+            const a1 = ((i + 1) / RING_SEG) * Math.PI * 2;
+            const c0 = Math.cos(a0), s0 = Math.sin(a0);
+            const c1 = Math.cos(a1), s1 = Math.sin(a1);
+            if (plane === 0)
+                seg([0, c0, s0], [0, c1, s1]);
+            else if (plane === 1)
+                seg([s0, 0, c0], [s1, 0, c1]);
+            else
+                seg([c0, s0, 0], [c1, s1, 0]);
+        }
+    }
+    close("sphere");
+    // box — the 12 edges of a cube of half-extent 1.
+    open("box");
+    for (let axis = 0; axis < 3; axis++) {
+        for (let a = -1; a <= 1; a += 2) {
+            for (let b = -1; b <= 1; b += 2) {
+                const p0 = [0, 0, 0];
+                const p1 = [0, 0, 0];
+                p0[axis] = -1;
+                p1[axis] = 1;
+                p0[(axis + 1) % 3] = p1[(axis + 1) % 3] = a;
+                p0[(axis + 2) % 3] = p1[(axis + 2) % 3] = b;
+                seg(p0, p1);
+            }
+        }
+    }
+    close("box");
+    // capsule — radius 1, with both hemispheres AT the origin and the cap sign
+    // saying which way `extent` pushes them. Nothing here is scaled along Y, so a
+    // long thin body keeps round caps.
+    open("capsule");
+    for (const capSign of [1, -1]) {
+        for (let i = 0; i < RING_SEG; i++) {
+            const a0 = (i / RING_SEG) * Math.PI * 2;
+            const a1 = ((i + 1) / RING_SEG) * Math.PI * 2;
+            seg([Math.cos(a0), 0, Math.sin(a0)], [Math.cos(a1), 0, Math.sin(a1)], capSign, capSign);
+        }
+        for (let plane = 0; plane < 2; plane++) {
+            for (let i = 0; i < CAP_SEG; i++) {
+                const a0 = (i / CAP_SEG) * Math.PI;
+                const a1 = ((i + 1) / CAP_SEG) * Math.PI;
+                const c0 = Math.cos(a0), s0 = Math.sin(a0) * capSign;
+                const c1 = Math.cos(a1), s1 = Math.sin(a1) * capSign;
+                if (plane === 0)
+                    seg([c0, s0, 0], [c1, s1, 0], capSign, capSign);
+                else
+                    seg([0, s0, c0], [0, s1, c1], capSign, capSign);
+            }
+        }
+    }
+    // The cylinder's four side lines. Both endpoints are the same point on the
+    // ring — the cap signs are what separate them, one pushed to +extent and one
+    // to -extent, so the line is exactly as long as the body is.
+    for (const [x, z] of [
+        [1, 0],
+        [0, 1],
+        [-1, 0],
+        [0, -1],
+    ]) {
+        seg([x, 0, z], [x, 0, z], 1, -1);
+    }
+    close("capsule");
+    // ── Solid volumes ────────────────────────────────────────────────
+    // Mode 5: placed in world like their wireframe twins, but filled, so they
+    // skip the stroke extrusion. Same size conventions — half-extents for the
+    // box, radius for the sphere, radius plus `extent` for the capsule.
+    b = 5;
+    const LAT = 10;
+    const LON = 24;
+    open("solidSphere");
+    for (let y = 0; y < LAT; y++) {
+        const p0 = (y / LAT) * Math.PI - Math.PI / 2;
+        const p1 = ((y + 1) / LAT) * Math.PI - Math.PI / 2;
+        for (let x = 0; x < LON; x++) {
+            const t0 = (x / LON) * Math.PI * 2;
+            const t1 = ((x + 1) / LON) * Math.PI * 2;
+            const at = (phi, theta) => [
+                Math.cos(phi) * Math.cos(theta),
+                Math.sin(phi),
+                Math.cos(phi) * Math.sin(theta),
+            ];
+            tri(at(p0, t0), at(p1, t0), at(p1, t1));
+            tri(at(p0, t0), at(p1, t1), at(p0, t1));
+        }
+    }
+    close("solidSphere");
+    open("solidBox");
+    for (let axis = 0; axis < 3; axis++) {
+        for (const face of [-1, 1]) {
+            const corner = (u, w) => {
+                const q = [0, 0, 0];
+                q[axis] = face;
+                q[(axis + 1) % 3] = u;
+                q[(axis + 2) % 3] = w;
+                return q;
+            };
+            tri(corner(-1, -1), corner(1, -1), corner(1, 1));
+            tri(corner(-1, -1), corner(1, 1), corner(-1, 1));
+        }
+    }
+    close("solidBox");
+    open("solidCapsule");
+    for (let x = 0; x < LON; x++) {
+        const t0 = (x / LON) * Math.PI * 2;
+        const t1 = ((x + 1) / LON) * Math.PI * 2;
+        const r0 = [Math.cos(t0), 0, Math.sin(t0)];
+        const r1 = [Math.cos(t1), 0, Math.sin(t1)];
+        // The wall: one quad from the top cap's rim to the bottom cap's.
+        triC(r0, 1, r0, -1, r1, -1);
+        triC(r0, 1, r1, -1, r1, 1);
+        // The two hemispheres, each entirely on its own cap.
+        for (const capSign of [1, -1]) {
+            for (let y = 0; y < LAT; y++) {
+                const p0 = (y / LAT) * (Math.PI / 2);
+                const p1 = ((y + 1) / LAT) * (Math.PI / 2);
+                const at = (phi, theta) => [
+                    Math.cos(phi) * Math.cos(theta),
+                    Math.sin(phi) * capSign,
+                    Math.cos(phi) * Math.sin(theta),
+                ];
+                triC(at(p0, t0), capSign, at(p1, t0), capSign, at(p1, t1), capSign);
+                triC(at(p0, t0), capSign, at(p1, t1), capSign, at(p0, t1), capSign);
+            }
+        }
+    }
+    close("solidCapsule");
+    b = 0;
+    return { vertices: new Float32Array(v), ranges };
+}
+/** Packs one primitive into the pass's instance layout at `offset` floats. */
+export function writeOverlayInstance(p, out, offset) {
+    const r = p.rotation ?? IDENTITY_ROT;
+    const s = p.scale ?? UNIT_SCALE;
+    out[offset + 0] = r[0];
+    out[offset + 1] = r[1];
+    out[offset + 2] = r[2];
+    out[offset + 3] = r[3];
+    out[offset + 4] = p.position[0];
+    out[offset + 5] = p.position[1];
+    out[offset + 6] = p.position[2];
+    out[offset + 7] = p.extent ?? 0;
+    out[offset + 8] = s[0];
+    out[offset + 9] = s[1];
+    out[offset + 10] = s[2];
+    out[offset + 11] = p.thickness ?? OVERLAY_STYLE.strokePx;
+    out[offset + 12] = p.color[0];
+    out[offset + 13] = p.color[1];
+    out[offset + 14] = p.color[2];
+    out[offset + 15] = p.color[3];
+}
+const IDENTITY_ROT = [0, 0, 0, 1];
+const UNIT_SCALE = [1, 1, 1];
+/**
+ * Every bone's marker position in world space, root transform included.
+ *
+ * THE SAME points boneOverlay puts markers at, which is the whole reason it is a
+ * function rather than a loop inside the picker: a hit test that recomputes
+ * where a marker "should" be is a hit test that drifts away from the one drawn.
+ */
+export function boneMarkerPositions(model, out) {
+    const world = model.getWorldMatrices();
+    const dst = out && out.length >= world.length * 3 ? out : new Float32Array(world.length * 3);
+    const root = rootTransform(model);
+    const local = new Vec3(0, 0, 0);
+    for (let i = 0; i < world.length; i++) {
+        const m = world[i].values;
+        if (root.identity) {
+            dst[i * 3] = m[12];
+            dst[i * 3 + 1] = m[13];
+            dst[i * 3 + 2] = m[14];
+            continue;
+        }
+        local.setXYZ(m[12] * root.scale, m[13] * root.scale, m[14] * root.scale);
+        const r = Quat.rotateVec(root.rotation, local);
+        dst[i * 3] = r.x + root.position.x;
+        dst[i * 3 + 1] = r.y + root.position.y;
+        dst[i * 3 + 2] = r.z + root.position.z;
+    }
+    return dst;
+}
+/**
+ * How big this model is, from its bone positions — the reference every default
+ * size here is a fraction of, so one set of numbers suits a 1-unit model and a
+ * 100-unit one.
+ */
+function skeletonExtent(world) {
+    let minY = Infinity, maxY = -Infinity, minX = Infinity, maxX = -Infinity;
+    for (const m of world) {
+        const v = m.values;
+        if (v[12] < minX)
+            minX = v[12];
+        if (v[12] > maxX)
+            maxX = v[12];
+        if (v[13] < minY)
+            minY = v[13];
+        if (v[13] > maxY)
+            maxY = v[13];
+    }
+    return Math.max(maxY - minY, maxX - minX, 1e-4);
+}
+/**
+ * The overlay's colours, and the only place they live.
+ *
+ * NOT an option a host passes. An overlay means the same thing in every product
+ * that draws one — orange is a bone the solver drives, whichever app you are
+ * looking at — and a colour each app picks for itself is a colour that drifts.
+ * A host that wants its own look builds its own list through setOverlay.
+ *
+ * Every value is one step of the same ramp (Tailwind's 500), so the classes read
+ * as a set and hue is the only thing that separates them.
+ *
+ * The rig is one colour and selection is another, and that is the whole scheme.
+ * Every class that had a hue of its own lost it: on a 147-bone skeleton the
+ * distinctions were spent on bones nobody was hunting for, and the panel is
+ * where those belong. The classes remain so a panel can filter on them.
+ *
+ * Red is spent entirely on `selected`, the one distinction that must never be
+ * ambiguous, and green is not used at all — red-green being the confusion most
+ * colour blindness causes.
+ *
+ * A physics-driven bone and a dynamic body share orange on purpose. They are the
+ * same fact seen twice — the solver owns this — and colouring them apart would
+ * invent a difference that is not there.
+ *
+ * The CATEGORIES are MMD's, straight out of the PMX file — IK chains, 付与親,
+ * 軸制限, a body's physics mode. The colours are not: MMD has no canonical
+ * palette for them.
+ */
+/**
+ * Every number the overlay's LOOK depends on, in one place beside the colours,
+ * and for the same reason: an overlay should read the same in every product that
+ * draws one, so none of this is an option a host passes.
+ *
+ * A host that wants its own look builds its own list through setOverlay.
+ */
+export const OVERLAY_STYLE = {
+    /** Stroke width for the rig, in DEVICE pixels — half this on screen at 2x. */
+    strokePx: 2,
+    /** Stroke width for the mesh wireframe. Thinner: there are tens of thousands
+     *  of edges and they are a ground for the rig, not the subject. */
+    meshStrokePx: 2,
+    /** How much heavier the selected item draws, on both stroke and marker. */
+    selectedScale: 1.6,
+    /** Bone marker radius for a bone that governs the whole model, as a fraction
+     *  of the skeleton's extent — so one number suits any model scale. */
+    markerSize: 0.005,
+    /** The reach a full-size marker corresponds to, as a fraction of the extent. */
+    markerReference: 0.2,
+    /** Marker radius is held between these multiples of markerSize. */
+    markerMin: 0.55,
+    markerMax: 1.0,
+    /** Floor on a leaf's reach, world units, so a tip still has a marker. */
+    minReach: 0.25,
+    /** Joint cross arm length, as a fraction of the skeleton's extent. */
+    jointSize: 0.006,
+    /** Stroke for the material borders drawn over the mesh wireframe. */
+    seamStrokePx: 3,
+    /** Stroke for the material under the pointer — the same self-occluding reveal
+     *  a pick draws, layered over the section-wide view rather than replacing it,
+     *  and heavier than either a pick's own edges or a seam so it still pops out
+     *  of a view that already has two other things drawn in it. */
+    hoverStrokePx: 4,
+    /** How strongly the triangulation draws under those borders.
+     *
+     *  Both at full strength is one undifferentiated field of yellow — forty
+     *  thousand edges saying what the model is made of the way a page of hex says
+     *  what a file contains. The borders are the answer and the triangulation is
+     *  the ground it reads against, so the ground steps back. */
+    meshAlpha: 0.55,
+};
+export const DEFAULT_BONE_PALETTE = {
+    /** Nothing in particular drives it — most of the skeleton, so it is the colour
+     *  the whole overlay reads as. */
+    plain: [0.231, 0.51, 0.965, 1], // blue-500
+    /** Has an IK chain (ikLinks): the leg IK bones and friends. Blue, the same as
+     *  plain — a colour of its own bought nothing here. Leg IK sits on the floor
+     *  and reaches almost nothing, so these are the smallest markers in the rig
+     *  and mostly overlapped by the foot bones they share a place with; no hue
+     *  rescues that. If they need to stand out later it is their SIZE that has to
+     *  change, since a control bone's length means nothing to begin with. */
+    ik: [0.231, 0.51, 0.965, 1], // blue-500
+    /** A dynamic rigidbody moves it — hair, skirt, anything the solver owns. Blue,
+     *  the same as plain: which bones the solver owns is the rigidbody layer's
+     *  question, and it already answers it. Kept as a class so a panel can pick it
+     *  out, spending no colour on it here. */
+    physics: [0.231, 0.51, 0.965, 1], // blue-500
+    /** The one you picked. Red is spent entirely here and used nowhere else, so
+     *  nothing on screen can be mistaken for a selection. */
+    selected: [0.937, 0.267, 0.267, 1], // red-500
+};
+/**
+ * The skeleton, MMD's way: a ring with a solid centre at every bone, and two
+ * lines from that ring converging on the child's.
+ *
+ * Ring and centre are filled geometry facing the camera, so a marker is a circle
+ * from any angle and can be heavy without a stroke wide enough to tear itself
+ * apart. The two link lines leave the ring at its edge — the taper is what says
+ * which way the bone points, where a single line between centres would not.
+ */
+export function boneOverlay(model, options = {}) {
+    const bones = model.getSkeleton().bones;
+    const world = model.getWorldMatrices();
+    const palette = DEFAULT_BONE_PALETTE;
+    const include = options.include ? new Set(options.include) : null;
+    const extent = skeletonExtent(world);
+    const markerSize = extent * OVERLAY_STYLE.markerSize;
+    const physicsBones = new Set();
+    for (const rb of model.getRigidbodies()) {
+        if (rb.type !== RigidbodyType.Static && rb.boneIndex >= 0)
+            physicsBones.add(rb.boneIndex);
+    }
+    // Marker radius per bone, from its REACH: the longest chain still hanging off
+    // it, head to furthest descendant.
+    //
+    // Not the bone's own length, which is what this measured before. A bone's own
+    // length says nothing about its place in the rig — every segment of a hair
+    // strand is the same short segment, so a strand's ROOT scored no larger than
+    // its tip, and nothing stopped a child's segment being longer than its
+    // parent's and drawing bigger. Reach cannot do either: a parent's reach is its
+    // child's plus the step between them, so a marker never grows going down a
+    // chain, and a bone that governs an arm, a strand or a whole side of the body
+    // is marked for what it carries rather than for the gap to its first child.
+    const depth = new Int32Array(bones.length);
+    for (let i = 0; i < bones.length; i++) {
+        let d = 0;
+        let c = bones[i].parentIndex;
+        // Guarded: a malformed file can cycle, and this must not hang on one.
+        while (c >= 0 && c < bones.length && d < bones.length) {
+            d++;
+            c = bones[c].parentIndex;
+        }
+        depth[i] = d;
+    }
+    const deepestFirst = Array.from(bones.keys()).sort((a, b) => depth[b] - depth[a]);
+    const reach = new Float32Array(bones.length);
+    for (const i of deepestFirst) {
+        const p = bones[i].parentIndex;
+        if (p < 0 || p >= world.length || i >= world.length)
+            continue;
+        const m = world[p].values;
+        const cm = world[i].values;
+        const step = Math.hypot(cm[12] - m[12], cm[13] - m[13], cm[14] - m[14]);
+        if (reach[i] + step > reach[p])
+            reach[p] = reach[i] + step;
+    }
+    // Square-rooted, so the spread stays legible: without it the root bone's reach
+    // is the whole model and everything below it collapses into the floor.
+    const sizes = new Float32Array(bones.length);
+    const referenceReach = Math.max(extent * OVERLAY_STYLE.markerReference, 1e-6);
+    for (let i = 0; i < bones.length; i++) {
+        const r = Math.sqrt(Math.max(reach[i], OVERLAY_STYLE.minReach) / referenceReach);
+        sizes[i] = markerSize * Math.min(Math.max(r, OVERLAY_STYLE.markerMin), OVERLAY_STYLE.markerMax);
+    }
+    // MMD stacks control bones on one point — 全ての親, センター and グルーブ all sit
+    // at the hips. Sized per bone they draw as a nest of rings, so a position gets
+    // ONE marker, the largest asked for there. Links are still drawn for every
+    // bone: it is the markers that overlap, not the connections.
+    const grid = Math.max(extent * 1e-4, 1e-6);
+    const key = (m) => `${Math.round(m[12] / grid)},${Math.round(m[13] / grid)},${Math.round(m[14] / grid)}`;
+    const markerAt = new Map();
+    for (let i = 0; i < bones.length && i < world.length; i++) {
+        if (include && !include.has(bones[i].name))
+            continue;
+        const k = key(world[i].values);
+        const held = markerAt.get(k);
+        if (held === undefined || sizes[i] > sizes[held])
+            markerAt.set(k, i);
+    }
+    const root = rootTransform(model);
+    const out = [];
+    const head = new Vec3(0, 0, 0);
+    const tail = new Vec3(0, 0, 0);
+    const dir = new Vec3(0, 0, 0);
+    for (let i = 0; i < bones.length && i < world.length; i++) {
+        const bone = bones[i];
+        if (include && !include.has(bone.name))
+            continue;
+        const m = world[i].values;
+        head.setXYZ(m[12], m[13], m[14]);
+        const selected = options.selected != null && bone.name === options.selected;
+        const cls = selected
+            ? "selected"
+            : bone.ikLinks && bone.ikLinks.length > 0
+                ? "ik"
+                : physicsBones.has(i)
+                    ? "physics"
+                    : "plain";
+        const color = palette[cls];
+        const size = selected ? sizes[i] * OVERLAY_STYLE.selectedScale : sizes[i];
+        const stroke = selected ? OVERLAY_STYLE.strokePx * OVERLAY_STYLE.selectedScale : OVERLAY_STYLE.strokePx;
+        // One link per bone, from its PARENT down to it — so every parent-child
+        // edge is drawn exactly once and branches all show.
+        //
+        // Not "from this bone to its first child", which is what this did and what
+        // made a thigh point at the wrong place: children are ordered by bone INDEX,
+        // not by anatomy, so 左足's children[0] is 左腿物理, a physics bone hanging
+        // off the thigh, and 左ひざ — the actual knee — came second. There is no
+        // ordering of children that is reliably the continuation. Drawing all of
+        // them removes the need to guess.
+        const parent = bone.parentIndex;
+        if (parent >= 0 && parent < world.length) {
+            const pm = world[parent].values;
+            tail.setXYZ(pm[12], pm[13], pm[14]);
+            const span = Math.hypot(head.x - tail.x, head.y - tail.y, head.z - tail.z);
+            if (span > 1e-5) {
+                dir.setXYZ((head.x - tail.x) / span, (head.y - tail.y) / span, (head.z - tail.z) / span);
+                const rot = Quat.fromUnitVectors(UP, dir);
+                out.push(applyRoot(root, {
+                    shape: "link",
+                    // The taper starts at the PARENT's marker and narrows onto this one,
+                    // so its base half-width is the parent's radius.
+                    position: [tail.x, tail.y, tail.z],
+                    rotation: [rot.x, rot.y, rot.z, rot.w],
+                    scale: [sizes[parent], span, sizes[parent]],
+                    color,
+                    thickness: stroke,
+                }));
+            }
+        }
+        // Only the bone that owns this position draws the marker.
+        if (markerAt.get(key(m)) !== i)
+            continue;
+        out.push(applyRoot(root, {
+            shape: "circle",
+            position: [head.x, head.y, head.z],
+            scale: [size, size, size],
+            color,
+            // The same stroke the links carry, so they read as one line.
+            thickness: stroke,
+        }));
+        out.push(applyRoot(root, {
+            shape: "dot",
+            position: [head.x, head.y, head.z],
+            scale: [size * DOT_RADIUS, size * DOT_RADIUS, size * DOT_RADIUS],
+            color,
+        }));
+    }
+    return out;
+}
+/** Solid volumes, so alpha does the work a stroke used to: low enough to see the
+ *  body through them and the rig behind them. Cool follows its bone, warm is
+ *  driven by the solver. */
+export const DEFAULT_RIGIDBODY_PALETTE = {
+    static: [0.055, 0.647, 0.914, 0.28], // sky-500
+    dynamic: [0.976, 0.451, 0.086, 0.38], // orange-500
+    selected: [0.937, 0.267, 0.267, 0.55], // red-500
+};
+/** The joint cross, the dashed lines to the bodies it holds, and its selection. */
+export const DEFAULT_JOINT_PALETTE = {
+    cross: [0.055, 0.647, 0.914, 1], // sky-500
+    link: [0.055, 0.647, 0.914, 0.5], // sky-500
+    selected: [0.937, 0.267, 0.267, 1], // red-500
+};
+/** The mesh wireframe. Yellow, because it has to carry over pale skin and dark
+ *  cloth alike and the rig owns the blues and greens. */
+// yellow-400, opaque. yellow-500 measured correct on the canvas and still read
+// as gold: a 2px stroke through 4x MSAA is mostly partial-coverage pixels, so a
+// dense mesh of lines lands well under the flat swatch it is cut from. The step
+// up pays that back rather than the pipeline being wrong.
+export const DEFAULT_VERTEX_COLOR = [0.98, 0.8, 0.082, 1];
+/**
+ * The sphere, box or capsule each rigidbody actually is, where it actually is.
+ *
+ * With physics running the transforms come from the simulation, so a body drawn
+ * here is the body the solver collides — which is the point of drawing them
+ * while tuning cloth. Without it they fall back to the bone-driven bind pose.
+ */
+export function rigidbodyOverlay(model, physics, options = {}) {
+    const bodies = model.getRigidbodies();
+    const palette = DEFAULT_RIGIDBODY_PALETTE;
+    const include = options.include ? new Set(options.include) : null;
+    const root = rootTransform(model);
+    const pos = new Vec3(0, 0, 0);
+    const rot = new Quat(0, 0, 0, 1);
+    const out = [];
+    for (let i = 0; i < bodies.length; i++) {
+        const rb = bodies[i];
+        if (include && !include.has(rb.name))
+            continue;
+        resolveBodyTransform(model, physics, i, pos, rot);
+        const selected = options.selected != null && rb.name === options.selected;
+        const cls = selected ? "selected" : rb.type === RigidbodyType.Static ? "static" : "dynamic";
+        const color = palette[cls];
+        if (rb.shape === RigidbodyShape.Sphere) {
+            const r = rb.size.x;
+            out.push(applyRoot(root, {
+                shape: "solidSphere",
+                position: [pos.x, pos.y, pos.z],
+                rotation: [rot.x, rot.y, rot.z, rot.w],
+                scale: [r, r, r],
+                color,
+            }));
+        }
+        else if (rb.shape === RigidbodyShape.Box) {
+            out.push(applyRoot(root, {
+                shape: "solidBox",
+                position: [pos.x, pos.y, pos.z],
+                rotation: [rot.x, rot.y, rot.z, rot.w],
+                // PMX box size is half-extents already.
+                scale: [rb.size.x, rb.size.y, rb.size.z],
+                color,
+            }));
+        }
+        else {
+            const r = rb.size.x;
+            out.push(applyRoot(root, {
+                shape: "solidCapsule",
+                position: [pos.x, pos.y, pos.z],
+                rotation: [rot.x, rot.y, rot.z, rot.w],
+                scale: [r, r, r],
+                // PMX capsule size.y is the CYLINDER's length, caps not included.
+                extent: rb.size.y * 0.5,
+                color,
+            }));
+        }
+    }
+    return out;
+}
+/**
+ * An axis cross at each joint, plus a dashed line to each body it constrains.
+ *
+ * The cross is where and how the constraint frame sits; the two dashed lines
+ * are the pair it holds together, which is the question actually being asked of
+ * a skirt with two hundred of them. Dashed, because a relationship should not
+ * read as a thing.
+ */
+export function jointOverlay(model, physics, options = {}) {
+    const joints = model.getJoints();
+    const bodies = model.getRigidbodies();
+    const extent = skeletonExtent(model.getWorldMatrices());
+    const size = extent * OVERLAY_STYLE.jointSize;
+    const color = DEFAULT_JOINT_PALETTE.cross;
+    const linkColor = DEFAULT_JOINT_PALETTE.link;
+    const selectedColor = DEFAULT_JOINT_PALETTE.selected;
+    const links = options.links ?? true;
+    const include = options.include ? new Set(options.include) : null;
+    const root = rootTransform(model);
+    const jointPos = new Vec3(0, 0, 0);
+    const bodyPos = new Vec3(0, 0, 0);
+    const bodyRot = new Quat(0, 0, 0, 1);
+    const out = [];
+    for (const joint of joints) {
+        if (include && !include.has(joint.name))
+            continue;
+        const selected = options.selected != null && joint.name === options.selected;
+        const crossColor = selected ? selectedColor : color;
+        // A joint's frame is authored in bind pose, so drawing it there would leave
+        // every joint on a simulating skirt behind. Carry it on body A instead:
+        //   local = bindA⁻¹ · bindJoint,  posed = poseA · local.
+        jointPos.setXYZ(joint.position.x, joint.position.y, joint.position.z);
+        const rot = Quat.fromEuler(joint.rotation.x, joint.rotation.y, joint.rotation.z);
+        const a = joint.rigidbodyIndexA;
+        if (a >= 0 && a < bodies.length) {
+            resolveBodyTransform(model, physics, a, bodyPos, bodyRot);
+            const bind = bodies[a];
+            const bindRot = Quat.fromEuler(bind.shapeRotation.x, bind.shapeRotation.y, bind.shapeRotation.z);
+            const localPos = Quat.rotateVecInv(bindRot, new Vec3(joint.position.x - bind.shapePosition.x, joint.position.y - bind.shapePosition.y, joint.position.z - bind.shapePosition.z));
+            const localRot = Quat.conjugateInto(bindRot, new Quat(0, 0, 0, 1)).multiply(rot);
+            const carried = Quat.rotateVec(bodyRot, localPos);
+            jointPos.setXYZ(bodyPos.x + carried.x, bodyPos.y + carried.y, bodyPos.z + carried.z);
+            rot.set(bodyRot.multiply(localRot).normalize());
+        }
+        out.push(applyRoot(root, {
+            shape: "axes",
+            position: [jointPos.x, jointPos.y, jointPos.z],
+            rotation: [rot.x, rot.y, rot.z, rot.w],
+            scale: [size, size, size],
+            color: crossColor,
+            thickness: selected ? OVERLAY_STYLE.strokePx * OVERLAY_STYLE.selectedScale : OVERLAY_STYLE.strokePx,
+        }));
+        if (!links)
+            continue;
+        for (const idx of [joint.rigidbodyIndexA, joint.rigidbodyIndexB]) {
+            if (idx < 0 || idx >= bodies.length)
+                continue;
+            resolveBodyTransform(model, physics, idx, bodyPos, bodyRot);
+            const line = lineBetween([jointPos.x, jointPos.y, jointPos.z], [bodyPos.x, bodyPos.y, bodyPos.z], selected ? selectedColor : linkColor, true);
+            if (line) {
+                line.thickness = OVERLAY_STYLE.strokePx;
+                out.push(applyRoot(root, line));
+            }
+        }
+    }
+    return out;
+}
+/** A segment from `a` to `b`, solid or dashed. Null when the two coincide. */
+export function lineBetween(a, b, color, dashed = false) {
+    const dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2];
+    const length = Math.hypot(dx, dy, dz);
+    if (length < 1e-6)
+        return null;
+    const dir = new Vec3(dx / length, dy / length, dz / length);
+    const rot = Quat.fromUnitVectors(UP, dir);
+    return {
+        shape: dashed ? "dashedLine" : "line",
+        position: a,
+        rotation: [rot.x, rot.y, rot.z, rot.w],
+        scale: [1, length, 1],
+        color,
+    };
+}
+const UP = new Vec3(0, 1, 0);
+// ──────────────────────────────────────────────────────────────────
+// Shared
+/**
+ * Where body `index` is right now: the simulation's answer when physics is
+ * running, the bone-driven bind transform when it is not.
+ */
+function resolveBodyTransform(model, physics, index, outPos, outRot) {
+    if (physics) {
+        // RigidBodyStore is [...model bodies, floor], so a model index is a store
+        // index and needs no mapping.
+        const store = physics.getStore();
+        if (index < store.count) {
+            const i3 = index * 3;
+            const i4 = index * 4;
+            outPos.setXYZ(store.positions[i3], store.positions[i3 + 1], store.positions[i3 + 2]);
+            outRot.setXYZW(store.orientations[i4], store.orientations[i4 + 1], store.orientations[i4 + 2], store.orientations[i4 + 3]);
+            return;
+        }
+    }
+    const rb = model.getRigidbodies()[index];
+    const world = model.getWorldMatrices();
+    if (rb.bodyOffsetMatrix && rb.boneIndex >= 0 && rb.boneIndex < world.length) {
+        const m = world[rb.boneIndex].multiply(rb.bodyOffsetMatrix);
+        outPos.setXYZ(m.values[12], m.values[13], m.values[14]);
+        outRot.set(m.toQuat().normalize());
+        return;
+    }
+    outPos.setXYZ(rb.shapePosition.x, rb.shapePosition.y, rb.shapePosition.z);
+    outRot.set(Quat.fromEuler(rb.shapeRotation.x, rb.shapeRotation.y, rb.shapeRotation.z));
+}
+/** The model's scene placement, which bone and body transforms do NOT carry —
+ *  getSkinMatrices applies it on the way to the GPU, so an overlay has to too. */
+function rootTransform(model) {
+    const p = model.position;
+    const r = model.rotation;
+    const s = model.scale;
+    const identity = p.x === 0 && p.y === 0 && p.z === 0 && r.x === 0 && r.y === 0 && r.z === 0 && r.w === 1 && s === 1;
+    return { identity, position: p, rotation: r, scale: s };
+}
+function applyRoot(root, p) {
+    if (root.identity)
+        return p;
+    const local = new Vec3(p.position[0] * root.scale, p.position[1] * root.scale, p.position[2] * root.scale);
+    const rotated = Quat.rotateVec(root.rotation, local);
+    const rot = p.rotation ?? IDENTITY_ROT;
+    const worldRot = root.rotation.multiply(new Quat(rot[0], rot[1], rot[2], rot[3])).normalize();
+    const s = p.scale ?? UNIT_SCALE;
+    p.position = [rotated.x + root.position.x, rotated.y + root.position.y, rotated.z + root.position.z];
+    p.rotation = [worldRot.x, worldRot.y, worldRot.z, worldRot.w];
+    p.scale = [s[0] * root.scale, s[1] * root.scale, s[2] * root.scale];
+    if (p.extent)
+        p.extent = p.extent * root.scale;
+    return p;
+}