Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(assets): a glTF the importer cannot read says so

esenginec5afccbba3b5
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.ts
index 595f61d6c..58dca2213 100644
--- a/desktop/electron/importModel.ts
+++ b/desktop/electron/importModel.ts
@@ -49,7 +49,7 @@ export async function importModel(root: string, destDir: string, absSource: stri
const projectRef = (abs: string): string =>
path.relative(path.resolve(root), abs).split(path.sep).join('/');
- const { meshes, textures, nodes, warnings } = importGltfMeshes(
+ const { meshes, textures, nodes, externalFiles, warnings } = importGltfMeshes(
new Uint8Array(readFileSync(absSource)), stem,
(uri) => {
const abs = path.join(sourceDir, decodeURIComponent(uri));
@@ -67,28 +67,34 @@ export async function importModel(root: string, destDir: string, absSource: stri
return rel;
};
- // An image the source points at is left where it lies when that is already in
- // the project; one from outside is copied in, named for the model so a second
- // import of a different model cannot land on it.
+ // A file already in the project is left where it lies; one from outside comes
+ // WITH the model, at the same relative path. That is what keeps the copied
+ // .gltf pointing at its own .bin, so re-importing it still works.
const externalRefs = new Map<string, string>();
const external = (uri: string): string => externalRefs.get(uri) ?? uri;
- const sourceImages = meshes.flatMap((mesh) =>
- [mesh.material?.baseColorTexture, mesh.material?.normalTexture]);
- for (const image of sourceImages) {
- if (!image?.external || externalRefs.has(image.file)) continue;
- const abs = path.join(sourceDir, decodeURIComponent(image.file));
+ for (const uri of externalFiles) {
+ const abs = path.join(sourceDir, uri);
if (!existsSync(abs)) continue;
if (isInsideRoot(root, abs)) {
- externalRefs.set(image.file, projectRef(abs));
+ externalRefs.set(uri, projectRef(abs));
continue;
}
- const name = `${stem}_${path.basename(abs)}`;
+ // A uri that reaches outside the model's own folder cannot keep its shape in
+ // the project: it lands beside the model, and the source's link to it stays
+ // broken — said out loud rather than silently rewritten.
+ const keepsShape = isInsideRoot(absDir, path.resolve(absDir, uri));
+ if (!keepsShape) {
+ warnings.push(`${uri} came from outside the model's folder; the copy is beside it`);
+ }
+ const name = keepsShape ? uri : path.basename(uri);
const rel = destDir ? `${destDir}/${name}` : name;
+ const absDest = path.join(absDir, name);
await capture(rel, 'write');
- await copyFile(abs, path.join(absDir, name));
- await adoptOrphan(path.join(absDir, name));
+ await mkdir(path.dirname(absDest), { recursive: true });
+ await copyFile(abs, absDest);
+ await adoptOrphan(absDest);
products.push(rel);
- externalRefs.set(image.file, rel);
+ externalRefs.set(uri, rel);
}
for (const mesh of meshes) await write(`${mesh.name}.esmesh`, encodeImportedMesh(mesh));
diff --git a/desktop/tests/gltf-import.test.ts b/desktop/tests/gltf-import.test.ts
index edb383cae..3aa23d197 100644
--- a/desktop/tests/gltf-import.test.ts
+++ b/desktop/tests/gltf-import.test.ts
@@ -181,6 +181,73 @@ describe('glTF material import', () => {
.toEqual({ file: 'bump.png', external: true });
});
+ it('skips a Draco-compressed primitive rather than reading zeroes', () => {
+ const doc = {
+ ...withInlineImage(),
+ // Draco holds the geometry itself, so the accessors point at nothing.
+ accessors: [
+ { componentType: 5126, count: 3, type: 'VEC3' },
+ { componentType: 5126, count: 3, type: 'VEC2' },
+ { componentType: 5123, count: 3, type: 'SCALAR' },
+ ],
+ };
+ const { meshes, warnings } = importGltfMeshes(gltf(doc, [{
+ attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, material: 0, mode: 4,
+ extensions: { KHR_draco_mesh_compression: { bufferView: 0, attributes: {} } },
+ }]), 'model');
+ expect(meshes).toEqual([]);
+ expect(warnings.join('\n')).toContain('Draco-compressed');
+ expect(warnings.join('\n')).toContain('re-export without compression');
+ });
+
+ it('skips a primitive whose POSITION carries no data', () => {
+ const doc = {
+ ...withInlineImage(),
+ accessors: [
+ { componentType: 5126, count: 3, type: 'VEC3' },
+ { bufferView: 1, componentType: 5126, count: 3, type: 'VEC2' },
+ { bufferView: 2, componentType: 5123, count: 3, type: 'SCALAR' },
+ ],
+ };
+ const { meshes, warnings } = importGltfMeshes(gltf(doc), 'model');
+ expect(meshes).toEqual([]);
+ expect(warnings.join('\n')).toContain('POSITION has no data');
+ });
+
+ it('applies a sparse accessor, which is the geometry it actually has', () => {
+ // Replaces vertex 1's position; the base view is the ordinary one.
+ const target = Buffer.alloc(2);
+ target.writeUInt16LE(1, 0);
+ const value = Buffer.from(new Float32Array([9, 9, 9]).buffer);
+ const extra = Buffer.concat([target, value]);
+ const geo = geometryBuffer();
+ const base = Buffer.from(geo.uri.split(',')[1]!, 'base64');
+ const bytes = Buffer.concat([base, extra]);
+ const doc = {
+ ...withInlineImage(),
+ buffers: [{ byteLength: bytes.length, uri: `data:application/octet-stream;base64,${bytes.toString('base64')}` }],
+ bufferViews: [
+ ...(geo.views as unknown[]),
+ { buffer: 0, byteOffset: 66, byteLength: 2 },
+ { buffer: 0, byteOffset: 68, byteLength: 12 },
+ ],
+ accessors: [
+ {
+ bufferView: 0, componentType: 5126, count: 3, type: 'VEC3',
+ sparse: {
+ count: 1,
+ indices: { bufferView: 3, componentType: 5123 },
+ values: { bufferView: 4 },
+ },
+ },
+ { bufferView: 1, componentType: 5126, count: 3, type: 'VEC2' },
+ { bufferView: 2, componentType: 5123, count: 3, type: 'SCALAR' },
+ ],
+ };
+ const { meshes } = importGltfMeshes(gltf(doc), 'model');
+ expect(meshes[0]!.data.aabbMax).toEqual([9, 9, 9]);
+ });
+
it("flips V, because glTF's uv origin is the image's top-left", () => {
const { meshes } = importGltfMeshes(gltf(withInlineImage()), 'model');
expect(texCoords(meshes[0]!)).toEqual([0, 1, 1, 1, 0, 0]);
diff --git a/desktop/tests/import-model.test.ts b/desktop/tests/import-model.test.ts
index 7bdbc6ac0..b48b9b5fa 100644
--- a/desktop/tests/import-model.test.ts
+++ b/desktop/tests/import-model.test.ts
@@ -92,17 +92,68 @@ describe('importing a model', () => {
expect(existsSync(path.join(root, 'assets/elsewhere/tree.esmesh'))).toBe(false);
});
- it('brings an outside image in, named for the model', async () => {
- writeFileSync(path.join(outside, 'skin.png'), 'PNG');
+ it('brings an outside image in at the path the model names it by', async () => {
+ mkdirSync(path.join(outside, 'textures'), { recursive: true });
+ writeFileSync(path.join(outside, 'textures/skin.png'), 'PNG');
const src = path.join(outside, 'robot.gltf');
- writeFileSync(src, gltf('skin.png'));
+ writeFileSync(src, gltf('textures/skin.png'));
await importAssets(root, 'assets/models', [src]);
- const copied = path.join(root, 'assets/models/robot_skin.png');
+ // The same relative path, so the copied .gltf still points at its own image.
+ const copied = path.join(root, 'assets/models/textures/skin.png');
expect(existsSync(copied)).toBe(true);
expect(meta(copied).type).toBe('texture');
const prefab = prefabOf(path.join(root, 'assets/models/robot.esprefab'));
- expect(prefab.entities[0]!.components[1]!.data.texture).toBe('assets/models/robot_skin.png');
+ expect(prefab.entities[0]!.components[1]!.data.texture)
+ .toBe('assets/models/textures/skin.png');
+ });
+
+ it('brings the .bin with it, so the copy can be imported again', async () => {
+ const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+ const uvs = new Float32Array([0, 0, 1, 0, 0, 1]);
+ const indices = new Uint16Array([0, 1, 2]);
+ const bin = Buffer.concat([
+ Buffer.from(positions.buffer), Buffer.from(uvs.buffer), Buffer.from(indices.buffer),
+ ]);
+ writeFileSync(path.join(outside, 'robot.bin'), bin);
+ const doc = JSON.parse(gltf()) as { buffers: { uri: string; byteLength: number }[] };
+ doc.buffers = [{ uri: 'robot.bin', byteLength: bin.length }];
+ const src = path.join(outside, 'robot.gltf');
+ writeFileSync(src, JSON.stringify(doc));
+
+ const first = await importAssets(root, 'assets/models', [src]);
+ expect(first.imported).toContain('assets/models/robot.bin');
+ expect(first.warnings ?? []).toEqual([]);
+
+ // The copy, imported on its own terms: the geometry has to come out again.
+ rmSync(outside, { recursive: true, force: true });
+ const again = await importAssets(root, 'assets/models',
+ [path.join(root, 'assets/models/robot.gltf')]);
+ expect(again.imported).toContain('assets/models/robot.esmesh');
+ expect(again.warnings ?? []).toEqual([]);
+ });
+
+ it('says so when a dependency cannot keep its shape inside the project', async () => {
+ mkdirSync(path.join(outside, 'model'), { recursive: true });
+ writeFileSync(path.join(outside, 'shared.png'), 'PNG');
+ const src = path.join(outside, 'model/robot.gltf');
+ writeFileSync(src, gltf('../shared.png'));
+ const res = await importAssets(root, 'assets/models', [src]);
+
+ expect(existsSync(path.join(root, 'assets/models/shared.png'))).toBe(true);
+ expect(res.warnings?.join('\n')).toContain("outside the model's folder");
+ });
+
+ it('never writes a dependency outside the project', async () => {
+ mkdirSync(path.join(outside, 'model'), { recursive: true });
+ writeFileSync(path.join(outside, 'evil.png'), 'PNG');
+ const src = path.join(outside, 'model/robot.gltf');
+ // Escapes without starting with "..", which is what a hand-rolled check misses.
+ writeFileSync(src, gltf('sub/../../evil.png'));
+ await importAssets(root, 'assets/models', [src]);
+
+ expect(existsSync(path.join(root, 'assets/models/evil.png'))).toBe(true);
+ expect(existsSync(path.join(root, '../evil.png'))).toBe(false);
});
it('leaves an image that is already in the project where it lies', async () => {
diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.ts
index d93a941cc..87ecc4ca6 100644
--- a/pipeline/src/assets/gltfImport.ts
+++ b/pipeline/src/assets/gltfImport.ts
@@ -76,6 +76,9 @@ export interface GltfImportResult {
meshes: ImportedMesh[];
/** Images extracted from the file itself; external ones stay where they are. */
textures: ImportedTexture[];
+ /** Every uri the source points OUT to (buffers and images), in file order.
+ * Bringing a model into a project means bringing these with it. */
+ externalFiles: string[];
/** The scene's node roots. Empty for a file with no nodes, whose meshes then sit flat. */
nodes: ImportedNode[];
/** What was skipped and why — a silent drop is how half a model goes missing. */
@@ -95,15 +98,24 @@ const TYPE_COMPONENTS: Record<string, number> = {
interface GltfTextureRef { index: number; texCoord?: number }
+/** Per-spec sparse storage: a base of zeroes (or a view) with some values replaced. */
+interface GltfSparse {
+ count: number;
+ indices: { bufferView: number; byteOffset?: number; componentType: number };
+ values: { bufferView: number; byteOffset?: number };
+}
+
interface GltfJson {
accessors?: {
bufferView?: number; byteOffset?: number; componentType: number; count: number;
type: string; normalized?: boolean; min?: number[]; max?: number[];
+ sparse?: GltfSparse;
}[];
bufferViews?: { buffer: number; byteOffset?: number; byteLength: number; byteStride?: number }[];
buffers?: { byteLength: number; uri?: string }[];
meshes?: { name?: string; primitives: {
attributes: Record<string, number>; indices?: number; mode?: number; material?: number;
+ extensions?: Record<string, unknown>;
}[] }[];
materials?: {
name?: string;
@@ -128,6 +140,16 @@ interface GltfJson {
scene?: number;
}
+/**
+ * Extensions that hold a primitive's geometry themselves, so its accessors point
+ * at nothing this importer can read. Left undetected they decode as zeroes — a
+ * mesh whose every vertex sits on the origin, with nothing said about it.
+ */
+const COMPRESSED_GEOMETRY: Record<string, string> = {
+ KHR_draco_mesh_compression: 'Draco',
+ EXT_meshopt_compression: 'meshopt',
+};
+
const MIME_EXTENSION: Record<string, string> = {
'image/png': '.png', 'image/jpeg': '.jpg', 'image/webp': '.webp', 'image/ktx2': '.ktx2',
};
@@ -173,28 +195,55 @@ function readAccessor(json: GltfJson, bin: Uint8Array | null, buffers: (Uint8Arr
if (!compBytes) throw new Error(`accessor ${index} has unsupported componentType ${acc.componentType}`);
const out = new Float32Array(acc.count * comps);
- if (acc.bufferView === undefined) return out; // spec: absent view ⇒ zeroes
-
- const view = json.bufferViews?.[acc.bufferView];
- if (!view) throw new Error(`bufferView ${acc.bufferView} is missing`);
- const source = view.buffer === 0 && bin ? bin : buffers[view.buffer];
- if (!source) throw new Error(`buffer ${view.buffer} has no bytes (external .bin not loaded?)`);
-
- const base = (view.byteOffset ?? 0) + (acc.byteOffset ?? 0);
- const stride = view.byteStride && view.byteStride > 0 ? view.byteStride : comps * compBytes;
- const dv = new DataView(source.buffer, source.byteOffset, source.byteLength);
const scale = acc.normalized ? normalizedScale(acc.componentType) : 0;
+ const read = (dv: DataView, at: number): number => {
+ const raw = readComponent(dv, at, acc.componentType);
+ return acc.normalized ? raw * scale : raw;
+ };
- for (let i = 0; i < acc.count; i++) {
- for (let c = 0; c < comps; c++) {
- const at = base + i * stride + c * compBytes;
- const raw = readComponent(dv, at, acc.componentType);
- out[i * comps + c] = acc.normalized ? raw * scale : raw;
+ if (acc.bufferView !== undefined) {
+ const view = json.bufferViews?.[acc.bufferView];
+ if (!view) throw new Error(`bufferView ${acc.bufferView} is missing`);
+ const source = view.buffer === 0 && bin ? bin : buffers[view.buffer];
+ if (!source) throw new Error(`buffer ${view.buffer} has no bytes (external .bin not loaded?)`);
+
+ const base = (view.byteOffset ?? 0) + (acc.byteOffset ?? 0);
+ const stride = view.byteStride && view.byteStride > 0 ? view.byteStride : comps * compBytes;
+ const dv = new DataView(source.buffer, source.byteOffset, source.byteLength);
+ for (let i = 0; i < acc.count; i++) {
+ for (let c = 0; c < comps; c++) {
+ out[i * comps + c] = read(dv, base + i * stride + c * compBytes);
+ }
}
}
+ // A sparse accessor overrides some of that — or all of it, since the base
+ // view is optional. Ignoring it reads a mesh in its pre-morph state, which
+ // is wrong geometry rather than a failure.
+ if (acc.sparse) applySparse(json, bin, buffers, acc.sparse, comps, compBytes, read, out);
return out;
}
+function applySparse(json: GltfJson, bin: Uint8Array | null, buffers: (Uint8Array | null)[],
+ sparse: GltfSparse, comps: number, compBytes: number,
+ read: (dv: DataView, at: number) => number, out: Float32Array): void {
+ const indexBytes = COMPONENT_BYTES[sparse.indices.componentType];
+ if (!indexBytes) throw new Error(`sparse indices use componentType ${sparse.indices.componentType}`);
+ const indexView = sliceBufferView(json, bin, buffers, sparse.indices.bufferView);
+ const valueView = sliceBufferView(json, bin, buffers, sparse.values.bufferView);
+ if (!indexView || !valueView) throw new Error('sparse accessor has no bytes');
+
+ const iv = new DataView(indexView.buffer, indexView.byteOffset, indexView.byteLength);
+ const vv = new DataView(valueView.buffer, valueView.byteOffset, valueView.byteLength);
+ const indexBase = sparse.indices.byteOffset ?? 0;
+ const valueBase = sparse.values.byteOffset ?? 0;
+ for (let i = 0; i < sparse.count; i++) {
+ const target = readComponent(iv, indexBase + i * indexBytes, sparse.indices.componentType);
+ for (let c = 0; c < comps; c++) {
+ out[target * comps + c] = read(vv, valueBase + (i * comps + c) * compBytes);
+ }
+ }
+}
+
function normalizedScale(componentType: number): number {
switch (componentType) {
case 5120: return 1 / 127;
@@ -441,14 +490,24 @@ export function importGltfMeshes(
json = JSON.parse(new TextDecoder().decode(bytes)) as GltfJson;
}
+ const externalFiles: string[] = [];
+ const noteExternal = (uri: string): void => {
+ const decoded = decodeURIComponent(uri);
+ if (!externalFiles.includes(decoded)) externalFiles.push(decoded);
+ };
+
const buffers: (Uint8Array | null)[] = (json.buffers ?? []).map((b, i) => {
if (!b.uri) return i === 0 ? bin : null;
const inline = decodeDataUri(b.uri);
if (inline) return inline;
+ noteExternal(b.uri);
const external = externalBuffers?.(b.uri) ?? null;
if (!external) warnings.push(`buffer ${i}: ${b.uri} could not be read`);
return external;
});
+ for (const image of json.images ?? []) {
+ if (image.uri && !image.uri.startsWith('data:')) noteExternal(image.uri);
+ }
const meshes: ImportedMesh[] = [];
const textures: ImportedTexture[] = [];
@@ -475,11 +534,28 @@ export function importGltfMeshes(
warnings.push(`${label}: mode ${mode} is not TRIANGLES — skipped`);
return;
}
+ const compressed = Object.keys(prim.extensions ?? {})
+ .find(name => name in COMPRESSED_GEOMETRY);
+ if (compressed) {
+ warnings.push(`${label}: geometry is ${COMPRESSED_GEOMETRY[compressed]}-compressed`
+ + ' — skipped (re-export without compression)');
+ return;
+ }
+ for (const name of Object.keys(prim.extensions ?? {})) {
+ if (!(name in COMPRESSED_GEOMETRY)) warnings.push(`${label}: ${name} not imported`);
+ }
const posIndex = prim.attributes.POSITION;
if (posIndex === undefined) {
warnings.push(`${label}: no POSITION — skipped`);
return;
}
+ // Zeroes are a legal accessor per spec, and for POSITION they are a
+ // heap of vertices on the origin. Say so instead of writing one.
+ const posAccessor = json.accessors?.[posIndex];
+ if (posAccessor && posAccessor.bufferView === undefined && !posAccessor.sparse) {
+ warnings.push(`${label}: POSITION has no data — skipped`);
+ return;
+ }
try {
const positions = readAccessor(json, bin, buffers, posIndex);
@@ -561,7 +637,10 @@ export function importGltfMeshes(
if (meshes.length === 0 && warnings.length === 0) {
warnings.push('no triangle geometry found');
}
- return { meshes, textures, nodes: readNodes(json, meshIndexOf, warnings), warnings };
+ return {
+ meshes, textures, externalFiles,
+ nodes: readNodes(json, meshIndexOf, warnings), warnings,
+ };
}
/** The bytes to write for an imported mesh. */