A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(assets): an FBX brings its blend shapes
esengine86021bb0f47f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e8f0b2fee..4f4f748a4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -33,6 +33,11 @@ published separately; it ships inside the editor.primitive that node draws, one channel per target, and the clip that raises theexample robot's banner now furls it as it rises.+ **FBX brings its blend shapes too**, through the same door: ufbx's sparse+ per-vertex offsets become the same `.esmesh` section a glTF's targets do, at+ the weight the file left each channel on. Neither front end is the one that+ carries shapes.+The inspector shows **a slider per shape, under the name the mesh gave it** —a weight is positional, so a column of unlabelled numbers would be unusable forthe thing morph targets are for. The labels come from a source the fielddiff --git a/build-tools/ufbx/ufbx-load.wasm b/build-tools/ufbx/ufbx-load.wasmindex 2f843cefc..a9f813f7e 100755Binary files a/build-tools/ufbx/ufbx-load.wasm and b/build-tools/ufbx/ufbx-load.wasm differdiff --git a/pipeline/src/assets/fbxImport.ts b/pipeline/src/assets/fbxImport.tsindex 0b0ae051c..8b2a66ac6 100644--- a/pipeline/src/assets/fbxImport.ts+++ b/pipeline/src/assets/fbxImport.ts@@ -85,6 +85,11 @@ interface FbxMeshPart {colors: Slice | null;joints: Slice | null;weights: Slice | null;+ /** The shapes this part can be blended towards, in the order its deltas are in. */+ morphTargets: { name: string; weight: number }[];+ /** Whether each target carries a normal offset behind its position offset. */+ morphNormals: boolean;+ morphDeltas: Slice | null;indices: Slice;/** Source node index per bone, in the order the `Joints` channel indexes them. */skinJoints?: number[];@@ -505,6 +510,17 @@ function buildMesh(part: FbxMeshPart, name: string, payload: Uint8Array,}}+ // The shapes, transposed. The bridge writes one RECORD PER VERTEX, which is+ // what the deduplication it runs the vertices through can fold; the format+ // stores one SECTION PER TARGET. The only place that knows both layouts.+ const targets = part.morphTargets ?? [];+ const morph = targets.length > 0 && part.morphDeltas+ ? { names: targets.map((t, i) => t.name || `target ${i}`),+ hasNormals: !!part.morphNormals && !!normals,+ deltas: transposeMorph(floats(payload, part.morphDeltas), targets.length,+ vertexCount, part.morphNormals && !!normals ? 6 : 3) }+ : undefined;+return {name,data: {@@ -513,14 +529,30 @@ function buildMesh(part: FbxMeshPart, name: string, payload: Uint8Array,...(skinned && part.inverseBindMatrices? { inverseBindMatrices: floats(payload, part.inverseBindMatrices).slice() }: {}),+ ...(morph ? { morph } : {}),},vertexCount,triangleCount: indices.length / 3,...(material ? { material } : {}),...(skinned ? { skinJoints: part.skinJoints } : {}),+ ...(morph ? { morphWeights: targets.map((t) => t.weight) } : {}),};}+/** Per-vertex records of every target → per-target sections of every vertex. */+function transposeMorph(packed: Float32Array, targets: number, vertexCount: number,+ comps: number): Float32Array {+ const out = new Float32Array(targets * vertexCount * comps);+ for (let t = 0; t < targets; t++) {+ for (let v = 0; v < vertexCount; v++) {+ const from = (v * targets + t) * comps;+ const to = (t * vertexCount + v) * comps;+ for (let c = 0; c < comps; c++) out[to + c] = packed[from + c] ?? 0;+ }+ }+ return out;+}+/* -- Animation ---------------------------------------------------------- *//**diff --git a/pipeline/tests/fbx-import.test.ts b/pipeline/tests/fbx-import.test.tsindex db6e186fc..9d1be5312 100644--- a/pipeline/tests/fbx-import.test.ts+++ b/pipeline/tests/fbx-import.test.ts@@ -13,7 +13,7 @@ import { importFbxMeshes, dropInvisibleColors } from '../src/assets/fbxImport';import { assembleModelPrefab, materialProducts,type ImportedMesh, type ImportedNode } from '../src/assets/modelImport';import { MeshChannel } from 'esengine';-import { texturedTriangle, skinnedBar } from './fixtures/fbxFixtures.mjs';+import { texturedTriangle, skinnedBar, morphedQuad } from './fixtures/fbxFixtures.mjs';/** One channel's floats for vertex `index`, read back out of the packed buffer. */function attribute(mesh: ImportedMesh, semantic: number, index: number, comps: number): number[] {@@ -271,3 +271,41 @@ describe('fbx vertex colours that would import an invisible mesh', () => {expect(warnings).toHaveLength(1);});});++describe('fbx blend shapes', () => {+ it('carries each shape, its name and the weight the file left it at', async () => {+ const { meshes, warnings } = await importFbxMeshes(morphedQuad(), 'quad', 'quad.fbx');++ expect(warnings.join('\n')).not.toMatch(/blend shape/i);+ expect(warnings.join('\n')).not.toMatch(/blend shape/i);+ const morph = meshes[0]!.data.morph!;+ expect(morph.names).toEqual(['Slide', 'Lift']);+ // 40% in the file is 0.4 on the component: the channel's weight is a+ // percentage there and a fraction here, and shipping the percentage would+ // be a mesh forty times past its own shape.+ expect(meshes[0]!.morphWeights).toEqual([0.4, 0]);++ // Two of four vertices move, and they move differently per target — so the+ // deltas are read against the deduplicated vertex order, not corner order.+ const vertexCount = meshes[0]!.vertexCount;+ const slide = [...morph.deltas.subarray(0, vertexCount * 3)];+ const lift = [...morph.deltas.subarray(vertexCount * 3, vertexCount * 6)];+ expect(slide.filter((d) => d !== 0)).toEqual([3, 3]);+ expect(lift.filter((d) => d !== 0)).toEqual([5, 5]);+ // Along x for one shape and y for the other: an axis mix-up survives a+ // count and shows up only here.+ for (let v = 0; v < vertexCount; v++) {+ expect(slide[v * 3 + 1]).toBe(0);+ expect(lift[v * 3]).toBe(0);+ }+ });++ it('gives the prefab a MeshMorph holding those weights', async () => {+ const { meshes, nodes } = await importFbxMeshes(morphedQuad(), 'quad', 'quad.fbx');+ const prefab = assembleModelPrefab('quad', meshes, { nodes });+ const morph = prefab.entities+ .flatMap((e) => e.components)+ .find((c) => c.type === 'MeshMorph');+ expect(morph?.data).toEqual({ weights: [0.4, 0] });+ });+});diff --git a/pipeline/tests/fixtures/fbxFixtures.d.mts b/pipeline/tests/fixtures/fbxFixtures.d.mtsindex 5c517c718..add6eb90c 100644--- a/pipeline/tests/fixtures/fbxFixtures.d.mts+++ b/pipeline/tests/fixtures/fbxFixtures.d.mts@@ -7,3 +7,7 @@ export declare function texturedTriangle(): Uint8Array;/** Two bones and a quad bound to them, the upper bone turning 90° about Z. */export declare function skinnedBar(): Uint8Array;++/** A quad with two blend shapes — one slides its top edge, one lifts it — the+ * first left at 40% by the file. */+export declare function morphedQuad(): Uint8Array;diff --git a/pipeline/tests/fixtures/fbxFixtures.mjs b/pipeline/tests/fixtures/fbxFixtures.mjsindex 932ac4f73..abe4b4700 100644--- a/pipeline/tests/fixtures/fbxFixtures.mjs+++ b/pipeline/tests/fixtures/fbxFixtures.mjs@@ -201,6 +201,64 @@ export function texturedTriangle() {* bone at the origin, upper bone one unit up — so the inverse bind matrix a test* reads back is a translation it can check by eye.*/+/**+ * One blend shape: the vertices it moves, and by how much. FBX stores a shape as+ * its own Geometry — a sparse list of vertex indices with an offset each — which+ * is why `indexes` is not the whole mesh.+ */+function shapeGeometry(id, name, indexes, offsets, normals) {+ return `\tGeometry: ${id}, "Geometry::${name}", "Shape" {+\t\tVersion: 100+${array('Indexes', indexes, 2)}${array('Vertices', offsets, 2)}${+ normals ? array('Normals', normals, 2) : ''}\t}+`;+}++/** The channel a shape hangs off: its name, and the weight the file leaves it at. */+function blendChannel(id, name, percent) {+ return `\tDeformer: ${id}, "SubDeformer::${name}", "BlendShapeChannel" {+\t\tVersion: 100+\t\tDeformPercent: ${percent}+${array('FullWeights', [100], 2)}\t}+`;+}++/**+ * A quad with two shapes to blend towards: one slides the top edge right, the+ * other lifts it — and the file leaves the first at 40%. Different on purpose,+ * so a reader that mixed the two up, or lost the authored weight, says so.+ */+export function morphedQuad() {+ const objects = [+ geometry(1000, 'quad', {+ vertices: [-1, 0, 0, 1, 0, 0, 1, 2, 0, -1, 2, 0],+ faces: [[0, 1, 2, 3]],+ normals: Array.from({ length: 4 }, () => [0, 0, 1]).flat(),+ uvs: [0, 0, 1, 0, 1, 1, 0, 1],+ }),+ model(2000, 'Quad', 'Mesh'),+ `\tDeformer: 5000, "Deformer::BlendShape", "BlendShape" {+\t\tVersion: 100+\t}+`,+ blendChannel(5100, 'Slide', 40),+ blendChannel(5200, 'Lift', 0),+ // Only the top two vertices move, which is what makes the list sparse.+ shapeGeometry(6000, 'Slide', [2, 3], [3, 0, 0, 3, 0, 0]),+ shapeGeometry(6100, 'Lift', [2, 3], [0, 5, 0, 0, 5, 0]),+ ].join('');+ const connections = [+ connect(2000, 0),+ connect(1000, 2000),+ connect(5000, 1000),+ connect(5100, 5000),+ connect(5200, 5000),+ connect(6000, 5100),+ connect(6100, 5200),+ ].join('');+ return encode(`${header('estella fbxFixtures')}Objects: {\n${objects}}\nConnections: {\n${connections}}\n`);+}+export function skinnedBar() {const objects = [geometry(1000, 'bar', {diff --git a/tools/ufbx-wasm/bridge.c b/tools/ufbx-wasm/bridge.cindex f8fa7f8a0..e8931e1ba 100644--- a/tools/ufbx-wasm/bridge.c+++ b/tools/ufbx-wasm/bridge.c@@ -208,11 +208,17 @@ typedef struct {es_joints *joints;es_vec4 *weights;uint32_t *indices;+ /** Morph deltas, `vertex_count * morph_targets * (morph_normals ? 6 : 3)`+ * floats: per target, per vertex, the position offset and — where the+ * shapes state one — the normal offset behind it. */+ float *morph;+ size_t morph_targets;int has_normals;int has_uvs;int has_uvs1;int has_colors;int has_skin;+ int morph_normals;} es_part;static void es_part_free(es_part *p) {@@ -224,6 +230,7 @@ static void es_part_free(es_part *p) {free(p->joints);free(p->weights);free(p->indices);+ free(p->morph);memset(p, 0, sizeof(*p));}@@ -267,8 +274,28 @@ static void read_skin_vertex(const ufbx_skin_deformer *skin, uint32_t vertex,* merges the corners that agree on every stream, so what comes out is the* smallest vertex buffer that still draws what was authored.*/+/**+ * One shape's offsets as a vertex-indexed table: `-1` where it says nothing.+ *+ * `offset_vertices` is a sparse list — a shape states only the vertices it+ * moves — and it is walked once per CORNER, so the lookup is built rather than+ * searched. ufbx warns the indices may be out of bounds for the mesh; one that+ * is lands nowhere rather than in another vertex's row.+ */+static int32_t *shape_lookup(const ufbx_blend_shape *shape, size_t vertices) {+ int32_t *at = (int32_t *)malloc(vertices * sizeof(int32_t));+ if (!at) return NULL;+ for (size_t v = 0; v < vertices; v++) at[v] = -1;+ for (size_t i = 0; i < shape->num_offsets; i++) {+ uint32_t v = shape->offset_vertices.data[i];+ if (v < vertices) at[v] = (int32_t)i;+ }+ return at;+}+static int build_part(es_writer *w, const ufbx_mesh *mesh, const ufbx_mesh_part *part,- const ufbx_skin_deformer *skin, const char *label, es_part *out) {+ const ufbx_skin_deformer *skin, const ufbx_blend_deformer *blend,+ const char *label, es_part *out) {memset(out, 0, sizeof(*out));size_t corners = part->num_triangles * 3;if (corners == 0) return 0;@@ -280,6 +307,30 @@ static int build_part(es_writer *w, const ufbx_mesh *mesh, const ufbx_mesh_partout->has_colors = mesh->vertex_color.exists;out->has_skin = skin != NULL;+ // The shapes this mesh can be blended towards. A channel with no target is a+ // channel that states nothing, so it is not one of them.+ const ufbx_blend_shape **shapes = NULL;+ int32_t **lookups = NULL;+ if (blend && blend->channels.count > 0) {+ shapes = (const ufbx_blend_shape **)calloc(blend->channels.count, sizeof(*shapes));+ lookups = (int32_t **)calloc(blend->channels.count, sizeof(*lookups));+ if (shapes && lookups) {+ for (size_t c = 0; c < blend->channels.count; c++) {+ const ufbx_blend_shape *shape = blend->channels.data[c]->target_shape;+ if (!shape) continue;+ shapes[out->morph_targets] = shape;+ lookups[out->morph_targets] = shape_lookup(shape, mesh->num_vertices);+ if (shape->normal_offsets.count > 0) out->morph_normals = 1;+ out->morph_targets++;+ }+ }+ }+ // A normal offset with no normal to offset moves nothing, and the mesh format+ // stores the two together — so the geometry decides whether they are carried.+ if (!out->has_normals) out->morph_normals = 0;+ const size_t morph_comps = out->morph_normals ? 6u : 3u;+ const size_t morph_stride = out->morph_targets * morph_comps;+out->positions = (es_vec3 *)malloc(corners * sizeof(es_vec3));out->indices = (uint32_t *)malloc(corners * sizeof(uint32_t));if (out->has_normals) out->normals = (es_vec3 *)malloc(corners * sizeof(es_vec3));@@ -290,14 +341,19 @@ static int build_part(es_writer *w, const ufbx_mesh *mesh, const ufbx_mesh_partout->joints = (es_joints *)malloc(corners * sizeof(es_joints));out->weights = (es_vec4 *)malloc(corners * sizeof(es_vec4));}+ if (morph_stride > 0) out->morph = (float *)calloc(corners * morph_stride, sizeof(float));size_t tri_cap = mesh->max_face_triangles * 3;uint32_t *tri = (uint32_t *)malloc(tri_cap * sizeof(uint32_t));if (!out->positions || !out->indices || !tri|| (out->has_normals && !out->normals) || (out->has_uvs && !out->uvs)|| (out->has_uvs1 && !out->uvs1)|| (out->has_colors && !out->colors)- || (out->has_skin && (!out->joints || !out->weights))) {+ || (out->has_skin && (!out->joints || !out->weights))+ || (morph_stride > 0 && !out->morph)) {free(tri);+ if (lookups) for (size_t c = 0; c < out->morph_targets; c++) free(lookups[c]);+ free(lookups);+ free((void *)shapes);es_part_free(out);warnf(w, "%s: out of memory expanding %zu triangles", label, part->num_triangles);return 0;@@ -335,16 +391,41 @@ static int build_part(es_writer *w, const ufbx_mesh *mesh, const ufbx_mesh_partread_skin_vertex(skin, mesh->vertex_indices.data[ix],&out->joints[at], &out->weights[at]);}+ if (morph_stride > 0) {+ // The offsets are per VERTEX and this loop is per corner: two+ // corners of the same vertex carry the same offset, which is what+ // lets the deduplication below fold them back together.+ const uint32_t vertex = mesh->vertex_indices.data[ix];+ float *row = out->morph + at * morph_stride;+ for (size_t t = 0; t < out->morph_targets; t++) {+ const int32_t o = lookups[t] ? lookups[t][vertex] : -1;+ if (o < 0) continue;+ const ufbx_vec3 d = shapes[t]->position_offsets.data[o];+ float *cell = row + t * morph_comps;+ cell[0] = (float)d.x;+ cell[1] = (float)d.y;+ cell[2] = (float)d.z;+ if (!out->morph_normals+ || (size_t)o >= shapes[t]->normal_offsets.count) continue;+ const ufbx_vec3 n = shapes[t]->normal_offsets.data[o];+ cell[3] = (float)n.x;+ cell[4] = (float)n.y;+ cell[5] = (float)n.z;+ }+ }at++;}}free(tri);+ if (lookups) for (size_t c = 0; c < out->morph_targets; c++) free(lookups[c]);+ free(lookups);+ free((void *)shapes);if (at == 0) {es_part_free(out);return 0;}- ufbx_vertex_stream streams[7];+ ufbx_vertex_stream streams[8];size_t stream_count = 0;streams[stream_count].data = out->positions;streams[stream_count].vertex_count = at;@@ -377,6 +458,13 @@ static int build_part(es_writer *w, const ufbx_mesh *mesh, const ufbx_mesh_partstreams[stream_count].vertex_count = at;streams[stream_count++].vertex_size = sizeof(es_vec4);}+ // Through the deduplication like every other per-vertex value: a delta left+ // out of it would stay in corner order while the vertices moved to theirs.+ if (morph_stride > 0) {+ streams[stream_count].data = out->morph;+ streams[stream_count].vertex_count = at;+ streams[stream_count++].vertex_size = morph_stride * sizeof(float);+ }ufbx_error error;size_t unique = ufbx_generate_indices(streams, stream_count, out->indices, at, NULL, &error);@@ -523,8 +611,10 @@ static void write_meshes(es_writer *w, const ufbx_scene *scene) {warnf(w, "mesh \"%s\": %zu skin deformers; only the first is imported",mesh->name.data, mesh->skin_deformers.count);}- if (mesh->blend_deformers.count > 0) {- warnf(w, "mesh \"%s\": %zu blend shape(s) not imported",+ const ufbx_blend_deformer *blend = mesh->blend_deformers.count > 0+ ? mesh->blend_deformers.data[0] : NULL;+ if (mesh->blend_deformers.count > 1) {+ warnf(w, "mesh \"%s\": %zu blend deformers; only the first is imported",mesh->name.data, mesh->blend_deformers.count);}if (skin && skin->clusters.count > 65535) {@@ -541,7 +631,7 @@ static void write_meshes(es_writer *w, const ufbx_scene *scene) {char label[256];snprintf(label, sizeof(label), "mesh \"%s\"[%zu]", mesh->name.data, p);es_part built;- if (!build_part(w, mesh, part, skin, label, &built)) continue;+ if (!build_part(w, mesh, part, skin, blend, label, &built)) continue;if (!first) es_buf_text(&w->json, ",");first = 0;@@ -608,6 +698,35 @@ static void write_meshes(es_writer *w, const ufbx_scene *scene) {es_buf_text(&w->json, "null");}es_buf_text(&w->json, ",");+ json_key(&w->json, "morphTargets");+ es_buf_text(&w->json, "[");+ for (size_t t = 0, emitted = 0; t < (blend ? blend->channels.count : 0); t++) {+ const ufbx_blend_channel *ch = blend->channels.data[t];+ if (!ch->target_shape) continue;+ if (emitted++) es_buf_text(&w->json, ",");+ es_buf_text(&w->json, "{");+ json_key(&w->json, "name");+ json_string(&w->json, ch->name);+ es_buf_text(&w->json, ",");+ // What the file says this shape is blended to right now — the+ // weight the component starts at, as the source authored it.+ json_key(&w->json, "weight");+ json_number(&w->json, (double)ch->weight);+ es_buf_text(&w->json, "}");+ }+ es_buf_text(&w->json, "],");+ json_key(&w->json, "morphNormals");+ es_buf_text(&w->json, built.morph_normals ? "true" : "false");+ es_buf_text(&w->json, ",");+ json_key(&w->json, "morphDeltas");+ if (built.morph_targets > 0) {+ json_slice(w, built.morph,+ built.vertex_count * built.morph_targets+ * (built.morph_normals ? 6u : 3u) * sizeof(float));+ } else {+ es_buf_text(&w->json, "null");+ }+ es_buf_text(&w->json, ",");json_key(&w->json, "indices");json_slice(w, built.indices, built.index_count * sizeof(uint32_t));