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): a model's animations come in with it
esengine3ed8d551b6e1
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.tsindex 76e5a6c89..08c8c2ff2 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, externalFiles, warnings } = await importGltfMeshes(+ const { meshes, textures, nodes, animations, externalFiles, warnings } = await importGltfMeshes(new Uint8Array(readFileSync(absSource)), stem,(uri) => {const abs = path.join(sourceDir, decodeURIComponent(uri));@@ -118,8 +118,14 @@ export async function importModel(root: string, destDir: string, absSource: strifor (const material of materialProducts(meshes, stem, refs)) {await write(`${material.name}.esmaterial`, `${JSON.stringify(material.data, null, 2)}\n`);}+ let firstClip: string | undefined;+ for (const animation of animations) {+ const rel = await write(`${animation.name}.estimeline`,+ `${JSON.stringify(animation.document, null, 2)}\n`);+ firstClip ??= rel;+ }if (meshes.length > 0) {- const prefab = assembleGltfPrefab(stem, meshes, { refs, nodes, scale });+ const prefab = assembleGltfPrefab(stem, meshes, { refs, nodes, scale, timeline: firstClip });await write(`${stem}.esprefab`, `${JSON.stringify(prefab, null, 2)}\n`);// A glTF is in metres and a world unit is a design pixel, so a real-world// model arrives a few pixels across. Said, not guessed at: the scale is thediff --git a/desktop/public/scenes/model-animation.esscene b/desktop/public/scenes/model-animation.esscenenew file mode 100644index 000000000..0ec60b708--- /dev/null+++ b/desktop/public/scenes/model-animation.esscene@@ -0,0 +1,53 @@+{+ "version": 1,+ "name": "ModelAnimation",+ "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": 200, "isActive": true, "priority": 0 }+ }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Mover",+ "parent": null,+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": { "position": { "x": 150, "y": 0, "z": 0 } }+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "scenes/moving-quad.esmesh",+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },+ "enabled": true+ }+ },+ {+ "type": "TimelinePlayer",+ "data": {+ "timeline": "scenes/moving-quad_Slide.estimeline",+ "playing": true,+ "speed": 1,+ "wrapMode": "once"+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/moving-quad.esmesh b/desktop/public/scenes/moving-quad.esmeshnew file mode 100644index 000000000..76d12f34bBinary files /dev/null and b/desktop/public/scenes/moving-quad.esmesh differdiff --git a/desktop/public/scenes/moving-quad.esmesh.meta b/desktop/public/scenes/moving-quad.esmesh.metanew file mode 100644index 000000000..9a2714417--- /dev/null+++ b/desktop/public/scenes/moving-quad.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "20d9466a-0b70-462a-8fa0-adedda2dee9a",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/desktop/public/scenes/moving-quad.esprefab b/desktop/public/scenes/moving-quad.esprefabnew file mode 100644index 000000000..887e6f5e0--- /dev/null+++ b/desktop/public/scenes/moving-quad.esprefab@@ -0,0 +1,34 @@+{+ "version": "2",+ "name": "moving-quad",+ "rootEntityId": "n0",+ "entities": [+ {+ "prefabEntityId": "n0",+ "name": "Mover",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "scenes/moving-quad.esmesh",+ "enabled": true+ }+ },+ {+ "type": "TimelinePlayer",+ "data": {+ "timeline": "scenes/moving-quad_Slide.estimeline",+ "playing": false+ }+ }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/moving-quad.esprefab.meta b/desktop/public/scenes/moving-quad.esprefab.metanew file mode 100644index 000000000..1dcbd56a9--- /dev/null+++ b/desktop/public/scenes/moving-quad.esprefab.meta@@ -0,0 +1,6 @@+{+ "uuid": "a6bafc2e-2c4b-4037-953b-f4aad860e4a3",+ "version": "2.0",+ "type": "prefab",+ "importer": {}+}diff --git a/desktop/public/scenes/moving-quad.gltf b/desktop/public/scenes/moving-quad.gltfnew file mode 100644index 000000000..97a788f10--- /dev/null+++ b/desktop/public/scenes/moving-quad.gltf@@ -0,0 +1,125 @@+{+ "asset": {+ "version": "2.0",+ "generator": "estella test fixture"+ },+ "buffers": [+ {+ "byteLength": 92,+ "uri": "data:application/octet-stream;base64,AABwwgAAcMIAAAAAAABwQgAAcMIAAAAAAABwwgAAcEIAAAAAAABwQgAAcEIAAAAAAAACAAEAAQACAAMAAAAAAAAAgD8AAPDCAAAAAAAAAAAAAPBCAAAAAAAAAAA="+ }+ ],+ "bufferViews": [+ {+ "buffer": 0,+ "byteOffset": 0,+ "byteLength": 48+ },+ {+ "buffer": 0,+ "byteOffset": 48,+ "byteLength": 12+ },+ {+ "buffer": 0,+ "byteOffset": 60,+ "byteLength": 8+ },+ {+ "buffer": 0,+ "byteOffset": 68,+ "byteLength": 24+ }+ ],+ "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"+ },+ {+ "bufferView": 2,+ "componentType": 5126,+ "count": 2,+ "type": "SCALAR",+ "min": [+ 0+ ],+ "max": [+ 1+ ]+ },+ {+ "bufferView": 3,+ "componentType": 5126,+ "count": 2,+ "type": "VEC3"+ }+ ],+ "meshes": [+ {+ "name": "Quad",+ "primitives": [+ {+ "attributes": {+ "POSITION": 0+ },+ "indices": 1,+ "mode": 4+ }+ ]+ }+ ],+ "nodes": [+ {+ "name": "Mover",+ "mesh": 0+ }+ ],+ "scenes": [+ {+ "nodes": [+ 0+ ]+ }+ ],+ "scene": 0,+ "animations": [+ {+ "name": "Slide",+ "channels": [+ {+ "sampler": 0,+ "target": {+ "node": 0,+ "path": "translation"+ }+ }+ ],+ "samplers": [+ {+ "input": 2,+ "output": 3,+ "interpolation": "LINEAR"+ }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/moving-quad_Slide.estimeline b/desktop/public/scenes/moving-quad_Slide.estimelinenew file mode 100644index 000000000..b8093047d--- /dev/null+++ b/desktop/public/scenes/moving-quad_Slide.estimeline@@ -0,0 +1,73 @@+{+ "version": "1.2",+ "type": "timeline",+ "duration": 1,+ "wrapMode": "once",+ "tracks": [+ {+ "type": "property",+ "name": "Mover",+ "childPath": "",+ "component": "Transform",+ "channels": [+ {+ "property": "position.x",+ "keyframes": [+ {+ "time": 0,+ "value": -120,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 1,+ "value": 120,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ }+ ]+ },+ {+ "property": "position.y",+ "keyframes": [+ {+ "time": 0,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 1,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ }+ ]+ },+ {+ "property": "position.z",+ "keyframes": [+ {+ "time": 0,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 1,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ }+ ]+ }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/moving-quad_Slide.estimeline.meta b/desktop/public/scenes/moving-quad_Slide.estimeline.metanew file mode 100644index 000000000..0aca333cb--- /dev/null+++ b/desktop/public/scenes/moving-quad_Slide.estimeline.meta@@ -0,0 +1,6 @@+{+ "uuid": "4bcb6a54-dfbd-4045-977b-66ad5c6e63d6",+ "version": "2.0",+ "type": "animation",+ "importer": {}+}diff --git a/desktop/scripts/make-mesh-fixture.mjs b/desktop/scripts/make-mesh-fixture.mjsindex 86c5f6657..3e518d7a4 100644--- a/desktop/scripts/make-mesh-fixture.mjs+++ b/desktop/scripts/make-mesh-fixture.mjs@@ -29,9 +29,11 @@ const cli = path.join(HERE, '..', '..', 'pipeline', 'bin', 'estella.mjs');// — the spelling a component carries, resolved from the served root.// model-material: the three channels only a material can carry — emission,// occlusion, an alpha cutoff — one quad each.+// moving-quad: one node with a translation clip, which is what a node animation+// is once nothing is skinned — the products include its `.estimeline`.for (const name of ['two-triangles.gltf', 'lit-triangles.gltf', 'white-triangles.gltf','textured-quad.gltf', 'node-tree.gltf', 'normalmap-quad.gltf',- 'model-material.gltf']) {+ 'model-material.gltf', 'moving-quad.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 698c5bdd8..e3c0a3c49 100644--- a/desktop/tests/gltf-import.test.ts+++ b/desktop/tests/gltf-import.test.ts@@ -284,10 +284,10 @@ describe('glTF material import', () => {expect(meshes[0]!.material?.baseColorTexture?.settings?.wrapMode).toBe('clamp');});- it('reports deformation it cannot carry: skins, morph targets, animations', async () => {+ it('reports deformation it cannot carry: skins and morph targets', async () => {const doc = {...withInlineImage(),- skins: [{}], animations: [{}],+ skins: [{}],nodes: [{ mesh: 0, skin: 0 }], scenes: [{ nodes: [0] }], scene: 0,};const { warnings } = await importGltfMeshes(gltf(doc, [{@@ -298,7 +298,6 @@ describe('glTF material import', () => {expect(line).toContain('2 morph target(s) not imported');expect(line).toContain('skinning is not imported');expect(line).toContain('1 skin(s) not imported');- expect(line).toContain('1 animation(s) not imported');});it('reports a uv rewrite it does not apply', async () => {@@ -435,6 +434,16 @@ describe('glTF prefab assembly', () => {});});+ it('points the root at a clip, stopped', async () => {+ const prefab = await assemble(gltf({ ...withInlineImage(), ...oneNode }),+ { timeline: 'assets/models/model_Spin.estimeline' });+ // Stopped: the products say what the model HAS. Playing it is the scene's.+ expect(prefab.entities[0]!.components.at(-1)).toEqual({+ type: 'TimelinePlayer',+ data: { timeline: 'assets/models/model_Spin.estimeline', playing: false },+ });+ });+it('hangs a node’s further primitives off it', async () => {const two = [{ attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, material: 0, mode: 4 },@@ -528,6 +537,141 @@ describe('glTF prefab assembly', () => {});});+/**+ * A glTF whose animation sampler data is appended to the geometry buffer.+ * Accessors 0-2 are the triangle; 3 is the sampler input, 4 its output.+ */+function animatedGltf(opts: {+ times: number[]; values: number[]; components: number;+ path?: string; interpolation?: string;+ nodes?: unknown[]; targetNode?: number; skins?: unknown[];+}): Uint8Array {+ const geo = geometryBuffer();+ const geoBytes = Buffer.from(geo.uri.split(',')[1]!, 'base64');+ const pad = Buffer.alloc((4 - (geoBytes.length % 4)) % 4);+ const times = Buffer.from(new Float32Array(opts.times).buffer);+ const values = Buffer.from(new Float32Array(opts.values).buffer);+ const bytes = Buffer.concat([geoBytes, pad, times, values]);+ const timesAt = geoBytes.length + pad.length;+ const type = ['SCALAR', '', 'VEC2', 'VEC3', 'VEC4'][opts.components]!;++ const doc = {+ asset: { version: '2.0' },+ buffers: [{ byteLength: bytes.length, uri: `data:application/octet-stream;base64,${bytes.toString('base64')}` }],+ bufferViews: [+ ...(geo.views as Record<string, unknown>[]),+ { buffer: 0, byteOffset: timesAt, byteLength: times.length },+ { buffer: 0, byteOffset: timesAt + times.length, byteLength: values.length },+ ],+ accessors: [+ ...(geo.accessors as Record<string, unknown>[]),+ { bufferView: 3, componentType: 5126, count: opts.times.length, type: 'SCALAR' },+ { bufferView: 4, componentType: 5126, count: opts.values.length / opts.components, type },+ ],+ meshes: [{ name: 'Tri', primitives: [{ attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, mode: 4 }] }],+ nodes: opts.nodes ?? [{ name: 'Root', children: [1] }, { name: 'Spinner', mesh: 0 }],+ scenes: [{ nodes: [0] }],+ scene: 0,+ ...(opts.skins ? { skins: opts.skins } : {}),+ animations: [{+ name: 'Spin',+ channels: [{ sampler: 0, target: { node: opts.targetNode ?? 1, path: opts.path ?? 'rotation' } }],+ samplers: [{ input: 3, output: 4, interpolation: opts.interpolation ?? 'LINEAR' }],+ }],+ };+ return new TextEncoder().encode(JSON.stringify(doc));+}++describe('glTF animation import', () => {+ const HALF = Math.SQRT1_2;++ it('turns a rotation channel into four component channels on the target node', async () => {+ const result = await importGltfMeshes(animatedGltf({+ times: [0, 1], values: [0, 0, 0, 1, 0, HALF, 0, HALF], components: 4,+ }), 'robot');++ expect(result.animations).toHaveLength(1);+ const doc = result.animations[0]!.document as any;+ expect(result.animations[0]!.name).toBe('robot_Spin');+ expect(doc.duration).toBe(1);+ expect(doc.tracks).toHaveLength(1);+ // The lone root IS the prefab root, so its child is addressed by its name.+ expect(doc.tracks[0].childPath).toBe('Spinner');+ expect(doc.tracks[0].component).toBe('Transform');+ expect(doc.tracks[0].channels.map((c: any) => c.property))+ .toEqual(['rotation.x', 'rotation.y', 'rotation.z', 'rotation.w']);+ const y = doc.tracks[0].channels[1].keyframes;+ expect(y[0]).toMatchObject({ time: 0, value: 0, interpolation: 'linear' });+ expect(y[1].value).toBeCloseTo(HALF, 6);+ });++ it('carries a CUBICSPLINE tangent into the keyframe it belongs to', async () => {+ // Per key: [inTangent, value, outTangent] — one scalar-per-component triple.+ const result = await importGltfMeshes(animatedGltf({+ times: [0, 1], components: 3, path: 'translation', interpolation: 'CUBICSPLINE',+ values: [+ 0, 0, 0, /* v0 */ 0, 0, 0, /* out */ 2, 0, 0,+ 3, 0, 0, /* v1 */ 10, 0, 0, /* out */ 0, 0, 0,+ ],+ }), 'robot');++ const x = (result.animations[0]!.document as any).tracks[0].channels[0].keyframes;+ expect(x[0]).toMatchObject({ value: 0, inTangent: 0, outTangent: 2, interpolation: 'hermite' });+ expect(x[1]).toMatchObject({ value: 10, inTangent: 3, outTangent: 0 });+ });++ it('flips a quaternion keyframe that would interpolate the long way round', async () => {+ // 170° about Y, then the SAME rotation written negated: component-wise that+ // is a 190° turn backwards unless the sign is aligned.+ const s = Math.sin((170 * Math.PI) / 180 / 2);+ const c = Math.cos((170 * Math.PI) / 180 / 2);+ const result = await importGltfMeshes(animatedGltf({+ times: [0, 1], components: 4, values: [0, s, 0, c, -0, -s, -0, -c],+ }), 'robot');++ const ch = (result.animations[0]!.document as any).tracks[0].channels;+ const yEnd = ch[1].keyframes[1].value;+ const wEnd = ch[3].keyframes[1].value;+ expect(yEnd).toBeCloseTo(s, 6);+ expect(wEnd).toBeCloseTo(c, 6);+ });++ it('gives two siblings of the same name distinct paths', async () => {+ const result = await importGltfMeshes(animatedGltf({+ times: [0], components: 3, path: 'translation', values: [1, 2, 3], targetNode: 2,+ nodes: [+ { name: 'Root', children: [1, 2] },+ { name: 'Arm', mesh: 0 },+ { name: 'Arm' },+ ],+ }), 'robot');++ const paths = result.nodes[0]!.children.map(n => n.name);+ expect(paths).toEqual(['Arm', 'Arm_2']);+ expect((result.animations[0]!.document as any).tracks[0].childPath).toBe('Arm_2');+ });++ it('says a skinned node moves joints the mesh will not follow', async () => {+ const result = await importGltfMeshes(animatedGltf({+ times: [0, 1], components: 4, values: [0, 0, 0, 1, 0, HALF, 0, HALF],+ skins: [{ joints: [1] }],+ nodes: [{ name: 'Root', children: [1] }, { name: 'Spinner', mesh: 0, skin: 0 }],+ }), 'robot');++ expect(result.animations).toHaveLength(1);+ expect(result.warnings.some(w => /joints move/.test(w))).toBe(true);+ });++ it('reports a morph-weight channel rather than dropping it', async () => {+ const result = await importGltfMeshes(animatedGltf({+ times: [0, 1], components: 1, path: 'weights', values: [0, 1],+ }), 'robot');++ expect(result.animations).toHaveLength(0);+ expect(result.warnings.some(w => /weights/.test(w))).toBe(true);+ });+});+describe('meshopt-compressed geometry', () => {it('imports to the very same mesh the uncompressed file does', async () => {// The claim is not what the codec does — it is that compression is invisiblediff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex bf19f5173..63c15cc1f 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -184,7 +184,7 @@ if (opts.command === 'import-gltf') {external: (uri) => projectRef(path.resolve(sourceDir, uri)) }: {};- const { meshes, textures, nodes, warnings } = await importer.importGltfMeshes(+ const { meshes, textures, nodes, animations, warnings } = await importer.importGltfMeshes(new Uint8Array(readFileSync(opts.source)), stem,(uri) => {const abs = path.join(sourceDir, uri);@@ -226,9 +226,19 @@ if (opts.command === 'import-gltf') {await adopt(outFile);report(outFile, Object.keys(material.data.properties).join(', '));}+ let firstClip;+ for (const animation of animations) {+ const outFile = path.join(dir, `${animation.name}.estimeline`);+ writeFileSync(outFile, `${JSON.stringify(animation.document, null, 2)}\n`);+ await adopt(outFile);+ const tracks = animation.document.tracks.length;+ report(outFile, `${animation.document.duration}s, ${tracks} track${tracks === 1 ? '' : 's'}`);+ firstClip ??= `${refs.prefix ?? ''}${animation.name}.estimeline`;+ }if (meshes.length > 0) {const outFile = path.join(dir, `${stem}.esprefab`);- const prefab = importer.assembleGltfPrefab(stem, meshes, { refs, nodes, scale: opts.scale });+ const prefab = importer.assembleGltfPrefab(+ stem, meshes, { refs, nodes, scale: opts.scale, timeline: firstClip });writeFileSync(outFile, `${JSON.stringify(prefab, null, 2)}\n`);await adopt(outFile);report(outFile, `${prefab.entities.length} entit${prefab.entities.length === 1 ? 'y' : 'ies'}`);diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.tsindex e64c75266..74ef7b3e7 100644--- a/pipeline/src/assets/gltfImport.ts+++ b/pipeline/src/assets/gltfImport.ts@@ -12,6 +12,7 @@/// <reference path="./draco3dgltf.d.ts" />import {MeshChannel, MeshChannelType, packChannels, encodeMesh, PREFAB_FORMAT_VERSION,+ TIMELINE_FORMAT_VERSION,MATERIAL_FORMAT_VERSION, BlendMode, CullMode,type MeshData, type MaterialAssetData, type PrefabData, type PrefabEntityData,type PrefabComponentData as ComponentData,@@ -103,6 +104,13 @@ export interface ImportedNode {children: ImportedNode[];}+/** One glTF animation as the `.estimeline` document it will be written to. */+export interface ImportedAnimation {+ /** `<stem>_<animation name>` — named for the file it will be written to. */+ name: string;+ document: Record<string, unknown>;+}+export interface GltfImportResult {meshes: ImportedMesh[];/** Images extracted from the file itself; external ones stay where they are. */@@ -112,6 +120,8 @@ export interface GltfImportResult {externalFiles: string[];/** The scene's node roots. Empty for a file with no nodes, whose meshes then sit flat. */nodes: ImportedNode[];+ /** The file's animations, each addressing nodes by their path under the prefab. */+ animations: ImportedAnimation[];/** What was skipped and why — a silent drop is how half a model goes missing. */warnings: string[];}@@ -194,7 +204,11 @@ interface GltfJson {matrix?: number[]; translation?: number[]; rotation?: number[]; scale?: number[];}[];skins?: unknown[];- animations?: unknown[];+ animations?: {+ name?: string;+ channels: { sampler: number; target: { node?: number; path: string } }[];+ samplers: { input: number; output: number; interpolation?: string }[];+ }[];scenes?: { nodes?: number[] }[];scene?: number;}@@ -714,7 +728,194 @@ function readNodes(json: GltfJson, meshIndexOf: Map<string, number>,return { index, name: node.name ?? `node_${index}`, ...nodeTrs(node), meshes, children };};- return roots.map(build).filter((n): n is ImportedNode => n !== null);+ const built = roots.map(build).filter((n): n is ImportedNode => n !== null);+ disambiguate(built);+ return built;+}++/**+ * Make sibling names unique. An animation channel addresses its node by the path+ * of names from the root, so two siblings called "Arm" would leave a track+ * driving whichever the walk reached first — the wrong half of the model. glTF+ * allows the duplicate, so the import settles it and the products agree.+ */+function disambiguate(nodes: ImportedNode[]): void {+ const used = new Set<string>();+ for (const node of nodes) {+ if (used.has(node.name)) node.name = `${node.name}_${node.index}`;+ used.add(node.name);+ disambiguate(node.children);+ }+}++/**+ * Each node's path of names from the prefab root, matching what+ * {@link assembleGltfPrefab} builds: a lone root node IS the prefab root (empty+ * path), while several roots hang under a holder and so carry their own name.+ */+export function nodeChildPaths(nodes: ImportedNode[]): Map<number, string> {+ const paths = new Map<number, string>();+ const walk = (node: ImportedNode, prefix: string): void => {+ const path = prefix ? `${prefix}/${node.name}` : node.name;+ paths.set(node.index, path);+ for (const child of node.children) walk(child, path);+ };+ if (nodes.length === 1 && nodes[0]) {+ paths.set(nodes[0].index, '');+ for (const child of nodes[0].children) walk(child, '');+ } else {+ for (const node of nodes) walk(node, '');+ }+ return paths;+}++/** glTF's sampler interpolation → the engine's, which spells the same curves. */+const INTERPOLATION: Record<string, string> = {+ LINEAR: 'linear', STEP: 'step', CUBICSPLINE: 'hermite',+};++/** Which Transform channels a glTF animation path writes, in component order. */+const ANIMATED_PATHS: Record<string, { property: string; channels: string[] }> = {+ translation: { property: 'position', channels: ['position.x', 'position.y', 'position.z'] },+ scale: { property: 'scale', channels: ['scale.x', 'scale.y', 'scale.z'] },+ // glTF stores a rotation as (x, y, z, w) — the components, in that order.+ rotation: { property: 'rotation', channels: ['rotation.x', 'rotation.y', 'rotation.z', 'rotation.w'] },+};++interface OutKeyframe { time: number; value: number; inTangent: number; outTangent: number; interpolation: string }++/**+ * A quaternion and its negation are the same rotation, and interpolating the+ * four numbers takes the LONG way round whenever consecutive keyframes point+ * apart. Flipping the sign here means the products already describe the short+ * arc, so nothing downstream has to decide it per frame.+ */+function alignQuaternionSigns(frames: OutKeyframe[][]): void {+ if (frames.length !== 4) return;+ for (let k = 1; k < (frames[0]?.length ?? 0); k++) {+ let dot = 0;+ for (let c = 0; c < 4; c++) dot += frames[c]![k]!.value * frames[c]![k - 1]!.value;+ if (dot >= 0) continue;+ for (let c = 0; c < 4; c++) {+ const kf = frames[c]![k]!;+ kf.value = -kf.value;+ kf.inTangent = -kf.inTangent;+ kf.outTangent = -kf.outTangent;+ }+ }+}++/**+ * One sampler's keyframes, split into one list per component. CUBICSPLINE stores+ * each key as `[inTangent, value, outTangent]`, and its tangents are already per+ * second — the units the evaluator multiplies by the segment length — so the+ * three land in the three fields a keyframe has with no conversion.+ */+function samplerKeyframes(times: Float32Array, values: Float32Array,+ comps: number, interpolation: string): OutKeyframe[][] {+ const cubic = interpolation === 'CUBICSPLINE';+ const interp = INTERPOLATION[interpolation] ?? 'linear';+ const out: OutKeyframe[][] = Array.from({ length: comps }, () => []);+ for (let k = 0; k < times.length; k++) {+ for (let c = 0; c < comps; c++) {+ const at = cubic ? (3 * k + 1) * comps + c : k * comps + c;+ out[c]!.push({+ time: times[k] ?? 0,+ value: values[at] ?? 0,+ inTangent: cubic ? (values[3 * k * comps + c] ?? 0) : 0,+ outTangent: cubic ? (values[(3 * k + 2) * comps + c] ?? 0) : 0,+ interpolation: interp,+ });+ }+ }+ return out;+}++/**+ * A glTF animation as an `.estimeline` document. Channels are grouped per target+ * node, since a track drives one component on one entity and the runtime reads+ * and writes that component once per track.+ */+function readAnimations(json: GltfJson, src: GltfBytes, nodes: ImportedNode[],+ stem: string, warnings: string[]): ImportedAnimation[] {+ const animations = json.animations ?? [];+ if (animations.length === 0) return [];+ const paths = nodeChildPaths(nodes);+ const skinned = new Set<number>();+ for (const [i, node] of (json.nodes ?? []).entries()) if (node.skin !== undefined) skinned.add(i);++ const out: ImportedAnimation[] = [];+ for (const [index, animation] of animations.entries()) {+ const name = animation.name || `animation_${index}`;+ // childPath -> property -> keyframes, so one node's channels form one track.+ const byNode = new Map<string, { node: string; channels: Map<string, OutKeyframe[]> }>();+ let duration = 0;+ let drivesSkin = false;++ for (const channel of animation.channels ?? []) {+ const target = channel.target?.node;+ const spec = ANIMATED_PATHS[channel.target?.path ?? ''];+ if (target === undefined || !paths.has(target)) continue;+ if (!spec) {+ warnings.push(`${name}: "${channel.target?.path}" channels are not imported`+ + ' (morph target weights need blend shapes)');+ continue;+ }+ const sampler = animation.samplers?.[channel.sampler];+ if (!sampler) continue;+ const times = readAccessor(src, sampler.input);+ const values = readAccessor(src, sampler.output);+ if (times.length === 0 || values.length === 0) continue;+ if (skinned.has(target)) drivesSkin = true;++ const comps = spec.channels.length;+ const frames = samplerKeyframes(times, values, comps, sampler.interpolation ?? 'LINEAR');+ if (spec.property === 'rotation') alignQuaternionSigns(frames);+ duration = Math.max(duration, times[times.length - 1] ?? 0);++ const path = paths.get(target)!;+ const entry = byNode.get(path)+ ?? { node: nodeNameFor(nodes, target), channels: new Map<string, OutKeyframe[]>() };+ spec.channels.forEach((property, c) => entry.channels.set(property, frames[c]!));+ byNode.set(path, entry);+ }++ if (byNode.size === 0) {+ warnings.push(`${name}: no channel targets a node this import produced`);+ continue;+ }+ if (drivesSkin) {+ warnings.push(`${name}: drives skinned nodes — the joints move, but the mesh bound to`+ + ' them does not deform (skinning is not implemented)');+ }+ out.push({+ // A source's animation name is whatever the tool wrote (spaces, dots,+ // a slash), and it becomes a file name here.+ name: `${stem}_${name.replace(/[^\w.-]+/g, '_')}`,+ document: {+ version: TIMELINE_FORMAT_VERSION,+ type: 'timeline',+ duration,+ // glTF says nothing about looping, and the import does not guess.+ wrapMode: 'once',+ tracks: [...byNode].map(([childPath, entry]) => ({+ type: 'property', name: entry.node, childPath, component: 'Transform',+ channels: [...entry.channels].map(([property, keyframes]) => ({ property, keyframes })),+ })),+ },+ });+ }+ return out;+}++/** A node's own name, for the track label. */+function nodeNameFor(nodes: ImportedNode[], index: number): string {+ for (const node of nodes) {+ if (node.index === index) return node.name;+ const hit = nodeNameFor(node.children, index);+ if (hit) return hit;+ }+ return '';}/**@@ -930,18 +1131,16 @@ export async function importGltfMeshes(});});- // A rigged, animated source arrives as still geometry; that is a property of- // the import worth stating once for the file rather than per primitive.+ // A rigged source arrives as still geometry; that is a property of the import+ // worth stating once for the file rather than per primitive.if (json.skins?.length) warnings.push(`${json.skins.length} skin(s) not imported`);- if (json.animations?.length) {- warnings.push(`${json.animations.length} animation(s) not imported`);- }if (meshes.length === 0 && warnings.length === 0) {warnings.push('no triangle geometry found');}+ const nodes = readNodes(json, meshIndexOf, warnings);return {- meshes, textures, externalFiles,- nodes: readNodes(json, meshIndexOf, warnings), warnings,+ meshes, textures, externalFiles, nodes, warnings,+ animations: readAnimations(json, src, nodes, stem, warnings),};}@@ -965,6 +1164,9 @@ export interface PrefabAssembly {nodes?: ImportedNode[];/** Uniform scale on the root: a glTF is in metres, a world unit is a design pixel. */scale?: number;+ /** The clip the root's player points at — the products say what they have,+ * and it is left stopped because what to play is the scene's decision. */+ timeline?: string;}/** How a component spells a reference to an image: a project-relative path. */@@ -1160,6 +1362,13 @@ export function assembleGltfPrefab(name: string, meshes: ImportedMesh[],[transformComponent(), meshComponent(mesh, name, refs)]));});}+ // The player rides the root, which is the entity a clip's childPaths are+ // resolved from — the same root the tracks were addressed against.+ if (options.timeline && entities[0]) {+ entities[0].components.push({ type: 'TimelinePlayer', data: {+ timeline: options.timeline, playing: false,+ } });+ }return {version: PREFAB_FORMAT_VERSION, name,rootEntityId: entities[0]!.prefabEntityId, entities,diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 51ffe1d17..e4e4fc8be 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -44,6 +44,10 @@ export const SCENES = [// cell here, so the whole grid steps right by one and the left column empties.// It rides the per-frame origin, not the cached chunk vertices.{ id: "tilemap-origin", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SET_FIELD: "{\"entity\":1,\"component\":\"TilemapLayer\",\"key\":\"originOffset\",\"value\":[16,0]}", ESTELLA_VERIFY_SCENE: "/scenes/tilemap-flip.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/tilemap-flip.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.60,\"y\":0.36,\"rgb\":[255,0,0]},{\"x\":0.80,\"y\":0.36,\"rgb\":[0,255,0]},{\"x\":0.60,\"y\":0.58,\"rgb\":[0,0,255]},{\"x\":0.40,\"y\":0.36,\"rgb\":[0,0,0],\"tol\":20}]" } },+ // A glTF animation, through the shipped importer. The scene puts the quad at+ // x=150 and the clip runs -120 to 120 over a second, so 30 fixed steps is its+ // midpoint: the model is at the origin and where the SCENE put it is empty.+ { id: "model-animation", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/model-animation.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "30", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":30},{\"x\":0.875,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.2,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },// Cells the atlas does not hold, both ways one can be asked for: an id past a// 2x2 tileset, and four declared columns over a two-column atlas. The in-range// cells still draw — a layer that stopped drawing satisfies empty probes alone.