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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(assets): a glTF the importer cannot read says so
esenginec5afccbba3b5
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.tsindex 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: striconst 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: strireturn 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.tsindex 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.tsindex 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.tsindex 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: (Uint8Arrif (!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. */