reze-engine 0.25.2 → 0.27.0

package/dist/shaders/passes/composite.js

@@ -17,7 +17,7 @@ override APPLY_GAMMA: bool = true;
 @group(0) @binding(0) var hdrTex: texture_2d<f32>;
 @group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)
 @group(0) @binding(2) var bloomSamp: sampler;
-@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 7>;
+@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 10>;
 // Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).
 // .g = accumulated canvas alpha (what hdr.a carried before the HDR format
 // became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then
@@ -40,6 +40,8 @@ override APPLY_GAMMA: bool = true;
 // viewU[3] = (camera right, tanHalfFov·aspect); viewU[4] = (camera up, tanHalfFov);
 // viewU[5] = (camera forward, _) — refreshed per frame while skybox/effect active.
 // viewU[6] = (time seconds, effect on/off, canvas width, canvas height).
+// viewU[7] = (grade offset.rgb, contrast);  viewU[8] = (grade power.rgb, saturation);
+// viewU[9] = (grade slope.rgb, grade on/off) — see grade() below.
 // invGamma = 1/gamma precomputed on CPU — avoids a per-pixel divide.
 @group(0) @binding(6) var bgEquirect: texture_2d<f32>;
 
@@ -59,6 +61,24 @@ fn filmic(x: f32) -> f32 {
 
 /** Canvas size in pixels — for user background effects (aspect correction). */
 fn bgResolution() -> vec2f { return viewU[6].zw; }
+
+/** Color grading, applied to the tonemapped SCENE (not the background — see the
+ *  call site). The core is ASC CDL, the film-industry interchange standard:
+ *
+ *      out = (in · slope + offset) ^ power        then saturation  (SOP → SAT)
+ *
+ *  Using the real standard rather than invented controls means a look authored
+ *  here maps onto any grading tool. slope/offset/power are derived on the CPU
+ *  from the UI's shadow/midtone/highlight colors (see setColorGrading), so the
+ *  per-pixel cost is one mul-add, one pow, one lerp. */
+fn grade(c: vec3f) -> vec3f {
+  var x = pow(max(c * viewU[9].xyz + viewU[7].xyz, vec3f(0.0)), viewU[8].xyz);
+  // Contrast pivots on 0.5 — display-referred midpoint, since we grade post-Filmic.
+  x = (x - vec3f(0.5)) * viewU[7].w + vec3f(0.5);
+  // Rec.709 luma, matching the ASC SAT node.
+  let luma = dot(x, vec3f(0.2126, 0.7152, 0.0722));
+  return max(mix(vec3f(luma), x, viewU[8].w), vec3f(0.0));
+}
 `;
 const COMPOSITE_BODY = /* wgsl */ `
 @vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
@@ -84,6 +104,13 @@ const COMPOSITE_BODY = /* wgsl */ `
   let exposed = combined * exp2(viewU[0].x);
   let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));
   var disp = max(tm, vec3f(0.0));
+  // Grade the SCENE only, before the display gamma. Deliberately not applied to
+  // the background: it keeps a picked background color exactly as picked, and —
+  // load-bearing — leaves green-screen mode's key color unshifted so chroma
+  // keying still works. Skipped entirely when the grade is neutral.
+  if (viewU[9].w > 0.5) {
+    disp = grade(disp);
+  }
   if (APPLY_GAMMA) {
     disp = pow(disp, vec3f(viewU[0].y));
   }

package/dist/vmd-loader.d.ts

@@ -27,6 +27,16 @@ export interface CameraKeyframe {
     fov: number;
     interpolation: Uint8Array;
 }
+/** A VMD "IK/display" record: one moment at which chains are switched. */
+export interface IkFrame {
+    frame: number;
+    /** Model visibility rides in the same record. Parsed, unused by playback. */
+    visible: boolean;
+    states: {
+        boneName: string;
+        enabled: boolean;
+    }[];
+}
 export declare class VMDLoader {
     private view;
     private offset;
@@ -39,12 +49,24 @@ export declare class VMDLoader {
     static loadCamera(url: string): Promise<CameraKeyframe[]>;
     static loadCameraFromBuffer(buffer: ArrayBuffer): CameraKeyframe[];
     private parseCamera;
+    static loadIkFromBuffer(buffer: ArrayBuffer): IkFrame[];
+    /**
+     * The IK/display block, at the very end of the file.
+     *
+     * MMD writes it after camera, light and self-shadow, and a motion-only VMD
+     * often stops before any of them — so every block is bounds-checked and a
+     * short file simply reports no IK data rather than throwing. Record sizes:
+     * bone 111 B, morph 23 B, camera 61 B, light 28 B, self-shadow 9 B.
+     */
+    private parseIk;
     private parse;
     private readBoneFrame;
     private readMorphFrame;
     private getUint8;
     private getUint32;
     private getFloat32;
+    /** A fixed-width, NUL-padded Shift-JIS name — the form every VMD name takes. */
+    private getShiftJisName;
     private getString;
     private skip;
 }

package/dist/vmd-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vmd-loader.d.ts","sourceRoot":"","sources":["../src/vmd-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEnC,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,IAAI,CAAA;IACd,WAAW,EAAE,IAAI,CAAA;IACjB,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;qFAEqF;AACrF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,IAAI,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAa;IAE5B,OAAO;WAWM,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKtD,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE;IAKzD;mGAC+F;WAClF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK/D,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,EAAE;IAOlE,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,KAAK;IAgGb,OAAO,CAAC,aAAa;IAuDrB,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,IAAI;CAMb"}
+{"version":3,"file":"vmd-loader.d.ts","sourceRoot":"","sources":["../src/vmd-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEnC,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,IAAI,CAAA;IACd,WAAW,EAAE,IAAI,CAAA;IACjB,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;qFAEqF;AACrF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,IAAI,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;CACjD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAa;IAE5B,OAAO;WAWM,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKtD,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE;IAKzD;mGAC+F;WAClF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK/D,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,EAAE;IAOlE,OAAO,CAAC,WAAW;IA4BnB,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,EAAE;IAIvD;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IA8Bf,OAAO,CAAC,KAAK;IAgGb,OAAO,CAAC,aAAa;IAuDrB,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,UAAU;IASlB,gFAAgF;IAChF,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,IAAI;CAMb"}

package/dist/vmd-loader.js

@@ -61,6 +61,49 @@ export class VMDLoader {
         frames.sort((a, b) => a.frame - b.frame);
         return frames;
     }
+    static loadIkFromBuffer(buffer) {
+        return new VMDLoader(buffer).parseIk();
+    }
+    /**
+     * The IK/display block, at the very end of the file.
+     *
+     * MMD writes it after camera, light and self-shadow, and a motion-only VMD
+     * often stops before any of them — so every block is bounds-checked and a
+     * short file simply reports no IK data rather than throwing. Record sizes:
+     * bone 111 B, morph 23 B, camera 61 B, light 28 B, self-shadow 9 B.
+     */
+    parseIk() {
+        this.offset = 0;
+        const header = this.getString(30);
+        if (!header.startsWith("Vocaloid Motion Data"))
+            throw new Error("Invalid VMD file header");
+        this.skip(20);
+        const end = this.view.buffer.byteLength;
+        const seek = (size) => {
+            if (this.offset + 4 > end)
+                return false;
+            this.skip(this.getUint32() * size);
+            return this.offset <= end;
+        };
+        if (!seek(111) || !seek(23) || !seek(61) || !seek(28) || !seek(9))
+            return [];
+        if (this.offset + 4 > end)
+            return [];
+        const count = this.getUint32();
+        const frames = [];
+        for (let i = 0; i < count && this.offset + 9 <= end; i++) {
+            const frame = this.getUint32();
+            const visible = this.getUint8() !== 0;
+            const ikCount = this.getUint32();
+            const states = [];
+            for (let j = 0; j < ikCount && this.offset + 21 <= end; j++) {
+                states.push({ boneName: this.getShiftJisName(20), enabled: this.getUint8() !== 0 });
+            }
+            frames.push({ frame, visible, states });
+        }
+        frames.sort((a, b) => a.frame - b.frame);
+        return frames;
+    }
     parse() {
         // Read header (30 bytes)
         const header = this.getString(30);
@@ -244,6 +287,21 @@ export class VMDLoader {
         this.offset += 4;
         return v;
     }
+    /** A fixed-width, NUL-padded Shift-JIS name — the form every VMD name takes. */
+    getShiftJisName(len) {
+        const bytes = new Uint8Array(this.view.buffer, this.offset, len);
+        this.offset += len;
+        let end = bytes.indexOf(0);
+        if (end < 0)
+            end = len;
+        const slice = bytes.slice(0, end);
+        try {
+            return this.decoder.decode(slice);
+        }
+        catch {
+            return String.fromCharCode(...slice);
+        }
+    }
     getString(len) {
         const bytes = new Uint8Array(this.view.buffer, this.offset, len);
         this.offset += len;

package/dist/vmd-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vmd-writer.d.ts","sourceRoot":"","sources":["../src/vmd-writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAqB,MAAM,aAAa,CAAA;AA+C9D,qBAAa,SAAS;IACpB,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,WAAW;CAgFxC"}
+{"version":3,"file":"vmd-writer.d.ts","sourceRoot":"","sources":["../src/vmd-writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAqB,MAAM,aAAa,CAAA;AAiD9D,qBAAa,SAAS;IACpB,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,WAAW;CAwHxC"}

package/dist/vmd-writer.js

@@ -5,6 +5,8 @@ const BONE_NAME_SIZE = 15;
 const MORPH_NAME_SIZE = 15;
 const BONE_FRAME_SIZE = BONE_NAME_SIZE + 4 + 12 + 16 + 64; // 111 bytes
 const MORPH_FRAME_SIZE = MORPH_NAME_SIZE + 4 + 4; // 23 bytes
+/** IK bone names get 20 bytes in the IK block, not the 15 bones get elsewhere. */
+const IK_NAME_SIZE = 20;
 // Build a Unicode-to-Shift-JIS lookup by inverting the TextDecoder mapping.
 let shiftJISTable = null;
 function getShiftJISTable() {
@@ -54,10 +56,31 @@ export class VMDWriter {
         for (const frames of clip.morphTracks.values()) {
             totalMorphFrames += frames.length;
         }
+        // IK state is stored per MOMENT, not per bone: one record lists every chain
+        // and its state at that frame. So the tracks are transposed back into the
+        // frames they were flattened from.
+        const ikByFrame = new Map();
+        for (const [boneName, keys] of clip.ikTracks ?? []) {
+            for (const key of keys) {
+                const at = ikByFrame.get(key.frame);
+                if (at)
+                    at.push({ boneName, enabled: key.enabled });
+                else
+                    ikByFrame.set(key.frame, [{ boneName, enabled: key.enabled }]);
+            }
+        }
+        const ikFrames = [...ikByFrame.entries()].sort((a, b) => a[0] - b[0]);
+        let ikSize = 0;
+        for (const [, states] of ikFrames)
+            ikSize += 4 + 1 + 4 + states.length * (IK_NAME_SIZE + 1);
         const size = HEADER_SIZE +
             MODEL_NAME_SIZE +
             4 + totalBoneFrames * BONE_FRAME_SIZE +
-            4 + totalMorphFrames * MORPH_FRAME_SIZE;
+            4 + totalMorphFrames * MORPH_FRAME_SIZE +
+            // Camera, light and self-shadow counts, then the IK block. Written only
+            // when there is IK state to carry: a plain motion stays byte-identical to
+            // what this writer produced before.
+            (ikFrames.length > 0 ? 4 * 4 + ikSize : 0);
         const buffer = new ArrayBuffer(size);
         const view = new DataView(buffer);
         let offset = 0;
@@ -114,6 +137,27 @@ export class VMDWriter {
                 offset += 4;
             }
         }
+        if (ikFrames.length > 0) {
+            // Empty camera, light and self-shadow blocks — a reader walking the file
+            // in order has to pass through them to reach the IK block.
+            for (let i = 0; i < 3; i++, offset += 4)
+                view.setUint32(offset, 0, true);
+            view.setUint32(offset, ikFrames.length, true);
+            offset += 4;
+            for (const [frame, states] of ikFrames) {
+                view.setUint32(offset, frame, true);
+                offset += 4;
+                view.setUint8(offset, 1); // model visible
+                offset += 1;
+                view.setUint32(offset, states.length, true);
+                offset += 4;
+                for (const state of states) {
+                    offset = writeFixedShiftJIS(buffer, offset, state.boneName, IK_NAME_SIZE);
+                    view.setUint8(offset, state.enabled ? 1 : 0);
+                    offset += 1;
+                }
+            }
+        }
         return buffer;
     }
 }

package/package.json

@@ -1,44 +1,44 @@
 {
-    "name": "reze-engine",
-    "version": "0.25.2",
-    "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "type": "module",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/AmyangXYZ/reze-engine"
-    },
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        }
-    },
-    "files": [
-        "dist",
-        "src"
-    ],
-    "scripts": {
-        "build": "tsc",
-        "dev": "tsc --watch",
-        "test": "node --import ./tests/register.mjs --test tests/*.test.mjs",
-        "prepublishOnly": "node -e \"require('fs').copyFileSync('../README.md','README.md')\" && npm run build"
-    },
-    "keywords": [
-        "webgpu",
-        "3d",
-        "engine",
-        "pmx",
-        "physics"
-    ],
-    "author": "",
-    "license": "MIT",
-    "dependencies": {
-        "@webgpu/types": "^0.1.66"
-    },
-    "devDependencies": {
-        "@types/node": "^20",
-        "typescript": "^5"
+  "name": "reze-engine",
+  "version": "0.27.0",
+  "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AmyangXYZ/reze-engine"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
-}
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --import ./tests/register.mjs --test tests/*.test.mjs",
+    "prepublishOnly": "node -e \"require('fs').copyFileSync('../README.md','README.md')\" && npm run build"
+  },
+  "keywords": [
+    "webgpu",
+    "3d",
+    "engine",
+    "pmx",
+    "physics"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@webgpu/types": "^0.1.66"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}

package/src/animation.ts

@@ -26,9 +26,19 @@ export interface MorphKeyframe {
   weight: number
 }
 
+/** One IK chain switching on or off, keyed by its IK bone (左足ＩＫ and friends).
+ *  VMD stores these as steps — a state holds until the next keyframe changes it. */
+export interface IkKeyframe {
+  frame: number
+  enabled: boolean
+}
+
 export interface AnimationClip {
   boneTracks: Map<string, BoneKeyframe[]>
   morphTracks: Map<string, MorphKeyframe[]>
+  /** Per-chain IK state over time. Absent means "leave IK as the host set it" —
+   *  which is what every clip built before this existed will do. */
+  ikTracks?: Map<string, IkKeyframe[]>
   frameCount: number // last keyframe frame index
 }
 
@@ -70,9 +80,13 @@ export class AnimationState {
   private onEnd: ((animationName: string) => void) | null = null
 
   loadAnimation(name: string, clip: AnimationClip): void {
+    // Copied field by field rather than stored by reference, so the caller's
+    // object cannot mutate under playback. Every field has to be listed — an
+    // omission here is silent, and drops that part of the clip on the floor.
     this.animations.set(name, {
       boneTracks: clip.boneTracks,
       morphTracks: clip.morphTracks,
+      ikTracks: clip.ikTracks,
       frameCount: clip.frameCount,
     })
   }

package/src/engine.ts

@@ -283,6 +283,34 @@ export const DEFAULT_VIEW_TRANSFORM: ViewTransformOptions = {
   look: "medium_high_contrast",
 }
 
+/** Color grading applied to the tonemapped scene (ASC CDL — see grade() in
+ *  composite.ts). The three tonal controls are expressed as COLORS with
+ *  mid-gray (0.5, 0.5, 0.5) as neutral: the direction from neutral is the hue
+ *  you push toward, and the distance from neutral is the amount — so no
+ *  separate strength slider is needed. Display-space sRGB, since grading runs
+ *  after the view transform. */
+export type ColorGradingOptions = {
+  /** Lifts/tints the dark end (CDL offset). */
+  shadows: Vec3
+  /** Bends the midtones (CDL power) — brighter above neutral, darker below. */
+  midtones: Vec3
+  /** Scales/tints the bright end (CDL slope). */
+  highlights: Vec3
+  /** Contrast about the 0.5 display pivot. 1 = neutral. */
+  contrast: number
+  /** 1 = neutral, 0 = grayscale, >1 = punchier. */
+  saturation: number
+}
+
+const NEUTRAL_GRADE_CHANNEL = 0.5
+export const DEFAULT_COLOR_GRADING: ColorGradingOptions = {
+  shadows: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+  midtones: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+  highlights: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+  contrast: 1,
+  saturation: 1,
+}
+
 export type GizmoDragKind = "rotate" | "translate"
 
 export interface GizmoDragEvent {
@@ -651,7 +679,7 @@ export class Engine {
   private compositeBindGroup!: GPUBindGroup
   private compositeUniformBuffer!: GPUBuffer
   // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-  private readonly compositeUniformData = new Float32Array(28)
+  private readonly compositeUniformData = new Float32Array(40)
   /** Composite background (display-space sRGB 0–1) — null = transparent canvas. */
   private backgroundColor: Vec3 | null = null
   // 360 backdrop (equirectangular skybox, sampled by view ray in composite).
@@ -861,6 +889,42 @@ export class Engine {
     return { exposure: v.exposure, gamma: v.gamma, look: v.look }
   }
 
+  private colorGrading: ColorGradingOptions = {
+    shadows: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+    midtones: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+    highlights: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+    contrast: DEFAULT_COLOR_GRADING.contrast,
+    saturation: DEFAULT_COLOR_GRADING.saturation,
+  }
+
+  /**
+   * Color-grade the tonemapped scene (ASC CDL slope/offset/power + saturation).
+   * The background layer is deliberately left ungraded — see the call site in
+   * composite.ts. Uniforms-only: no pipeline rebuild, safe to call per frame
+   * (e.g. from a slider drag).
+   */
+  setColorGrading(patch: Partial<ColorGradingOptions>): void {
+    const g = this.colorGrading
+    if (patch.shadows) g.shadows = new Vec3(patch.shadows.x, patch.shadows.y, patch.shadows.z)
+    if (patch.midtones) g.midtones = new Vec3(patch.midtones.x, patch.midtones.y, patch.midtones.z)
+    if (patch.highlights) g.highlights = new Vec3(patch.highlights.x, patch.highlights.y, patch.highlights.z)
+    if (patch.contrast !== undefined) g.contrast = patch.contrast
+    if (patch.saturation !== undefined) g.saturation = patch.saturation
+    if (this.device && this.compositeUniformBuffer) this.writeCompositeViewUniforms()
+  }
+
+  /** Current grade (for serialization into a scene descriptor). */
+  getColorGrading(): ColorGradingOptions {
+    const g = this.colorGrading
+    return {
+      shadows: new Vec3(g.shadows.x, g.shadows.y, g.shadows.z),
+      midtones: new Vec3(g.midtones.x, g.midtones.y, g.midtones.z),
+      highlights: new Vec3(g.highlights.x, g.highlights.y, g.highlights.z),
+      contrast: g.contrast,
+      saturation: g.saturation,
+    }
+  }
+
   setViewTransformOptions(patch: Partial<ViewTransformOptions>): void {
     const v = this.viewTransform
     if (patch.exposure !== undefined) v.exposure = patch.exposure
@@ -901,6 +965,32 @@ export class Engine {
     u[25] = this.backgroundEffect ? 1 : 0
     u[26] = this.canvas.width
     u[27] = this.canvas.height
+    // ── Grade (viewU[7..9]) ── The UI's three tonal COLORS map to ASC CDL here,
+    // on the CPU, so the shader only ever sees slope/offset/power. Mid-gray is
+    // neutral in all three; the signed distance from it is the amount.
+    const g = this.colorGrading
+    const off = (c: number) => (c - NEUTRAL_GRADE_CHANNEL) * 0.5 // ±0.25 lift
+    // power < 1 brightens, so midtones ABOVE neutral must lower the exponent.
+    const pow_ = (c: number) => Math.max(0.05, 1 - (c - NEUTRAL_GRADE_CHANNEL) * 1.5)
+    const slope = (c: number) => Math.max(0, 1 + (c - NEUTRAL_GRADE_CHANNEL) * 1.5)
+    u[28] = off(g.shadows.x)
+    u[29] = off(g.shadows.y)
+    u[30] = off(g.shadows.z)
+    u[31] = g.contrast
+    u[32] = pow_(g.midtones.x)
+    u[33] = pow_(g.midtones.y)
+    u[34] = pow_(g.midtones.z)
+    u[35] = g.saturation
+    u[36] = slope(g.highlights.x)
+    u[37] = slope(g.highlights.y)
+    u[38] = slope(g.highlights.z)
+    // Neutral grade → flag off, so the default pipeline pays nothing per pixel.
+    const neutral =
+      u[28] === 0 && u[29] === 0 && u[30] === 0 &&
+      u[32] === 1 && u[33] === 1 && u[34] === 1 &&
+      u[36] === 1 && u[37] === 1 && u[38] === 1 &&
+      g.contrast === 1 && g.saturation === 1
+    u[39] = neutral ? 0 : 1
     this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u)
   }
 
@@ -2005,10 +2095,11 @@ export class Engine {
     // mirroring EEVEE where bloom color/intensity are combine-stage params, not prefilter).
     this.compositeUniformBuffer = this.device.createBuffer({
       label: "composite view uniforms",
-      // 7 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
+      // 10 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
       // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray ·
-      // (time, _, canvas width, canvas height) for user background effects.
-      size: 112,
+      // (time, _, canvas width, canvas height) for user background effects ·
+      // three grade vectors (CDL offset+contrast, power+saturation, slope+flag).
+      size: 160,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
     this.bgParamsDummyBuffer = this.device.createBuffer({
@@ -3080,15 +3171,21 @@ export class Engine {
     return inst ? !inst.hiddenMaterials.has(materialName) : false
   }
 
-  setIKEnabled(enabled: boolean): void {
-    this.ikEnabled = enabled
-  }
-
   // Toggle the GPU vertex-morph path. Only affects models loaded afterwards.
   setGpuMorphsEnabled(enabled: boolean): void {
     this.useGpuMorphs = enabled
   }
 
+  /**
+   * Engine-wide IK switch. Off suppresses every chain regardless of what any
+   * motion says — for hosts that pose the skeleton themselves and want their
+   * own rotations left alone. On (the default) hands the decision to the clip,
+   * which carries per-chain state from the VMD it came from.
+   */
+  setIKEnabled(enabled: boolean): void {
+    this.ikEnabled = enabled
+  }
+
   getIKEnabled(): boolean {
     return this.ikEnabled
   }

package/src/index.ts

@@ -2,6 +2,8 @@ export {
   Engine,
   DEFAULT_BLOOM_OPTIONS,
   DEFAULT_VIEW_TRANSFORM,
+  DEFAULT_COLOR_GRADING,
+  type ColorGradingOptions,
   type EngineStats,
   type EngineOptions,
   type BloomOptions,
@@ -57,11 +59,12 @@ export type {
   AnimationPlayOptions,
   AnimationProgress,
   BoneKeyframe,
+  IkKeyframe,
   MorphKeyframe,
   BoneInterpolation,
   ControlPoint,
 } from "./animation"
 export { FPS } from "./animation"
-export { VMDLoader, type CameraKeyframe } from "./vmd-loader"
+export { VMDLoader, type CameraKeyframe, type IkFrame } from "./vmd-loader"
 export { CameraAnimation, type CameraPose } from "./camera-animation"
 export { RezePhysics } from "./physics"

package/src/model.ts

@@ -12,6 +12,7 @@ import {
   AnimationState,
   BoneInterpolation,
   BoneKeyframe,
+  IkKeyframe,
   MorphKeyframe,
   interpolateControlPoints,
   rawInterpolationToBoneInterpolation,
@@ -1222,6 +1223,21 @@ export class Model {
     return loadBuffer().then((buf) => {
       const vmdKeyFrames = VMDLoader.loadFromBuffer(buf)
       const clip = this.buildClipFromVmdKeyFrames(vmdKeyFrames)
+      // The IK block lives past every other section, so it is read separately
+      // rather than threaded through the keyframe grouping.
+      const ikFrames = VMDLoader.loadIkFromBuffer(buf)
+      if (ikFrames.length > 0) {
+        const ikTracks = new Map<string, IkKeyframe[]>()
+        for (const record of ikFrames) {
+          for (const state of record.states) {
+            const track = ikTracks.get(state.boneName)
+            if (track) track.push({ frame: record.frame, enabled: state.enabled })
+            else ikTracks.set(state.boneName, [{ frame: record.frame, enabled: state.enabled }])
+          }
+        }
+        for (const track of ikTracks.values()) track.sort((a, b) => a.frame - b.frame)
+        clip.ikTracks = ikTracks
+      }
       this.animationState.loadAnimation(name, clip)
     })
   }
@@ -1359,8 +1375,35 @@ export class Model {
     return idx
   }
 
+  /**
+   * IK bones whose chains are switched OFF at the current frame.
+   *
+   * VMD carries this per chain and over time — a motion legitimately disables
+   * foot IK for a lift and restores it on landing — so it belongs to the clip,
+   * not to a global switch on the engine.
+   */
+  private ikDisabled = new Set<number>()
+
+  /** Step the IK state to `frame`. VMD IK keys are steps: a state holds until
+   *  the next one changes it, so this is a lookup, not an interpolation. */
+  private applyIkFromClip(clip: AnimationClip, frame: number): void {
+    if (!clip.ikTracks || clip.ikTracks.size === 0) {
+      if (this.ikDisabled.size > 0) this.ikDisabled.clear()
+      return
+    }
+    this.ikDisabled.clear()
+    for (const [boneName, keys] of clip.ikTracks) {
+      const index = this.runtimeSkeleton.nameIndex[boneName]
+      if (index === undefined || index < 0 || keys.length === 0) continue
+      let state = keys[0].frame <= frame ? keys[0].enabled : true
+      for (let i = 1; i < keys.length && keys[i].frame <= frame; i++) state = keys[i].enabled
+      if (!state) this.ikDisabled.add(index)
+    }
+  }
+
   private applyPoseFromClip(clip: AnimationClip | null, frame: number): void {
     if (!clip) return
+    this.applyIkFromClip(clip, frame)
     if (clip !== this.lastAppliedClip) {
       this.boneTrackIndices.clear()
       this.morphTrackIndices.clear()
@@ -1447,8 +1490,12 @@ export class Model {
     }
   }
 
-  // Returns true when morphs changed (vertex buffer may need upload). ikEnabled is driven by engine (same for all models).
-  update(deltaTime: number, ikEnabled: boolean): boolean {
+  // Returns true when morphs changed (vertex buffer may need upload). `ikEnabled`
+  // is the host's runtime switch (engine-wide); the clip decides which chains
+  // within that. A host driving bones directly — motion capture writing FK
+  // rotations every frame with no clip playing — turns it off wholesale, because
+  // there is no motion present to carry the per-chain answer.
+  update(deltaTime: number, ikEnabled = true): boolean {
     // Update tween time (in milliseconds)
     this.tweenTimeMs += deltaTime * 1000
 
@@ -1472,7 +1519,8 @@ export class Model {
     // Compute world matrices (needed for IK solving to read bone positions)
     this.computeWorldMatrices()
 
-    // Solve IK chains (modifies localRotations with final IK rotations)
+    // Solve IK chains (modifies localRotations with final IK rotations). Chains
+    // the clip switched off are skipped inside.
     if (ikEnabled) {
       this.solveIKChains()
       // Recompute world matrices with final IK rotations applied to localRotations
@@ -1492,6 +1540,9 @@ export class Model {
     // Solve each IK solver sequentially, ensuring consistent state between solvers
     let firstSolver = true
     for (const solver of ikSolvers) {
+      // Switched off by the motion for this frame — leave the chain on whatever
+      // the FK track put there.
+      if (this.ikDisabled.has(solver.ikBoneIndex)) continue
       // Each solver must see the effects of previous solvers on localRotations, so
       // recompute world matrices between solvers. The first solver is skipped: the
       // caller (update) already computed them and nothing has changed localRotations yet.