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): a model's animations come in with it

esengine3ed8d551b6e1
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.ts
index 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: stri
const 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: stri
for (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 the
diff --git a/desktop/public/scenes/model-animation.esscene b/desktop/public/scenes/model-animation.esscene
new file mode 100644
index 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.esmesh
new file mode 100644
index 000000000..76d12f34b
Binary files /dev/null and b/desktop/public/scenes/moving-quad.esmesh differ
diff --git a/desktop/public/scenes/moving-quad.esmesh.meta b/desktop/public/scenes/moving-quad.esmesh.meta
new file mode 100644
index 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.esprefab
new file mode 100644
index 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.meta
new file mode 100644
index 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.gltf
new file mode 100644
index 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.estimeline
new file mode 100644
index 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.meta
new file mode 100644
index 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.mjs
index 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.ts
index 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 invisible
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index 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.ts
index 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.mjs
index 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.