reze-engine 0.41.1 → 0.41.3

package/dist/psd-loader.js

@@ -0,0 +1,192 @@
+// PSD → RGBA8, from the merged composite.
+//
+// MMD texture packs are often shipped as the artist's working files, so a
+// material's texture path points at a .psd that no browser will decode. The
+// layers are none of our business — Photoshop writes a flattened composite of
+// the whole document at the end of the file, which is exactly the image the
+// artist saw, so that is what this reads.
+//
+// (A file saved with "Maximize Compatibility" off has no useful composite. There
+// is nothing to be done about that here beyond failing clearly: reconstructing it
+// would mean compositing every layer, blend mode and clipping group — a Photoshop,
+// not a texture loader.)
+const MAGIC = 0x38425053; // "8BPS", big-endian — PSD is big-endian throughout
+var ColorMode;
+(function (ColorMode) {
+    ColorMode[ColorMode["Bitmap"] = 0] = "Bitmap";
+    ColorMode[ColorMode["Grayscale"] = 1] = "Grayscale";
+    ColorMode[ColorMode["Indexed"] = 2] = "Indexed";
+    ColorMode[ColorMode["RGB"] = 3] = "RGB";
+    ColorMode[ColorMode["CMYK"] = 4] = "CMYK";
+    ColorMode[ColorMode["Multichannel"] = 7] = "Multichannel";
+    ColorMode[ColorMode["Duotone"] = 8] = "Duotone";
+    ColorMode[ColorMode["Lab"] = 9] = "Lab";
+})(ColorMode || (ColorMode = {}));
+const MODE_NAMES = {
+    [ColorMode.Bitmap]: "bitmap",
+    [ColorMode.CMYK]: "CMYK",
+    [ColorMode.Multichannel]: "multichannel",
+    [ColorMode.Lab]: "Lab",
+};
+/** True when these bytes are a PSD/PSB, by magic rather than by file extension. */
+export function isPsd(buffer) {
+    return buffer.byteLength >= 26 && new DataView(buffer).getUint32(0, false) === MAGIC;
+}
+/**
+ * PackBits, one row at a time.
+ *
+ * `end` bounds the row rather than the buffer: the row-length table says how many
+ * compressed bytes this row occupies, and trusting the control bytes past that
+ * would let one malformed row eat the next one's data.
+ */
+function unpackBits(src, start, end, dst, at, limit) {
+    let i = start;
+    let o = at;
+    while (i < end && o < limit) {
+        const n = (src[i++] << 24) >> 24; // to signed
+        if (n >= 0) {
+            const count = Math.min(n + 1, limit - o, end - i);
+            for (let k = 0; k < count; k++)
+                dst[o++] = src[i++];
+        }
+        else if (n !== -128) {
+            // -128 is a no-op by the spec, not a run of 129.
+            const count = Math.min(1 - n, limit - o);
+            const b = src[i++];
+            for (let k = 0; k < count; k++)
+                dst[o++] = b;
+        }
+    }
+    return o;
+}
+/**
+ * Decode a PSD's composite to RGBA8.
+ *
+ * RGB, grayscale, indexed and duotone at 8 or 16 bits per channel, raw or RLE —
+ * which is every texture that has actually turned up. CMYK and Lab throw: they
+ * need a colour conversion that would be guesswork without a profile, and a
+ * silently wrong-coloured texture is worse than a missing one.
+ */
+export function decodePsd(buffer) {
+    const v = new DataView(buffer);
+    if (buffer.byteLength < 26 || v.getUint32(0, false) !== MAGIC)
+        throw new Error("not a PSD");
+    const version = v.getUint16(4, false); // 1 = PSD, 2 = PSB
+    if (version !== 1 && version !== 2)
+        throw new Error(`PSD unsupported version ${version}`);
+    const channels = v.getUint16(12, false);
+    const height = v.getUint32(14, false);
+    const width = v.getUint32(18, false);
+    const depth = v.getUint16(22, false);
+    const mode = v.getUint16(24, false);
+    if (width <= 0 || height <= 0)
+        throw new Error(`PSD bad dimensions ${width}x${height}`);
+    if (depth !== 8 && depth !== 16)
+        throw new Error(`PSD unsupported bit depth ${depth}`);
+    if (mode in MODE_NAMES)
+        throw new Error(`PSD unsupported colour mode: ${MODE_NAMES[mode]}`);
+    // Three variable-length sections stand between the header and the pixels. Only
+    // the indexed palette is worth reading; the rest is skipped by its length.
+    let p = 26;
+    const colorDataLen = v.getUint32(p, false);
+    const colorData = p + 4;
+    p = colorData + colorDataLen;
+    p += 4 + v.getUint32(p, false); // image resources
+    // PSB states this length in 8 bytes. Only the low word can matter — the high
+    // one would mean a layer section larger than 4GB.
+    if (version === 2) {
+        p += 8 + v.getUint32(p + 4, false);
+    }
+    else {
+        p += 4 + v.getUint32(p, false);
+    }
+    if (p + 2 > buffer.byteLength)
+        throw new Error("PSD truncated before the composite");
+    const compression = v.getUint16(p, false);
+    p += 2;
+    // Only the channels that carry colour, plus one alpha. A PSD can hold spot and
+    // mask channels past those; they are stored after, so ignoring them is a matter
+    // of not reading that far.
+    const colourChannels = mode === ColorMode.RGB ? 3 : 1;
+    const hasAlpha = channels > colourChannels;
+    const used = colourChannels + (hasAlpha ? 1 : 0);
+    if (channels < colourChannels)
+        throw new Error(`PSD has ${channels} channel(s), expected ${colourChannels}`);
+    const bytesPerSample = depth === 16 ? 2 : 1;
+    const planeSamples = width * height;
+    const planeBytes = planeSamples * bytesPerSample;
+    const planes = new Uint8Array(used * planeBytes);
+    if (compression === 0) {
+        const need = used * planeBytes;
+        if (p + need > buffer.byteLength)
+            throw new Error("PSD truncated composite");
+        planes.set(new Uint8Array(buffer, p, need));
+    }
+    else if (compression === 1) {
+        // A table of per-row compressed lengths for EVERY channel comes first,
+        // including the channels being skipped — so the table is read in full even
+        // though only the first `used` channels' rows are decoded.
+        const countBytes = version === 2 ? 4 : 2;
+        const tableBytes = channels * height * countBytes;
+        if (p + tableBytes > buffer.byteLength)
+            throw new Error("PSD truncated row table");
+        const rowLengths = new Uint32Array(channels * height);
+        for (let i = 0; i < rowLengths.length; i++) {
+            rowLengths[i] = countBytes === 2 ? v.getUint16(p + i * 2, false) : v.getUint32(p + i * 4, false);
+        }
+        const src = new Uint8Array(buffer);
+        let at = p + tableBytes;
+        for (let c = 0; c < channels; c++) {
+            for (let y = 0; y < height; y++) {
+                const len = rowLengths[c * height + y];
+                if (at + len > buffer.byteLength)
+                    throw new Error("PSD truncated composite");
+                if (c < used) {
+                    const rowStart = c * planeBytes + y * width * bytesPerSample;
+                    unpackBits(src, at, at + len, planes, rowStart, rowStart + width * bytesPerSample);
+                }
+                at += len;
+            }
+        }
+    }
+    else {
+        // 2 and 3 are the Zip codes. They appear on layer data, effectively never on
+        // the composite, and inflating would mean shipping a decompressor.
+        throw new Error(`PSD unsupported compression ${compression}`);
+    }
+    // 16-bit samples are big-endian; the high byte is the 8-bit value.
+    const sample = (plane, i) => depth === 16 ? planes[plane * planeBytes + i * 2] : planes[plane * planeBytes + i];
+    const rgba = new Uint8Array(planeSamples * 4);
+    if (mode === ColorMode.Indexed) {
+        // The palette is the colour mode data: 256 reds, then 256 greens, then blues.
+        if (colorDataLen < 768)
+            throw new Error("PSD indexed image has no palette");
+        const pal = new Uint8Array(buffer, colorData, 768);
+        for (let i = 0; i < planeSamples; i++) {
+            const idx = sample(0, i);
+            rgba[i * 4] = pal[idx];
+            rgba[i * 4 + 1] = pal[256 + idx];
+            rgba[i * 4 + 2] = pal[512 + idx];
+            rgba[i * 4 + 3] = hasAlpha ? sample(1, i) : 255;
+        }
+        return { rgba, width, height };
+    }
+    for (let i = 0; i < planeSamples; i++) {
+        if (mode === ColorMode.RGB) {
+            rgba[i * 4] = sample(0, i);
+            rgba[i * 4 + 1] = sample(1, i);
+            rgba[i * 4 + 2] = sample(2, i);
+        }
+        else {
+            // Grayscale and duotone: one plane across all three. Duotone's ink colours
+            // live in the colour mode data, and the spec's own advice is to treat the
+            // data as grayscale — which is what every other reader does.
+            const g = sample(0, i);
+            rgba[i * 4] = g;
+            rgba[i * 4 + 1] = g;
+            rgba[i * 4 + 2] = g;
+        }
+        rgba[i * 4 + 3] = hasAlpha ? sample(colourChannels, i) : 255;
+    }
+    return { rgba, width, height };
+}

package/dist/shaders/passes/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;+BAwB+B;AAC/B,MAAM,MAAM,qBAAqB,GAAG;IAClC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;CACvB,CAAA;AA0WD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAclF;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;+BAwB+B;AAC/B,MAAM,MAAM,qBAAqB,GAAG;IAClC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;CACvB,CAAA;AA4XD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAclF;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}

package/dist/shaders/passes/composite.js

@@ -23,7 +23,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>, 11>;
+@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 15>;
 // 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
@@ -171,6 +171,24 @@ fn bgResolution() -> vec2f { return viewU[6].zw; }
 /** The camera's world position. */
 fn bgCameraPos() -> vec3f { return viewU[10].xyz; }
 
+/** How many characters are in the scene, up to four. */
+fn bgSubjectCount() -> i32 { return i32(viewU[10].w); }
+
+/**
+ * Where a character is standing, in world space.
+ *
+ * An effect that wants to RESPOND to the cast — ripples under the feet, a glow
+ * that follows someone, dust kicked up where they are — needs to know where
+ * they are, and the ray and the depth cannot tell it: they describe the pixel,
+ * not the scene. This is the model's root, which for a PMX is between the feet
+ * on the floor, so it is already the contact point a ripple wants.
+ *
+ * Clamped rather than bounds-checked: an effect looping past the count reads the
+ * last subject instead of sampling whatever follows the array, which is a wrong
+ * ripple rather than an undefined one.
+ */
+fn bgSubjectPos(i: i32) -> vec3f { return viewU[11 + clamp(i, 0, 3)].xyz; }
+
 /** Where in the WORLD the scene drew this pixel — the depth handed to
  *  foreground() turned into a place. Without it an effect can only think in
  *  distances from the lens, which is no use to anything that belongs somewhere:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.41.1",
+  "version": "0.41.3",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/dds-loader.ts

@@ -0,0 +1,236 @@
+// DDS → RGBA8, decoded on the CPU.
+//
+// Stage models converted out of games ship their textures as DDS far more often
+// than MMD character models do, and the browser cannot read one: createImageBitmap
+// refuses it, and the TGA fallback reads the header as garbage and reports a
+// height of zero. Every such material fell back to white.
+//
+// Decoded rather than uploaded as-is on purpose. WebGPU can sample BC formats
+// natively, but only where the texture-compression-bc feature was requested at
+// device creation — it is absent on much mobile hardware, and requesting a
+// feature that may not exist to read a file that may not appear is a worse trade
+// than spending a few milliseconds per texture at load.
+
+import type { DecodedImage } from "./tga-loader"
+
+const MAGIC = 0x20534444 // "DDS "
+const fourCC = (s: string) => s.charCodeAt(0) | (s.charCodeAt(1) << 8) | (s.charCodeAt(2) << 16) | (s.charCodeAt(3) << 24)
+const FOURCC_DXT1 = fourCC("DXT1")
+const FOURCC_DXT3 = fourCC("DXT3")
+const FOURCC_DXT5 = fourCC("DXT5")
+const FOURCC_DX10 = fourCC("DX10")
+
+// The DXGI formats worth answering. BC1/2/3 are what a converted stage carries;
+// the two RGBA8 spellings turn up in tools that write a DX10 header for an
+// uncompressed surface.
+const DXGI_BC1 = new Set([70, 71, 72])
+const DXGI_BC2 = new Set([73, 74, 75])
+const DXGI_BC3 = new Set([76, 77, 78])
+const DXGI_RGBA8 = new Set([27, 28, 29])
+const DXGI_BGRA8 = new Set([87, 88, 91])
+
+/** True when these bytes are a DDS, by magic rather than by file extension. */
+export function isDds(buffer: ArrayBuffer): boolean {
+  return buffer.byteLength >= 128 && new DataView(buffer).getUint32(0, true) === MAGIC
+}
+
+function rgb565(c: number, out: Uint8Array, o: number): void {
+  const r = (c >> 11) & 0x1f
+  const g = (c >> 5) & 0x3f
+  const b = c & 0x1f
+  // Bit-replication, not a shift: (r << 3) leaves white at 248 and tints every
+  // bright surface, which reads as a dull texture rather than a decode bug.
+  out[o] = (r << 3) | (r >> 2)
+  out[o + 1] = (g << 2) | (g >> 4)
+  out[o + 2] = (b << 3) | (b >> 2)
+  out[o + 3] = 255
+}
+
+/**
+ * One BC1 colour block into `dst`.
+ *
+ * `opaque` forces the four-colour mode. BC1 on its own picks its mode per block
+ * from the endpoint order — c0 <= c1 means three colours and a transparent
+ * fourth — but when a BC1 block is the colour half of a BC2/BC3 pair the alpha
+ * lives in the other half and the four-colour mode is unconditional.
+ */
+function bc1Block(v: DataView, off: number, dst: Uint8Array, x0: number, y0: number, w: number, h: number, opaque: boolean): void {
+  const c0 = v.getUint16(off, true)
+  const c1 = v.getUint16(off + 2, true)
+  const bits = v.getUint32(off + 4, true)
+  const pal = new Uint8Array(16)
+  rgb565(c0, pal, 0)
+  rgb565(c1, pal, 4)
+  if (c0 > c1 || opaque) {
+    for (let i = 0; i < 3; i++) {
+      pal[8 + i] = (2 * pal[i] + pal[4 + i] + 1) / 3
+      pal[12 + i] = (pal[i] + 2 * pal[4 + i] + 1) / 3
+    }
+    pal[11] = 255
+    pal[15] = 255
+  } else {
+    for (let i = 0; i < 3; i++) pal[8 + i] = (pal[i] + pal[4 + i]) >> 1
+    pal[11] = 255
+    // The fourth entry is transparent black in this mode — the 1-bit alpha.
+    pal[12] = 0
+    pal[13] = 0
+    pal[14] = 0
+    pal[15] = 0
+  }
+  for (let py = 0; py < 4; py++) {
+    for (let px = 0; px < 4; px++) {
+      const x = x0 + px
+      const y = y0 + py
+      if (x >= w || y >= h) continue
+      const idx = ((bits >> (2 * (4 * py + px))) & 3) * 4
+      const o = (y * w + x) * 4
+      dst[o] = pal[idx]
+      dst[o + 1] = pal[idx + 1]
+      dst[o + 2] = pal[idx + 2]
+      dst[o + 3] = pal[idx + 3]
+    }
+  }
+}
+
+/** BC3's 3-bit interpolated alpha block. */
+function bc3Alpha(v: DataView, off: number, dst: Uint8Array, x0: number, y0: number, w: number, h: number): void {
+  const a0 = v.getUint8(off)
+  const a1 = v.getUint8(off + 1)
+  const a = new Uint8Array(8)
+  a[0] = a0
+  a[1] = a1
+  if (a0 > a1) {
+    for (let i = 1; i < 7; i++) a[i + 1] = ((7 - i) * a0 + i * a1) / 7
+  } else {
+    for (let i = 1; i < 5; i++) a[i + 1] = ((5 - i) * a0 + i * a1) / 5
+    a[6] = 0
+    a[7] = 255
+  }
+  // 16 three-bit indices over six bytes; read as two 24-bit halves so the
+  // shifts stay inside the 32-bit range JS bit ops actually work in.
+  const lo = v.getUint8(off + 2) | (v.getUint8(off + 3) << 8) | (v.getUint8(off + 4) << 16)
+  const hi = v.getUint8(off + 5) | (v.getUint8(off + 6) << 8) | (v.getUint8(off + 7) << 16)
+  for (let i = 0; i < 16; i++) {
+    const x = x0 + (i & 3)
+    const y = y0 + (i >> 2)
+    if (x >= w || y >= h) continue
+    const bitsFor = i < 8 ? (lo >> (3 * i)) & 7 : (hi >> (3 * (i - 8))) & 7
+    dst[(y * w + x) * 4 + 3] = a[bitsFor]
+  }
+}
+
+/** BC2's 4-bit explicit alpha block. */
+function bc2Alpha(v: DataView, off: number, dst: Uint8Array, x0: number, y0: number, w: number, h: number): void {
+  for (let i = 0; i < 16; i++) {
+    const x = x0 + (i & 3)
+    const y = y0 + (i >> 2)
+    if (x >= w || y >= h) continue
+    const nib = v.getUint8(off + (i >> 1))
+    const a = i & 1 ? nib >> 4 : nib & 0x0f
+    dst[(y * w + x) * 4 + 3] = (a << 4) | a
+  }
+}
+
+/**
+ * Decode the top mip of a DDS to RGBA8.
+ *
+ * Only the first surface: the engine generates its own mip chain, and a cube map
+ * or an array reaching here is a texture slot that was never going to mean what
+ * the file meant anyway.
+ */
+export function decodeDds(buffer: ArrayBuffer): DecodedImage {
+  const v = new DataView(buffer)
+  if (buffer.byteLength < 128 || v.getUint32(0, true) !== MAGIC) throw new Error("not a DDS")
+
+  const headerFlags = v.getUint32(8, true)
+  const height = v.getUint32(12, true)
+  const width = v.getUint32(16, true)
+  const pitch = v.getUint32(20, true)
+  if (width <= 0 || height <= 0) throw new Error(`DDS bad dimensions ${width}x${height}`)
+
+  const pfFlags = v.getUint32(80, true)
+  const pfFourCC = v.getUint32(84, true)
+  const rgbBits = v.getUint32(88, true)
+  const rMask = v.getUint32(92, true)
+  const aMask = v.getUint32(104, true)
+
+  let data = 128
+  let kind: "bc1" | "bc2" | "bc3" | "rgba" | "bgra" | null = null
+
+  if (pfFlags & 0x4) {
+    if (pfFourCC === FOURCC_DXT1) kind = "bc1"
+    else if (pfFourCC === FOURCC_DXT3) kind = "bc2"
+    else if (pfFourCC === FOURCC_DXT5) kind = "bc3"
+    else if (pfFourCC === FOURCC_DX10) {
+      const dxgi = v.getUint32(128, true)
+      data = 148 // 128 header + 20-byte DX10 extension
+      if (DXGI_BC1.has(dxgi)) kind = "bc1"
+      else if (DXGI_BC2.has(dxgi)) kind = "bc2"
+      else if (DXGI_BC3.has(dxgi)) kind = "bc3"
+      else if (DXGI_RGBA8.has(dxgi)) kind = "rgba"
+      else if (DXGI_BGRA8.has(dxgi)) kind = "bgra"
+      else throw new Error(`DDS unsupported DXGI format ${dxgi}`)
+    } else {
+      throw new Error(`DDS unsupported fourCC 0x${pfFourCC.toString(16)}`)
+    }
+  } else if (pfFlags & 0x40 && (rgbBits === 32 || rgbBits === 24)) {
+    // Uncompressed. The masks are stated over the little-endian DWORD, so the
+    // channel owning the LOW byte is the one stored first: red low is RGBA,
+    // and the classic D3D A8R8G8B8 (red at 0x00ff0000) is BGRA in memory.
+    kind = rMask === 0x000000ff ? "rgba" : "bgra"
+  }
+  if (!kind) throw new Error("DDS unsupported pixel format")
+
+  const rgba = new Uint8Array(width * height * 4)
+
+  if (kind === "rgba" || kind === "bgra") {
+    const bytes = rgbBits === 24 ? 3 : 4
+    const hasAlpha = bytes === 4 && aMask !== 0
+    // Rows can be padded, and the header says by how much — DDSD_PITCH means the
+    // pitch field is a byte stride rather than a total size. Reading past it
+    // shears the image diagonally, which looks like a corrupt texture.
+    const stride = headerFlags & 0x8 && pitch >= width * bytes ? pitch : width * bytes
+    if (data + stride * height > buffer.byteLength) throw new Error("DDS truncated")
+    const src = new Uint8Array(buffer, data)
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const s = y * stride + x * bytes
+        const o = (y * width + x) * 4
+        if (kind === "bgra") {
+          rgba[o] = src[s + 2]
+          rgba[o + 1] = src[s + 1]
+          rgba[o + 2] = src[s]
+        } else {
+          rgba[o] = src[s]
+          rgba[o + 1] = src[s + 1]
+          rgba[o + 2] = src[s + 2]
+        }
+        rgba[o + 3] = hasAlpha ? src[s + 3] : 255
+      }
+    }
+    return { rgba, width, height }
+  }
+
+  const blockBytes = kind === "bc1" ? 8 : 16
+  const bw = Math.max(1, (width + 3) >> 2)
+  const bh = Math.max(1, (height + 3) >> 2)
+  if (data + bw * bh * blockBytes > buffer.byteLength) throw new Error("DDS truncated")
+
+  for (let by = 0; by < bh; by++) {
+    for (let bx = 0; bx < bw; bx++) {
+      const off = data + (by * bw + bx) * blockBytes
+      const x0 = bx * 4
+      const y0 = by * 4
+      if (kind === "bc1") {
+        bc1Block(v, off, rgba, x0, y0, width, height, false)
+      } else {
+        // Colour first so the alpha block can overwrite what BC1 wrote — in
+        // BC2/BC3 the colour half is always the opaque four-colour mode.
+        bc1Block(v, off + 8, rgba, x0, y0, width, height, true)
+        if (kind === "bc2") bc2Alpha(v, off, rgba, x0, y0, width, height)
+        else bc3Alpha(v, off, rgba, x0, y0, width, height)
+      }
+    }
+  }
+  return { rgba, width, height }
+}

package/src/engine.ts

@@ -1,5 +1,7 @@
 import { Camera } from "./camera"
+import { decodeDds, isDds } from "./dds-loader"
 import { Mat4, Quat, Vec3 } from "./math"
+import { decodePsd, isPsd } from "./psd-loader"
 import { Model, MATERIAL_MORPH_MULTIPLY, type Material } from "./model"
 import { MORPH_COMPUTE_WGSL } from "./shaders/passes/morph"
 import { decodeTga } from "./tga-loader"
@@ -232,6 +234,14 @@ export type WorldOptions = {
 
 /** A model's scene placement — root offset baked into skinning + visibility. Serializable
  *  into a scene descriptor via getModelTransform. */
+/** How many character positions an effect can read (viewU[11..14]). */
+const MAX_EFFECT_SUBJECTS = 4
+/** Where a character IS, for an effect that follows them. センター carries a
+ *  motion's root movement — walking, jumping — where the model transform only
+ *  carries where the model was placed; 全ての親 is the fallback for a model that
+ *  animates the true root instead. */
+const SUBJECT_BONES = ["センター", "全ての親"]
+
 export type ModelTransform = {
   position: Vec3
   rotation: Quat
@@ -652,7 +662,9 @@ export class Engine {
   private device!: GPUDevice
   private context!: GPUCanvasContext
   private presentationFormat!: GPUTextureFormat
-  private camera!: Camera
+  // No `!`: the constructor assigns it, so the type is the guarantee. Every other
+  // `!` field here is genuinely absent until init() — this one no longer is.
+  private camera: Camera
   private cameraUniformBuffer!: GPUBuffer
   private cameraMatrixData = new Float32Array(36)
   // Blender-style scene config groups (resolved from EngineOptions)
@@ -802,7 +814,7 @@ export class Engine {
   // 11 × vec4f — see the viewU comment in composite.ts. The last one is the
   // camera's world position, which is what lets a foreground effect turn the
   // depth it is handed into a PLACE (bgWorldPos) rather than a distance.
-  private readonly compositeUniformData = new Float32Array(44)
+  private readonly compositeUniformData = new Float32Array(60)
   /** 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).
@@ -979,6 +991,20 @@ export class Engine {
       target: options?.camera?.target ?? d.camera.target,
       fov: options?.camera?.fov ?? d.camera.fov,
     }
+    // Built HERE and not in setupCamera, because a host holds the Engine before
+    // init() resolves — the reference is assigned, then init is awaited — and it
+    // reads the camera in that window. isCameraVmdEnabled() on a camera that did
+    // not exist yet threw "Cannot read properties of undefined (reading
+    // 'vmdDriven')", which surfaces as the whole page failing to load. The Camera
+    // is pure math, so nothing about it needed the device; only its aspect and
+    // its input listeners do, and those still wait for a sized canvas.
+    this.camera = new Camera(
+      Math.PI,
+      Math.PI / 2.5,
+      this.cameraConfig.distance,
+      this.cameraConfig.target,
+      this.cameraConfig.fov,
+    )
     this.onRaycast = options?.onRaycast
     this.onGizmoDrag = options?.onGizmoDrag
     this.bloomSettings = Engine.mergeBloomDefaults(options?.bloom)
@@ -2412,8 +2438,9 @@ export class Engine {
       // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray ·
       // (time, _, canvas width, canvas height) for user effects · three grade
       // vectors (CDL offset+contrast, power+saturation, slope+flag) · camera
-      // world position, for an effect placing itself in the scene.
-      size: 176,
+      // world position, for an effect placing itself in the scene · four
+      // character positions, for one that wants to respond to the cast.
+      size: 240,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
     this.dofUniformBuffer = this.device.createBuffer({
@@ -3040,14 +3067,8 @@ export class Engine {
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
 
-    this.camera = new Camera(
-      Math.PI,
-      Math.PI / 2.5,
-      this.cameraConfig.distance,
-      this.cameraConfig.target,
-      this.cameraConfig.fov,
-    )
-
+    // The camera came up with the engine (see the constructor). What waits for
+    // init is only what needs a device and a sized canvas.
     this.camera.aspect = this.canvas.width / this.canvas.height
     this.camera.attachControl(this.canvas)
   }
@@ -4614,21 +4635,28 @@ export class Engine {
       return null
     }
 
-    // Decode to either an ImageBitmap (web-native formats) or raw RGBA (TGA). .tga skips
-    // straight to the TGA decoder (createImageBitmap can't read it); other extensions try
-    // the browser decoder first, then fall back to TGA in case a .spa/.sph/etc. is TGA
-    // under its extension. Every failure is logged and soft — never throws to the caller.
+    // Decode to either an ImageBitmap (web-native formats) or raw RGBA (TGA, DDS, PSD).
+    //
+    // DDS and PSD are recognised by their MAGIC rather than their extension, because
+    // the extension lies often enough to matter — a converted stage's .tga is
+    // sometimes a DDS, and a repacked texture folder is full of .png that never
+    // stopped being Photoshop files. TGA has no magic to key on, so .tga skips
+    // straight to its decoder (createImageBitmap can't read it) and every other
+    // extension tries the browser first, then falls back to TGA in case a
+    // .spa/.sph/etc. is TGA underneath. Every failure is logged and soft — this
+    // never throws to the caller; the material just gets the white texture.
     let source: ImageBitmap | null = null
     let rgba: Uint8Array | null = null
     let width: number
     let height: number
 
+    const cpuDecoder = isDds(buffer) ? decodeDds : isPsd(buffer) ? decodePsd : null
     const isTga = logicalPath.toLowerCase().endsWith(".tga")
-    if (!isTga) {
+    if (!isTga && !cpuDecoder) {
       try {
         source = await createImageBitmap(new Blob([buffer]), { premultiplyAlpha: "none", colorSpaceConversion: "none" })
       } catch {
-        source = null // not a browser-native image — try TGA below
+        source = null // not a browser-native image — try the CPU decoders below
       }
     }
 
@@ -4637,7 +4665,7 @@ export class Engine {
       height = source.height
     } else {
       try {
-        const img = decodeTga(buffer)
+        const img = (cpuDecoder ?? decodeTga)(buffer)
         rgba = img.rgba
         width = img.width
         height = img.height
@@ -6122,6 +6150,40 @@ export class Engine {
       u[40] = cameraPos.x
       u[41] = cameraPos.y
       u[42] = cameraPos.z
+      // Character positions (viewU[11..14]), count in viewU[10].w. Stages are
+      // excluded: an effect asking where the cast is means the characters, and a
+      // stage's origin is wherever its author put it, which is not a place
+      // anything is standing. Four is the cap because the uniform is small and a
+      // scene with five characters is not the case this serves.
+      let n = 0
+      this.forEachInstance((inst) => {
+        if (n >= MAX_EFFECT_SUBJECTS || inst.isStage) return
+        const m = inst.model
+        // The model transform is only where the model was PLACED. A motion moves
+        // the character by animating bones, so an effect anchored to the
+        // transform never follows anyone anywhere — it sits at the spawn point
+        // while they walk out of it. Composed exactly as the follow camera
+        // composes it, for the same reason: bone matrices are model-space.
+        let px = m.position.x
+        let py = m.position.y
+        let pz = m.position.z
+        for (const bone of SUBJECT_BONES) {
+          const pos = m.getBoneWorldPosition(bone)
+          if (!pos) continue
+          const sc = m.scale
+          pos.setXYZ(pos.x * sc, pos.y * sc, pos.z * sc)
+          Quat.rotateVecInto(m.rotation, pos, pos)
+          px += pos.x
+          py += pos.y
+          pz += pos.z
+          break
+        }
+        u[44 + n * 4] = px
+        u[45 + n * 4] = py
+        u[46 + n * 4] = pz
+        n++
+      })
+      u[43] = n
       this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u)
     }
   }