diff --git a/packages/melonjs/CHANGELOG.md b/packages/melonjs/CHANGELOG.md index 27bcc54a1..3419546c1 100644 --- a/packages/melonjs/CHANGELOG.md +++ b/packages/melonjs/CHANGELOG.md @@ -7,6 +7,7 @@ ### Fixed - `NineSliceSprite` blinks with `flicker()`, as a `Sprite` does; it ignored it +- glTF: a model compressed with Draco or meshopt, which the loader cannot decode, says so in the console, naming the extension, instead of failing on an accessor error that did not mention it ## [20.16.0] (melonJS 2) - _2026-11-17_ diff --git a/packages/melonjs/skills/melonjs-3d-assets/SKILL.md b/packages/melonjs/skills/melonjs-3d-assets/SKILL.md index faee36d9d..ad6ddd6d4 100644 --- a/packages/melonjs/skills/melonjs-3d-assets/SKILL.md +++ b/packages/melonjs/skills/melonjs-3d-assets/SKILL.md @@ -160,9 +160,12 @@ arrives without them, which reads as "flatter than the preview in my authoring tool". Bake what you need into the base colour. (OBJ/MTL does carry a normal map, see below.) -**Draco compression is the exception that does error.** Its geometry sits in -accessors with no buffer view, which the parser rejects outright, so the whole -asset fails to load. Export uncompressed. +**Mesh compression is the exception that does error.** Draco +(`KHR_draco_mesh_compression`) and meshopt (`EXT_meshopt_compression`, +`KHR_meshopt_compression`) cannot be decoded. A file that requires one warns in +the console, naming it, and fails to load; a file that only uses one (it also +carries its meshes uncompressed) warns and loads the uncompressed copy. Export +without mesh compression. `textureFilter` on the Application settings (`"auto"` / `"nearest"` / `"linear"` / `"linear-mipmap"`) drives sampling; glTF materials that declare @@ -689,7 +692,7 @@ need a prefix. | model mirrored — text backwards, gear on the wrong side | `Mesh` defaults `rightHanded` to `false`; pass `true` | | model upside down | a manual axis flip on top of the loader's conversion | | scene is enormous or invisibly small | `scale` left at 1 against a metre-scale export | -| the asset fails to load entirely | an external buffer/image `uri` that 404s, or Draco-compressed geometry | +| the asset fails to load entirely | an external buffer/image `uri` that 404s, or mesh compression the loader cannot decode (Draco, meshopt): the console names it | | everything is blown out white | authored lux/candela intensities; use `lightIntensityScale` | | materials flatter than the authoring-tool preview | no normal or metallic/roughness *textures* are imported | | a glTF `alphaMode: "BLEND"` material draws opaque | the loader does not set `transparent`; set it on that part yourself | diff --git a/packages/melonjs/src/loader/parsers/gltf.js b/packages/melonjs/src/loader/parsers/gltf.js index 7cc3691ac..ef48dbea1 100644 --- a/packages/melonjs/src/loader/parsers/gltf.js +++ b/packages/melonjs/src/loader/parsers/gltf.js @@ -658,6 +658,49 @@ function loadImageFromUrl(url, revoke = false, crossOrigin) { }); } +/** + * The glTF mesh compression extensions the loader cannot decode, and what + * to call each in a message. + * @ignore + */ +const MESH_COMPRESSION = { + KHR_draco_mesh_compression: "Draco mesh compression", + EXT_meshopt_compression: "meshopt compression", + KHR_meshopt_compression: "meshopt compression", +}; + +/** + * Say so in the console when a model's meshes are compressed in a way the + * loader cannot decode, rather than failing on an accessor with no data. + * + * A file that only uses the extension (`extensionsUsed`) also carries its + * meshes uncompressed, and loads from those, with a warning. One that + * requires it (`extensionsRequired`) has nothing else to read: it warns, and + * the load fails with the same message. + * @ignore + * @internal + * @param {object} json - the glTF JSON + * @param {string} [baseURI] - where the file came from, for the message + */ +export function checkMeshCompression(json, baseURI) { + const required = json.extensionsRequired || []; + for (const ext of json.extensionsUsed || []) { + const name = MESH_COMPRESSION[ext]; + if (name === undefined) { + continue; + } + const where = baseURI ? ` (${baseURI})` : ""; + if (required.includes(ext)) { + const message = `melonJS: this glTF model${where} uses ${name} (${ext}), which the loader cannot decode: export it again without mesh compression`; + console.warn(message); + throw new Error(message); + } + console.warn( + `melonJS: this glTF model${where} uses ${name} (${ext}), which the loader cannot decode: its uncompressed copy is loaded instead`, + ); + } +} + /** * Parse a glTF/GLB ArrayBuffer into a flat, instantiable scene descriptor. * @param {ArrayBuffer} arrayBuffer - the .glb / .gltf bytes @@ -721,6 +764,7 @@ function readSkinInfluences(json, buffers, prim, vertexCount, skin) { export async function parseGLTF(arrayBuffer, baseURI, settings) { const { json, bin } = parseGLB(arrayBuffer); + checkMeshCompression(json, baseURI); const buffers = await resolveBuffers(json, bin, baseURI, settings); // decode every image once, keyed by image index diff --git a/packages/melonjs/tests/gltf.spec.js b/packages/melonjs/tests/gltf.spec.js index 719105841..ee749f820 100644 --- a/packages/melonjs/tests/gltf.spec.js +++ b/packages/melonjs/tests/gltf.spec.js @@ -1,4 +1,4 @@ -import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; import { Application, boot, @@ -272,6 +272,92 @@ describe("parseGLTF()", () => { // A malformed asset must degrade gracefully (empty-but-valid descriptor or a // clear thrown error) — never crash the engine or silently render nothing. +describe("parseGLTF() with mesh compression it cannot decode", () => { + /** a one-triangle model, its mesh compressed with `ext` */ + const compressed = (ext, required) => { + const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]); + return packGLB( + { + asset: { version: "2.0" }, + extensionsUsed: [ext], + extensionsRequired: required ? [ext] : undefined, + scene: 0, + scenes: [{ nodes: [0] }], + nodes: [{ mesh: 0 }], + meshes: [ + { + primitives: [ + { + attributes: { POSITION: required ? 1 : 0 }, + extensions: { [ext]: { bufferView: 0, attributes: {} } }, + }, + ], + }, + ], + accessors: [ + { bufferView: 0, componentType: 5126, count: 3, type: "VEC3" }, + // compressed: no data of its own + { componentType: 5126, count: 3, type: "VEC3" }, + ], + bufferViews: [ + { buffer: 0, byteOffset: 0, byteLength: positions.byteLength }, + ], + buffers: [{ byteLength: positions.byteLength }], + }, + new Uint8Array(positions.buffer), + ); + }; + + for (const [ext, name] of [ + ["KHR_draco_mesh_compression", "Draco"], + ["EXT_meshopt_compression", "meshopt"], + ["KHR_meshopt_compression", "meshopt"], + ]) { + it(`${ext}, required: warns, and fails naming it`, async () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + try { + await expect(parseGLTF(compressed(ext, true))).rejects.toThrow( + new RegExp(`${name}.*${ext}`), + ); + expect(warn).toHaveBeenCalledTimes(1); + expect(warn.mock.calls[0][0]).toMatch(ext); + expect(warn.mock.calls[0][0]).toMatch(/export it again/); + } finally { + warn.mockRestore(); + } + }); + + it(`${ext}, only used: warns, and loads the uncompressed copy`, async () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + try { + const scene = await parseGLTF(compressed(ext, false)); + expect(scene.nodes).toHaveLength(1); + expect(warn).toHaveBeenCalledTimes(1); + expect(warn.mock.calls[0][0]).toMatch(/uncompressed copy/); + } finally { + warn.mockRestore(); + } + }); + } + + it("an extension it can read is not warned about", async () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + try { + const json = { + asset: { version: "2.0" }, + extensionsUsed: ["KHR_materials_unlit"], + scene: 0, + scenes: [{ nodes: [] }], + nodes: [], + }; + await parseGLTF(packGLB(json, new Uint8Array(0))); + expect(warn).not.toHaveBeenCalled(); + } finally { + warn.mockRestore(); + } + }); +}); + describe("parseGLTF() robustness", () => { it("synthesizes a sequential index buffer for non-indexed primitives", async () => { const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);