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.

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.esprefab
index 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.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esprefab
new file mode 100644
index 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.gltf
new file mode 100644
index 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.esmesh
new file mode 100644
index 000000000..c90a0f0e0
Binary files /dev/null and b/desktop/public/scenes/node-tree_0_0.esmesh differ
diff --git a/desktop/public/scenes/node-tree_1_0.esmesh b/desktop/public/scenes/node-tree_1_0.esmesh
new file mode 100644
index 000000000..c90a0f0e0
Binary files /dev/null and b/desktop/public/scenes/node-tree_1_0.esmesh differ
diff --git a/desktop/public/scenes/textured-quad.esprefab b/desktop/public/scenes/textured-quad.esprefab
index 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.esprefab
index 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.esprefab
index 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.mjs
index 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.ts
index 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.mjs
index 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, so
and 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.ts
index 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.mjs
index 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.