3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Ignore TANGENT morph deltas in glTF with a warning (#2073)
Nguyen Xuan Anf752f9252ff6
diff --git a/changes/2073.md b/changes/2073.mdnew file mode 100644index 00000000..369e8dce--- /dev/null+++ b/changes/2073.md@@ -0,0 +1 @@+- glTF files with TANGENT morph target deltas (such as Khronos AnimatedMorphCube) now load: the TANGENT deltas are ignored with a warning, and other unsupported morph semantics are refused with a message that says to re-export the GLB without them (#2073)diff --git a/changes/2073.size.md b/changes/2073.size.mdnew file mode 100644index 00000000..48008de4--- /dev/null+++ b/changes/2073.size.md@@ -0,0 +1,4 @@+- scene:gltf-box: 122 bytes gzip let glTF files with TANGENT morph targets (Khronos AnimatedMorphCube) load with a warning instead of being refused whole, and turn the "fix the recipe" error into a re-export instruction+- scene:gltf-box+lazy: the same 122 bytes in the lazy bundle+- entry:gltf: the same loader change, 135 bytes+- entry:gltf+lazy: the same loader change, 135 bytesdiff --git a/docs/gltf.md b/docs/gltf.mdindex da747740..54e8b3e3 100644--- a/docs/gltf.md+++ b/docs/gltf.md@@ -155,7 +155,7 @@ The current source supports four-influence [GPU skinning](https://crucible.codepNegative skin weights, which three.js and Blender also accept, are clamped to 0 and each vertex is renormalised. A vertex left with no positive weight binds fully to joint 0. `warnings` names the primitive and counts the clamped weights. NaN and Infinity weights still fail.The current source also supports relative POSITION/NORMAL morph targets and weight animations. See [morph import](https://crucible.codepawl.com/gltf-morph.md).-A morph primitive without an authored base NORMAL loads with normals generated from its triangles; its morph NORMAL deltas are dropped, with a warning. TANGENT targets remain unsupported.+A morph primitive without an authored base NORMAL loads with normals generated from its triangles; its morph NORMAL deltas are dropped, with a warning. TANGENT morph deltas are ignored with a warning (`unsupported-asset-feature` in `scene_create_asset`); any other morph semantic is refused, and the error says to re-export the GLB without it.The caller owns the CrucibleRenderer instance.`asset.dispose()` releases importer textures, image bitmaps, parser resources, and temporary object URLs.diff --git a/src/gltf.js b/src/gltf.jsindex 302b5907..24c95bc9 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -366,7 +366,9 @@ function validateDocument(document, limits, allowedExtensions) {for (const target of primitive.targets ?? []) {if (!target || typeof target !== 'object' || Array.isArray(target) || !Object.keys(target).length) throw new Error('Morph targets require POSITION or NORMAL channels.');for (const [semantic, accessorIndex] of Object.entries(target)) {- if (!['POSITION', 'NORMAL'].includes(semantic)) throw new Error(`Unsupported morph target semantic: ${semantic}.`);+ // TANGENT deltas are derived data the renderer never reads; they are ignored with a warning (see ignoredMorphTangentWarnings).+ if (semantic === 'TANGENT') continue;+ if (!['POSITION', 'NORMAL'].includes(semantic)) throw new Error(`Unsupported morph target semantic: ${semantic}. Crucible reads morph POSITION and NORMAL (TANGENT is ignored). Re-export the GLB without ${semantic} morph deltas.`);const accessor = document.accessors?.[accessorIndex];// A morph NORMAL without a base NORMAL is dropped at conversion with a warning, so it needs no base attribute here.if (primitive.attributes?.[semantic] === undefined && semantic !== 'NORMAL') throw new Error('Morph target channels require corresponding base attributes.');@@ -867,6 +869,13 @@ function computeVertexNormals(positions, indices) {return normals;}+/** One warning when any morph target carries TANGENT deltas, which the loader ignores. */+function ignoredMorphTangentWarnings(document) {+ const hasTangentDeltas = (document.meshes ?? []).some(mesh => (mesh.primitives ?? [])+ .some(primitive => (primitive.targets ?? []).some(target => target?.TANGENT !== undefined)));+ return hasTangentDeltas ? ['Ignored morph target TANGENT deltas; the POSITION and NORMAL morphs and the weight animation load as authored.'] : [];+}+/** A primitive whose decoded data cannot be drawn; the loader skips it with a warning instead of refusing the file. */class UnusablePrimitiveError extends Error {}@@ -1263,7 +1272,7 @@ export async function parseGltf(data, options = {}) {}const { ignoredExtensions, overruns } = validated;await loadLayerShadersFor(document);- const warnings = [...fallbackWarnings, ...ignoredExtensions.map(extension => `${extension} is accepted but not rendered.`), ...skippedPrimitiveWarnings(document), ...unusablePrimitiveWarnings, ...clampedIorWarnings(document)];+ const warnings = [...fallbackWarnings, ...ignoredExtensions.map(extension => `${extension} is accepted but not rendered.`), ...skippedPrimitiveWarnings(document), ...unusablePrimitiveWarnings, ...clampedIorWarnings(document), ...ignoredMorphTangentWarnings(document)];const dataBytes = typeof data === 'string' ? new TextEncoder().encode(data).byteLength : data.byteLength;const { resourceBytes, textureScaling } = await prepareResources(document, data, dataBytes, options, limits, overruns);if (textureScaling.scaledTextures.length) {diff --git a/tests/gltf-morph-normals-and-nan.test.js b/tests/gltf-morph-normals-and-nan.test.jsindex 7e183d30..123b9121 100644--- a/tests/gltf-morph-normals-and-nan.test.js+++ b/tests/gltf-morph-normals-and-nan.test.js@@ -74,3 +74,25 @@ test('a NaN joint transform loads with a warning and a finite palette', async ()assert.ok(Array.from(asset.parts[0].skin.jointMatrices).every(Number.isFinite));asset.dispose();});++function tangentMorphDocument() {+ const document = JSON.parse(morphDocument());+ document.accessors.push({ ...document.accessors[1] });+ document.meshes[0].primitives[0].targets = [{ POSITION: 1, TANGENT: 2 }];+ return document;+}++test('TANGENT morph deltas are ignored with a warning that names TANGENT, and the POSITION morph loads', async () => {+ const asset = await parseGltf(JSON.stringify(tangentMorphDocument()));+ const channels = asset.parts[0].geometry.morphTargets[0];+ assert.equal(channels.positions.length, 9);+ assert.equal(channels.tangents, undefined);+ assert.ok(asset.warnings.some(warning => /morph target TANGENT deltas/.test(warning)));+ asset.dispose();+});++test('another unsupported morph semantic is refused with a message that says to re-export the GLB', async () => {+ const document = tangentMorphDocument();+ document.meshes[0].primitives[0].targets = [{ POSITION: 1, TEXCOORD_0: 2 }];+ await assert.rejects(() => parseGltf(JSON.stringify(document)), /Unsupported morph target semantic: TEXCOORD_0\..*Re-export the GLB without TEXCOORD_0 morph deltas/);+});diff --git a/tests/gltf.test.js b/tests/gltf.test.jsindex 10466a43..92b531f6 100644--- a/tests/gltf.test.js+++ b/tests/gltf.test.js@@ -168,7 +168,7 @@ test('unsupported features fail explicitly before loading resources', async () =[document => {const primitive = document.meshes[0].primitives[0];primitive.attributes.NORMAL = primitive.attributes.POSITION;- primitive.targets = [{ TANGENT: 0 }];+ primitive.targets = [{ TEXCOORD_0: 0 }];}, /Unsupported morph/],[document => { document.meshes[0].primitives[0].attributes.COLOR_0 = 1; }, /COLOR_0/],[document => { document.meshes[0].primitives[0].mode = 5; }, /TRIANGLES/],