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
feat(assets): an imported model stands where it was built
esengine1b0350f2cb3a
diff --git a/desktop/public/scenes/lit-triangles.esprefab b/desktop/public/scenes/lit-triangles.esprefabindex 1101c73ee..79b3d0769 100644--- a/desktop/public/scenes/lit-triangles.esprefab+++ b/desktop/public/scenes/lit-triangles.esprefab@@ -1,11 +1,11 @@{"version": "2","name": "lit-triangles",- "rootEntityId": "0",+ "rootEntityId": "n0","entities": [{- "prefabEntityId": "0",- "name": "lit-triangles",+ "prefabEntityId": "n0",+ "name": "node_0","parent": null,"children": [],"visible": true,diff --git a/desktop/public/scenes/mesh-nodes.esscene b/desktop/public/scenes/mesh-nodes.esscenenew file mode 100644index 000000000..e639f63c6--- /dev/null+++ b/desktop/public/scenes/mesh-nodes.esscene@@ -0,0 +1,17 @@+{+ "version": 1,+ "name": "MeshNodes",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mesh-nodes.textures.json b/desktop/public/scenes/mesh-nodes.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mesh-nodes.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/node-tree.esprefab b/desktop/public/scenes/node-tree.esprefabnew file mode 100644index 000000000..4803c5169--- /dev/null+++ b/desktop/public/scenes/node-tree.esprefab@@ -0,0 +1,98 @@+{+ "version": "2",+ "name": "node-tree",+ "rootEntityId": "n0",+ "entities": [+ {+ "prefabEntityId": "n0",+ "name": "Model",+ "parent": null,+ "children": [+ "n1",+ "n2"+ ],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 40,+ "y": 0,+ "z": 0+ }+ }+ }+ ]+ },+ {+ "prefabEntityId": "n1",+ "name": "Left",+ "parent": "n0",+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -120,+ "y": 60,+ "z": 0+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "scenes/node-tree_0_0.esmesh",+ "color": {+ "r": 1,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "enabled": true+ }+ }+ ]+ },+ {+ "prefabEntityId": "n2",+ "name": "Right",+ "parent": "n0",+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 120,+ "y": -60,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 1+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "scenes/node-tree_1_0.esmesh",+ "color": {+ "r": 0,+ "g": 1,+ "b": 0,+ "a": 1+ },+ "enabled": true+ }+ }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/node-tree.gltf b/desktop/public/scenes/node-tree.gltfnew file mode 100644index 000000000..90236a810--- /dev/null+++ b/desktop/public/scenes/node-tree.gltf@@ -0,0 +1,147 @@+{+ "asset": {+ "version": "2.0",+ "generator": "estella test fixture"+ },+ "buffers": [+ {+ "byteLength": 60,+ "uri": "data:application/octet-stream;base64,AABwwgAAcEIAAAAAAABwQgAAcEIAAAAAAABwwgAAcMIAAAAAAABwQgAAcMIAAAAAAAACAAEAAQACAAMA"+ }+ ],+ "bufferViews": [+ {+ "buffer": 0,+ "byteOffset": 0,+ "byteLength": 48+ },+ {+ "buffer": 0,+ "byteOffset": 48,+ "byteLength": 12+ }+ ],+ "accessors": [+ {+ "bufferView": 0,+ "componentType": 5126,+ "count": 4,+ "type": "VEC3",+ "min": [+ -60,+ -60,+ 0+ ],+ "max": [+ 60,+ 60,+ 0+ ]+ },+ {+ "bufferView": 1,+ "componentType": 5123,+ "count": 6,+ "type": "SCALAR"+ }+ ],+ "materials": [+ {+ "name": "Red",+ "pbrMetallicRoughness": {+ "baseColorFactor": [+ 1,+ 0,+ 0,+ 1+ ],+ "metallicFactor": 0+ }+ },+ {+ "name": "Green",+ "pbrMetallicRoughness": {+ "baseColorFactor": [+ 0,+ 1,+ 0,+ 1+ ],+ "metallicFactor": 0+ }+ }+ ],+ "meshes": [+ {+ "name": "Left",+ "primitives": [+ {+ "attributes": {+ "POSITION": 0+ },+ "indices": 1,+ "material": 0,+ "mode": 4+ }+ ]+ },+ {+ "name": "Right",+ "primitives": [+ {+ "attributes": {+ "POSITION": 0+ },+ "indices": 1,+ "material": 1,+ "mode": 4+ }+ ]+ }+ ],+ "nodes": [+ {+ "name": "Model",+ "translation": [+ 40,+ 0,+ 0+ ],+ "children": [+ 1,+ 2+ ]+ },+ {+ "name": "Left",+ "mesh": 0,+ "translation": [+ -120,+ 60,+ 0+ ]+ },+ {+ "name": "Right",+ "mesh": 1,+ "translation": [+ 120,+ -60,+ 0+ ],+ "scale": [+ 0.5,+ 0.5,+ 1+ ]+ }+ ],+ "scenes": [+ {+ "nodes": [+ 0+ ]+ }+ ],+ "scene": 0+}diff --git a/desktop/public/scenes/node-tree_0_0.esmesh b/desktop/public/scenes/node-tree_0_0.esmeshnew file mode 100644index 000000000..c90a0f0e0Binary files /dev/null and b/desktop/public/scenes/node-tree_0_0.esmesh differdiff --git a/desktop/public/scenes/node-tree_1_0.esmesh b/desktop/public/scenes/node-tree_1_0.esmeshnew file mode 100644index 000000000..c90a0f0e0Binary files /dev/null and b/desktop/public/scenes/node-tree_1_0.esmesh differdiff --git a/desktop/public/scenes/textured-quad.esprefab b/desktop/public/scenes/textured-quad.esprefabindex 66d0dea6b..797b7c0e7 100644--- a/desktop/public/scenes/textured-quad.esprefab+++ b/desktop/public/scenes/textured-quad.esprefab@@ -1,11 +1,11 @@{"version": "2","name": "textured-quad",- "rootEntityId": "0",+ "rootEntityId": "n0","entities": [{- "prefabEntityId": "0",- "name": "textured-quad",+ "prefabEntityId": "n0",+ "name": "node_0","parent": null,"children": [],"visible": true,diff --git a/desktop/public/scenes/two-triangles.esprefab b/desktop/public/scenes/two-triangles.esprefabindex dbafee4b4..f08619325 100644--- a/desktop/public/scenes/two-triangles.esprefab+++ b/desktop/public/scenes/two-triangles.esprefab@@ -1,11 +1,11 @@{"version": "2","name": "two-triangles",- "rootEntityId": "0",+ "rootEntityId": "n0","entities": [{- "prefabEntityId": "0",- "name": "two-triangles",+ "prefabEntityId": "n0",+ "name": "node_0","parent": null,"children": [],"visible": true,diff --git a/desktop/public/scenes/white-triangles.esprefab b/desktop/public/scenes/white-triangles.esprefabindex b3b26783d..003c6281b 100644--- a/desktop/public/scenes/white-triangles.esprefab+++ b/desktop/public/scenes/white-triangles.esprefab@@ -1,11 +1,11 @@{"version": "2","name": "white-triangles",- "rootEntityId": "0",+ "rootEntityId": "n0","entities": [{- "prefabEntityId": "0",- "name": "white-triangles",+ "prefabEntityId": "n0",+ "name": "node_0","parent": null,"children": [],"visible": true,diff --git a/desktop/scripts/make-mesh-fixture.mjs b/desktop/scripts/make-mesh-fixture.mjsindex 8767d0756..bd954a09d 100644--- a/desktop/scripts/make-mesh-fixture.mjs+++ b/desktop/scripts/make-mesh-fixture.mjs@@ -21,12 +21,13 @@ const cli = path.join(HERE, '..', '..', 'pipeline', 'bin', 'estella.mjs');// two-triangles: the mesh2d geometry, so a file drawing what the scene draws is// the claim. lit-triangles: the same shape with per-face NORMALS and one white-// colour. textured-quad: an inline image and a baseColor factor.+// colour. textured-quad: an inline image and a baseColor factor. node-tree: a+// parent and two placed children, one of them scaled.//// public/ stands in for the project root, so the prefab's refs read `scenes/…`// — the spelling a component carries, resolved from the served root.for (const name of ['two-triangles.gltf', 'lit-triangles.gltf', 'white-triangles.gltf',- 'textured-quad.gltf']) {+ 'textured-quad.gltf', 'node-tree.gltf']) {const run = spawnSync(process.execPath,[cli, 'import-gltf', path.join(scenes, name), '--project', path.join(HERE, '..', 'public')], {stdio: 'inherit',diff --git a/desktop/tests/gltf-import.test.ts b/desktop/tests/gltf-import.test.tsindex d37f4b17b..2f79249f9 100644--- a/desktop/tests/gltf-import.test.ts+++ b/desktop/tests/gltf-import.test.ts@@ -1,15 +1,15 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file glTF material/image import: what the products say about each other.+ * @file glTF material/image/node import: what the products say about each other.*- * The pixels a gate asserts prove the chain end to end, but only for one file.- * These cover the shapes that file is not: an image in a GLB chunk, an image- * already on disk, a primitive with no material, several primitives at once.+ * The pixel gates prove the chain end to end, but only for the files they draw.+ * These cover the shapes those are not: an image in a GLB chunk, an image+ * already on disk, a node given as a matrix, a file with no node tree at all.*/import { describe, it, expect } from 'vitest';import {- importGltfMeshes, assembleGltfPrefab, type ImportedMesh,+ importGltfMeshes, assembleGltfPrefab, type ImportedMesh, type PrefabAssembly,} from '../../pipeline/src/assets/gltfImport';import { MeshChannel } from 'esengine';@@ -174,13 +174,17 @@ describe('glTF material import', () => {});describe('glTF prefab assembly', () => {- const meshesOf = (bytes: Uint8Array) => importGltfMeshes(bytes, 'model').meshes;+ const assemble = (bytes: Uint8Array, options: Partial<PrefabAssembly> = {}) => {+ const { meshes, nodes } = importGltfMeshes(bytes, 'model');+ return assembleGltfPrefab('model', meshes, { nodes, ...options });+ };+ const oneNode = { nodes: [{ mesh: 0 }], scenes: [{ nodes: [0] }], scene: 0 };- it('makes the single primitive the root itself', () => {- const prefab = assembleGltfPrefab('model', meshesOf(gltf(withInlineImage())),- { prefix: 'assets/models/' });+ it('draws a single-primitive node from the node itself', () => {+ const prefab = assemble(gltf({ ...withInlineImage(), ...oneNode }),+ { refs: { prefix: 'assets/models/' } });expect(prefab.entities).toHaveLength(1);- expect(prefab.rootEntityId).toBe('0');+ expect(prefab.rootEntityId).toBe('n0');expect(prefab.entities[0]!.components[1]).toEqual({type: 'Mesh2D',data: {@@ -192,27 +196,80 @@ describe('glTF prefab assembly', () => {});});- it('holds several primitives under one root', () => {+ it('hangs a node’s further primitives off it', () => {const two = [{ attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, material: 0, mode: 4 },{ attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, mode: 4 },];- const prefab = assembleGltfPrefab('model', meshesOf(gltf(withInlineImage(), two)));- expect(prefab.entities.map(e => e.prefabEntityId)).toEqual(['0', '1', '2']);- expect(prefab.entities[0]!.children).toEqual(['1', '2']);- expect(prefab.entities[1]!.parent).toBe('0');+ const prefab = assemble(gltf({ ...withInlineImage(), ...oneNode }, two));+ expect(prefab.entities.map(e => e.prefabEntityId)).toEqual(['n0', 'n0_p0', 'n0_p1']);+ expect(prefab.entities[0]!.children).toEqual(['n0_p0', 'n0_p1']);+ expect(prefab.entities[1]!.parent).toBe('n0');// The second primitive names no material: no texture, no tint, engine defaults.expect(prefab.entities[2]!.components[1]!.data).toEqual({mesh: 'model_0_1.esmesh', enabled: true,});});+ it('places each node where the source puts it, parents included', () => {+ const doc = {+ ...withInlineImage(),+ nodes: [+ { name: 'Model', translation: [40, 0, 0], children: [1, 2] },+ { name: 'Left', mesh: 0, translation: [-120, 60, 0] },+ { name: 'Right', mesh: 0, scale: [0.5, 0.5, 1] },+ ],+ scenes: [{ nodes: [0] }], scene: 0,+ };+ const prefab = assemble(gltf(doc));+ expect(prefab.entities.map(e => e.name)).toEqual(['Model', 'Left', 'Right']);+ expect(prefab.entities[0]!.components[0]!.data)+ .toEqual({ position: { x: 40, y: 0, z: 0 } });+ expect(prefab.entities[1]!.components[0]!.data)+ .toEqual({ position: { x: -120, y: 60, z: 0 } });+ expect(prefab.entities[2]!.components[0]!.data)+ .toEqual({ scale: { x: 0.5, y: 0.5, z: 1 } });+ // One mesh drawn by two nodes is one product referenced twice.+ expect(prefab.entities[1]!.components[1]!.data.mesh)+ .toBe(prefab.entities[2]!.components[1]!.data.mesh);+ });++ it('decomposes a node given as a matrix', () => {+ const doc = {+ ...withInlineImage(),+ // 90° about Z, scaled 2, moved to (10, 20, 30) — column-major.+ nodes: [{ mesh: 0, matrix: [0, 2, 0, 0, -2, 0, 0, 0, 0, 0, 2, 0, 10, 20, 30, 1] }],+ scenes: [{ nodes: [0] }], scene: 0,+ };+ const data = assemble(gltf(doc)).entities[0]!.components[0]!.data as {+ position: { x: number }; rotation: { z: number; w: number }; scale: { x: number };+ };+ expect(data.position).toEqual({ x: 10, y: 20, z: 30 });+ expect(data.scale.x).toBeCloseTo(2);+ expect(data.rotation.z).toBeCloseTo(Math.SQRT1_2);+ expect(data.rotation.w).toBeCloseTo(Math.SQRT1_2);+ });++ it('scales the root, since a glTF is in metres', () => {+ const prefab = assemble(gltf({ ...withInlineImage(), ...oneNode }), { scale: 32 });+ expect(prefab.entities[0]!.components[0]!.data)+ .toEqual({ scale: { x: 32, y: 32, z: 32 } });+ });++ it('lays the meshes under a holder when the file has no nodes', () => {+ const prefab = assemble(gltf(withInlineImage()));+ expect(prefab.entities.map(e => e.prefabEntityId)).toEqual(['root', 'm0']);+ expect(prefab.entities[1]!.parent).toBe('root');+ });+it('spells an external image through the project resolver', () => {const doc = withInlineImage();doc.images = [{ uri: '../textures/skin.png' }];- const prefab = assembleGltfPrefab('model', meshesOf(gltf(doc)), {- prefix: 'assets/models/',- external: uri => `assets/${uri.replace('../', '')}`,+ const prefab = assemble(gltf({ ...doc, ...oneNode }), {+ refs: {+ prefix: 'assets/models/',+ external: uri => `assets/${uri.replace('../', '')}`,+ },});expect(prefab.entities[0]!.components[1]!.data.texture).toBe('assets/textures/skin.png');});diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex 0c9bb107d..fff717dae 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -13,7 +13,8 @@ const PIPELINE = path.join(HERE, '..');const REPO = path.join(PIPELINE, '..');const USAGE = `usage: node pipeline/bin/estella.mjs export <projectDir> [options]- node pipeline/bin/estella.mjs import-gltf <file.gltf|file.glb> [outDir] [--project <dir>]+ node pipeline/bin/estella.mjs import-gltf <file.gltf|file.glb> [outDir]+ [--project <dir>] [--scale <n>]--platform <id> web | desktop | wechat | playable | android | ios (default web)--out <dir> output dir (default <projectDir>/dist-<platform>)@@ -34,11 +35,12 @@ second file — \`result.size\` carries the verdicts the build dialog draws, soand the editor cannot disagree about whether a build fits.import-gltf writes one \`.esmesh\` per triangle primitive next to the source (or-into outDir), the images the file carries inline, and one \`.esprefab\` naming-which geometry is drawn with which image and tint. A glTF holds many primitives,-so it is a source that PRODUCES assets rather than one the engine loads — the-products are what a scene references. Asset refs are project-relative, so the-project is found above the source unless --project says otherwise.`;+into outDir), the images the file carries inline, and one \`.esprefab\` placing+each piece where the source's node tree puts it, with its image and tint. A glTF+holds many primitives, so it is a source that PRODUCES assets rather than one the+engine loads — the products are what a scene references. Asset refs are+project-relative, so the project is found above the source unless --project says+otherwise; --scale sizes the model, whose metres are world units otherwise.`;/** Options take a value; these do not — without the distinction a trailing flag* swallows nothing, ends the loop, and a CI job silently gets no gate. */@@ -56,10 +58,12 @@ function parseArgs(argv) {process.exit(2);}const flag = rest.indexOf('--project');+ const scale = rest.indexOf('--scale');const out = rest[0] && !rest[0].startsWith('--') ? path.resolve(rest[0]) : null;return {command, out, source: path.resolve(projectDir),project: flag >= 0 && rest[flag + 1] ? path.resolve(rest[flag + 1]) : null,+ scale: scale >= 0 ? Number(rest[scale + 1]) || 1 : 1,};}if (command !== 'export' || !projectDir) {@@ -175,7 +179,7 @@ if (opts.command === 'import-gltf') {external: (uri) => projectRef(path.resolve(sourceDir, uri)) }: {};- const { meshes, textures, warnings } = importer.importGltfMeshes(+ const { meshes, textures, nodes, warnings } = importer.importGltfMeshes(new Uint8Array(readFileSync(opts.source)), stem,(uri) => {const abs = path.join(sourceDir, uri);@@ -202,9 +206,18 @@ if (opts.command === 'import-gltf') {}if (meshes.length > 0) {const outFile = path.join(dir, `${stem}.esprefab`);- const prefab = importer.assembleGltfPrefab(stem, meshes, refs);+ const prefab = importer.assembleGltfPrefab(stem, meshes, { refs, nodes, scale: opts.scale });writeFileSync(outFile, `${JSON.stringify(prefab, null, 2)}\n`);- report(outFile, `${meshes.length} mesh entit${meshes.length === 1 ? 'y' : 'ies'}`);+ report(outFile, `${prefab.entities.length} entit${prefab.entities.length === 1 ? 'y' : 'ies'}`);++ // A glTF is authored in metres and a world unit is a design pixel, so a+ // real-world model arrives a few pixels across unless --scale says otherwise.+ const extent = Math.max(...meshes.flatMap(+ (m) => m.data.aabbMax.map((v, i) => v - m.data.aabbMin[i])));+ if (opts.scale === 1 && extent < 8) {+ console.warn(` ! the model is ${extent.toFixed(2)} units across — a glTF is in metres`+ + ' and a world unit is a design pixel; pass --scale if it should be bigger');+ }}imported = meshes.length;} finally {diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.tsindex 20f435460..0c21a2af7 100644--- a/pipeline/src/assets/gltfImport.ts+++ b/pipeline/src/assets/gltfImport.ts@@ -12,6 +12,7 @@import {MeshChannel, MeshChannelType, packChannels, encodeMesh, PREFAB_FORMAT_VERSION,type MeshData, type PrefabData, type PrefabEntityData,+ type PrefabComponentData as ComponentData,} from 'esengine';/** One primitive's worth of geometry, named for the file it will be written to. */@@ -52,10 +53,29 @@ export interface ImportedTexture {bytes: Uint8Array;}+/**+ * A node of the source's own hierarchy: where its geometry sits, and what hangs+ * off it. Without this every primitive of a model lands on the origin.+ */+export interface ImportedNode {+ /** The node's own index in the source, so a re-import addresses the same entity. */+ index: number;+ name: string;+ translation: [number, number, number];+ /** Quaternion, glTF's (x, y, z, w) order — the same components a Transform holds. */+ rotation: [number, number, number, number];+ scale: [number, number, number];+ /** Indices into @ref GltfImportResult.meshes; one node can draw several primitives. */+ meshes: number[];+ children: ImportedNode[];+}+export interface GltfImportResult {meshes: ImportedMesh[];/** Images extracted from the file itself; external ones stay where they are. */textures: ImportedTexture[];+ /** 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. */warnings: string[];}@@ -97,6 +117,12 @@ interface GltfJson {}[];textures?: { source?: number; sampler?: number }[];images?: { uri?: string; bufferView?: number; mimeType?: string; name?: string }[];+ nodes?: {+ name?: string; children?: number[]; mesh?: number;+ matrix?: number[]; translation?: number[]; rotation?: number[]; scale?: number[];+ }[];+ scenes?: { nodes?: number[] }[];+ scene?: number;}const MIME_EXTENSION: Record<string, string> = {@@ -292,6 +318,93 @@ function readMaterial(ctx: MaterialContext, textureCache: Map<number, ImportedIm};}+type Trs = Pick<ImportedNode, 'translation' | 'rotation' | 'scale'>;++/**+ * A node's local transform. A glTF gives either TRS or a column-major matrix,+ * and the engine's Transform holds TRS — so a matrix is decomposed here rather+ * than a whole second placement path existing downstream.+ */+function nodeTrs(node: NonNullable<GltfJson['nodes']>[number]): Trs {+ if (!node.matrix || node.matrix.length !== 16) {+ const r = node.rotation ?? [0, 0, 0, 1];+ const t = node.translation ?? [0, 0, 0];+ const s = node.scale ?? [1, 1, 1];+ return {+ translation: [t[0] ?? 0, t[1] ?? 0, t[2] ?? 0],+ rotation: [r[0] ?? 0, r[1] ?? 0, r[2] ?? 0, r[3] ?? 1],+ scale: [s[0] ?? 1, s[1] ?? 1, s[2] ?? 1],+ };+ }+ const m = node.matrix as number[];+ const at = (i: number): number => m[i] ?? 0;+ const column = (c: number): [number, number, number] => [at(c * 4), at(c * 4 + 1), at(c * 4 + 2)];+ const length = (v: [number, number, number]): number => Math.hypot(v[0], v[1], v[2]) || 1;+ const cols = [column(0), column(1), column(2)];+ const scale: [number, number, number] = [length(cols[0]!), length(cols[1]!), length(cols[2]!)];+ // A mirrored matrix has a negative determinant, which no rotation can carry;+ // the convention is to give the sign to the first axis.+ const det = cols[0]![0] * (cols[1]![1] * cols[2]![2] - cols[1]![2] * cols[2]![1])+ - cols[1]![0] * (cols[0]![1] * cols[2]![2] - cols[0]![2] * cols[2]![1])+ + cols[2]![0] * (cols[0]![1] * cols[1]![2] - cols[0]![2] * cols[1]![1]);+ if (det < 0) scale[0] = -scale[0];++ const r = cols.map((c, i) => c.map(v => v / scale[i]!) as [number, number, number]);+ const [x0, y0, z0] = r[0]!, [x1, y1, z1] = r[1]!, [x2, y2, z2] = r[2]!;+ const trace = x0 + y1 + z2;+ let q: [number, number, number, number];+ if (trace > 0) {+ const s = Math.sqrt(trace + 1) * 2;+ q = [(z1 - y2) / s, (x2 - z0) / s, (y0 - x1) / s, s / 4];+ } else if (x0 > y1 && x0 > z2) {+ const s = Math.sqrt(1 + x0 - y1 - z2) * 2;+ q = [s / 4, (x1 + y0) / s, (x2 + z0) / s, (z1 - y2) / s];+ } else if (y1 > z2) {+ const s = Math.sqrt(1 + y1 - x0 - z2) * 2;+ q = [(x1 + y0) / s, s / 4, (y2 + z1) / s, (x2 - z0) / s];+ } else {+ const s = Math.sqrt(1 + z2 - x0 - y1) * 2;+ q = [(x2 + z0) / s, (y2 + z1) / s, s / 4, (y0 - x1) / s];+ }+ return { translation: [at(12), at(13), at(14)], rotation: q, scale };+}++/**+ * The scene's node tree, carrying only what survives: a node whose primitives+ * were all skipped keeps its place, because its children hang off it.+ */+function readNodes(json: GltfJson, meshIndexOf: Map<string, number>,+ warnings: string[]): ImportedNode[] {+ const source = json.nodes;+ if (!source || source.length === 0) return [];++ const roots = json.scenes?.[json.scene ?? 0]?.nodes+ ?? source.map((_, i) => i).filter(i => !source.some(n => n.children?.includes(i)));++ const visiting = new Set<number>();+ const build = (index: number): ImportedNode | null => {+ const node = source[index];+ if (!node || visiting.has(index)) {+ if (node) warnings.push(`node ${index} is its own ancestor — subtree skipped`);+ return null;+ }+ visiting.add(index);+ const meshes: number[] = [];+ if (node.mesh !== undefined) {+ const primitives = json.meshes?.[node.mesh]?.primitives ?? [];+ primitives.forEach((_, primIndex) => {+ const product = meshIndexOf.get(`${node.mesh}_${primIndex}`);+ if (product !== undefined) meshes.push(product);+ });+ }+ const children = (node.children ?? []).map(build).filter((n): n is ImportedNode => n !== null);+ visiting.delete(index);+ return { index, name: node.name ?? `node_${index}`, ...nodeTrs(node), meshes, children };+ };++ return roots.map(build).filter((n): n is ImportedNode => n !== null);+}+/*** A glTF's triangle geometry as `.esmesh` payloads. NORMAL is carried when the* source has it: the engine then draws the mesh with its lit variant, and the@@ -329,6 +442,7 @@ export function importGltfMeshes(const meshes: ImportedMesh[] = [];const textures: ImportedTexture[] = [];+ const meshIndexOf = new Map<string, number>();const single = (json.meshes ?? []).reduce((n, m) => n + m.primitives.length, 0) === 1;const materialCtx: MaterialContext = { json, bin, buffers, stem, textures, warnings };@@ -420,6 +534,7 @@ export function importGltfMeshes(}}+ meshIndexOf.set(`${meshIndex}_${primIndex}`, meshes.length);meshes.push({name: single ? stem : `${stem}_${meshIndex}_${primIndex}`,data: { channels, vertexStride, vertexCount, vertices, indices, aabbMin: min, aabbMax: max },@@ -436,7 +551,7 @@ export function importGltfMeshes(if (meshes.length === 0 && warnings.length === 0) {warnings.push('no triangle geometry found');}- return { meshes, textures, warnings };+ return { meshes, textures, nodes: readNodes(json, meshIndexOf, warnings), warnings };}/** The bytes to write for an imported mesh. */@@ -452,50 +567,103 @@ export interface ProductRefs {external?: (uri: string) => string;}-function meshEntity(id: string, mesh: ImportedMesh, refs: ProductRefs,- parent: string | null): PrefabEntityData {+/** How the products go together. */+export interface PrefabAssembly {+ refs?: ProductRefs;+ /** The source's hierarchy; without it every mesh sits at the origin. */+ nodes?: ImportedNode[];+ /** Uniform scale on the root: a glTF is in metres, a world unit is a design pixel. */+ scale?: number;+}++function meshComponent(mesh: ImportedMesh, refs: ProductRefs): ComponentData {const prefix = refs.prefix ?? '';const image = mesh.material?.baseColorTexture;const texture = image? (image.external ? refs.external?.(image.file) ?? image.file : prefix + image.file): null;const color = mesh.material?.baseColor;- return {- prefabEntityId: id,- name: mesh.name,- parent,- children: [],- visible: true,- components: [- { type: 'Transform', data: {} },- { type: 'Mesh2D', data: {- mesh: `${prefix}${mesh.name}.esmesh`,- ...(texture ? { texture } : {}),- ...(color ? { color: { r: color[0], g: color[1], b: color[2], a: color[3] } } : {}),- enabled: true,- } },- ],- };+ return { type: 'Mesh2D', data: {+ mesh: `${prefix}${mesh.name}.esmesh`,+ ...(texture ? { texture } : {}),+ ...(color ? { color: { r: color[0], g: color[1], b: color[2], a: color[3] } } : {}),+ enabled: true,+ } };+}++/** Only what differs from a Transform's defaults, so a diff shows the placement. */+function transformComponent(trs?: Trs, scale?: number): ComponentData {+ const s = trs?.scale ?? [1, 1, 1];+ const k = scale ?? 1;+ const [x, y, z] = trs?.translation ?? [0, 0, 0];+ const [rx, ry, rz, rw] = trs?.rotation ?? [0, 0, 0, 1];+ return { type: 'Transform', data: {+ ...(x || y || z ? { position: { x, y, z } } : {}),+ ...(rx || ry || rz || rw !== 1 ? { rotation: { w: rw, x: rx, y: ry, z: rz } } : {}),+ ...(s[0] * k !== 1 || s[1] * k !== 1 || s[2] * k !== 1+ ? { scale: { x: s[0] * k, y: s[1] * k, z: s[2] * k } } : {}),+ } };+}++function entity(id: string, name: string, parent: string | null,+ components: ComponentData[]): PrefabEntityData {+ return { prefabEntityId: id, name, parent, children: [], visible: true, components };}/**- * The import's assembly: which geometry is drawn with which image and tint. The- * products are separate files and nothing else records how they go together, so- * without this a model arrives as a pile of parts to be re-connected by hand.+ * The import's assembly: where each piece of geometry sits, and which image and+ * tint it is drawn with. The products are separate files and nothing else+ * records how they go together, so without this a model arrives as a pile of+ * parts to be re-connected by hand.*/export function assembleGltfPrefab(name: string, meshes: ImportedMesh[],- refs: ProductRefs = {}): PrefabData {- // A single primitive needs no holder: the root IS the mesh, which is what a- // scene wants to place. Several get one, since they are one model.- const entities: PrefabEntityData[] = meshes.length === 1 && meshes[0]- ? [meshEntity('0', meshes[0], refs, null)]- : [- {- prefabEntityId: '0', name, parent: null, visible: true,- children: meshes.map((_, i) => String(i + 1)),- components: [{ type: 'Transform', data: {} }],- },- ...meshes.map((mesh, i) => meshEntity(String(i + 1), mesh, refs, '0')),- ];- return { version: PREFAB_FORMAT_VERSION, name, rootEntityId: '0', entities };+ options: PrefabAssembly = {}): PrefabData {+ const refs = options.refs ?? {};+ const entities: PrefabEntityData[] = [];+ const nodes = options.nodes ?? [];++ const emitNode = (node: ImportedNode, parent: string | null, rootScale?: number): string => {+ const id = `n${node.index}`;+ const drawn = node.meshes.map(i => meshes[i]).filter((m): m is ImportedMesh => !!m);+ // One primitive rides the node itself; several cannot, since a Mesh2D+ // draws one mesh — they become its children, at its own origin.+ const own = drawn.length === 1 && drawn[0] ? [meshComponent(drawn[0], refs)] : [];+ const self = entity(id, node.name, parent,+ [transformComponent(node, rootScale), ...own]);+ entities.push(self);+ if (own.length === 0) {+ drawn.forEach((mesh, i) => {+ const childId = `${id}_p${i}`;+ self.children.push(childId);+ entities.push(entity(childId, mesh.name, id,+ [transformComponent(), meshComponent(mesh, refs)]));+ });+ }+ for (const child of node.children) self.children.push(emitNode(child, id));+ return id;+ };++ if (nodes.length === 1 && nodes[0]) {+ emitNode(nodes[0], null, options.scale);+ } else if (nodes.length > 1) {+ // Several roots are one model all the same, so they get a holder to be+ // placed by — and it is where the import's own scale belongs.+ const root = entity('root', name, null, [transformComponent(undefined, options.scale)]);+ entities.push(root);+ for (const node of nodes) root.children.push(emitNode(node, 'root'));+ } else {+ // No node tree: the meshes are all there is to place.+ const root = entity('root', name, null, [transformComponent(undefined, options.scale)]);+ entities.push(root);+ meshes.forEach((mesh, i) => {+ const id = `m${i}`;+ root.children.push(id);+ entities.push(entity(id, mesh.name, 'root',+ [transformComponent(), meshComponent(mesh, refs)]));+ });+ }+ return {+ version: PREFAB_FORMAT_VERSION, name,+ rootEntityId: entities[0]!.prefabEntityId, entities,+ };}diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 41f5cfad4..39c513ecb 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -132,6 +132,10 @@ export const SCENES = [// inline image, and the baseColor factor as the tint. The probes sit at the// texel centres of a 2x2 image, so a flipped V swaps colours between them.{ id: "mesh-textured", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PREFAB: "/scenes/textured-quad.esprefab", ESTELLA_VERIFY_SCENE: "/scenes/mesh-textured.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-textured.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.3333,\"y\":0.4167,\"rgb\":[128,0,0],\"tol\":40},{\"x\":0.6667,\"y\":0.4167,\"rgb\":[0,128,0],\"tol\":40},{\"x\":0.3333,\"y\":0.5833,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.6667,\"y\":0.5833,\"rgb\":[128,128,0],\"tol\":40}]" } },+ // The source's own hierarchy, placing the pieces. Two probes need the parent's+ // offset to have reached the child, and the fourth is background only if the+ // child's scale survived — ignore the tree and everything stacks on the origin.+ { id: "mesh-nodes", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PREFAB: "/scenes/node-tree.esprefab", ESTELLA_VERIFY_SCENE: "/scenes/mesh-nodes.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-nodes.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.3667,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.45,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.7667,\"y\":0.60,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.7667,\"y\":0.5333,\"rgb\":[0,0,0],\"tol\":30}]" } },// Takes the GPU away for real and captures AFTER the cycle: the four points// sample the atlas, so they fail unless the content came back. A vertex-colour// scene passed with the re-upload deleted. No webgpu — no GL extension there.