Skip to content

Code-first video & image, rendered natively on WebGPU.

Expand glTF geometry, animation and texture support

okanasl96099919dcc0
diff --git a/.changeset/improve-gltf-geometry-and-materials.md b/.changeset/improve-gltf-geometry-and-materials.md
new file mode 100644
index 00000000..0b6c72d9
--- /dev/null
+++ b/.changeset/improve-gltf-geometry-and-materials.md
@@ -0,0 +1,7 @@
+---
+"framefields": patch
+"@framefields/webgpu-renderers": patch
+"@framefields/node-compositor": patch
+---
+
+Render all glTF primitive modes, per-map UV sets and transforms, sparse accessors, animated morph targets, Draco or meshopt compressed geometry, and ETC1S/UASTC KTX2 textures. Reject unsupported required glTF extensions explicitly.
diff --git a/nodes/node-compositor/SKILL.md b/nodes/node-compositor/SKILL.md
index 62fa7fba..810d97d1 100644
--- a/nodes/node-compositor/SKILL.md
+++ b/nodes/node-compositor/SKILL.md
@@ -210,7 +210,7 @@ Each track represents animatable property modifications:
- **Audio-Reactive 3D Models:** a `kind: "model3d"` node loading an OBJ/FBX/GLTF/STL/PLY mesh with `audioDeform: { audioTrackId, mode: "normal_extrusion" | "radial_pulse" | "harmonic_wave" | "twist" | "ripple", amplitudeMultiplier, damping }`, deformed directly in VRAM via WebGPU compute shaders driven by audio frequency spectra and transient energies. `twist` turns each slice about Y by its height (harder on the bass); `ripple` runs concentric waves across XY, struck by the drums. `audioTrackId` may be an audio layer's id or an audio file path.
- **Transparent meshes:** glTF `BLEND` materials and meshes with reduced layer, material, tint, or vertex alpha draw after opaque items, back to front by the camera-space center of each mesh’s transformed bounds, without writing depth. This is object-level sorting: intersecting meshes, self-overlap, skinned/deformed bounds, translucent flat layers, glass, and transparent shadows have separate limitations.
- **Mesh wireframe:** `wireframe: true` on a `model3d` draws triangle edges as one-pixel lines, including triangulation and back edges; it also applies to skinned and audio-deformed meshes and their shadows.
-- **glTF scenes:** a glTF/GLB `model3d` keeps its node hierarchy, every skin and its animation clips (translation, rotation, scale; linear, step and cubic-spline). Skinned meshes are posed per frame from the clip (`animationName`, `animationTime`/`animationProgress`, `loop`); base-colour textures (with mipmaps), alpha `MASK`/`BLEND` and VRM MToon materials (`material: "toon"`, picked automatically when `material` is unset) render as authored. `center`/`normalizeSize` apply above the scene graph, so skinning stays intact.
+- **glTF scenes:** a glTF/GLB `model3d` keeps its node hierarchy, every skin and its animation clips (translation, rotation, scale and morph weights; linear, step and cubic-spline). Draco and meshopt compressed geometry and all seven core primitive modes are supported; per-map UV sets and texture transforms are independent. Basis KTX2 (ETC1S/UASTC) textures transcode offline to RGBA8 with their mip levels. Unsupported required extensions fail clearly. Morph targets run on the GPU before skinning and audio deformation. Skinned meshes are posed per frame from the clip (`animationName`, `animationTime`/`animationProgress`, `loop`); base-colour textures (with mipmaps), alpha `MASK`/`BLEND` and VRM MToon materials (`material: "toon"`, picked automatically when `material` is unset) render as authored. `center`/`normalizeSize` apply above the scene graph, so skinning stays intact.
## Don't Forget
- If text rendering required, you must include a font in spec (CLI TOOL only). No emoji font ships with framefields: to draw emoji, provide a color emoji font yourself with `FontManager.registerEmojiFont(path)` (a CBDT/CBLC bitmap font such as Noto Color Emoji).
diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
index 0a7f92bf..922c23a4 100644
--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
@@ -67,6 +67,7 @@ import {
type ShapeGeometryConfig,
SlugFontCache,
type SlugGlyphBatch,
+ sampleMorphWeights,
spansText,
srtLoader,
Vector3Math,
@@ -1322,14 +1323,24 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
sampleCount3d,
);
- // Execute audio mesh deformation compute passes before beginning render pass
+ // Morph targets are applied in object space before audio deformation and skinning.
for (const item of pending3DItems) {
- if (item.kind === "mesh" && item.opts.audioDeform) {
+ if (item.kind !== "mesh") continue;
+ if (item.opts.morphWeights?.length) {
+ item.meshBuffers = r3d.morphMesh(
+ encoder,
+ item.mesh,
+ item.opts.morphWeights,
+ item.opts.wireframe,
+ );
+ }
+ if (item.opts.audioDeform) {
item.meshBuffers = r3d.deformMesh(
encoder,
item.mesh,
item.opts.audioDeform,
item.opts.wireframe,
+ item.meshBuffers,
);
}
}
@@ -1924,13 +1935,15 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
modelSrc !== null &&
"meshes" in modelSrc
? (modelSrc as Model3DData)
- : r3d.loadModel(modelSrc, lop.modelFormat ?? "auto", {
+ : await r3d.loadModelAsync(modelSrc, lop.modelFormat ?? "auto", {
center: lop.center,
normalizeSize: lop.normalizeSize,
});
} catch (err) {
- console.error("Failed to load 3D model:", err);
- return;
+ throw new Error(
+ `Failed to load 3D model ${lop.id ?? "(unnamed)"}: ${err instanceof Error ? err.message : String(err)}`,
+ { cause: err },
+ );
}
if (!model || model.meshes.length === 0) return;
@@ -2297,6 +2310,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
const meshOpts: DrawMesh3DOpts = {
modelMatrix: placed.matrix,
+ morphWeights: sampleMorphWeights(mesh, clip, clipSec),
opacity: modelOpacity * (mat?.opacity ?? 1.0),
colorTint: meshColorTint,
transparent:
diff --git a/packages/framefields/src/gltf-scene-render.test.ts b/packages/framefields/src/gltf-scene-render.test.ts
index 9702ea99..ac23bb4f 100644
--- a/packages/framefields/src/gltf-scene-render.test.ts
+++ b/packages/framefields/src/gltf-scene-render.test.ts
@@ -4,6 +4,7 @@
* Each scene is a GLB built in the test and checked by its pixels.
*/
import fs from "node:fs/promises";
+import { createRequire } from "node:module";
import os from "node:os";
import path from "node:path";
import { Canvas, loadImage } from "skia-canvas";
@@ -79,10 +80,7 @@ class GlbBuilder {
const header = Buffer.alloc(12);
header.writeUInt32LE(0x46546c67, 0);
header.writeUInt32LE(2, 4);
- header.writeUInt32LE(
- 12 + 8 + docPadded.length + 8 + binPadded.length,
- 8,
- );
+ header.writeUInt32LE(12 + 8 + docPadded.length + 8 + binPadded.length, 8);
const chunk = (data: Buffer, type: number) => {
const h = Buffer.alloc(8);
h.writeUInt32LE(data.length, 0);
@@ -127,7 +125,7 @@ async function pixels(png: Buffer) {
}
/** Renders a GLB centred in a SIZE² frame, model units = pixels, Y up flipped to the screen's Y down. */
-async function render(file: string, frame = 0, fps = 30) {
+async function render(file: string, frame = 0, fps = 30, lit = false) {
const comp = new Composition({
width: SIZE,
height: SIZE,
@@ -154,7 +152,7 @@ async function render(file: string, frame = 0, fps = 30) {
y: SIZE / 2,
z: 0,
rotateX: 180,
- material: "unlit",
+ material: lit ? "lit" : "unlit",
loop: false,
}),
);
@@ -191,9 +189,16 @@ describe("glTF scene rendering", () => {
],
},
],
- materials: [{ pbrMetallicRoughness: { baseColorTexture: { index: 0 } } }],
+ materials: [
+ { pbrMetallicRoughness: { baseColorTexture: { index: 0 } } },
+ ],
textures: [{ source: 0 }],
- images: [{ bufferView: g.image(await solidPng("#ff2000")), mimeType: "image/png" }],
+ images: [
+ {
+ bufferView: g.image(await solidPng("#ff2000")),
+ mimeType: "image/png",
+ },
+ ],
}),
);
const px = await render(file);
@@ -203,14 +208,491 @@ describe("glTF scene rendering", () => {
expect(b).toBeLessThan(40);
});
+ it("reports unsupported required extensions instead of rendering a blank model", async () => {
+ const file = path.join(dir, "unsupported.gltf");
+ await fs.writeFile(
+ file,
+ JSON.stringify({
+ asset: { version: "2.0" },
+ extensionsRequired: ["VENDOR_unknown"],
+ }),
+ );
+ const comp = new Composition({
+ width: SIZE,
+ height: SIZE,
+ fps: 30,
+ durationMs: 1000,
+ backgroundColor: BG,
+ });
+ comp.add(
+ Layer.camera({
+ x: 200,
+ y: 200,
+ z: -600,
+ targetX: 200,
+ targetY: 200,
+ targetZ: 0,
+ }),
+ );
+ comp.add(Layer.glb(file, { id: "unsupported", x: 200, y: 200 }));
+ await expect(comp.renderFrame({ frame: 0 })).rejects.toThrow(
+ /VENDOR_unknown/,
+ );
+ });
+
+ it.each([
+ "etc1s",
+ "uastc-ldr",
+ ])("renders required KTX2/Basis %s textures offline", async (format) => {
+ const g = new GlbBuilder();
+ const q = rect(-100, -100, 100, 100);
+ const image = await fs.readFile(
+ new URL(
+ `../../webgpu-renderers/src/renderer3d/fixtures/${format}.ktx2`,
+ import.meta.url,
+ ),
+ );
+ const file = path.join(dir, `${format}.glb`);
+ await fs.writeFile(
+ file,
+ g.build({
+ extensionsUsed: ["KHR_texture_basisu"],
+ extensionsRequired: ["KHR_texture_basisu"],
+ meshes: [
+ {
+ primitives: [
+ {
+ attributes: {
+ POSITION: g.accessor(new Float32Array(q.positions), "VEC3"),
+ TEXCOORD_0: g.accessor(new Float32Array(q.uvs), "VEC2"),
+ },
+ indices: g.accessor(new Uint16Array(q.indices), "SCALAR"),
+ material: 0,
+ },
+ ],
+ },
+ ],
+ materials: [
+ { pbrMetallicRoughness: { baseColorTexture: { index: 0 } } },
+ ],
+ textures: [{ extensions: { KHR_texture_basisu: { source: 0 } } }],
+ images: [{ bufferView: g.image(image), mimeType: "image/ktx2" }],
+ }),
+ );
+ const color = (await render(file))(200, 200);
+ expect(color[0]).toBeGreaterThan(180);
+ expect(color[1]).toBeLessThan(60);
+ expect(color[2]).toBeLessThan(50);
+ });
+
+ it("blends an ETC1S KTX2 texture with alpha", async () => {
+ const g = new GlbBuilder();
+ const q = rect(-100, -100, 100, 100);
+ const image = await fs.readFile(
+ new URL(
+ "../../webgpu-renderers/src/renderer3d/fixtures/etc1s-alpha.ktx2",
+ import.meta.url,
+ ),
+ );
+ const file = path.join(dir, "ktx-alpha.glb");
+ await fs.writeFile(
+ file,
+ g.build({
+ extensionsUsed: ["KHR_texture_basisu"],
+ extensionsRequired: ["KHR_texture_basisu"],
+ meshes: [
+ {
+ primitives: [
+ {
+ attributes: {
+ POSITION: g.accessor(new Float32Array(q.positions), "VEC3"),
+ TEXCOORD_0: g.accessor(new Float32Array(q.uvs), "VEC2"),
+ },
+ indices: g.accessor(new Uint16Array(q.indices), "SCALAR"),
+ material: 0,
+ },
+ ],
+ },
+ ],
+ materials: [
+ {
+ alphaMode: "BLEND",
+ pbrMetallicRoughness: { baseColorTexture: { index: 0 } },
+ },
+ ],
+ textures: [{ extensions: { KHR_texture_basisu: { source: 0 } } }],
+ images: [{ bufferView: g.image(image), mimeType: "image/ktx2" }],
+ }),
+ );
+ const color = (await render(file))(200, 200);
+ expect(color[0]).toBeGreaterThan(100);
+ expect(color[0]).toBeLessThan(135);
+ });
+
+ it("renders meshopt-compressed glTF through the compositor", async () => {
+ const encoded = Buffer.from(
+ "oAAAAAEzAAAA//8AAAABDAAAAP8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMjCAADIwgAAAAA=",
+ "base64",
+ );
+ const file = path.join(dir, "meshopt.gltf");
+ await fs.writeFile(
+ file,
+ JSON.stringify({
+ asset: { version: "2.0" },
+ extensionsUsed: ["EXT_meshopt_compression"],
+ extensionsRequired: ["EXT_meshopt_compression"],
+ buffers: [
+ {
+ byteLength: encoded.length,
+ uri: `data:application/octet-stream;base64,${encoded.toString("base64")}`,
+ },
+ ],
+ bufferViews: [
+ {
+ buffer: 0,
+ byteLength: 48,
+ byteStride: 12,
+ extensions: {
+ EXT_meshopt_compression: {
+ buffer: 0,
+ byteOffset: 0,
+ byteLength: encoded.length,
+ byteStride: 12,
+ count: 4,
+ mode: "ATTRIBUTES",
+ },
+ },
+ },
+ ],
+ accessors: [
+ { bufferView: 0, componentType: 5126, count: 4, type: "VEC3" },
+ ],
+ meshes: [{ primitives: [{ attributes: { POSITION: 0 }, mode: 6 }] }],
+ }),
+ );
+ expect((await render(file))(200, 200)[0]).toBeGreaterThan(180);
+ });
+
+ it("renders Draco-compressed glTF through the compositor", async () => {
+ const requireFromRenderer = createRequire(
+ import.meta.resolve("@framefields/webgpu-renderers"),
+ );
+ const dracoRoot = path.dirname(requireFromRenderer.resolve("draco3dgltf"));
+ const encoded = await fs.readFile(path.join(dracoRoot, "bunny.drc"));
+ const file = path.join(dir, "draco.gltf");
+ await fs.writeFile(
+ file,
+ JSON.stringify({
+ asset: { version: "2.0" },
+ extensionsUsed: ["KHR_draco_mesh_compression"],
+ extensionsRequired: ["KHR_draco_mesh_compression"],
+ buffers: [
+ {
+ byteLength: encoded.length,
+ uri: `data:application/octet-stream;base64,${encoded.toString("base64")}`,
+ },
+ ],
+ bufferViews: [{ buffer: 0, byteLength: encoded.length }],
+ accessors: [
+ { componentType: 5126, count: 34834, type: "VEC3" },
+ { componentType: 5125, count: 69451 * 3, type: "SCALAR" },
+ ],
+ meshes: [
+ {
+ primitives: [
+ {
+ attributes: { POSITION: 0 },
+ indices: 1,
+ extensions: {
+ KHR_draco_mesh_compression: {
+ bufferView: 0,
+ attributes: { POSITION: 0 },
+ },
+ },
+ },
+ ],
+ },
+ ],
+ }),
+ );
+ const comp = new Composition({
+ width: SIZE,
+ height: SIZE,
+ fps: 30,
+ durationMs: 1000,
+ backgroundColor: BG,
+ });
+ comp.add(
+ Layer.camera({
+ x: 200,
+ y: 200,
+ z: -600,
+ targetX: 200,
+ targetY: 200,
+ targetZ: 0,
+ }),
+ );
+ comp.add(
+ Layer.glb(file, {
+ x: 200,
+ y: 200,
+ center: true,
+ normalizeSize: 240,
+ material: "unlit",
+ }),
+ );
+ const px = await pixels(await comp.renderFrame({ frame: 0 }));
+ let lit = 0;
+ for (let y = 100; y < 300; y += 4)
+ for (let x = 100; x < 300; x += 4) if ((px(x, y)[0] ?? 0) > 50) lit++;
+ expect(lit).toBeGreaterThan(100);
+ });
+
+ it.each([
+ 0, 1, 2, 3, 5, 6,
+ ])("renders glTF primitive mode %i", async (mode) => {
+ const g = new GlbBuilder();
+ const file = path.join(dir, `primitive-${mode}.glb`);
+ const q = rect(-100, -100, 100, 100);
+ await fs.writeFile(
+ file,
+ g.build({
+ meshes: [
+ {
+ primitives: [
+ {
+ attributes: {
+ POSITION: g.accessor(new Float32Array(q.positions), "VEC3"),
+ },
+ mode,
+ },
+ ],
+ },
+ ],
+ }),
+ );
+ const px = await render(file);
+ const litNear = (x: number, y: number) => {
+ for (let dy = -2; dy <= 2; dy++)
+ for (let dx = -2; dx <= 2; dx++) {
+ if ((px(x + dx, y + dy)[0] ?? 0) > 50) return true;
+ }
+ return false;
+ };
+ if (mode === 0) expect(litNear(100, 300)).toBe(true);
+ else if (mode < 4) expect(litNear(200, 300)).toBe(true);
+ else expect(litNear(200, 200)).toBe(true);
+ });
+
+ it("samples an emissive map using its own UV set and transform", async () => {
+ const canvas = new Canvas(8, 8);
+ const ctx = canvas.getContext("2d");
+ ctx.fillStyle = "#ff0000";
+ ctx.fillRect(0, 0, 4, 8);
+ ctx.fillStyle = "#00ff00";
+ ctx.fillRect(4, 0, 4, 8);
+ const image = await canvas.toBuffer("png");
+ const renderUv = async (offset: number) => {
+ const g = new GlbBuilder();
+ const q = rect(-100, -100, 100, 100);
+ const file = path.join(dir, `map-uv-${offset}.glb`);
+ await fs.writeFile(
+ file,
+ g.build({
+ meshes: [
+ {
+ primitives: [
+ {
+ attributes: {
+ POSITION: g.accessor(new Float32Array(q.positions), "VEC3"),
+ TEXCOORD_0: g.accessor(
+ new Float32Array([
+ 0.25, 0.5, 0.25, 0.5, 0.25, 0.5, 0.25, 0.5,
+ ]),
+ "VEC2",
+ ),
+ TEXCOORD_1: g.accessor(
+ new Float32Array([
+ 0.75, 0.5, 0.75, 0.5, 0.75, 0.5, 0.75, 0.5,
+ ]),
+ "VEC2",
+ ),
+ },
+ indices: g.accessor(new Uint16Array(q.indices), "SCALAR"),
+ material: 0,
+ },
+ ],
+ },
+ ],
+ materials: [
+ {
+ pbrMetallicRoughness: {
+ baseColorFactor: [0, 0, 0, 1],
+ baseColorTexture: { index: 0, texCoord: 0 },
+ },
+ emissiveFactor: [1, 1, 1],
+ emissiveTexture: {
+ index: 0,
+ texCoord: 1,
+ extensions: { KHR_texture_transform: { offset: [offset, 0] } },
+ },
+ },
+ ],
+ textures: [{ source: 0 }],
+ images: [{ bufferView: g.image(image), mimeType: "image/png" }],
+ }),
+ );
+ return (await render(file, 0, 30, true))(SIZE / 2, SIZE / 2);
+ };
+ const green = await renderUv(0);
+ const red = await renderUv(-0.5);
+ expect(green[1]).toBeGreaterThan(200);
+ expect(green[0]).toBeLessThan(40);
+ expect(red[0]).toBeGreaterThan(200);
+ expect(red[1]).toBeLessThan(40);
+ });
+
+ it("applies animated morph weights to mesh positions", async () => {
+ const g = new GlbBuilder();
+ const q = rect(-100, -30, -40, 30);
+ const file = path.join(dir, "morph.glb");
+ const delta = new Float32Array([
+ 120, 0, 0, 120, 0, 0, 120, 0, 0, 120, 0, 0,
+ ]);
+ await fs.writeFile(
+ file,
+ g.build({
+ nodes: [{ mesh: 0 }],
+ scenes: [{ nodes: [0] }],
+ meshes: [
+ {
+ weights: [0],
+ primitives: [
+ {
+ attributes: {
+ POSITION: g.accessor(new Float32Array(q.positions), "VEC3"),
+ },
+ indices: g.accessor(new Uint16Array(q.indices), "SCALAR"),
+ targets: [{ POSITION: g.accessor(delta, "VEC3") }],
+ },
+ ],
+ },
+ ],
+ animations: [
+ {
+ channels: [{ sampler: 0, target: { node: 0, path: "weights" } }],
+ samplers: [
+ {
+ input: g.accessor(new Float32Array([0, 1]), "SCALAR"),
+ output: g.accessor(new Float32Array([0, 1]), "SCALAR"),
+ interpolation: "LINEAR",
+ },
+ ],
+ },
+ ],
+ }),
+ );
+ const rest = await render(file, 0);
+ const halfway = await render(file, 15);
+ const end = await render(file, 30);
+ expect(rest(130, 200)[0]).toBeGreaterThan(200);
+ expect(rest(250, 200)[0]).toBeLessThan(10);
+ expect(halfway(190, 200)[0]).toBeGreaterThan(200);
+ expect(end(130, 200)[0]).toBeLessThan(10);
+ expect(end(250, 200)[0]).toBeGreaterThan(200);
+ });
+
+ it("applies morph deltas before the skin's joint transform", async () => {
+ const g = new GlbBuilder();
+ const q = rect(-100, -20, -60, 20);
+ const file = path.join(dir, "morph-skin.glb");
+ const delta = new Float32Array([50, 0, 0, 50, 0, 0, 50, 0, 0, 50, 0, 0]);
+ const joints = new Uint16Array(16);
+ const weights = new Float32Array([
+ 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0,
+ ]);
+ await fs.writeFile(
+ file,
+ g.build({
+ nodes: [
+ { mesh: 0, skin: 0, weights: [1] },
+ { translation: [40, 0, 0] },
+ ],
+ scenes: [{ nodes: [0, 1] }],
+ skins: [{ joints: [1] }],
+ meshes: [
+ {
+ primitives: [
+ {
+ attributes: {
+ POSITION: g.accessor(new Float32Array(q.positions), "VEC3"),
+ JOINTS_0: g.accessor(joints, "VEC4"),
+ WEIGHTS_0: g.accessor(weights, "VEC4"),
+ },
+ indices: g.accessor(new Uint16Array(q.indices), "SCALAR"),
+ targets: [{ POSITION: g.accessor(delta, "VEC3") }],
+ },
+ ],
+ },
+ ],
+ }),
+ );
+ const px = await render(file);
+ expect(px(210, 200)[0]).toBeGreaterThan(200);
+ expect(px(120, 200)[0]).toBeLessThan(10);
+ });
+
+ it("keeps independent default weights on instances of the same morph mesh", async () => {
+ const g = new GlbBuilder();
+ const q = rect(-20, -20, 20, 20);
+ const file = path.join(dir, "morph-instances.glb");
+ const delta = new Float32Array([
+ 100, 0, 0, 100, 0, 0, 100, 0, 0, 100, 0, 0,
+ ]);
+ await fs.writeFile(
+ file,
+ g.build({
+ nodes: [
+ { mesh: 0, translation: [-100, 70, 0], weights: [0] },
+ { mesh: 0, translation: [-100, -70, 0], weights: [1] },
+ ],
+ scenes: [{ nodes: [0, 1] }],
+ meshes: [
+ {
+ weights: [0],
+ primitives: [
+ {
+ attributes: {
+ POSITION: g.accessor(new Float32Array(q.positions), "VEC3"),
+ },
+ indices: g.accessor(new Uint16Array(q.indices), "SCALAR"),
+ targets: [{ POSITION: g.accessor(delta, "VEC3") }],
+ },
+ ],
+ },
+ ],
+ }),
+ );
+ const px = await render(file);
+ expect(px(100, 130)[0]).toBeGreaterThan(200);
+ expect(px(200, 270)[0]).toBeGreaterThan(200);
+ expect(px(100, 270)[0]).toBeLessThan(10);
+ });
+
it("poses a skinned mesh through its joint chain from a rotation track", async () => {
// A 20×200 strip: the lower half on joint 0 (origin), the upper on
// joint 1 (100 up, child of joint 0). The clip turns joint 1 by 90°
// about Z over one second, folding the upper half to the left.
const g = new GlbBuilder();
- const positions = [-10, 0, 0, 10, 0, 0, -10, 100, 0, 10, 100, 0, -10, 200, 0, 10, 200, 0];
- const joints = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0];
- const weights = [1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0];
+ const positions = [
+ -10, 0, 0, 10, 0, 0, -10, 100, 0, 10, 100, 0, -10, 200, 0, 10, 200, 0,
+ ];
+ const joints = [
+ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0,
+ ];
+ const weights = [
+ 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0,
+ ];
const ibm = [
...[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
...[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, -100, 0, 1],
@@ -226,7 +708,12 @@ describe("glTF scene rendering", () => {
{ name: "root", children: [2] },
{ name: "tip", translation: [0, 100, 0] },
],
- skins: [{ joints: [1, 2], inverseBindMatrices: g.accessor(new Float32Array(ibm), "MAT4") }],
+ skins: [
+ {
+ joints: [1, 2],
+ inverseBindMatrices: g.accessor(new Float32Array(ibm), "MAT4"),
+ },
+ ],
meshes: [
{
primitives: [
@@ -236,20 +723,28 @@ describe("glTF scene rendering", () => {
JOINTS_0: g.accessor(new Uint16Array(joints), "VEC4"),
WEIGHTS_0: g.accessor(new Float32Array(weights), "VEC4"),
},
- indices: g.accessor(new Uint16Array([0, 1, 3, 0, 3, 2, 2, 3, 5, 2, 5, 4]), "SCALAR"),
+ indices: g.accessor(
+ new Uint16Array([0, 1, 3, 0, 3, 2, 2, 3, 5, 2, 5, 4]),
+ "SCALAR",
+ ),
material: 0,
},
],
},
],
- materials: [{ pbrMetallicRoughness: { baseColorFactor: [1, 1, 1, 1] } }],
+ materials: [
+ { pbrMetallicRoughness: { baseColorFactor: [1, 1, 1, 1] } },
+ ],
animations: [
{
channels: [{ sampler: 0, target: { node: 2, path: "rotation" } }],
samplers: [
{
input: g.accessor(new Float32Array([0, 1]), "SCALAR"),
- output: g.accessor(new Float32Array([0, 0, 0, 1, 0, 0, s45, s45]), "VEC4"),
+ output: g.accessor(
+ new Float32Array([0, 0, 0, 1, 0, 0, s45, s45]),
+ "VEC4",
+ ),
},
],
},
@@ -257,8 +752,11 @@ describe("glTF scene rendering", () => {
}),
);
// Model (x, y) lands on screen (SIZE/2 + x, SIZE/2 - y).
- const lit = (px: (x: number, y: number) => number[], x: number, y: number) =>
- (px(SIZE / 2 + x, SIZE / 2 - y)[0] ?? 0) > 128;
+ const lit = (
+ px: (x: number, y: number) => number[],
+ x: number,
+ y: number,
+ ) => (px(SIZE / 2 + x, SIZE / 2 - y)[0] ?? 0) > 128;
const rest = await render(file, 0);
expect(lit(rest, 0, 150)).toBe(true);
expect(lit(rest, -60, 100)).toBe(false);
@@ -285,7 +783,9 @@ describe("glTF scene rendering", () => {
{
primitives: [
{
- attributes: { POSITION: g.accessor(new Float32Array(q.positions), "VEC3") },
+ attributes: {
+ POSITION: g.accessor(new Float32Array(q.positions), "VEC3"),
+ },
indices: g.accessor(new Uint16Array(q.indices), "SCALAR"),
},
],
diff --git a/packages/webgpu-renderers/package.json b/packages/webgpu-renderers/package.json
index 51e8b674..aa265b94 100644
--- a/packages/webgpu-renderers/package.json
+++ b/packages/webgpu-renderers/package.json
@@ -41,15 +41,18 @@
"test:ci": "vitest run --coverage"
},
"dependencies": {
+ "@forgeax/engine-codec": "^0.3.11",
"@framefields/client-utils": "workspace:*",
"@framefields/core": "workspace:*",
"@lottiefiles/dotlottie-web": "^0.74.0",
"@resvg/resvg-js": "^2.6.2",
"bidi-js": "^1.0.3",
+ "draco3dgltf": "^1.5.9",
"earcut": "^3.2.4",
"fontkit": "^2.0.4",
"gifuct-js": "^2.1.2",
"mediabunny": "^1.61.6",
+ "meshoptimizer": "^1.3.0",
"sharp": "^0.35.4",
"skia-canvas": "^3.0.8",
"webgpu": "^0.4.0"
diff --git a/packages/webgpu-renderers/src/loaders/draco3dgltf.d.ts b/packages/webgpu-renderers/src/loaders/draco3dgltf.d.ts
new file mode 100644
index 00000000..38db0aed
--- /dev/null
+++ b/packages/webgpu-renderers/src/loaders/draco3dgltf.d.ts
@@ -0,0 +1,39 @@
+declare module "draco3dgltf" {
+ interface DracoArray {
+ size(): number;
+ GetValue(index: number): number;
+ }
+ interface DracoBuffer {
+ Init(data: Int8Array, size: number): void;
+ }
+ interface DracoMesh {
+ num_points(): number;
+ num_faces(): number;
+ }
+ interface DracoStatus {
+ ok(): boolean;
+ error_msg(): string;
+ }
+ interface DracoDecoder {
+ GetEncodedGeometryType(buffer: DracoBuffer): number;
+ DecodeBufferToMesh(buffer: DracoBuffer, mesh: DracoMesh): DracoStatus;
+ GetAttributeByUniqueId(mesh: DracoMesh, id: number): object | null;
+ GetAttributeFloatForAllPoints(
+ mesh: DracoMesh,
+ attribute: object,
+ array: DracoArray,
+ ): boolean;
+ GetFaceFromMesh(mesh: DracoMesh, face: number, array: DracoArray): boolean;
+ }
+ interface DracoModule {
+ Decoder: new () => DracoDecoder;
+ DecoderBuffer: new () => DracoBuffer;
+ Mesh: new () => DracoMesh;
+ DracoFloat32Array: new () => DracoArray;
+ DracoInt32Array: new () => DracoArray;
+ TRIANGULAR_MESH: number;
+ destroy(value: object): void;
+ }
+ const draco: { createDecoderModule(options: object): Promise<DracoModule> };
+ export default draco;
+}
diff --git a/packages/webgpu-renderers/src/loaders/gltf-features.test.ts b/packages/webgpu-renderers/src/loaders/gltf-features.test.ts
index 92796a60..5ef083b5 100644
--- a/packages/webgpu-renderers/src/loaders/gltf-features.test.ts
+++ b/packages/webgpu-renderers/src/loaders/gltf-features.test.ts
@@ -1,5 +1,7 @@
import fs from "node:fs";
import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MeshoptEncoder } from "meshoptimizer/encoder";
import { afterEach, describe, expect, it, vi } from "vitest";
import { GltfLoader, loadGLTF } from "./gltf-loader.js";
@@ -74,29 +76,31 @@ describe("glTF texture features", () => {
}),
);
const uvs = Array.from(model.meshes[0]!.uvs);
- // uv (1, 0): scaled to (2, 0), rotated to (0, -2), offset to (0.5, -1.75).
+ // uv (1, 0): scaled to (2, 0), rotated to (0, 2), offset to (0.5, 2.25).
expect(uvs[2]).toBeCloseTo(0.5, 5);
- expect(uvs[3]).toBeCloseTo(-1.75, 5);
- // uv (0, 1): scaled to (0, 4), rotated to (4, 0), offset to (4.5, 0.25).
- expect(uvs[4]).toBeCloseTo(4.5, 5);
+ expect(uvs[3]).toBeCloseTo(2.25, 5);
+ // uv (0, 1): scaled to (0, 4), rotated to (-4, 0), offset to (-3.5, 0.25).
+ expect(uvs[4]).toBeCloseTo(-3.5, 5);
expect(uvs[5]).toBeCloseTo(0.25, 5);
});
- it("draws with the base color's UV set and skips maps on another set", () => {
- const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ it("keeps each map's UV set and texture transform", () => {
const model = parse(
quadGltf({
pbrMetallicRoughness: { baseColorTexture: { index: 0, texCoord: 1 } },
- occlusionTexture: { index: 0 },
+ occlusionTexture: {
+ index: 0,
+ extensions: { KHR_texture_transform: { offset: [0.25, 0.5] } },
+ },
}),
);
expect(Array.from(model.meshes[0]!.uvs.slice(0, 4))).toEqual([
10, 10, 11, 10,
]);
expect(model.materials.M?.diffuseTextureBuffer).toBeDefined();
- expect(model.materials.M?.occlusionTextureBuffer).toBeUndefined();
- expect(warn).toHaveBeenCalledWith(
- expect.stringContaining('occlusion map of material "M" uses UV set 0'),
+ expect(model.materials.M?.occlusionTextureBuffer).toBeDefined();
+ expect(Array.from(model.meshes[0]!.mapUvs!.occlusion!.slice(0, 4))).toEqual(
+ [0.25, 0.5, 1.25, 0.5],
);
});
@@ -110,8 +114,7 @@ describe("glTF texture features", () => {
expect(mat.textureWrap).toBe("clamp");
});
- it("prefers EXT_texture_webp and skips KTX2 / Basis textures", () => {
- const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ it("prefers WebP and Basis extension sources", () => {
const doc = quadGltf({
pbrMetallicRoughness: { baseColorTexture: { index: 0 } },
normalTexture: { index: 1 },
@@ -122,8 +125,7 @@ describe("glTF texture features", () => {
];
const mat = parse(doc).materials.M!;
expect(mat.diffuseTextureMime).toBe("image/webp");
- expect(mat.normalTextureBuffer).toBeUndefined();
- expect(warn).toHaveBeenCalledWith(expect.stringContaining("KTX2 / Basis"));
+ expect(mat.normalTextureBuffer).toBeDefined();
});
it("fails clearly on required mesh compression", () => {
@@ -134,7 +136,224 @@ describe("glTF texture features", () => {
).toThrow(/KHR_draco_mesh_compression.*cannot decode/);
expect(() =>
parse(quadGltf({}, { extensionsRequired: ["EXT_meshopt_compression"] })),
- ).toThrow(/meshopt/);
+ ).toThrow(/EXT_meshopt_compression/);
+ });
+
+ it("decodes Draco positions and per-map UV attributes", async () => {
+ const encoded = Buffer.from(
+ "RFJBQ08CAgEBAAAAAwEBAQAAAQf/AREBAQAC/wAAAAAAAQAJAwAAAAEDCQIAAQAAAIA/AAAAAAAAAAAAAAAAAACAPwAAAAAAAAAAAAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAA=",
+ "base64",
+ );
+ const doc = quadGltf(
+ { normalTexture: { index: 0 } },
+ {
+ extensionsRequired: ["KHR_draco_mesh_compression"],
+ buffers: [
+ {
+ byteLength: encoded.length,
+ uri: `data:application/octet-stream;base64,${encoded.toString("base64")}`,
+ },
+ ],
+ bufferViews: [{ buffer: 0, byteLength: encoded.length }],
+ accessors: [
+ { componentType: 5126, count: 3, type: "VEC3" },
+ { componentType: 5126, count: 3, type: "VEC2" },
+ ],
+ meshes: [
+ {
+ primitives: [
+ {
+ attributes: { POSITION: 0, TEXCOORD_0: 1 },
+ material: 0,
+ extensions: {
+ KHR_draco_mesh_compression: {
+ bufferView: 0,
+ attributes: { POSITION: 0, TEXCOORD_0: 1 },
+ },
+ },
+ },
+ ],
+ },
+ ],
+ },
+ );
+ const result = await GltfLoader.parseAsync(JSON.stringify(doc));
+ const mesh = result.meshes[0]!;
+ expect(Array.from(mesh.positions)).toEqual([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+ expect(Array.from(mesh.mapUvs!.normal!)).toEqual([0, 0, 1, 0, 0, 1]);
+ doc.extensionsRequired = [];
+ expect(() => parse(doc)).toThrow(/requires GltfLoader.parseAsync/);
+ });
+
+ it("decodes a required Draco-compressed mesh asynchronously", async () => {
+ const dracoRoot = path.dirname(
+ fileURLToPath(import.meta.resolve("draco3dgltf")),
+ );
+ const encoded = fs.readFileSync(path.join(dracoRoot, "bunny.drc"));
+ const doc = quadGltf(
+ {},
+ {
+ extensionsUsed: ["KHR_draco_mesh_compression"],
+ extensionsRequired: ["KHR_draco_mesh_compression"],
+ buffers: [
+ {
+ byteLength: encoded.length,
+ uri: `data:application/octet-stream;base64,${encoded.toString("base64")}`,
+ },
+ ],
+ bufferViews: [{ buffer: 0, byteLength: encoded.length }],
+ accessors: [
+ { componentType: 5126, count: 34834, type: "VEC3" },
+ { componentType: 5125, count: 69451 * 3, type: "SCALAR" },
+ ],
+ meshes: [
+ {
+ primitives: [
+ {
+ attributes: { POSITION: 0 },
+ indices: 1,
+ extensions: {
+ KHR_draco_mesh_compression: {
+ bufferView: 0,
+ attributes: { POSITION: 0 },
+ },
+ },
+ },
+ ],
+ },
+ ],
+ },
+ );
+ const result = await GltfLoader.parseAsync(JSON.stringify(doc));
+ expect(result.meshes[0]!.positions.length).toBe(34834 * 3);
+ expect(result.meshes[0]!.indices.length).toBe(69451 * 3);
+ expect(result.bounds.size.every((v) => v > 0)).toBe(true);
+ });
+
+ it.each([
+ "EXT_meshopt_compression",
+ "KHR_meshopt_compression",
+ ])("decodes required %s vertex buffers asynchronously", async (extension) => {
+ await MeshoptEncoder.ready;
+ const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+ const compressed = MeshoptEncoder.encodeGltfBuffer(
+ new Uint8Array(positions.buffer),
+ 3,
+ 12,
+ "ATTRIBUTES",
+ extension.startsWith("KHR_") ? 1 : 0,
+ );
+ const doc = quadGltf(
+ {},
+ {
+ extensionsUsed: [extension],
+ extensionsRequired: [extension],
+ buffers: [
+ {
+ byteLength: compressed.length,
+ uri: `data:application/octet-stream;base64,${Buffer.from(compressed).toString("base64")}`,
+ },
+ ],
+ bufferViews: [
+ {
+ buffer: 0,
+ byteLength: positions.byteLength,
+ byteStride: 12,
+ extensions: {
+ [extension]: {
+ buffer: 0,
+ byteOffset: 0,
+ byteLength: compressed.length,
+ byteStride: 12,
+ count: 3,
+ mode: "ATTRIBUTES",
+ },
+ },
+ },
+ ],
+ accessors: [
+ { bufferView: 0, componentType: 5126, count: 3, type: "VEC3" },
+ ],
+ meshes: [{ primitives: [{ attributes: { POSITION: 0 } }] }],
+ },
+ );
+ const result = await GltfLoader.parseAsync(JSON.stringify(doc));
+ expect(Array.from(result.meshes[0]!.positions)).toEqual(
+ Array.from(positions),
+ );
+ });
+
+ it("applies sparse accessor values over an implicit zero base", () => {
+ const position = new Float32Array([7, 8, 9]);
+ const bytes = Buffer.concat([
+ Buffer.from([1, 0, 0, 0]),
+ Buffer.from(position.buffer),
+ ]);
+ const doc = quadGltf(
+ {},
+ {
+ buffers: [
+ {
+ byteLength: bytes.length,
+ uri: `data:application/octet-stream;base64,${bytes.toString("base64")}`,
+ },
+ ],
+ bufferViews: [
+ { buffer: 0, byteOffset: 0, byteLength: 1 },
+ { buffer: 0, byteOffset: 4, byteLength: 12 },
+ ],
+ accessors: [
+ {
+ componentType: 5126,
+ count: 3,
+ type: "VEC3",
+ sparse: {
+ count: 1,
+ indices: { bufferView: 0, componentType: 5121 },
+ values: { bufferView: 1 },
+ },
+ },
+ ],
+ meshes: [{ primitives: [{ attributes: { POSITION: 0 } }] }],
+ },
+ );
+ expect(Array.from(parse(doc).meshes[0]!.positions)).toEqual([
+ 0, 0, 0, 7, 8, 9, 0, 0, 0,
+ ]);
+ });
+
+ it("rejects unknown required extensions", () => {
+ for (const ext of ["VENDOR_unknown", "KHR_materials_transmission"]) {
+ expect(() => parse(quadGltf({}, { extensionsRequired: [ext] }))).toThrow(
+ ext,
+ );
+ }
+ });
+
+ it.each([
+ [5, [0, 1, 2, 2, 1, 3]],
+ [6, [0, 1, 2, 0, 2, 3]],
+ ])("expands triangle primitive mode %i", (mode, expected) => {
+ const doc = quadGltf(
+ {},
+ { meshes: [{ primitives: [{ attributes: { POSITION: 0 }, mode }] }] },
+ );
+ expect(Array.from(parse(doc).meshes[0]!.indices)).toEqual(expected);
+ });
+
+ it.each([
+ [0, "point-list", [0, 1, 2, 3]],
+ [1, "line-list", [0, 1, 2, 3]],
+ [2, "line-list", [0, 1, 1, 2, 2, 3, 3, 0]],
+ [3, "line-list", [0, 1, 1, 2, 2, 3]],
+ ] as const)("converts glTF primitive mode %i", (mode, topology, expected) => {
+ const doc = quadGltf(
+ {},
+ { meshes: [{ primitives: [{ attributes: { POSITION: 0 }, mode }] }] },
+ );
+ const mesh = parse(doc).meshes[0]!;
+ expect(mesh.topology).toBe(topology);
+ expect(Array.from(mesh.indices)).toEqual(expected);
});
it("loads a model from a bare relative path", () => {
diff --git a/packages/webgpu-renderers/src/loaders/gltf-loader.ts b/packages/webgpu-renderers/src/loaders/gltf-loader.ts
index 4d04e9e8..92525876 100644
--- a/packages/webgpu-renderers/src/loaders/gltf-loader.ts
+++ b/packages/webgpu-renderers/src/loaders/gltf-loader.ts
@@ -1,5 +1,7 @@
import fs from "node:fs";
import path from "node:path";
+import draco from "draco3dgltf";
+import { MeshoptDecoder } from "meshoptimizer/decoder";
import { type Mat4, Matrix4Math, type Vec3 } from "../math3d/index.js";
import { MAX_JOINTS, poseNodes } from "./pose.js";
import { textureMime } from "./texture-files.js";
@@ -69,6 +71,25 @@ interface GltfAccessor {
type: "SCALAR" | "VEC2" | "VEC3" | "VEC4" | "MAT2" | "MAT3" | "MAT4";
max?: number[];
min?: number[];
+ sparse?: {
+ count: number;
+ indices: {
+ bufferView: number;
+ byteOffset?: number;
+ componentType: 5121 | 5123 | 5125;
+ };
+ values: { bufferView: number; byteOffset?: number };
+ };
+}
+
+interface MeshoptExtension {
+ buffer: number;
+ byteOffset?: number;
+ byteLength: number;
+ byteStride: number;
+ count: number;
+ mode: "ATTRIBUTES" | "TRIANGLES" | "INDICES";
+ filter?: "NONE" | "OCTAHEDRAL" | "QUATERNION" | "EXPONENTIAL" | "COLOR";
}
interface GltfBufferView {
@@ -77,6 +98,10 @@ interface GltfBufferView {
byteLength: number;
byteStride?: number;
target?: number;
+ extensions?: {
+ EXT_meshopt_compression?: MeshoptExtension;
+ KHR_meshopt_compression?: MeshoptExtension;
+ };
}
interface GltfBuffer {
@@ -98,11 +123,22 @@ interface GltfPrimitive {
indices?: number;
material?: number;
mode?: number; // 4 = TRIANGLES
- extensions?: { KHR_draco_mesh_compression?: unknown };
+ targets?: { POSITION?: number; NORMAL?: number; TANGENT?: number }[];
+ extensions?: {
+ KHR_draco_mesh_compression?: {
+ bufferView: number;
+ attributes: Record<string, number>;
+ };
+ };
+ decodedDraco?: {
+ attributes: Record<number, Float32Array>;
+ indices: Uint16Array | Uint32Array;
+ };
}
interface GltfMesh {
name?: string;
+ weights?: number[];
primitives: GltfPrimitive[];
}
@@ -172,6 +208,7 @@ interface GltfNode {
skin?: number;
matrix?: number[];
mesh?: number;
+ weights?: number[];
rotation?: [number, number, number, number]; // [x, y, z, w] quaternion
scale?: [number, number, number];
translation?: [number, number, number];
@@ -223,19 +260,53 @@ interface GltfDocument {
buffers?: GltfBuffer[];
}
-/** Mesh compression the loader cannot decode: a file that requires it fails with a clear error. */
-const UNSUPPORTED_REQUIRED_EXTENSIONS: Record<string, string> = {
- KHR_draco_mesh_compression: "Draco mesh compression",
- EXT_meshopt_compression: "meshopt compression",
-};
+/** Required extensions whose semantics this loader implements. */
+const SUPPORTED_REQUIRED_EXTENSIONS = new Set([
+ "KHR_materials_unlit",
+ "KHR_materials_emissive_strength",
+ "KHR_texture_transform",
+ "KHR_texture_basisu",
+ "EXT_texture_webp",
+]);
-/**
- * The UV set and transform a material's textures share: the mesh's UVs are
- * read from that set with the transform baked in.
- */
-interface UvPlan {
- texCoord: number;
- transform?: GltfTextureTransform;
+/** Converts glTF's strip, loop and fan modes to GPU list primitives. */
+function expandPrimitive(
+ indices: Uint16Array | Uint32Array,
+ mode: number,
+): {
+ indices: Uint16Array | Uint32Array;
+ topology: "triangle-list" | "line-list" | "point-list";
+} {
+ if (mode === 0) return { indices, topology: "point-list" };
+ if (mode === 1) {
+ if (indices.length % 2 !== 0)
+ throw new Error("glTF LINES index count must be even");
+ return { indices, topology: "line-list" };
+ }
+ if (mode === 4) return { indices, topology: "triangle-list" };
+ if (![2, 3, 5, 6].includes(mode))
+ throw new Error(`Invalid glTF primitive mode ${mode}`);
+ const out: number[] = [];
+ if (mode === 2 || mode === 3) {
+ for (let i = 1; i < indices.length; i++)
+ out.push(indices[i - 1]!, indices[i]!);
+ if (mode === 2 && indices.length > 1)
+ out.push(indices[indices.length - 1]!, indices[0]!);
+ } else {
+ for (let i = 2; i < indices.length; i++) {
+ if (mode === 6) out.push(indices[0]!, indices[i - 1]!, indices[i]!);
+ else if (i % 2 === 0)
+ out.push(indices[i - 2]!, indices[i - 1]!, indices[i]!);
+ else out.push(indices[i - 1]!, indices[i - 2]!, indices[i]!);
+ }
+ }
+ return {
+ indices:
+ indices instanceof Uint32Array
+ ? Uint32Array.from(out)
+ : Uint16Array.from(out),
+ topology: mode <= 3 ? "line-list" : "triangle-list",
+ };
}
const GLB_MAGIC = 0x46546c67; // "glTF"
@@ -262,6 +333,258 @@ export class GltfLoader {
options: LoadModelOptions = {},
basePath?: string,
): Model3DData {
+ const { doc, binaryBuffers } = GltfLoader.readDocument(data, basePath);
+ GltfLoader.checkExtensions(doc);
+ for (const mesh of doc.meshes ?? []) {
+ for (const primitive of mesh.primitives) {
+ const compressed = primitive.extensions?.KHR_draco_mesh_compression;
+ if (!compressed) continue;
+ if (primitive.indices !== undefined) {
+ const indexAccessor = doc.accessors?.[primitive.indices];
+ if (
+ !indexAccessor ||
+ (indexAccessor.bufferView === undefined && !indexAccessor.sparse)
+ ) {
+ throw new Error(
+ "Draco indices without an uncompressed fallback require GltfLoader.parseAsync",
+ );
+ }
+ }
+ for (const semantic of Object.keys(compressed.attributes)) {
+ const index = (
+ primitive.attributes as Record<string, number | undefined>
+ )[semantic];
+ const accessor =
+ index === undefined ? undefined : doc.accessors?.[index];
+ if (
+ !accessor ||
+ (accessor.bufferView === undefined && !accessor.sparse)
+ ) {
+ throw new Error(
+ "Draco geometry without an uncompressed fallback requires GltfLoader.parseAsync",
+ );
+ }
+ }
+ }
+ }
+ return GltfLoader.buildModel(doc, binaryBuffers, options, basePath);
+ }
+
+ /** Asynchronous import initializes WASM decoders before reading compressed buffers. */
+ public static async parseAsync(
+ data: string | Uint8Array | ArrayBuffer,
+ options: LoadModelOptions = {},
+ basePath?: string,
+ ): Promise<Model3DData> {
+ const { doc, binaryBuffers } = GltfLoader.readDocument(data, basePath);
+ GltfLoader.checkExtensions(
+ doc,
+ new Set([
+ "EXT_meshopt_compression",
+ "KHR_meshopt_compression",
+ "KHR_draco_mesh_compression",
+ ]),
+ );
+ await GltfLoader.decodeMeshopt(doc, binaryBuffers);
+ await GltfLoader.decodeDraco(doc, binaryBuffers);
+ return GltfLoader.buildModel(doc, binaryBuffers, options, basePath);
+ }
+
+ private static checkExtensions(
+ doc: GltfDocument,
+ extra: Set<string> = new Set(),
+ ): void {
+ for (const ext of doc.extensionsRequired ?? []) {
+ if (!SUPPORTED_REQUIRED_EXTENSIONS.has(ext) && !extra.has(ext)) {
+ throw new Error(
+ `glTF file requires ${ext}, which framefields cannot decode or render`,
+ );
+ }
+ }
+ }
+
+ private static async decodeMeshopt(
+ doc: GltfDocument,
+ buffers: Uint8Array[],
+ ): Promise<void> {
+ const views = (doc.bufferViews ?? []).filter(
+ (view) =>
+ view.extensions?.EXT_meshopt_compression ||
+ view.extensions?.KHR_meshopt_compression,
+ );
+ if (!views.length) return;
+ await MeshoptDecoder.ready;
+ for (const view of views) {
+ if (
+ view.extensions?.EXT_meshopt_compression &&
+ view.extensions?.KHR_meshopt_compression
+ ) {
+ throw new Error(
+ "A buffer view cannot use both EXT and KHR meshopt compression",
+ );
+ }
+ const ext =
+ view.extensions?.KHR_meshopt_compression ??
+ view.extensions?.EXT_meshopt_compression;
+ if (!ext) continue;
+ const source = buffers[ext.buffer];
+ if (!source) throw new Error(`meshopt buffer ${ext.buffer} not loaded`);
+ const offset = ext.byteOffset ?? 0;
+ if (
+ offset < 0 ||
+ ext.byteLength < 0 ||
+ offset + ext.byteLength > source.byteLength
+ )
+ throw new Error("Invalid meshopt compressed buffer range");
+ const length = ext.count * ext.byteStride;
+ if (
+ !Number.isSafeInteger(ext.count) ||
+ ext.count < 0 ||
+ !Number.isSafeInteger(ext.byteStride) ||
+ ext.byteStride < 1 ||
+ !Number.isSafeInteger(length) ||
+ length !== view.byteLength
+ ) {
+ throw new Error("Invalid meshopt decoded buffer length");
+ }
+ if (
+ !["ATTRIBUTES", "TRIANGLES", "INDICES"].includes(ext.mode) ||
+ !["NONE", "OCTAHEDRAL", "QUATERNION", "EXPONENTIAL", "COLOR"].includes(
+ ext.filter ?? "NONE",
+ )
+ ) {
+ throw new Error("Invalid meshopt compression mode or filter");
+ }
+ const decoded = new Uint8Array(length);
+ MeshoptDecoder.decodeGltfBuffer(
+ decoded,
+ ext.count,
+ ext.byteStride,
+ source.subarray(offset, offset + ext.byteLength),
+ ext.mode,
+ ext.filter ?? "NONE",
+ );
+ view.buffer = buffers.length;
+ view.byteOffset = 0;
+ buffers.push(decoded);
+ }
+ }
+
+ private static async decodeDraco(
+ doc: GltfDocument,
+ buffers: Uint8Array[],
+ ): Promise<void> {
+ const primitives = (doc.meshes ?? [])
+ .flatMap((mesh) => mesh.primitives)
+ .filter((primitive) => primitive.extensions?.KHR_draco_mesh_compression);
+ if (!primitives.length) return;
+ const module = await draco.createDecoderModule({});
+ const decoder = new module.Decoder();
+ try {
+ for (const primitive of primitives) {
+ const ext = primitive.extensions?.KHR_draco_mesh_compression;
+ if (!ext) continue;
+ const view = doc.bufferViews?.[ext.bufferView];
+ if (!view)
+ throw new Error(`Draco bufferView ${ext.bufferView} not found`);
+ const source = buffers[view.buffer];
+ if (!source) throw new Error(`Draco buffer ${view.buffer} not loaded`);
+ const offset = view.byteOffset ?? 0;
+ if (offset < 0 || offset + view.byteLength > source.byteLength)
+ throw new Error("Invalid Draco buffer range");
+ const compressed = source.subarray(offset, offset + view.byteLength);
+ const input = new module.DecoderBuffer();
+ const mesh = new module.Mesh();
+ try {
+ input.Init(
+ new Int8Array(
+ compressed.buffer,
+ compressed.byteOffset,
+ compressed.byteLength,
+ ),
+ compressed.byteLength,
+ );
+ if (decoder.GetEncodedGeometryType(input) !== module.TRIANGULAR_MESH)
+ throw new Error("Draco primitive is not a triangular mesh");
+ const status = decoder.DecodeBufferToMesh(input, mesh);
+ const success = status.ok();
+ const message = success ? "" : status.error_msg();
+ module.destroy(status);
+ if (!success) throw new Error(`Draco decode failed: ${message}`);
+ const attributes: Record<number, Float32Array> = {};
+ for (const [semantic, id] of Object.entries(ext.attributes)) {
+ const accessorIndex = (
+ primitive.attributes as Record<string, number | undefined>
+ )[semantic];
+ const accessor =
+ accessorIndex === undefined
+ ? undefined
+ : doc.accessors?.[accessorIndex];
+ if (accessorIndex === undefined || !accessor)
+ throw new Error(`Draco ${semantic} accessor not found`);
+ const attribute = decoder.GetAttributeByUniqueId(mesh, id);
+ if (!attribute)
+ throw new Error(`Draco ${semantic} attribute ${id} not found`);
+ const array = new module.DracoFloat32Array();
+ try {
+ if (
+ !decoder.GetAttributeFloatForAllPoints(mesh, attribute, array)
+ )
+ throw new Error(`Failed to decode Draco ${semantic}`);
+ const count =
+ mesh.num_points() * (COMPONENTS[accessor.type] ?? 1);
+ if (
+ accessor.count !== mesh.num_points() ||
+ array.size() !== count
+ )
+ throw new Error(`Invalid Draco ${semantic} attribute size`);
+ const values = new Float32Array(count);
+ for (let i = 0; i < count; i++) {
+ let value = array.GetValue(i);
+ if (accessor.normalized) {
+ if (accessor.componentType === 5120)
+ value = Math.max(value / 127, -1);
+ else if (accessor.componentType === 5121) value /= 255;
+ else if (accessor.componentType === 5122)
+ value = Math.max(value / 32767, -1);
+ else if (accessor.componentType === 5123) value /= 65535;
+ }
+ values[i] = value;
+ }
+ attributes[accessorIndex] = values;
+ } finally {
+ module.destroy(array);
+ }
+ }
+ const indices =
+ mesh.num_points() > 65535
+ ? new Uint32Array(mesh.num_faces() * 3)
+ : new Uint16Array(mesh.num_faces() * 3);
+ const face = new module.DracoInt32Array();
+ try {
+ for (let i = 0; i < mesh.num_faces(); i++) {
+ if (!decoder.GetFaceFromMesh(mesh, i, face))
+ throw new Error(`Failed to decode Draco face ${i}`);
+ for (let j = 0; j < 3; j++) indices[i * 3 + j] = face.GetValue(j);
+ }
+ } finally {
+ module.destroy(face);
+ }
+ primitive.decodedDraco = { attributes, indices };
+ } finally {
+ module.destroy(mesh);
+ module.destroy(input);
+ }
+ }
+ } finally {
+ module.destroy(decoder);
+ }
+ }
+
+ private static readDocument(
+ data: string | Uint8Array | ArrayBuffer,
+ basePath?: string,
+ ): { doc: GltfDocument; binaryBuffers: Uint8Array[] } {
let doc: GltfDocument;
const binaryBuffers: Uint8Array[] = [];
@@ -320,15 +643,7 @@ export class GltfLoader {
}
}
- for (const ext of doc.extensionsRequired ?? []) {
- const what = UNSUPPORTED_REQUIRED_EXTENSIONS[ext];
- if (what)
- throw new Error(
- `glTF file requires ${ext} (${what}), which framefields cannot decode. Re-export the model without mesh compression (in Blender's glTF exporter, turn off Compression).`,
- );
- }
-
- return GltfLoader.buildModel(doc, binaryBuffers, options, basePath);
+ return { doc, binaryBuffers };
}
private static unpackGlb(bytes: Uint8Array): {
@@ -384,22 +699,62 @@ export class GltfLoader {
if (!accessor) throw new Error(`Accessor ${accessorIndex} not found`);
const itemSize = COMPONENTS[accessor.type] ?? 1;
const out = new Float32Array(accessor.count * itemSize);
- if (accessor.bufferView === undefined)
- return { data: out, itemSize, count: accessor.count };
-
- const view = doc.bufferViews?.[accessor.bufferView];
- if (!view) throw new Error(`BufferView ${accessor.bufferView} not found`);
- const raw = binaryBuffers[view.buffer];
- if (!raw) throw new Error(`Binary buffer ${view.buffer} not loaded`);
-
const bytes = COMPONENT_BYTES[accessor.componentType] ?? 4;
- const stride = view.byteStride ?? bytes * itemSize;
- const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
- const base = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
const read = componentReader(accessor.componentType, accessor.normalized);
- for (let i = 0; i < accessor.count; i++) {
- for (let c = 0; c < itemSize; c++) {
- out[i * itemSize + c] = read(dv, base + i * stride + c * bytes);
+ if (accessor.bufferView !== undefined) {
+ const view = doc.bufferViews?.[accessor.bufferView];
+ if (!view) throw new Error(`BufferView ${accessor.bufferView} not found`);
+ const raw = binaryBuffers[view.buffer];
+ if (!raw) throw new Error(`Binary buffer ${view.buffer} not loaded`);
+ const stride = view.byteStride ?? bytes * itemSize;
+ const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+ const base = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+ for (let i = 0; i < accessor.count; i++) {
+ for (let c = 0; c < itemSize; c++)
+ out[i * itemSize + c] = read(dv, base + i * stride + c * bytes);
+ }
+ }
+ if (accessor.sparse) {
+ const sparse = accessor.sparse;
+ const indexView = doc.bufferViews?.[sparse.indices.bufferView];
+ const valueView = doc.bufferViews?.[sparse.values.bufferView];
+ if (!indexView || !valueView)
+ throw new Error(
+ `Sparse accessor ${accessorIndex} references a missing buffer view`,
+ );
+ const indexData = binaryBuffers[indexView.buffer];
+ const valueData = binaryBuffers[valueView.buffer];
+ if (!indexData || !valueData)
+ throw new Error(
+ `Sparse accessor ${accessorIndex} references a missing buffer`,
+ );
+ const indexReader = componentReader(sparse.indices.componentType);
+ const indexBytes = COMPONENT_BYTES[sparse.indices.componentType];
+ const indexDv = new DataView(
+ indexData.buffer,
+ indexData.byteOffset,
+ indexData.byteLength,
+ );
+ const valueDv = new DataView(
+ valueData.buffer,
+ valueData.byteOffset,
+ valueData.byteLength,
+ );
+ const indexBase =
+ (indexView.byteOffset ?? 0) + (sparse.indices.byteOffset ?? 0);
+ const valueBase =
+ (valueView.byteOffset ?? 0) + (sparse.values.byteOffset ?? 0);
+ for (let i = 0; i < sparse.count; i++) {
+ const index = indexReader(indexDv, indexBase + i * indexBytes);
+ if (index >= accessor.count)
+ throw new Error(
+ `Sparse accessor ${accessorIndex} index ${index} is out of range`,
+ );
+ for (let c = 0; c < itemSize; c++)
+ out[index * itemSize + c] = read(
+ valueDv,
+ valueBase + (i * itemSize + c) * bytes,
+ );
}
}
return { data: out, itemSize, count: accessor.count };
@@ -472,27 +827,9 @@ export class GltfLoader {
);
}
- /** The UV set and transform of the material's base color map (else its first map). */
- private static uvPlan(mat: GltfMaterial | undefined): UvPlan {
- const first = [
- mat?.pbrMetallicRoughness?.baseColorTexture,
- mat?.normalTexture,
- mat?.pbrMetallicRoughness?.metallicRoughnessTexture,
- mat?.occlusionTexture,
- mat?.emissiveTexture,
- ].find((t) => t !== undefined);
- return first
- ? {
- texCoord: GltfLoader.texCoordOf(first),
- transform: first.extensions?.KHR_texture_transform,
- }
- : { texCoord: 0 };
- }
-
/**
* A texture's decodable image: EXT_texture_webp's source when present.
- * KTX2 / Basis (KHR_texture_basisu) and other formats the renderer
- * cannot decode are skipped with a warning.
+ * Basis KTX2 and EXT_texture_webp override a texture's fallback source.
*/
private static textureImage(
doc: GltfDocument,
@@ -504,14 +841,10 @@ export class GltfLoader {
const texture = doc.textures?.[textureIndex];
if (!texture) return undefined;
const source =
- texture.extensions?.EXT_texture_webp?.source ?? texture.source;
- if (source === undefined) {
- if (texture.extensions?.KHR_texture_basisu)
- GltfLoader.warn(
- `${label} is a KTX2 / Basis texture, which framefields cannot decode; it is skipped (use PNG, JPEG or WebP).`,
- );
- return undefined;
- }
+ texture.extensions?.KHR_texture_basisu?.source ??
+ texture.extensions?.EXT_texture_webp?.source ??
+ texture.source;
+ if (source === undefined) return undefined;
const image = GltfLoader.imageBytes(doc, binaryBuffers, source, basePath);
if (!image) return undefined;
if (!SUPPORTED_IMAGE_MIMES.has(image.mime)) {
@@ -564,29 +897,14 @@ export class GltfLoader {
} else if (mat.extensions?.KHR_materials_unlit) {
material.shading = "unlit";
}
- // Every map is sampled with the mesh's one UV set (see uvPlan).
- const plan = GltfLoader.uvPlan(mat);
const image = (info: GltfTextureInfo | undefined, slot: string) => {
if (!info) return undefined;
- const label = `The ${slot} map of material "${name}"`;
- const set = GltfLoader.texCoordOf(info);
- if (set !== plan.texCoord) {
- GltfLoader.warn(
- `${label} uses UV set ${set}, but the mesh draws with UV set ${plan.texCoord}; the map is skipped.`,
- );
- return undefined;
- }
- const t = info.extensions?.KHR_texture_transform;
- if (JSON.stringify(t ?? null) !== JSON.stringify(plan.transform ?? null))
- GltfLoader.warn(
- `${label} has a different KHR_texture_transform than the mesh's first map; it is drawn with that one's.`,
- );
return GltfLoader.textureImage(
doc,
binaryBuffers,
info.index,
basePath,
- label,
+ `The ${slot} map of material "${name}"`,
);
};
const base = image(pbr?.baseColorTexture, "base color");
@@ -653,8 +971,7 @@ export class GltfLoader {
for (const chan of animDef.channels) {
const sampler = animDef.samplers[chan.sampler];
const node = chan.target.node;
- if (!sampler || node === undefined || chan.target.path === "weights")
- continue;
+ if (!sampler || node === undefined) continue;
const times = GltfLoader.readFloats(
doc,
binaryBuffers,
@@ -679,7 +996,8 @@ export class GltfLoader {
};
if (chan.target.path === "translation") track.translations = values;
else if (chan.target.path === "rotation") track.rotations = values;
- else track.scales = values;
+ else if (chan.target.path === "scale") track.scales = values;
+ else track.weights = values;
tracks.push(track);
}
return {
@@ -717,8 +1035,6 @@ export class GltfLoader {
);
});
- const uvPlans = (doc.materials ?? []).map((mat) => GltfLoader.uvPlan(mat));
-
const nodes = GltfLoader.buildNodes(doc);
const skins = (doc.skins ?? []).map((skin) => ({
joints: skin.joints,
@@ -777,26 +1093,69 @@ export class GltfLoader {
const meshDef = doc.meshes?.[inst.mesh];
if (!meshDef) continue;
meshDef.primitives.forEach((prim, primIdx) => {
- if (prim.attributes.POSITION === undefined) return;
- if (prim.mode !== undefined && prim.mode !== 4) return;
- const read = (acc: number | undefined) =>
- acc === undefined
- ? undefined
- : GltfLoader.readFloats(doc, binaryBuffers, acc);
+ if (prim.attributes.POSITION === undefined) {
+ throw new Error(
+ `glTF mesh ${inst.mesh} primitive ${primIdx} has no POSITION attribute`,
+ );
+ }
+ const read = (acc: number | undefined) => {
+ if (acc === undefined) return undefined;
+ const data = prim.decodedDraco?.attributes[acc];
+ if (!data) return GltfLoader.readFloats(doc, binaryBuffers, acc);
+ const accessor = doc.accessors?.[acc];
+ if (!accessor) throw new Error(`Accessor ${acc} not found`);
+ return {
+ data,
+ itemSize: COMPONENTS[accessor.type] ?? 1,
+ count: accessor.count,
+ };
+ };
const pos = read(prim.attributes.POSITION)!;
const numVerts = pos.count;
- const plan =
- prim.material !== undefined ? uvPlans[prim.material] : undefined;
+ const mat =
+ prim.material === undefined
+ ? undefined
+ : doc.materials?.[prim.material];
const attributes = prim.attributes as Record<
string,
number | undefined
>;
+ const mapUv = (
+ info: GltfTextureInfo | undefined,
+ ): Float32Array | undefined => {
+ if (!info) return undefined;
+ const set = GltfLoader.texCoordOf(info);
+ const accessor = attributes[`TEXCOORD_${set}`];
+ if (accessor === undefined)
+ throw new Error(
+ `glTF mesh ${inst.mesh} primitive ${primIdx} lacks TEXCOORD_${set} required by a texture`,
+ );
+ const uv = read(accessor);
+ if (!uv)
+ throw new Error(
+ `glTF mesh ${inst.mesh} has missing texture coordinates`,
+ );
+ if (uv.itemSize !== 2 || uv.count !== numVerts)
+ throw new Error(
+ `Invalid TEXCOORD_${set} on glTF mesh ${inst.mesh} primitive ${primIdx}`,
+ );
+ const transform = info.extensions?.KHR_texture_transform;
+ if (transform) applyTextureTransform(uv.data, transform);
+ return uv.data;
+ };
const uvs =
- read(attributes[`TEXCOORD_${plan?.texCoord ?? 0}`])?.data ??
+ mapUv(mat?.pbrMetallicRoughness?.baseColorTexture) ??
read(prim.attributes.TEXCOORD_0)?.data ??
new Float32Array(numVerts * 2);
- if (plan?.transform) applyTextureTransform(uvs, plan.transform);
+ const mapUvs = {
+ normal: mapUv(mat?.normalTexture),
+ metallicRoughness: mapUv(
+ mat?.pbrMetallicRoughness?.metallicRoughnessTexture,
+ ),
+ occlusion: mapUv(mat?.occlusionTexture),
+ emissive: mapUv(mat?.emissiveTexture),
+ };
const colors = read(prim.attributes.COLOR_0);
let rgba: Float32Array | undefined;
if (colors) {
@@ -810,7 +1169,9 @@ export class GltfLoader {
}
let indices: Uint16Array | Uint32Array;
- if (prim.indices !== undefined) {
+ if (prim.decodedDraco) {
+ indices = prim.decodedDraco.indices;
+ } else if (prim.indices !== undefined) {
indices = GltfLoader.readIndices(doc, binaryBuffers, prim.indices);
} else {
indices =
@@ -820,6 +1181,9 @@ export class GltfLoader {
for (let i = 0; i < numVerts; i++) indices[i] = i;
}
+ const primitive = expandPrimitive(indices, prim.mode ?? 4);
+ indices = primitive.indices;
+
// Skinned vertices are in bind (model) space; others sit under their node.
const skinned =
inst.skin !== undefined && prim.attributes.JOINTS_0 !== undefined;
@@ -835,6 +1199,27 @@ export class GltfLoader {
} else grow(x, y, z);
}
+ const morphTargets = prim.targets?.map((target) => {
+ const positions = read(target.POSITION);
+ const normals = read(target.NORMAL);
+ if (
+ (positions &&
+ (positions.count !== numVerts || positions.itemSize !== 3)) ||
+ (normals && (normals.count !== numVerts || normals.itemSize !== 3))
+ ) {
+ throw new Error(
+ `Invalid morph target on glTF mesh ${inst.mesh} primitive ${primIdx}`,
+ );
+ }
+ return { positions: positions?.data, normals: normals?.data };
+ });
+ const defaultWeights =
+ (inst.node === undefined
+ ? undefined
+ : doc.nodes?.[inst.node]?.weights) ?? meshDef.weights;
+ const morphWeights = morphTargets?.map(
+ (_, i) => defaultWeights?.[i] ?? 0,
+ );
model.meshes.push({
id: `gltf_mesh_${inst.mesh}_${primIdx}${inst.node !== undefined ? `_n${inst.node}` : ""}`,
name: meshDef.name ?? `Mesh_${inst.mesh}`,
@@ -843,6 +1228,9 @@ export class GltfLoader {
read(prim.attributes.NORMAL)?.data ??
new Float32Array(numVerts * 3),
uvs,
+ mapUvs,
+ morphTargets,
+ morphWeights,
colors: rgba,
jointIndices: skinned
? read(prim.attributes.JOINTS_0)?.data
@@ -851,6 +1239,7 @@ export class GltfLoader {
? read(prim.attributes.WEIGHTS_0)?.data
: undefined,
indices,
+ topology: primitive.topology,
materialName:
prim.material !== undefined
? materialKeys[prim.material]
@@ -927,6 +1316,25 @@ export class GltfLoader {
/**
* Loads a glTF / GLB file synchronously or asynchronously from a path or URL.
*/
+ public static async loadAsync(
+ srcOrData: string | ArrayBuffer | Uint8Array,
+ options: LoadModelOptions = {},
+ ): Promise<Model3DData> {
+ if (typeof srcOrData !== "string")
+ return GltfLoader.parseAsync(srcOrData, options);
+ const cleanPath = srcOrData.startsWith("file://")
+ ? srcOrData.replace("file://", "")
+ : srcOrData;
+ if (!srcOrData.trimStart().startsWith("{") && fs.existsSync(cleanPath)) {
+ return GltfLoader.parseAsync(
+ fs.readFileSync(cleanPath),
+ options,
+ path.dirname(cleanPath),
+ );
+ }
+ return GltfLoader.parseAsync(srcOrData, options);
+ }
+
public static load(
srcOrData: string | ArrayBuffer | Uint8Array,
options: LoadModelOptions = {},
@@ -969,6 +1377,13 @@ export function loadGLTF(
return GltfLoader.load(srcOrData, options);
}
+export async function loadGLTFAsync(
+ srcOrData: string | ArrayBuffer | Uint8Array,
+ options: LoadModelOptions = {},
+): Promise<Model3DData> {
+ return GltfLoader.loadAsync(srcOrData, options);
+}
+
export function parseGLB(
data: Uint8Array | ArrayBuffer,
options: LoadModelOptions = {},
@@ -996,6 +1411,7 @@ const SUPPORTED_IMAGE_MIMES = new Set([
"image/gif",
"image/tiff",
"image/avif",
+ "image/ktx2",
]);
/**
@@ -1011,7 +1427,7 @@ function applyTextureTransform(
for (let i = 0; i < uvs.length; i += 2) {
const u = uvs[i]! * scale[0];
const v = uvs[i + 1]! * scale[1];
- uvs[i] = c * u + s * v + offset[0];
- uvs[i + 1] = -s * u + c * v + offset[1];
+ uvs[i] = c * u - s * v + offset[0];
+ uvs[i + 1] = s * u + c * v + offset[1];
}
}
diff --git a/packages/webgpu-renderers/src/loaders/morph.test.ts b/packages/webgpu-renderers/src/loaders/morph.test.ts
new file mode 100644
index 00000000..e27f37ec
--- /dev/null
+++ b/packages/webgpu-renderers/src/loaders/morph.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { sampleMorphWeights } from "./pose.js";
+import type { AnimationClip3D, Mesh3DData } from "./types.js";
+
+const mesh: Mesh3DData = {
+ positions: new Float32Array(3),
+ normals: new Float32Array(3),
+ uvs: new Float32Array(2),
+ indices: new Uint16Array(),
+ node: 1,
+ morphTargets: [{}, {}, {}, {}],
+ morphWeights: [0.1, 0.2, 0.3, 0.4],
+};
+function clip(
+ interpolation: "linear" | "step" | "cubic",
+ values: number[],
+): AnimationClip3D {
+ return {
+ name: "clip",
+ duration: 1,
+ fps: 30,
+ tracks: [
+ {
+ nodeName: "mesh",
+ node: 1,
+ times: new Float32Array([0, 1]),
+ weights: new Float32Array(values),
+ interpolation,
+ },
+ ],
+ };
+}
+describe("morph weight animation", () => {
+ it("uses the mesh instance defaults without a track", () => {
+ expect(sampleMorphWeights(mesh, undefined, 0)).toEqual([
+ 0.1, 0.2, 0.3, 0.4,
+ ]);
+ });
+ it("interpolates four weights independently, not as a quaternion", () => {
+ const animation = clip("linear", [0, 0, 0, 0, 1, 1, 1, 1]);
+ expect(sampleMorphWeights(mesh, animation, 0.5)).toEqual([
+ 0.5, 0.5, 0.5, 0.5,
+ ]);
+ });
+ it("holds STEP and evaluates CUBICSPLINE weights", () => {
+ expect(
+ sampleMorphWeights(mesh, clip("step", [0, 0, 0, 0, 1, 1, 1, 1]), 0.5),
+ ).toEqual([0, 0, 0, 0]);
+ const values = [
+ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0,
+ ];
+ expect(sampleMorphWeights(mesh, clip("cubic", values), 0.5)).toEqual([
+ 0.5, 0.5, 0.5, 0.5,
+ ]);
+ });
+});
diff --git a/packages/webgpu-renderers/src/loaders/pose.ts b/packages/webgpu-renderers/src/loaders/pose.ts
index c340f572..34564b6e 100644
--- a/packages/webgpu-renderers/src/loaders/pose.ts
+++ b/packages/webgpu-renderers/src/loaders/pose.ts
@@ -7,6 +7,7 @@
import { type Mat4, Matrix4Math, type Vec3 } from "../math3d/index.js";
import type {
AnimationClip3D,
+ Mesh3DData,
Model3DData,
ModelNode3D,
NodeAnimationTrack3D,
@@ -107,6 +108,7 @@ function sampleChannel(
values: Float32Array,
size: number,
time: number,
+ quaternion = false,
): number[] {
const { times } = track;
const cubic = track.interpolation === "cubic";
@@ -133,12 +135,28 @@ function sampleChannel(
(-2 * u3 + 3 * u2) * (b[i] ?? 0) +
(u3 - u2) * dt * (inB[i] ?? 0),
);
- return size === 4 ? normalizeQuat(out as Quat) : out;
+ return quaternion ? normalizeQuat(out as Quat) : out;
}
- if (size === 4) return slerp(a as Quat, b as Quat, u);
+ if (quaternion) return slerp(a as Quat, b as Quat, u);
return a.map((v, i) => v + ((b[i] ?? v) - v) * u);
}
+/** Samples per-instance glTF morph weights without quaternion interpolation. */
+export function sampleMorphWeights(
+ mesh: Mesh3DData,
+ clip: AnimationClip3D | undefined,
+ time: number,
+): number[] {
+ const count = mesh.morphTargets?.length ?? 0;
+ if (!count) return [];
+ const track = clip?.tracks.find(
+ (t) => t.node === mesh.node && t.weights && t.times.length > 0,
+ );
+ return track?.weights
+ ? sampleChannel(track, track.weights, count, time)
+ : (mesh.morphWeights ?? Array(count).fill(0));
+}
+
/** Each node's local matrix with the clip's tracks applied at `time` (seconds). */
function localMatrices(
nodes: ModelNode3D[],
@@ -155,8 +173,9 @@ function localMatrices(
if (track.translations)
t[i] = sampleChannel(track, track.translations, 3, time) as Vec3;
if (track.rotations)
- r[i] = sampleChannel(track, track.rotations, 4, time) as Quat;
- if (track.scales) s[i] = sampleChannel(track, track.scales, 3, time) as Vec3;
+ r[i] = sampleChannel(track, track.rotations, 4, time, true) as Quat;
+ if (track.scales)
+ s[i] = sampleChannel(track, track.scales, 3, time) as Vec3;
}
return nodes.map((n, i) => n.matrix ?? trsMatrix(t[i]!, r[i]!, s[i]!));
}
diff --git a/packages/webgpu-renderers/src/loaders/texture-files.ts b/packages/webgpu-renderers/src/loaders/texture-files.ts
index ea0aad16..140b7e3c 100644
--- a/packages/webgpu-renderers/src/loaders/texture-files.ts
+++ b/packages/webgpu-renderers/src/loaders/texture-files.ts
@@ -3,6 +3,7 @@ import path from "node:path";
/** The texture formats the renderer decodes (sharp); others (TGA, BMP, PSD, DDS, …) are skipped. */
const MIME_BY_EXT: Record<string, string> = {
+ ".ktx2": "image/ktx2",
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
diff --git a/packages/webgpu-renderers/src/loaders/types.ts b/packages/webgpu-renderers/src/loaders/types.ts
index ffa0bcce..5841b5c8 100644
--- a/packages/webgpu-renderers/src/loaders/types.ts
+++ b/packages/webgpu-renderers/src/loaders/types.ts
@@ -5,8 +5,21 @@ export interface Mesh3DData {
name?: string;
positions: Float32Array; // 3 floats per vertex (x, y, z)
normals: Float32Array; // 3 floats per vertex (nx, ny, nz)
- uvs: Float32Array; // 2 floats per vertex (u, v)
+ uvs: Float32Array; // 2 floats per vertex (u, v), for the base color map
+ /** Object-space morph deltas, applied before skinning. */
+ morphTargets?: { positions?: Float32Array; normals?: Float32Array }[];
+ /** Default morph weights for this mesh instance. */
+ morphWeights?: number[];
+ /** Per-map UVs, with the map's own texture transform already applied. */
+ mapUvs?: {
+ normal?: Float32Array;
+ metallicRoughness?: Float32Array;
+ occlusion?: Float32Array;
+ emissive?: Float32Array;
+ };
indices: Uint16Array | Uint32Array;
+ /** GPU primitive topology; defaults to triangles. */
+ topology?: "triangle-list" | "line-list" | "point-list";
colors?: Float32Array; // 4 floats per vertex (r, g, b, a), display (sRGB) 0..1; multiplies the base color
tangents?: Float32Array; // 4 floats per vertex (x, y, z, w)
// Skinned Mesh / Skeletal Animation attributes
@@ -109,6 +122,7 @@ export interface NodeAnimationTrack3D {
translations?: Float32Array; // 3 floats per keyframe [x, y, z]
rotations?: Float32Array; // 4 floats per keyframe [x, y, z, w] quaternion or Euler [rx, ry, rz]
scales?: Float32Array; // 3 floats per keyframe [sx, sy, sz]
+ weights?: Float32Array; // morph weights, target count values per keyframe
/** "cubic" (glTF CUBICSPLINE) stores [inTangent, value, outTangent] per keyframe. */
interpolation?: "linear" | "step" | "cubic";
}
diff --git a/packages/webgpu-renderers/src/renderer3d/fixtures/etc1s-alpha.ktx2 b/packages/webgpu-renderers/src/renderer3d/fixtures/etc1s-alpha.ktx2
new file mode 100644
index 00000000..6cf4f491
Binary files /dev/null and b/packages/webgpu-renderers/src/renderer3d/fixtures/etc1s-alpha.ktx2 differ
diff --git a/packages/webgpu-renderers/src/renderer3d/fixtures/etc1s.ktx2 b/packages/webgpu-renderers/src/renderer3d/fixtures/etc1s.ktx2
new file mode 100644
index 00000000..d775071e
Binary files /dev/null and b/packages/webgpu-renderers/src/renderer3d/fixtures/etc1s.ktx2 differ
diff --git a/packages/webgpu-renderers/src/renderer3d/fixtures/uastc-ldr.ktx2 b/packages/webgpu-renderers/src/renderer3d/fixtures/uastc-ldr.ktx2
new file mode 100644
index 00000000..aeec0185
Binary files /dev/null and b/packages/webgpu-renderers/src/renderer3d/fixtures/uastc-ldr.ktx2 differ
diff --git a/packages/webgpu-renderers/src/renderer3d/ktx2.test.ts b/packages/webgpu-renderers/src/renderer3d/ktx2.test.ts
new file mode 100644
index 00000000..c9834a6c
--- /dev/null
+++ b/packages/webgpu-renderers/src/renderer3d/ktx2.test.ts
@@ -0,0 +1,30 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+import { decodeKtx2, isKtx2 } from "./ktx2.js";
+
+describe("KTX2 Basis transcoding", () => {
+ it.each([
+ "etc1s",
+ "uastc-ldr",
+ ])("decodes %s and all mip levels offline", async (format) => {
+ const bytes = await readFile(
+ new URL(`./fixtures/${format}.ktx2`, import.meta.url),
+ );
+ expect(isKtx2(bytes)).toBe(true);
+ const image = await decodeKtx2(bytes);
+ expect([image.width, image.height]).toEqual([16, 16]);
+ expect(image.levels.map((level) => level.length)).toEqual([
+ 1024, 256, 64, 16, 4,
+ ]);
+ expect(image.levels[0]?.[0]).toBeGreaterThan(180);
+ expect(image.levels[0]?.[1]).toBeLessThan(60);
+ });
+ it("preserves ETC1S alpha", async () => {
+ const bytes = await readFile(
+ new URL("./fixtures/etc1s-alpha.ktx2", import.meta.url),
+ );
+ const image = await decodeKtx2(bytes);
+ expect(image.levels[0]?.[3]).toBeGreaterThan(115);
+ expect(image.levels[0]?.[3]).toBeLessThan(140);
+ });
+});
diff --git a/packages/webgpu-renderers/src/renderer3d/ktx2.ts b/packages/webgpu-renderers/src/renderer3d/ktx2.ts
new file mode 100644
index 00000000..5c32ea00
--- /dev/null
+++ b/packages/webgpu-renderers/src/renderer3d/ktx2.ts
@@ -0,0 +1,40 @@
+import {
+ KTX2_IDENTIFIER,
+ parseKtx2,
+ transcodeKtx2,
+} from "@forgeax/engine-codec";
+
+export function isKtx2(bytes: Uint8Array): boolean {
+ return (
+ bytes.length >= KTX2_IDENTIFIER.length &&
+ KTX2_IDENTIFIER.every((byte, i) => bytes[i] === byte)
+ );
+}
+
+/** Transcodes Basis KTX2 to portable RGBA8 mip levels for any WebGPU device. */
+export async function decodeKtx2(
+ bytes: Uint8Array,
+): Promise<{ width: number; height: number; levels: Uint8Array[] }> {
+ const parsed = await parseKtx2(bytes);
+ if (!parsed.ok) throw new Error(`KTX2 parse failed: ${parsed.error.code}`);
+ const { pixelDepth, layerCount, faceCount } = parsed.value.header;
+ if (pixelDepth > 1 || layerCount > 1 || faceCount !== 1)
+ throw new Error("Only 2D KTX2 textures are supported");
+ const decoded = await transcodeKtx2(parsed.value, "rgba8unorm");
+ if (!decoded.ok)
+ throw new Error(`KTX2 transcode failed: ${decoded.error.code}`);
+ const { width, height, mips } = decoded.value;
+ if (
+ !mips.length ||
+ mips.some(
+ (mip, i) =>
+ mip.level !== i ||
+ mip.width !== Math.max(1, width >> i) ||
+ mip.height !== Math.max(1, height >> i) ||
+ mip.data.length !== mip.width * mip.height * 4,
+ )
+ ) {
+ throw new Error("KTX2 transcoder returned an invalid mip chain");
+ }
+ return { width, height, levels: mips.map((mip) => mip.data) };
+}
diff --git a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
index 2f9d57c2..b07b2a62 100644
--- a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
+++ b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts
@@ -49,6 +49,8 @@ export interface MeshUniformData extends SurfaceParams {
wireframe?: boolean;
/** Blend without writing depth; the caller draws transparent meshes back to front. */
transparent?: boolean;
+ /** Extra per-map UV vertex attributes are present. */
+ hasMapUvs?: boolean;
isSkinned?: boolean;
skinningMatrices?: Float32Array; // 128 * 16 floats
material?: "lit" | "unlit" | "toon";
@@ -79,8 +81,10 @@ export interface GPUMeshBuffers {
indexBuffer: GPUBuffer;
indexCount: number;
indexFormat: GPUIndexFormat;
+ topology?: "triangle-list" | "line-list" | "point-list";
/** Per-vertex RGBA (display / sRGB), 4 floats each; absent = white. */
colorBuffer?: GPUBuffer;
+ mapUvBuffer?: GPUBuffer;
wireIndexBuffer?: GPUBuffer;
wireIndexCount?: number;
}
@@ -94,6 +98,17 @@ export class Mesh3DPipeline {
private wireMrt: GPURenderPipeline;
private wireBloom: BloomPipelineVariants;
private wireShadow: GPURenderPipeline;
+ private pointPipelines: {
+ single: GPURenderPipeline;
+ mrt: GPURenderPipeline;
+ bloom: BloomPipelineVariants;
+ };
+ private transparentPointPipelines: {
+ single: GPURenderPipeline;
+ mrt: GPURenderPipeline;
+ bloom: BloomPipelineVariants;
+ };
+ private pointShadow: GPURenderPipeline;
private transparentPipelines: {
single: GPURenderPipeline;
mrt: GPURenderPipeline;
@@ -228,6 +243,15 @@ export class Mesh3DPipeline {
arrayStride: 16, // RGBA vertex color
attributes: [{ shaderLocation: 5, offset: 0, format: "float32x4" }],
},
+ {
+ arrayStride: 32,
+ attributes: [
+ { shaderLocation: 6, offset: 0, format: "float32x2" },
+ { shaderLocation: 7, offset: 8, format: "float32x2" },
+ { shaderLocation: 8, offset: 16, format: "float32x2" },
+ { shaderLocation: 9, offset: 24, format: "float32x2" },
+ ],
+ },
],
};
@@ -276,6 +300,37 @@ export class Mesh3DPipeline {
...createBasePipelines(device, transparentWireBase),
bloom: new BloomPipelineVariants(device, transparentWireBase),
};
+ const pointBase: PipelineVariantBase = {
+ ...base,
+ label: "Mesh3DPoints",
+ primitive: { topology: "point-list" },
+ };
+ const transparentPointBase: PipelineVariantBase = {
+ ...pointBase,
+ label: "Mesh3DTransparentPoints",
+ depthStencil: { ...base.depthStencil, depthWriteEnabled: false },
+ };
+ this.pointPipelines = {
+ ...createBasePipelines(device, pointBase),
+ bloom: new BloomPipelineVariants(device, pointBase),
+ };
+ this.transparentPointPipelines = {
+ ...createBasePipelines(device, transparentPointBase),
+ bloom: new BloomPipelineVariants(device, transparentPointBase),
+ };
+ this.pointShadow = device.createRenderPipeline({
+ label: "Mesh3DPointShadow",
+ layout: device.createPipelineLayout({
+ bindGroupLayouts: [this.cameraLayout, this.modelLayout],
+ }),
+ vertex: vertexState,
+ depthStencil: {
+ format: SHADOW_DEPTH_STENCIL.format,
+ depthWriteEnabled: true,
+ depthCompare: "less-equal",
+ },
+ primitive: { topology: "point-list" },
+ });
this.wireShadow = device.createRenderPipeline({
label: "Mesh3DWireframeShadow",
layout: device.createPipelineLayout({
@@ -363,7 +418,7 @@ export class Mesh3DPipeline {
this.modelData[36] = data.opacity ?? 1.0;
this.modelData[37] = data.twoSided ? 1.0 : 0.0;
this.modelData[38] = data.isSkinned ? 1.0 : 0.0;
- this.modelData[39] = 0;
+ this.modelData[39] = data.hasMapUvs ? 1 : 0;
const shininess =
data.roughness !== undefined
@@ -440,7 +495,10 @@ export class Mesh3DPipeline {
useMrt = false,
useBloom = false,
): void {
- const modelBindGroup = this.packModel(data);
+ const modelBindGroup = this.packModel({
+ ...data,
+ hasMapUvs: Boolean(meshBuffers.mapUvBuffer),
+ });
const white = this.defaultWhiteTexture;
const maps = data.maps;
const textureBindGroup = this.device.createBindGroup({
@@ -461,21 +519,33 @@ export class Mesh3DPipeline {
],
});
- const wireframe = data.wireframe === true;
+ const wireframe =
+ data.wireframe === true &&
+ (!meshBuffers.topology || meshBuffers.topology === "triangle-list");
if (wireframe && !meshBuffers.wireIndexBuffer) {
throw new Error("Wireframe requires mesh buffers with edge indices");
}
- const variants = data.transparent
- ? wireframe
- ? this.transparentWirePipelines
- : this.transparentPipelines
- : wireframe
- ? { single: this.wireSingle, mrt: this.wireMrt, bloom: this.wireBloom }
- : {
- single: this.pipelineSingle,
- mrt: this.pipelineMrt,
- bloom: this.bloomVariants,
- };
+ const line = wireframe || meshBuffers.topology === "line-list";
+ const variants =
+ meshBuffers.topology === "point-list"
+ ? data.transparent
+ ? this.transparentPointPipelines
+ : this.pointPipelines
+ : data.transparent
+ ? line
+ ? this.transparentWirePipelines
+ : this.transparentPipelines
+ : line
+ ? {
+ single: this.wireSingle,
+ mrt: this.wireMrt,
+ bloom: this.wireBloom,
+ }
+ : {
+ single: this.pipelineSingle,
+ mrt: this.pipelineMrt,
+ bloom: this.bloomVariants,
+ };
pass.setPipeline(
useBloom
? variants.bloom.get(useMrt)
@@ -489,6 +559,10 @@ export class Mesh3DPipeline {
pass.setBindGroup(3, lightsBindGroup);
pass.setVertexBuffer(0, meshBuffers.vertexBuffer);
pass.setVertexBuffer(1, this.colorsFor(meshBuffers));
+ pass.setVertexBuffer(
+ 2,
+ meshBuffers.mapUvBuffer ?? meshBuffers.vertexBuffer,
+ );
pass.setIndexBuffer(
wireframe ? meshBuffers.wireIndexBuffer! : meshBuffers.indexBuffer,
meshBuffers.indexFormat,
@@ -505,15 +579,27 @@ export class Mesh3DPipeline {
meshBuffers: GPUMeshBuffers,
data: MeshUniformData,
): void {
- const wireframe = data.wireframe === true;
+ const wireframe =
+ data.wireframe === true &&
+ (!meshBuffers.topology || meshBuffers.topology === "triangle-list");
if (wireframe && !meshBuffers.wireIndexBuffer) {
throw new Error("Wireframe requires mesh buffers with edge indices");
}
- pass.setPipeline(wireframe ? this.wireShadow : this.pipelineShadow);
+ pass.setPipeline(
+ meshBuffers.topology === "point-list"
+ ? this.pointShadow
+ : wireframe || meshBuffers.topology === "line-list"
+ ? this.wireShadow
+ : this.pipelineShadow,
+ );
pass.setBindGroup(0, lightCameraBindGroup);
pass.setBindGroup(1, this.packModel(data));
pass.setVertexBuffer(0, meshBuffers.vertexBuffer);
pass.setVertexBuffer(1, this.colorsFor(meshBuffers));
+ pass.setVertexBuffer(
+ 2,
+ meshBuffers.mapUvBuffer ?? meshBuffers.vertexBuffer,
+ );
pass.setIndexBuffer(
wireframe ? meshBuffers.wireIndexBuffer! : meshBuffers.indexBuffer,
meshBuffers.indexFormat,
diff --git a/packages/webgpu-renderers/src/renderer3d/morph-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/morph-pipeline.ts
new file mode 100644
index 00000000..7a41a34d
--- /dev/null
+++ b/packages/webgpu-renderers/src/renderer3d/morph-pipeline.ts
@@ -0,0 +1,176 @@
+import type { Mesh3DData } from "../loaders/types.js";
+import { BufferPool } from "../renderer2d/buffer-pool.js";
+
+const morphWgsl = `
+struct Counts { vertices: u32, targets: u32, pad0: u32, pad1: u32 };
+@group(0) @binding(0) var<storage, read> source: array<f32>;
+@group(0) @binding(1) var<storage, read> deltas: array<f32>;
+@group(0) @binding(2) var<storage, read> weights: array<f32>;
+@group(0) @binding(3) var<uniform> counts: Counts;
+@group(0) @binding(4) var<storage, read_write> dest: array<f32>;
+@compute @workgroup_size(128)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+ let vertex = gid.x;
+ if (vertex >= counts.vertices) { return; }
+ let v = vertex * 16u;
+ for (var c = 0u; c < 16u; c++) { dest[v + c] = source[v + c]; }
+ var position = vec3<f32>(source[v], source[v + 1u], source[v + 2u]);
+ var normal = vec3<f32>(source[v + 5u], source[v + 6u], source[v + 7u]);
+ for (var t = 0u; t < counts.targets; t++) {
+ let d = (t * counts.vertices + vertex) * 6u;
+ let w = weights[t];
+ position += vec3<f32>(deltas[d], deltas[d + 1u], deltas[d + 2u]) * w;
+ normal += vec3<f32>(deltas[d + 3u], deltas[d + 4u], deltas[d + 5u]) * w;
+ }
+ dest[v] = position.x; dest[v + 1u] = position.y; dest[v + 2u] = position.z;
+ dest[v + 5u] = normal.x; dest[v + 6u] = normal.y; dest[v + 7u] = normal.z;
+}`;
+
+/** Applies per-instance morph targets on the GPU before skinning or audio deformation. */
+export class MorphPipeline {
+ private pipeline: GPUComputePipeline;
+ private layout: GPUBindGroupLayout;
+ private weights = new BufferPool(
+ 16,
+ GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+ );
+ private counts = new BufferPool(
+ 16,
+ GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+ );
+ private targets = new WeakMap<Mesh3DData, GPUBuffer>();
+ private outputs: GPUBuffer[] = [];
+ private outputIndex = 0;
+
+ constructor(private device: GPUDevice) {
+ this.layout = device.createBindGroupLayout({
+ entries: [
+ {
+ binding: 0,
+ visibility: GPUShaderStage.COMPUTE,
+ buffer: { type: "read-only-storage" },
+ },
+ {
+ binding: 1,
+ visibility: GPUShaderStage.COMPUTE,
+ buffer: { type: "read-only-storage" },
+ },
+ {
+ binding: 2,
+ visibility: GPUShaderStage.COMPUTE,
+ buffer: { type: "read-only-storage" },
+ },
+ {
+ binding: 3,
+ visibility: GPUShaderStage.COMPUTE,
+ buffer: { type: "uniform" },
+ },
+ {
+ binding: 4,
+ visibility: GPUShaderStage.COMPUTE,
+ buffer: { type: "storage" },
+ },
+ ],
+ });
+ this.pipeline = device.createComputePipeline({
+ label: "MeshMorphPipeline",
+ layout: device.createPipelineLayout({ bindGroupLayouts: [this.layout] }),
+ compute: {
+ module: device.createShaderModule({ code: morphWgsl }),
+ entryPoint: "main",
+ },
+ });
+ }
+
+ private targetBuffer(mesh: Mesh3DData): GPUBuffer {
+ const existing = this.targets.get(mesh);
+ if (existing) return existing;
+ const targets = mesh.morphTargets ?? [];
+ const count = mesh.positions.length / 3;
+ const data = new Float32Array(count * targets.length * 6);
+ for (let t = 0; t < targets.length; t++) {
+ const target = targets[t];
+ for (let v = 0; v < count; v++) {
+ for (let k = 0; k < 3; k++) {
+ data[(t * count + v) * 6 + k] = target.positions?.[v * 3 + k] ?? 0;
+ data[(t * count + v) * 6 + 3 + k] = target.normals?.[v * 3 + k] ?? 0;
+ }
+ }
+ }
+ const buffer = this.device.createBuffer({
+ label: "MeshMorphTargets",
+ size: Math.max(4, data.byteLength),
+ usage: GPUBufferUsage.STORAGE,
+ mappedAtCreation: true,
+ });
+ new Float32Array(buffer.getMappedRange()).set(data);
+ buffer.unmap();
+ this.targets.set(mesh, buffer);
+ return buffer;
+ }
+
+ execute(
+ encoder: GPUCommandEncoder,
+ mesh: Mesh3DData,
+ source: GPUBuffer,
+ weights: number[],
+ ): GPUBuffer {
+ const vertexCount = mesh.positions.length / 3;
+ const targetCount = mesh.morphTargets?.length ?? 0;
+ const size = Math.max(64, vertexCount * 64);
+ let output = this.outputs[this.outputIndex];
+ if (!output || output.size < size) {
+ if (output) {
+ const old = output;
+ this.device.queue.onSubmittedWorkDone().then(() => old.destroy());
+ }
+ output = this.device.createBuffer({
+ label: "MeshMorphOutput",
+ size,
+ usage: GPUBufferUsage.STORAGE | GPUBufferUsage.VERTEX,
+ });
+ this.outputs[this.outputIndex] = output;
+ }
+ this.outputIndex++;
+ const weightData = new Float32Array(Math.max(4, targetCount));
+ for (let i = 0; i < targetCount; i++) weightData[i] = weights[i] ?? 0;
+ const bind = this.device.createBindGroup({
+ layout: this.layout,
+ entries: [
+ { binding: 0, resource: { buffer: source } },
+ { binding: 1, resource: { buffer: this.targetBuffer(mesh) } },
+ {
+ binding: 2,
+ resource: { buffer: this.weights.getBuffer(this.device, weightData) },
+ },
+ {
+ binding: 3,
+ resource: {
+ buffer: this.counts.getBuffer(
+ this.device,
+ new Uint32Array([vertexCount, targetCount, 0, 0]),
+ ),
+ },
+ },
+ { binding: 4, resource: { buffer: output } },
+ ],
+ });
+ const pass = encoder.beginComputePass({ label: "MeshMorphPass" });
+ pass.setPipeline(this.pipeline);
+ pass.setBindGroup(0, bind);
+ pass.dispatchWorkgroups(Math.ceil(vertexCount / 128));
+ pass.end();
+ return output;
+ }
+
+ resetPools(): void {
+ this.outputIndex = 0;
+ this.weights.reset();
+ this.counts.reset();
+ }
+ destroy(): void {
+ this.weights.destroy();
+ this.counts.destroy();
+ for (const output of this.outputs) output.destroy();
+ }
+}
diff --git a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
index 0fb8ae79..3282d6db 100644
--- a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
+++ b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
@@ -7,6 +7,7 @@ import {
loadFBX,
loadGLB,
loadGLTF,
+ loadGLTFAsync,
loadOBJ,
loadOFF,
loadPLY,
@@ -44,11 +45,13 @@ import { dofBokehWgsl } from "../shaders/dof-bokeh.js";
import type { SlugGlyphBatch } from "../slug/slug-pipeline.js";
import { AudioMeshDeformPipeline } from "./audio-mesh-deform-pipeline.js";
import { type BloomOptions, BloomPipeline } from "./bloom-pipeline.js";
+import { decodeKtx2, isKtx2 } from "./ktx2.js";
import {
type GPUMeshBuffers,
Mesh3DPipeline,
type MeshMaterialMaps,
} from "./mesh3d-pipeline.js";
+import { MorphPipeline } from "./morph-pipeline.js";
import { Quad3DPipeline } from "./quad3d-pipeline.js";
import { SHADOW_DEPTH_FORMAT } from "./shadow-depth.js";
import {
@@ -148,6 +151,8 @@ export interface DrawMesh3DOpts extends SurfaceParams {
colorTint?: [number, number, number, number];
/** Whether backface is rendered */
twoSided?: boolean;
+ /** Per-instance morph target weights, evaluated before skinning. */
+ morphWeights?: number[];
/** Wireframe mode */
wireframe?: boolean;
/** Blend without writing depth; draw transparent meshes back to front. */
@@ -232,6 +237,7 @@ export class Renderer3D {
public slug3dPipeline: Slug3DPipeline;
public mesh3dPipeline: Mesh3DPipeline;
public audioMeshDeformPipeline: AudioMeshDeformPipeline;
+ private morphPipeline: MorphPipeline;
private dofPipeline: GPURenderPipeline;
private dofBindGroupLayout: GPUBindGroupLayout;
private cameraPool: BufferPool;
@@ -301,6 +307,7 @@ export class Renderer3D {
sampleCount,
);
this.audioMeshDeformPipeline = new AudioMeshDeformPipeline(device);
+ this.morphPipeline = new MorphPipeline(device);
this.cameraPool = new BufferPool(
320,
@@ -377,6 +384,7 @@ export class Renderer3D {
this.slug3dPipeline.resetPools();
this.mesh3dPipeline.resetPools();
this.audioMeshDeformPipeline.resetPools();
+ this.morphPipeline.resetPools();
}
getOrCreateDepthTexture(width: number, height: number): GPUTexture {
@@ -1099,7 +1107,8 @@ export class Renderer3D {
getOrCreateMeshBuffers(mesh: Mesh3DData, wireframe = false): GPUMeshBuffers {
let cached = this.meshBuffersCache.get(mesh);
if (cached) {
- if (wireframe) this.ensureWireIndices(mesh, cached);
+ if (wireframe && (!mesh.topology || mesh.topology === "triangle-list"))
+ this.ensureWireIndices(mesh, cached);
return cached;
}
@@ -1191,15 +1200,44 @@ export class Renderer3D {
colorBuffer.unmap();
}
+ let mapUvBuffer: GPUBuffer | undefined;
+ if (mesh.mapUvs && Object.values(mesh.mapUvs).some(Boolean)) {
+ const data = new Float32Array(numVerts * 8);
+ const maps = [
+ mesh.mapUvs.normal,
+ mesh.mapUvs.metallicRoughness,
+ mesh.mapUvs.occlusion,
+ mesh.mapUvs.emissive,
+ ];
+ for (let i = 0; i < numVerts; i++) {
+ for (let j = 0; j < maps.length; j++) {
+ const uv = maps[j] ?? mesh.uvs;
+ data[i * 8 + j * 2] = uv[i * 2] ?? 0;
+ data[i * 8 + j * 2 + 1] = uv[i * 2 + 1] ?? 0;
+ }
+ }
+ mapUvBuffer = this.device.createBuffer({
+ label: "Mesh3DMapUvs",
+ size: Math.max(32, data.byteLength),
+ usage: GPUBufferUsage.VERTEX,
+ mappedAtCreation: true,
+ });
+ new Float32Array(mapUvBuffer.getMappedRange()).set(data);
+ mapUvBuffer.unmap();
+ }
+
cached = {
vertexBuffer,
indexBuffer,
indexCount: mesh.indices.length,
indexFormat: is32Bit ? "uint32" : "uint16",
+ topology: mesh.topology,
colorBuffer,
+ mapUvBuffer,
};
this.meshBuffersCache.set(mesh, cached);
- if (wireframe) this.ensureWireIndices(mesh, cached);
+ if (wireframe && (!mesh.topology || mesh.topology === "triangle-list"))
+ this.ensureWireIndices(mesh, cached);
return cached;
}
@@ -1241,6 +1279,26 @@ export class Renderer3D {
buffers.wireIndexCount = data.length;
}
+ morphMesh(
+ encoder: GPUCommandEncoder,
+ mesh: Mesh3DData,
+ weights: number[],
+ wireframe = false,
+ ): GPUMeshBuffers {
+ const buffers = this.getOrCreateMeshBuffers(mesh, wireframe);
+ if (!mesh.morphTargets?.length || !weights.some((weight) => weight !== 0))
+ return buffers;
+ return {
+ ...buffers,
+ vertexBuffer: this.morphPipeline.execute(
+ encoder,
+ mesh,
+ buffers.vertexBuffer,
+ weights,
+ ),
+ };
+ }
+
deformMesh(
encoder: GPUCommandEncoder,
mesh: Mesh3DData,
@@ -1251,8 +1309,9 @@ export class Renderer3D {
sampleRate?: number;
},
wireframe = false,
+ input?: GPUMeshBuffers,
): GPUMeshBuffers {
- const meshBuffers = this.getOrCreateMeshBuffers(mesh, wireframe);
+ const meshBuffers = input ?? this.getOrCreateMeshBuffers(mesh, wireframe);
const numVerts = mesh.positions.length / 3;
const deformedVertexBuffer = this.audioMeshDeformPipeline.execute(
encoder,
@@ -1270,7 +1329,9 @@ export class Renderer3D {
indexBuffer: meshBuffers.indexBuffer,
indexCount: meshBuffers.indexCount,
indexFormat: meshBuffers.indexFormat,
+ topology: meshBuffers.topology,
colorBuffer: meshBuffers.colorBuffer,
+ mapUvBuffer: meshBuffers.mapUvBuffer,
wireIndexBuffer: meshBuffers.wireIndexBuffer,
wireIndexCount: meshBuffers.wireIndexCount,
};
@@ -1396,6 +1457,30 @@ export class Renderer3D {
return model;
}
+ /** Loads glTF asynchronously so its compressed buffer decoders can initialize. */
+ async loadModelAsync(
+ srcOrData: string | ArrayBuffer | Uint8Array,
+ format: Parameters<Renderer3D["loadModel"]>[1] = "auto",
+ options: LoadModelOptions = {},
+ ): Promise<Model3DData> {
+ const isGltf =
+ format === "gltf" ||
+ format === "glb" ||
+ (format === "auto" &&
+ (typeof srcOrData === "string"
+ ? /\.(gltf|glb)$/i.test(srcOrData) ||
+ srcOrData.trimStart().startsWith("{")
+ : GltfLoader.isGlb(srcOrData)));
+ if (!isGltf) return this.loadModel(srcOrData, format, options);
+ if (typeof srcOrData !== "string") return loadGLTFAsync(srcOrData, options);
+ const key = `${format}|${JSON.stringify(options)}|${srcOrData}`;
+ const cached = this.modelCache.get(key);
+ if (cached) return cached;
+ const model = await loadGLTFAsync(srcOrData, options);
+ this.modelCache.set(key, model);
+ return model;
+ }
+
/**
* The material's diffuse texture on the GPU, decoded once with a full mip
* chain (a character's 2K maps are drawn a few hundred pixels tall).
@@ -1464,6 +1549,29 @@ export class Renderer3D {
label: string,
): Promise<GPUTexture | undefined> {
if (!encoded) return undefined;
+ const bytes =
+ encoded instanceof Uint8Array ? encoded : new Uint8Array(encoded);
+ if (isKtx2(bytes)) {
+ const decoded = await decodeKtx2(bytes);
+ const texture = this.device.createTexture({
+ label,
+ size: { width: decoded.width, height: decoded.height },
+ mipLevelCount: decoded.levels.length,
+ format: "rgba8unorm",
+ usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+ });
+ for (const [level, data] of decoded.levels.entries()) {
+ const width = Math.max(1, decoded.width >> level);
+ const height = Math.max(1, decoded.height >> level);
+ this.device.queue.writeTexture(
+ { texture, mipLevel: level },
+ data,
+ { bytesPerRow: width * 4, rowsPerImage: height },
+ { width, height },
+ );
+ }
+ return texture;
+ }
const sharp = (await import(/* webpackIgnore: true */ "sharp")).default;
const source = Buffer.from(
encoded instanceof Uint8Array ? encoded : new Uint8Array(encoded),
@@ -1574,6 +1682,7 @@ export class Renderer3D {
this.quad3dPipeline.destroy();
this.slug3dPipeline.destroy();
this.mesh3dPipeline.destroy();
+ this.morphPipeline.destroy();
this.cameraPool.destroy();
this.lightsPool.destroy();
this.cameraUniformBindGroupCache.destroy();
diff --git a/packages/webgpu-renderers/src/shaders/mesh3d.ts b/packages/webgpu-renderers/src/shaders/mesh3d.ts
index 5b63a458..99c740ce 100644
--- a/packages/webgpu-renderers/src/shaders/mesh3d.ts
+++ b/packages/webgpu-renderers/src/shaders/mesh3d.ts
@@ -17,7 +17,7 @@ struct ModelUniforms {
modelMatrix : mat4x4<f32>,
normalMatrix : mat4x4<f32>,
colorTint : vec4<f32>,
- params : vec4<f32>, // x = opacity, y = twoSided (1.0 = yes), z = isSkinned (1.0 = yes), w = reserved
+ params : vec4<f32>, // x = opacity, y = twoSided (1.0 = yes), z = isSkinned (1.0 = yes), w = hasMapUvs
materialParams : vec4<f32>, // x = shininess, y = specularIntensity, z = ambientIntensity, w = materialMode (0=unlit, 1=lit, 2=toon)
shade : vec4<f32>, // rgb = toon shadow-side color multiplier, a = alpha cutoff (0 = none)
pbr : vec4<f32>, // x = roughness (<0 = default), y = metallic
@@ -48,6 +48,10 @@ struct VertexInput {
@location(3) joints : vec4<f32>,
@location(4) weights : vec4<f32>,
@location(5) color : vec4<f32>, // vertex color (display / sRGB), white when absent
+ @location(6) normalUv : vec2<f32>,
+ @location(7) mrUv : vec2<f32>,
+ @location(8) aoUv : vec2<f32>,
+ @location(9) emissiveUv : vec2<f32>,
};
struct VertexOutput {
@@ -57,6 +61,10 @@ struct VertexOutput {
@location(2) worldNormal : vec3<f32>,
@location(3) linearDepth : f32,
@location(4) color : vec4<f32>,
+ @location(5) normalUv : vec2<f32>,
+ @location(6) mrUv : vec2<f32>,
+ @location(7) aoUv : vec2<f32>,
+ @location(8) emissiveUv : vec2<f32>,
};
@vertex
@@ -101,6 +109,10 @@ fn vs_main(in: VertexInput) -> VertexOutput {
out.clipPos = cam.viewProjMatrix * worldPos4;
out.uv = in.uv;
+ out.normalUv = select(in.uv, in.normalUv, model.params.w > 0.5);
+ out.mrUv = select(in.uv, in.mrUv, model.params.w > 0.5);
+ out.aoUv = select(in.uv, in.aoUv, model.params.w > 0.5);
+ out.emissiveUv = select(in.uv, in.emissiveUv, model.params.w > 0.5);
out.color = in.color;
out.linearDepth = dot(worldPos4.xyz - cam.cameraPos.xyz, cam.cameraDir.xyz);
@@ -230,14 +242,14 @@ fn shadeGlass(in: VertexOutput, Nin: vec3<f32>, tint: vec3<f32>, alpha: f32, rim
fn shadeMesh(in: VertexOutput, isFront: bool) -> MeshFragment {
// Every sample and derivative up front, in uniform control flow.
var texColor = textureSample(mainTex, texSampler, in.uv);
- let normalSample = textureSample(normalTex, texSampler, in.uv).xyz;
- let mrSample = textureSample(metalRoughTex, texSampler, in.uv);
- let aoSample = textureSample(occlusionTex, texSampler, in.uv).r;
- let emissiveSample = textureSample(emissiveTex, texSampler, in.uv).rgb;
+ let normalSample = textureSample(normalTex, texSampler, in.normalUv).xyz;
+ let mrSample = textureSample(metalRoughTex, texSampler, in.mrUv);
+ let aoSample = textureSample(occlusionTex, texSampler, in.aoUv).r;
+ let emissiveSample = textureSample(emissiveTex, texSampler, in.emissiveUv).rgb;
let dp1 = dpdx(in.worldPos);
let dp2 = dpdy(in.worldPos);
- let duv1 = dpdx(in.uv);
- let duv2 = dpdy(in.uv);
+ let duv1 = dpdx(in.normalUv);
+ let duv2 = dpdy(in.normalUv);
let rimWidth = fwidth(1.0 - abs(dot(normalize(in.worldNormal), normalize(cam.cameraPos.xyz - in.worldPos))));
if (!isFront && model.params.y < 0.5) {
@@ -272,7 +284,7 @@ fn shadeMesh(in: VertexOutput, isFront: bool) -> MeshFragment {
if (dot(Nf, cam.cameraPos.xyz - in.worldPos) < 0.0) {
Nf = -Nf;
}
- N = perturbNormal(Nf, in.worldPos, in.uv, tn, dp1, dp2, duv1, duv2);
+ N = perturbNormal(Nf, in.worldPos, in.normalUv, tn, dp1, dp2, duv1, duv2);
}
var pbr = model.pbr;
if (model.maps.z > 0.5) {
diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.md
index d26f739d..2403724b 100644
--- a/plugins/framefields/skills/framefields-compose/SKILL.md
+++ b/plugins/framefields/skills/framefields-compose/SKILL.md
@@ -443,7 +443,7 @@ Layer3D.cylinder({ ..., color: "#111", emissive: "#4da3ff", emissiveIntensity: 3
- **Bloom only takes light well past white** (emissive ≳ 3, hot speculars), so ordinary bright surfaces don't glow. Raise `emissiveIntensity` to make something glow.
- **Shadows:** one `castShadow` directional or spot light per scene. Meshes cast by default (`castShadow: false` opts out); flat layers (planes, cards) cast only with `castShadow: true`. Everything receives.
- **Fog** fades to `fog.color` exactly, so set it to the composition background for a seamless horizon.
-- **Models:** glTF materials bring base color, normal, metallic-roughness, occlusion and emissive maps; OBJ (`map_Kd`, `norm` in the `.mtl`) and FBX bring diffuse and normal maps, looked up next to the model. Textures must be PNG, JPEG, WebP, GIF, TIFF or AVIF: TGA, PSD, DDS and KTX2 are skipped with a warning (convert them). Draco / meshopt-compressed glTF files fail to load: re-export without mesh compression. Vertex colors (VOX, PLY, OFF, glTF `COLOR_0`) multiply the base color.
+- **Models:** glTF materials bring base color, normal, metallic-roughness, occlusion and emissive maps; OBJ (`map_Kd`, `norm` in the `.mtl`) and FBX bring diffuse and normal maps, looked up next to the model. Textures can be PNG, JPEG, WebP, GIF, TIFF, AVIF or Basis KTX2 (ETC1S/UASTC, transcoded offline to RGBA8); TGA, PSD and DDS are skipped with a warning. Draco and meshopt-compressed glTF geometry is decoded by the asynchronous compositor loader; individual maps retain their own UV sets and texture transforms. glTF morph weights animate on the GPU before skinning. Unknown required glTF extensions fail clearly. Vertex colors (VOX, PLY, OFF, glTF `COLOR_0`) multiply the base color.
- **Model orientation:** the world is y-down, so a y-up model (most glTF, OBJ and FBX files) needs `rotateX: 180` to stand upright.
- `emissive` / `emissiveIntensity` / `exposure` animate like any prop (`.keys("emissiveIntensity", …)`).
- **Transparent 3D meshes:** glTF `BLEND` materials and meshes with reduced opacity draw after opaque scene items, sorted back to front by each mesh's bounds center without writing depth. This is an object-level approximation: intersecting or self-overlapping meshes cannot always sort correctly; translucent flat layers and glass use separate rendering paths.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 498e06f9..6f7d9a27 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2738,7 +2738,7 @@ importers:
version: 5.8.3
vitest:
specifier: ^4.1.11
webgpu:
specifier: ^0.4.0
version: 0.4.0
@@ -2766,7 +2766,7 @@ importers:
version: 5.8.3
vitest:
specifier: ^4.1.11
packages/framefields:
dependencies:
@@ -3371,7 +3371,7 @@ importers:
version: 5.8.3
vitest:
specifier: ^5.0.1
packages/tensor-webgpu:
dependencies:
@@ -3399,7 +3399,7 @@ importers:
version: 5.9.3
vitest:
specifier: ^4.1.11
packages/tsconfig: {}
@@ -3445,6 +3445,9 @@ importers:
packages/webgpu-renderers:
dependencies:
+ '@forgeax/engine-codec':
+ specifier: ^0.3.11
+ version: 0.3.11
'@framefields/client-utils':
specifier: workspace:*
version: link:../client-utils
@@ -3460,6 +3463,9 @@ importers:
bidi-js:
specifier: ^1.0.3
version: 1.0.3
+ draco3dgltf:
+ specifier: ^1.5.9
+ version: 1.5.9
earcut:
specifier: ^3.2.4
version: 3.2.4
@@ -3472,9 +3478,12 @@ importers:
mediabunny:
specifier: ^1.61.6
version: 1.61.6
+ meshoptimizer:
+ specifier: ^1.3.0
+ version: 1.3.0
sharp:
specifier: ^0.35.4
- version: 0.35.5(@types/[email protected])
+ version: 0.35.5(@types/[email protected])
skia-canvas:
specifier: ^3.0.8
version: 3.0.8
@@ -3502,7 +3511,7 @@ importers:
version: 5.8.3
vitest:
specifier: ^4.1.11
vitest-mock-extended:
specifier: ^4.0.0
@@ -3684,6 +3693,9 @@ packages:
cpu: [x64]
os: [win32]
+ '@bokuweb/[email protected]':
+ resolution: {integrity: sha512-GDm2uOTK3ESjnYmSeLQifJnBsRCWajKLvN32D2ZcQaaCIJI/Hse9s74f7APXjHit95S10UImsRGkTsbwHmrtmg==}
+
'@bramus/[email protected]':
resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==}
hasBin: true
@@ -3967,6 +3979,9 @@ packages:
resolution: {integrity: sha512-nwc2iesjyc9hkuzcrMCBXQRn653XuAUKorfWM8PZyJawiy1QzLj4vahwzaI25+pfpwOLvMzbJ0uKpWLDNmo16w==}
engines: {node: '>= 8'}
+ '@forgeax/[email protected]':
+ resolution: {integrity: sha512-5dabvHxTEo+7m5U0wHR99KFl1IDps+ColnuC9gOChOfdo1lnUj5M22VSAaPZ1Qjif7T6uqgQHPQSIn6fYC5ScQ==}
+
resolution: {integrity: sha512-eWpQYr67tqJLeaSUl0Q+TquuYfUdTibpOJlUMV2FfUP7+KqCC5TufnwnlXL6mobZBJbGAYRd7ZvEBDCbLInjhg==}
engines: {node: '>=20'}
@@ -5141,6 +5156,9 @@ packages:
resolution: {integrity: sha512-OowOUbD1lBCOFIPOZ8xnMIhgqA4sCutMiYOmPHL1PTLt5+y1XA+g2+yC9OOyz8p+deMZqPZLxfMjYIfrKsPeFg==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-b4e2xxj/yMeT2hNlD6x7zNFiQK2Dlmkb9CQ6v3/1G2RezKN4YS2lcEv8lzGm1mhs4f2lM4yNAMI/zUDBZBBt7w==}
+
resolution: {integrity: sha512-1mAINjtQCXXeLkJ9ehXkwOcBpqtLxiVtKhpUf83DdRNdQKV0iXZpaHYqRr7nj+wvxuJzoAmAwXI+sCNMv1CzLQ==}
@@ -5455,6 +5473,9 @@ packages:
resolution: {integrity: sha512-IO8C/dzEb6O3F9/twg6ZLXz164a2fhTnEWb95H23Dm4OuN+92NmEAlTrupP9VW6Jm3sO26tQlqyvyi4CsnY9GA==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-nIRZumqUwjqVYAdtt8q0F3FZc5qo2rCPTBH2hHhfSvHSPVJazzaepEHFdAZv4wrQKk5CkaclWGHhpyJ4eUdcJQ==}
+
resolution: {integrity: sha512-bihc7jPC90VrosXNzK0LTE2cuLP6jr0Ro8jk+kMugHReJVLIpHz/xadeq3MhuwyO4TD4OA3L1Q8pBBFRc08Tsw==}
engines: {node: '>=20.19.0'}
@@ -5598,6 +5619,9 @@ packages:
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
os: [darwin]
+ resolution: {integrity: sha512-dkuVSOKKwh3eas5VkJy1AW1vFpet8TA/fGmVA5krThl8YcOVE/8ZIoEA1+U1vEn5ckxxhLirSdY837azmbaNHA==}
+
resolution: {integrity: sha512-eeB5GfMNeevm/GRYq20ShmsaGcmI81kIX2K9XQx5miC8KdHaC6Jm0qQ8ZNeGOi7wYB8OsdxKs+Y2oVuTFuVwKQ==}
@@ -5966,6 +5990,9 @@ packages:
resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
engines: {node: '>= 8'}
+ resolution: {integrity: sha512-2oZqMAcEEiCtXWUjIGtZ71oPx1B0ZxYGTqIKsXB1wzWFhleNsCFxQuUJzgCV706bRcwPWtMGf1odmQvAcqKkIw==}
+
resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
engines: {node: '>=8.6'}
@@ -6550,6 +6577,9 @@ packages:
resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+ resolution: {integrity: sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==}
+
resolution: {integrity: sha512-dkrQXeHSaoamnItlYbmzG0wFYrM0ZwDxCIg0A7aKjTyyhh9svRzCNFEzV+Vm05/yehjCzjDZ31KXfGEjYSztDQ==}
engines: {node: '>=20.18.1'}
@@ -7053,6 +7083,8 @@ snapshots:
'@biomejs/[email protected]':
optional: true
+ '@bokuweb/[email protected]': {}
+
'@bramus/[email protected]':
dependencies:
css-tree: 3.2.1
@@ -7346,6 +7378,11 @@ snapshots:
tweetnacl: 1.0.3
optional: true
+ '@forgeax/[email protected]':
+ dependencies:
+ '@bokuweb/zstd-wasm': 0.0.27
+ fzstd: 0.1.1
+
dependencies:
hono: 4.13.13
@@ -8224,6 +8261,11 @@ snapshots:
dependencies:
undici-types: 7.16.0
+ '@types/[email protected]':
+ dependencies:
+ undici-types: 7.24.6
+ optional: true
+
'@types/[email protected]': {}
@@ -8238,7 +8280,7 @@ snapshots:
obug: 2.2.1
std-env: 4.2.0
tinyrainbow: 3.1.0
'@vitest/[email protected]':
dependencies:
@@ -8257,14 +8299,22 @@ snapshots:
optionalDependencies:
+ dependencies:
+ '@vitest/spy': 4.1.11
+ estree-walker: 3.0.3
+ magic-string: 0.30.21
+ optionalDependencies:
+
dependencies:
'@jridgewell/trace-mapping': 0.3.31
'@vitest/spy': 5.0.1
estree-walker: 3.0.3
magic-string: 1.4.1
optionalDependencies:
'@vitest/[email protected]':
dependencies:
@@ -8532,6 +8582,8 @@ snapshots:
+
optionalDependencies:
oxc-resolver: 11.19.1
@@ -8684,6 +8736,8 @@ snapshots:
optional: true
+
dependencies:
is-property: 1.0.2
@@ -9041,6 +9095,8 @@ snapshots:
+
dependencies:
braces: 3.0.3
@@ -9510,6 +9566,39 @@ snapshots:
'@img/sharp-win32-x64': 0.35.5
'@types/node': 24.10.14
+ dependencies:
+ '@img/colour': 1.1.0
+ detect-libc: 2.1.2
+ semver: 7.8.5
+ optionalDependencies:
+ '@img/sharp-darwin-arm64': 0.35.5
+ '@img/sharp-darwin-x64': 0.35.5
+ '@img/sharp-freebsd-wasm32': 0.35.5
+ '@img/sharp-libvips-darwin-arm64': 1.3.4
+ '@img/sharp-libvips-darwin-x64': 1.3.4
+ '@img/sharp-libvips-linux-arm': 1.3.4
+ '@img/sharp-libvips-linux-arm64': 1.3.4
+ '@img/sharp-libvips-linux-ppc64': 1.3.4
+ '@img/sharp-libvips-linux-riscv64': 1.3.4
+ '@img/sharp-libvips-linux-s390x': 1.3.4
+ '@img/sharp-libvips-linux-x64': 1.3.4
+ '@img/sharp-libvips-linuxmusl-arm64': 1.3.4
+ '@img/sharp-libvips-linuxmusl-x64': 1.3.4
+ '@img/sharp-linux-arm': 0.35.5
+ '@img/sharp-linux-arm64': 0.35.5
+ '@img/sharp-linux-ppc64': 0.35.5
+ '@img/sharp-linux-riscv64': 0.35.5
+ '@img/sharp-linux-s390x': 0.35.5
+ '@img/sharp-linux-x64': 0.35.5
+ '@img/sharp-linuxmusl-arm64': 0.35.5
+ '@img/sharp-linuxmusl-x64': 0.35.5
+ '@img/sharp-webcontainers-wasm32': 0.35.5
+ '@img/sharp-win32-arm64': 0.35.5
+ '@img/sharp-win32-ia32': 0.35.5
+ '@img/sharp-win32-x64': 0.35.5
+ '@types/node': 25.9.9
+
dependencies:
shebang-regex: 3.0.0
@@ -9791,6 +9880,9 @@ snapshots:
+ optional: true
+
optional: true
@@ -9838,11 +9930,27 @@ snapshots:
tsx: 4.21.0
yaml: 2.8.3
+ dependencies:
+ lightningcss: 1.33.0
+ picomatch: 4.0.7
+ postcss: 8.5.26
+ rolldown: 1.2.3
+ tinyglobby: 0.2.17
+ optionalDependencies:
+ '@types/node': 25.9.9
+ esbuild: 0.28.1
+ fsevents: 2.3.3
+ jiti: 2.7.0
+ terser: 5.46.0
+ tsx: 4.21.0
+ yaml: 2.8.3
+
dependencies:
ts-essentials: 10.2.0([email protected])
typescript: 5.8.3
dependencies:
@@ -9874,10 +9982,40 @@ snapshots:
transitivePeerDependencies:
- msw
+ dependencies:
+ '@vitest/expect': 4.1.11
+ '@vitest/pretty-format': 4.1.11
+ '@vitest/runner': 4.1.11
+ '@vitest/snapshot': 4.1.11
+ '@vitest/spy': 4.1.11
+ '@vitest/utils': 4.1.11
+ es-module-lexer: 2.3.2
+ expect-type: 1.4.0
+ magic-string: 0.30.21
+ obug: 2.2.1
+ pathe: 2.0.3
+ picomatch: 4.0.7
+ std-env: 4.2.0
+ tinybench: 2.9.0
+ tinyexec: 1.3.0
+ tinyglobby: 0.2.17
+ tinyrainbow: 3.1.0
+ why-is-node-running: 2.3.0
+ optionalDependencies:
+ '@opentelemetry/api': 1.9.0
+ '@types/node': 25.9.9
+ '@vitest/coverage-v8': 4.1.11([email protected])
+ jsdom: 29.1.0(@noble/[email protected])([email protected])
+ transitivePeerDependencies:
+ - msw
+
dependencies:
'@types/chai': 5.2.3
chai: 6.2.2
es-module-lexer: 2.3.2
expect-type: 1.4.0
@@ -9888,11 +10026,11 @@ snapshots:
tinybench: 6.1.4
tinyexec: 1.3.0
tinyglobby: 0.2.17
why-is-node-running: 2.3.0
optionalDependencies:
'@opentelemetry/api': 1.9.0
- '@types/node': 24.10.14
+ '@types/node': 25.9.9
jsdom: 29.1.0(@noble/[email protected])([email protected])
transitivePeerDependencies:
- msw