reze-engine 0.54.16 → 0.55.1

package/dist/camera.d.ts

@@ -35,6 +35,19 @@ export declare class Camera {
     maxZ: number;
     lowerBetaLimit: number;
     upperBetaLimit: number;
+    /**
+     * Orbit roll, radians — the lean the orbit itself cannot state.
+     *
+     * alpha and beta are a yaw and a pitch about an upright axis, and lookAt is
+     * handed world up, so an orbiting shot is level by construction. This tips
+     * that up vector about the eye→target line, which leaves WHERE the camera is
+     * and WHAT it looks at exactly as they were.
+     *
+     * That is the whole reason it lives here rather than in a pose pushed from
+     * outside: a rolled shot still follows a bone, still orbits, still zooms. A
+     * pose replaces all of that with one frozen answer.
+     */
+    roll: number;
     private _viewMat;
     private _projMat;
     vmdDriven: boolean;

package/dist/camera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../src/camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAQ,IAAI,EAAE,MAAM,QAAQ,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAyBpD,qBAAa,MAAM;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,IAAI,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAI;IAClB;;;oFAGgF;IAChF,IAAI,EAAE,MAAM,CAAiB;IAC7B,GAAG,EAAE,MAAM,CAAU;IACrB;+EAC2E;IAC3E,SAAS,UAAQ;IAGjB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,iBAAiB,CAAY;IACrC,OAAO,CAAC,iBAAiB,CAAiB;IAC1C,OAAO,CAAC,oBAAoB,CAAY;IAGxC,kBAAkB,EAAE,MAAM,CAAQ;IAClC,cAAc,EAAE,MAAM,CAAS;IAC/B,cAAc,EAAE,MAAM,CAAO;IAC7B,cAAc,EAAE,MAAM,CAAO;IAC7B,IAAI,EAAE,MAAM,CAAO;IACnB,IAAI,EAAE,MAAM,CAAU;IACtB,cAAc,EAAE,MAAM,CAAQ;IAC9B,cAAc,EAAE,MAAM,CAAkB;IAGxC,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,QAAQ,CAAiC;IAKjD,SAAS,EAAE,OAAO,CAAQ;IAC1B,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,YAAY,CAAuB;gBAE/B,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAE,MAAoB;IAmBhG,WAAW,IAAI,IAAI;IAQnB;wFACoF;IACpF,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAOpC,0FAA0F;IAC1F;;;;;;;;;;OAUG;IACH,OAAO,IAAI,UAAU;IAoBrB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAelC,OAAO,CAAC,MAAM;IAUd;;;;;;;;;;;OAWG;IACH,cAAc,IAAI,IAAI;IAItB,aAAa,IAAI,IAAI;IA2BrB,OAAO,CAAC,gBAAgB;IA0CxB,OAAO,CAAC,SAAS;IAiBjB,kFAAkF;IAClF,OAAO,CAAC,mBAAmB;IAK3B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,oBAAoB;IAM5B,mBAAmB,IAAI,IAAI;IAW3B,aAAa,CAAC,MAAM,EAAE,iBAAiB;IAiBvC,aAAa;IAkBb,cAAc,CAAC,MAAM,EAAE,OAAO;IAS9B,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,WAAW;IAsBnB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,YAAY;IA8BpB,OAAO,CAAC,WAAW;IAuFnB,OAAO,CAAC,UAAU;CA+BnB"}
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../src/camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAQ,IAAI,EAAE,MAAM,QAAQ,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAyBpD,qBAAa,MAAM;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,IAAI,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAI;IAClB;;;oFAGgF;IAChF,IAAI,EAAE,MAAM,CAAiB;IAC7B,GAAG,EAAE,MAAM,CAAU;IACrB;+EAC2E;IAC3E,SAAS,UAAQ;IAGjB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,iBAAiB,CAAY;IACrC,OAAO,CAAC,iBAAiB,CAAiB;IAC1C,OAAO,CAAC,oBAAoB,CAAY;IAGxC,kBAAkB,EAAE,MAAM,CAAQ;IAClC,cAAc,EAAE,MAAM,CAAS;IAC/B,cAAc,EAAE,MAAM,CAAO;IAC7B,cAAc,EAAE,MAAM,CAAO;IAC7B,IAAI,EAAE,MAAM,CAAO;IACnB,IAAI,EAAE,MAAM,CAAU;IACtB,cAAc,EAAE,MAAM,CAAQ;IAC9B,cAAc,EAAE,MAAM,CAAkB;IACxC;;;;;;;;;;;OAWG;IACH,IAAI,EAAE,MAAM,CAAI;IAGhB,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,QAAQ,CAAiC;IAKjD,SAAS,EAAE,OAAO,CAAQ;IAC1B,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,YAAY,CAAuB;gBAE/B,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAE,MAAoB;IAmBhG,WAAW,IAAI,IAAI;IAQnB;wFACoF;IACpF,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAOpC,0FAA0F;IAC1F;;;;;;;;;;OAUG;IACH,OAAO,IAAI,UAAU;IAuBrB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAelC,OAAO,CAAC,MAAM;IAUd;;;;;;;;;;;OAWG;IACH,cAAc,IAAI,IAAI;IAItB,aAAa,IAAI,IAAI;IAqErB,OAAO,CAAC,gBAAgB;IA0CxB,OAAO,CAAC,SAAS;IAiBjB,kFAAkF;IAClF,OAAO,CAAC,mBAAmB;IAK3B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,oBAAoB;IAM5B,mBAAmB,IAAI,IAAI;IAW3B,aAAa,CAAC,MAAM,EAAE,iBAAiB;IAiBvC,aAAa;IAkBb,cAAc,CAAC,MAAM,EAAE,OAAO;IAS9B,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,WAAW;IAsBnB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,YAAY;IA8BpB,OAAO,CAAC,WAAW;IAuFnB,OAAO,CAAC,UAAU;CA+BnB"}

package/dist/camera.js

@@ -54,6 +54,19 @@ export class Camera {
         this.maxZ = FAR_CAP;
         this.lowerBetaLimit = 0.001;
         this.upperBetaLimit = Math.PI - 0.001;
+        /**
+         * Orbit roll, radians — the lean the orbit itself cannot state.
+         *
+         * alpha and beta are a yaw and a pitch about an upright axis, and lookAt is
+         * handed world up, so an orbiting shot is level by construction. This tips
+         * that up vector about the eye→target line, which leaves WHERE the camera is
+         * and WHAT it looks at exactly as they were.
+         *
+         * That is the whole reason it lives here rather than in a pose pushed from
+         * outside: a rolled shot still follows a bone, still orbits, still zooms. A
+         * pose replaces all of that with one frozen answer.
+         */
+        this.roll = 0;
         // Reused each frame so getViewMatrix/getProjectionMatrix don't allocate a Mat4 per call.
         this._viewMat = new Mat4(new Float32Array(16));
         this._projMat = new Mat4(new Float32Array(16));
@@ -126,7 +139,10 @@ export class Camera {
         // NEGATIVE to match: in a VMD the camera sits behind its target.
         return {
             target: new Vec3(this.target.x, this.target.y, this.target.z),
-            rotation: new Vec3(this.beta - Math.PI / 2, -this.alpha, 0),
+            // z carries the roll, so a rolled orbit exports and reads back as the
+            // same shot rather than a level one — the AE rig and the VMD writer both
+            // take this channel.
+            rotation: new Vec3(this.beta - Math.PI / 2, -this.alpha, this.roll),
             distance: -this.radius,
             fov: this.fov,
         };
@@ -199,7 +215,42 @@ export class Camera {
         }
         const eye = this.getPosition();
         const t = this.target;
-        Mat4.lookAtInto(this._viewMat.values, eye.x, eye.y, eye.z, t.x, t.y, t.z, 0, 1, 0);
+        if (this.roll === 0) {
+            Mat4.lookAtInto(this._viewMat.values, eye.x, eye.y, eye.z, t.x, t.y, t.z, 0, 1, 0);
+            return this._viewMat;
+        }
+        // Roll = the up vector, turned about the view axis. Build the shot's own
+        // basis first (forward, then right, then a true up), because world up is
+        // only the camera's up while the shot is level — which is the thing this is
+        // about to stop being.
+        let fx = t.x - eye.x;
+        let fy = t.y - eye.y;
+        let fz = t.z - eye.z;
+        const fl = Math.hypot(fx, fy, fz) || 1;
+        fx /= fl;
+        fy /= fl;
+        fz /= fl;
+        // right = forward × worldUp, with worldUp = (0,1,0), which is (−fz, 0, fx).
+        //
+        // WRITTEN THE OTHER WAY ROUND ONCE, and it did not fail quietly: that is
+        // worldUp × forward, so `right` pointed left, `up` below came out as right ×
+        // forward = DOWN, and the camera turned upside down the moment roll left
+        // zero. Degenerate only when the shot looks straight up or down, where
+        // beta's own limits already keep it from arriving.
+        let rx = -fz;
+        let ry = 0;
+        let rz = fx;
+        const rl = Math.hypot(rx, ry, rz) || 1;
+        rx /= rl;
+        ry /= rl;
+        rz /= rl;
+        // up = right × forward
+        const ux = ry * fz - rz * fy;
+        const uy = rz * fx - rx * fz;
+        const uz = rx * fy - ry * fx;
+        const c = Math.cos(this.roll);
+        const sn = Math.sin(this.roll);
+        Mat4.lookAtInto(this._viewMat.values, eye.x, eye.y, eye.z, t.x, t.y, t.z, ux * c + rx * sn, uy * c + ry * sn, uz * c + rz * sn);
         return this._viewMat;
     }
     // Get camera's right and up vectors for panning

package/dist/engine.d.ts

@@ -9,6 +9,7 @@ import { type ParamKey } from "./param-track";
 import { type EffectWindow } from "./effect-schedule";
 import { type HdrImage } from "./hdr";
 import { type LyricLine, type LyricRect } from "./shaders/lyrics-api";
+import { type BoneOverlayOptions, type JointOverlayOptions, type OverlayPrimitive, type RigidbodyOverlayOptions } from "./overlay";
 import { type CompileOptions, type StyleSlot } from "./graph/compile";
 import type { AlphaMode, RenderClass } from "./graph/render-class";
 import type { ApplyStyleGroupResult, ApplyStyleGroupsResult, StyleGroup } from "./graph/style-group";
@@ -428,6 +429,19 @@ interface ModelInstance {
     materialMorphTargets: MaterialMorphTarget[] | null;
     /** The same targets by PMX material index, so a named offset is one lookup. */
     materialMorphByIndex: Map<number, MaterialMorphTarget> | null;
+    /** The mesh's unique edges as a line-list index buffer, built on first use.
+     *  Deduplicated: an interior edge belongs to two triangles, so drawing the
+     *  triangle list's edges directly would draw most of the mesh twice.
+     *
+     *  Keyed by the material the edges were cut from, "" for the whole mesh. A
+     *  material is a consecutive index run, so scoping is a slice of the same
+     *  build — and both stay cached, because narrowing to one material and
+     *  widening back out is the loop somebody auditing a model is in. */
+    wireEdges: Map<string, {
+        buffer: GPUBuffer;
+        count: number;
+        bindGroup: GPUBindGroup;
+    } | null>;
     physics: RezePhysics | null;
     vertexBufferNeedsUpdate: boolean;
     gpuMorph: GpuMorph | null;
@@ -530,7 +544,67 @@ export declare class Engine {
     private selectionEdgeUniformBuffer;
     private selectionEdgePassDescriptor;
     private selectionSampler;
+    private overlayVertexBuffer;
+    private overlayInstanceBuffer;
+    private overlayInstanceCapacity;
+    private overlayPipeline;
+    private overlaySolidPipeline;
+    private overlayBindGroup;
+    private overlayGeometry;
+    private overlayPassDescriptor;
+    private overlayDepthTexture;
+    private overlayMsaaTexture;
+    private overlayResolveTexture;
+    private overlayUniformBuffer;
+    private overlayUniformData;
+    private overlayCompositePipeline;
+    private overlayCompositeLayout;
+    private overlayCompositeBindGroup;
+    private overlayCompositePassDescriptor;
+    private overlayTargetSize;
+    /** The overlay renders multisampled into its own layer; the scene's own depth
+     *  is discarded before the composite (see the depthRead note in render), so it
+     *  could not have shared either that or the single-sample swapchain. */
+    private static readonly OVERLAY_SAMPLE_COUNT;
+    /** Dash period in device pixels — dashes are geometry, so this is only the
+     *  reference the dashedLine shape is cut against. */
+    private static readonly OVERLAY_DASH_PERIOD_PX;
+    private overlayLayers;
+    private overlayBones;
+    private overlayBodies;
+    private overlayJoints;
+    private overlayVertices;
+    private wireframePipeline;
+    private wireframeDepthPipeline;
+    private wireframeUniformBuffer;
+    private wireframeBindGroup;
+    /** The seam pass draws in the same frame at a different stroke and alpha, and
+     *  every queue write lands before the command buffer runs — writing the one
+     *  buffer twice would give both draws the second value. */
+    private wireframeSeamUniformBuffer;
+    private wireframeSeamBindGroup;
+    /** Same reason: the hovered material draws its own stroke, self-occluding, in
+     *  the same frame as the base mesh and the seams. */
+    private wireframeHoverUniformBuffer;
+    private wireframeHoverBindGroup;
+    private wireframeSkinLayout;
+    private wireframeColorData;
+    /** Rebuilt every frame into these, grouped by shape so each shape is one draw. */
+    private overlayByShape;
+    private overlayScratch;
+    private bonePickScratch;
+    private overlayInstanceData;
     private selectedBone;
+    /** The material a pointer is currently over, or null. Cheap and separate from
+     *  setVertexOverlay on purpose — the same split setSelectedBone takes from
+     *  setBoneOverlay — because this is written every frame the pointer moves and
+     *  the overlay's own option object is not something to reconstruct that often. */
+    private hoverMaterial;
+    /** The transform gizmo follows setSelectedBone, which is also what selects a
+     *  bone to INSPECT. A model editor selects bones constantly and poses them
+     *  rarely, so the two need separating: off leaves selection working and takes
+     *  the handles away. */
+    private gizmoEnabled;
     private gizmoVertexBuffer;
     private gizmoTransformBuffer;
     private gizmoPipeline;
@@ -1094,6 +1168,28 @@ export declare class Engine {
     setColorGrading(patch: Partial<ColorGradingOptions>): void;
     /** Current grade (for serialization into a scene descriptor). */
     getColorGrading(): ColorGradingOptions;
+    /** Sensor grain: how much, and whether it moves. */
+    private grain;
+    /**
+     * Film grain over the rendered scene, 0–1.
+     *
+     * A property of a SENSOR, so it belongs to the camera rather than to any one
+     * subject, and it lands on what the engine drew and on nothing else — never on
+     * a background image or a backdrop video, which arrived with grain of their
+     * own and would be graded rather than matched by a second helping.
+     *
+     * `animated` false freezes it. A still photograph's grain does not move, and
+     * noise crawling over a frozen picture makes the rendering look more alive
+     * than the thing it is standing in.
+     *
+     * Costs one hash per pixel in a pass that already runs, and nothing at all at
+     * zero — the branch is on a uniform.
+     */
+    setFilmGrain(amount: number, animated?: boolean): void;
+    getFilmGrain(): Readonly<{
+        amount: number;
+        animated: boolean;
+    }>;
     setViewTransformOptions(patch: Partial<ViewTransformOptions>): void;
     /**
      * Whether bloom will actually reach the frame this frame.
@@ -1643,6 +1739,7 @@ export declare class Engine {
     setRenderSize(size: null): void;
     private handleResize;
     private setupGizmo;
+    private setupOverlay;
     private setupCamera;
     /** Set static camera look-at / orbit center. Clears any model follow binding. */
     setCameraTarget(v: Vec3): void;
@@ -1650,6 +1747,32 @@ export declare class Engine {
     setCameraTarget(model: Model | null, boneName: string, offset?: Vec3): void;
     /** Souls-style follow cam: orbit center tracks a model bone each frame. Shorthand for setCameraTarget(model, boneName, offset). */
     setCameraFollow(model: Model | null, boneName?: string, offset?: Vec3, smoothing?: number): void;
+    /** Whether a loaded camera track is allowed to drive (setCameraVmdEnabled).
+     *  Held separately from `camera.vmdDriven` because that flag now answers to
+     *  two sources, and a track switched off must stay off when the other one
+     *  releases the camera. */
+    private cameraVmdEnabled;
+    /** A pose pushed in from outside — see setCameraPose. Reapplied every frame,
+     *  so it outranks the orbit AND a loaded track for as long as it is set. */
+    private cameraPoseOverride;
+    /** The one place that decides who is holding the camera. An external pose
+     *  wins; a track drives when it is loaded and enabled; otherwise orbit. */
+    private refreshCameraDrive;
+    /**
+     * Aim the camera from outside — a solved match-move, a saved shot, a rig
+     * driving the view from the host's own clock.
+     *
+     * The exact partner of `getCameraPose`, and the same five channels: the shot
+     * as MMD states it, roll included. Orbit cannot express roll, so this is the
+     * only way a tilted camera reaches the engine.
+     *
+     * Reapplied every frame while set, which makes it authoritative rather than
+     * advisory — nothing the transport or a loaded track does moves it. Pass null
+     * to release, and whatever was driving before takes the camera back.
+     */
+    setCameraPose(pose: CameraPose | null): void;
+    /** The pose currently forced from outside, or null when nothing is. */
+    getCameraPoseOverride(): CameraPose | null;
     /** Load a camera VMD (dedicated camera file, or any VMD's camera block) and drive the shot
      *  from it. Default-on once a non-empty track loads; toggle with setCameraVmdEnabled. */
     loadCameraVmd(url: string): Promise<void>;
@@ -1774,12 +1897,42 @@ export declare class Engine {
     private transportTime;
     /** Current orbit eye position (spherical coords resolved to a point). */
     getCameraPosition(): Vec3;
+    /**
+     * The live orbit, read in ONE call.
+     *
+     * A host that stores the shot has to be able to ask where the camera actually
+     * IS, because a drag on the canvas moves this and nothing else — and a
+     * document that never asks will happily write back the angle it last set,
+     * discarding whatever the person just did with the mouse. Reading the four
+     * separately invites a torn set across a frame boundary; this cannot tear.
+     *
+     * `target` is the orbit's own centre. While the engine is following a bone
+     * that point rides the bone, so a caller storing a FOLLOW offset must keep its
+     * own and take only the angles from here.
+     */
+    getCameraOrbit(): {
+        alpha: number;
+        beta: number;
+        distance: number;
+        target: Vec3;
+    };
     getCameraDistance(): number;
     setCameraDistance(d: number): void;
     getCameraAlpha(): number;
     setCameraAlpha(a: number): void;
     getCameraBeta(): number;
     setCameraBeta(b: number): void;
+    /**
+     * Roll the orbiting shot, radians — the lean alpha and beta cannot state.
+     *
+     * Tips the up vector about the eye→target line, so the camera stays exactly
+     * where it was and keeps looking at exactly what it looked at. Everything the
+     * orbit does still works underneath it: following a bone, dragging, zooming.
+     *
+     * A camera VMD carries its own roll and ignores this while it drives.
+     */
+    setCameraRoll(r: number): void;
+    getCameraRoll(): number;
     /** Vertical field of view in radians (default π/4). While a camera VMD
      *  drives the view it animates fov itself; the orbit value set here is
      *  restored when the VMD releases the camera. */
@@ -1836,6 +1989,16 @@ export declare class Engine {
         /** Mirror softness, 0–1: 0 a polished mirror, 1 the softest blur level,
          *  scaled by how far the reflected geometry sits behind the surface. */
         mirrorBlur?: number;
+        /** How soft the received shadow's edge is, 0–1. 0 (default) is the sharp
+         *  kernel this has always used, to the bit; 1 spreads the taps fourteen
+         *  times as wide, which is the edge an overcast sky throws.
+         *
+         *  A property of the LIGHT, applied where the light is received: the sun
+         *  in a scene is either a point source with a hard edge or a sky with
+         *  none, and a floor that always answers "hard" can only match one of
+         *  them. Above 0 the taps go from nine to sixteen, so leave it at 0 for
+         *  scenes that want the sharp edge and pay nothing. */
+        shadowSoftness?: number;
     }): void;
     /**
      * The scene's positional lights — an ADDITIVE layer over the sun, which stays
@@ -1862,6 +2025,12 @@ export declare class Engine {
     }[] | null): void;
     /** How many positional lights the scene is carrying. */
     getLightCount(): number;
+    /** Guarded, unlike most private writers here, because its callers are not:
+     *  setWorld/setSun are public and can be called before init() finishes
+     *  assigning `device` — a scene-settings effect firing on mount races the
+     *  engine's own async setup. The state write still lands immediately either
+     *  way; only the GPU upload defers, and setupLighting's own writeWorld/
+     *  writeSun calls during init pick up whatever was already set. */
     private updateLightBuffer;
     getStats(): EngineStats;
     runRenderLoop(callback?: () => void): void;
@@ -2001,7 +2170,100 @@ export declare class Engine {
     getModelTransform(name: string): ModelTransform | null;
     markVertexBufferDirty(modelNameOrModel?: string | Model): void;
     setSelectedMaterial(modelName: string | null, materialName: string | null): void;
+    /** Show the transform gizmo on the selected bone. On by default. */
+    setGizmoEnabled(on: boolean): void;
+    /** A pointer-driven preview of a pick, not a pick itself — see pickMaterial
+     *  for the click that actually selects one. Cheap: a field write, nothing
+     *  rebuilt, safe to call every frame the pointer is over the canvas. */
+    setHoveredMaterial(modelName: string | null, materialName: string | null): void;
     setSelectedBone(modelName: string | null, boneName: string | null): void;
+    /**
+     * Replace one named layer of overlay primitives. World space, drawn as given
+     * until it is replaced. An empty list removes the layer.
+     */
+    setOverlay(layer: string, primitives: OverlayPrimitive[]): void;
+    /** Drop one named layer, or every one. Live layers keep drawing. */
+    clearOverlay(layer?: string): void;
+    /**
+     * The bone whose marker is nearest a point on the canvas, or null.
+     *
+     * On the CPU, and exact. A few hundred bones with known world positions is a
+     * loop, not a render pass — and having the answer synchronously is what makes
+     * cycling through overlapping bones possible at all. Only VERTICES justify GPU
+     * picking, at tens of thousands.
+     *
+     * `x`/`y` are CSS pixels relative to the canvas, which is what a MouseEvent
+     * gives once getBoundingClientRect is subtracted.
+     *
+     * It projects boneMarkerPositions, the same points the overlay draws markers
+     * at, so the hit box cannot drift away from the circle you are aiming at.
+     */
+    pickBone(x: number, y: number, options?: {
+        radiusPx?: number;
+        modelName?: string;
+    }): {
+        modelName: string;
+        boneName: string;
+        boneIndex: number;
+    } | null;
+    /** Skinned positions for picking, grown on demand. One click's worth of work
+     *  reused across clicks — a model's vertex count does not change. */
+    private materialPickScratch;
+    /**
+     * The material under a point on the canvas, or null for a miss.
+     *
+     * On the CPU, like pickBone, and for the same reason: a click (or a hover) is
+     * rare and an answer you have synchronously is worth more than one that
+     * arrives a frame later. Tens of thousands of triangles is a loop that costs
+     * a few milliseconds ONCE, against a GPU id pass that costs an attachment and
+     * a readback every frame whether anyone is pointing at the model or not.
+     *
+     * Skinned on the CPU with getSkinMatrices — the same matrices the vertex
+     * shader uses — so the pick lands on the POSED mesh. Bind-pose geometry would
+     * be right on a T-posed model and wrong on every animated one, which is
+     * exactly when someone is clicking around a costume.
+     *
+     * Morph offsets are NOT applied: they move a face, never move it into another
+     * material, and reading them back per click would cost more than the pick.
+     *
+     * `x`/`y` are CSS pixels relative to the canvas, as pickBone takes them.
+     */
+    pickMaterial(x: number, y: number, options?: {
+        modelName?: string;
+    }): {
+        modelName: string;
+        materialName: string;
+        materialIndex: number;
+    } | null;
+    /** Draw an octahedron per bone of `modelName`, rebuilt each frame. Null off. */
+    setBoneOverlay(modelName: string | null, options?: BoneOverlayOptions): void;
+    /** Draw every rigidbody of `modelName` where the simulation has it, rebuilt
+     *  each frame. Null off. */
+    setRigidbodyOverlay(modelName: string | null, options?: RigidbodyOverlayOptions): void;
+    /** Draw a cross per joint of `modelName` plus dashed lines to the bodies it
+     *  holds together, rebuilt each frame. Null off. */
+    setJointOverlay(modelName: string | null, options?: JointOverlayOptions): void;
+    /**
+     * Draw `modelName`'s mesh as a wireframe — its vertices and its topology.
+     *
+     * Skinned on the GPU from the model's own vertex buffer and skin matrices, so
+     * it sits on the POSED mesh. The loader's CPU-side positions are bind pose: a
+     * wireframe built from those looks right on a T-posed model and slides off
+     * every animated one, which is exactly the state a user is in while looking at
+     * weights.
+     *
+     * The edge list is deduplicated and built once, on the first frame this is on.
+     *
+     * `material` narrows the wireframe to one material's faces. The mesh still
+     * writes depth in full, so the material reads as part of the body rather than
+     * as a shell floating in front of it — which is the point of scoping it: you
+     * are asking where this material's faces ARE, and an answer that ignores the
+     * torso in front of them is not one.
+     */
+    setVertexOverlay(modelName: string | null, options?: {
+        xray?: boolean;
+        material?: string | null;
+    }): void;
     /** A group's uniform buffer and its maps have the same lifetime — freeing one
      *  without the other is how a re-apply leaks GPU memory a frame at a time. */
     private destroyInstall;
@@ -2021,6 +2283,15 @@ export declare class Engine {
      */
     setIKEnabled(enabled: boolean): void;
     getIKEnabled(): boolean;
+    /**
+     * Run the solver, or stop it.
+     *
+     * Turning it OFF snaps every body back onto its bone. Merely halting the step
+     * leaves hair and skirts hanging wherever the simulation happened to be — a
+     * pose nothing in the document describes, which is the opposite of what "off"
+     * is asked for: you switch physics off to see what the RIG does, and a frozen
+     * mid-swing is still the solver's answer, just a stale one.
+     */
     setPhysicsEnabled(enabled: boolean): void;
     getPhysicsEnabled(): boolean;
     /**
@@ -2342,9 +2613,55 @@ export declare class Engine {
     private handleCanvasTouch;
     private performRaycast;
     private renderSelectionPasses;
+    /** The index run `material` owns, or the whole list when it is null. Materials
+     *  are consecutive runs in declaration order, so the offset is a prefix sum —
+     *  the same walk the draw list does. Returns null for a name the model does
+     *  not have, which is what a stale selection looks like after a reload. */
+    private materialIndexRange;
+    /** A cache key no material can collide with — a PMX name is never empty and
+     *  never contains a NUL. */
+    private static readonly SEAM_KEY;
+    /**
+     * @param material one material's own edges, or null for the whole mesh
+     * @param seams    every material's OUTLINE instead — the borders between them
+     */
+    private ensureEdgeBuffer;
+    private renderWireframe;
+    /** The bone overlay's options with `selected` filled in from setSelectedBone,
+     *  so clicking a bone highlights it without the host mirroring the state. An
+     *  explicit `selected` in the options still wins. */
+    private boneOverlayOptions;
+    private boneOptionsScratch;
+    private overlayActive;
+    private overlayModel;
+    /** The primitives a live layer would draw right now. Same list the pass uses,
+     *  so a host can show it as data, diff it, or hit-test it on the CPU. */
+    getOverlayPrimitives(layer: "bones" | "rigidbodies" | "joints"): OverlayPrimitive[];
+    private ensureOverlayTargets;
+    private ensureOverlayInstanceCapacity;
+    private renderOverlayPass;
     private renderGizmoPass;
     private rotateVec3ByQuat;
     private unproject;
+    /**
+     * Where a point on the canvas lands on a horizontal plane.
+     *
+     * `px,py` are canvas-relative pixels, top-left origin — what a pointer event
+     * gives you after subtracting the element's rect. Returns null when the ray
+     * cannot reach the plane: parallel to it, or pointing the other way, which is
+     * what a click on the sky above the horizon is.
+     *
+     * The one primitive a placement UI needs. Dragging a thing across the floor is
+     * otherwise three sliders in world units, which asks someone to guess numbers
+     * that have no visible relation to the picture they are looking at — and it
+     * throws away the property that makes pointing work at all: under perspective,
+     * moving something further away makes it smaller by exactly the right amount,
+     * so position and size stop being two controls to tune against each other.
+     */
+    groundPointAt(px: number, py: number, planeY?: number): Vec3 | null;
+    /** Hand the pointer to something else — a placement drag, a gizmo, a host's own
+     *  overlay — so the orbit does not also act on it. */
+    setCameraInputLocked(locked: boolean): void;
     private buildMouseRay;
     private hitTestGizmo;
     private distSegmentRay;