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 FBX brings its blend shapes

esengine86021bb0f47f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 the
example 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 for
the thing morph targets are for. The labels come from a source the field
diff --git a/build-tools/ufbx/ufbx-load.wasm b/build-tools/ufbx/ufbx-load.wasm
index 2f843cefc..a9f813f7e 100755
Binary files a/build-tools/ufbx/ufbx-load.wasm and b/build-tools/ufbx/ufbx-load.wasm differ
diff --git a/pipeline/src/assets/fbxImport.ts b/pipeline/src/assets/fbxImport.ts
index 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.ts
index 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.mts
index 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.mjs
index 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.c
index 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_part
out->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_part
out->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_part
read_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_part
streams[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));