Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/melonjs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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_

Expand Down
11 changes: 7 additions & 4 deletions packages/melonjs/skills/melonjs-3d-assets/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 |
Expand Down
44 changes: 44 additions & 0 deletions packages/melonjs/src/loader/parsers/gltf.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
88 changes: 87 additions & 1 deletion packages/melonjs/tests/gltf.spec.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import {
Application,
boot,
Expand Down Expand Up @@ -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]);
Expand Down
Loading