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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file FBX → one self-describing blob, so the TypeScript importer never walks
* a ufbx struct across the wasm heap.
*
* The blob is shaped like a GLB: a JSON header describing the scene, and a
* payload holding every large array, addressed by `[offset, length]` pairs. That
* boundary is the whole point of this file — struct layouts stay on this side,
* and a rebuild of ufbx cannot silently move a field the reader indexes by hand.
*
* What ufbx is asked to do here is the conversion nobody should write twice:
* axes and units to the engine's (which are glTF's), geometry transforms turned
* into real nodes, polygons triangulated, and Euler curves with their pivots and
* pre-rotations baked into TRS keyframes.
*/
#include "ufbx.h"
#include <stdarg.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <math.h>
#define ES_FBX_MAGIC 0x42465345u /* "ESFB" little-endian */
#define ES_FBX_BLOB_VERSION 2u
/** Weights per vertex the engine's skinning reads; the rest are dropped. */
#define ES_FBX_MAX_WEIGHTS 4
typedef struct {
unsigned char *data;
size_t size;
size_t cap;
} es_buf;
static int es_buf_reserve(es_buf *b, size_t extra) {
if (b->size + extra <= b->cap) return 1;
size_t cap = b->cap ? b->cap : 4096;
while (cap < b->size + extra) cap *= 2;
unsigned char *data = (unsigned char *)realloc(b->data, cap);
if (!data) return 0;
b->data = data;
b->cap = cap;
return 1;
}
static int es_buf_write(es_buf *b, const void *data, size_t bytes) {
if (!es_buf_reserve(b, bytes)) return 0;
memcpy(b->data + b->size, data, bytes);
b->size += bytes;
return 1;
}
static int es_buf_text(es_buf *b, const char *text) {
return es_buf_write(b, text, strlen(text));
}
static void es_buf_free(es_buf *b) {
free(b->data);
b->data = NULL;
b->size = 0;
b->cap = 0;
}
/* -- JSON writing ------------------------------------------------------- */
/**
* A string as a JSON literal. FBX names carry whatever the authoring tool put
* there — quotes, backslashes, control characters — and ufbx hands them over as
* UTF-8 without a terminator, so the escaping happens here rather than in a
* printf somewhere.
*/
static void json_string(es_buf *b, ufbx_string s) {
es_buf_text(b, "\"");
for (size_t i = 0; i < s.length; i++) {
unsigned char c = (unsigned char)s.data[i];
switch (c) {
case '"': es_buf_text(b, "\\\""); break;
case '\\': es_buf_text(b, "\\\\"); break;
case '\n': es_buf_text(b, "\\n"); break;
case '\r': es_buf_text(b, "\\r"); break;
case '\t': es_buf_text(b, "\\t"); break;
default:
if (c < 0x20) {
char esc[8];
snprintf(esc, sizeof(esc), "\\u%04x", c);
es_buf_text(b, esc);
} else {
es_buf_write(b, &c, 1);
}
}
}
es_buf_text(b, "\"");
}
static void json_cstr(es_buf *b, const char *text) {
ufbx_string s = { text, strlen(text) };
json_string(b, s);
}
static void json_int(es_buf *b, long long value) {
char text[32];
snprintf(text, sizeof(text), "%lld", value);
es_buf_text(b, text);
}
/** A finite number, or `null` — a NaN in a JSON document is a parse error. */
static void json_number(es_buf *b, double value) {
if (!isfinite(value)) {
es_buf_text(b, "null");
return;
}
char text[40];
snprintf(text, sizeof(text), "%.9g", value);
es_buf_text(b, text);
}
static void json_key(es_buf *b, const char *key) {
json_cstr(b, key);
es_buf_text(b, ":");
}
static void json_vec3(es_buf *b, ufbx_vec3 v) {
es_buf_text(b, "[");
json_number(b, v.x); es_buf_text(b, ",");
json_number(b, v.y); es_buf_text(b, ",");
json_number(b, v.z);
es_buf_text(b, "]");
}
/* -- Blob assembly ------------------------------------------------------ */
typedef struct {
es_buf json;
es_buf payload;
es_buf warnings;
size_t warning_count;
} es_writer;
/**
* Copies an array into the payload and writes its `[offset, length]` slice.
* Every slice starts 4-byte aligned so the reader can view it as a typed array
* without copying — an unaligned offset is a runtime error in JS, not a
* slowdown.
*/
static void json_slice(es_writer *w, const void *data, size_t bytes) {
size_t pad = (4 - (w->payload.size % 4)) % 4;
if (pad) {
const unsigned char zeros[4] = { 0, 0, 0, 0 };
es_buf_write(&w->payload, zeros, pad);
}
size_t offset = w->payload.size;
es_buf_write(&w->payload, data, bytes);
es_buf_text(&w->json, "[");
json_int(&w->json, (long long)offset);
es_buf_text(&w->json, ",");
json_int(&w->json, (long long)bytes);
es_buf_text(&w->json, "]");
}
static void warn(es_writer *w, const char *text) {
if (w->warning_count++) es_buf_text(&w->warnings, ",");
json_cstr(&w->warnings, text);
}
static void warnf(es_writer *w, const char *format, ...) {
char text[512];
va_list args;
va_start(args, format);
vsnprintf(text, sizeof(text), format, args);
va_end(args);
warn(w, text);
}
/* -- Geometry ----------------------------------------------------------- */
typedef struct {
float x, y, z;
} es_vec3;
typedef struct {
float x, y;
} es_vec2;
typedef struct {
float x, y, z, w;
} es_vec4;
typedef struct {
uint16_t joints[ES_FBX_MAX_WEIGHTS];
} es_joints;
/**
* One mesh part expanded into per-corner arrays and re-indexed. A part is the
* run of faces sharing one material, which is exactly what one `.esmesh` holds
* — the same split a glTF calls a primitive.
*/
typedef struct {
size_t vertex_count;
size_t index_count;
es_vec3 *positions;
es_vec3 *normals;
es_vec2 *uvs;
/** The second UV set, where the mesh has one — a lightmap or detail unwrap. */
es_vec2 *uvs1;
es_vec4 *colors;
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) {
free(p->positions);
free(p->normals);
free(p->uvs);
free(p->uvs1);
free(p->colors);
free(p->joints);
free(p->weights);
free(p->indices);
free(p->morph);
memset(p, 0, sizeof(*p));
}
static es_vec3 to_vec3(ufbx_vec3 v) {
es_vec3 out = { (float)v.x, (float)v.y, (float)v.z };
return out;
}
/**
* The skin influences of one logical vertex, as the four the engine carries.
* ufbx sorts a vertex's weights by descending strength, so the first four are
* the strongest; they are renormalized because dropping the tail otherwise
* shrinks the vertex toward the origin.
*/
static void read_skin_vertex(const ufbx_skin_deformer *skin, uint32_t vertex,
es_joints *out_joints, es_vec4 *out_weights) {
memset(out_joints, 0, sizeof(*out_joints));
memset(out_weights, 0, sizeof(*out_weights));
if (vertex >= skin->vertices.count) return;
ufbx_skin_vertex sv = skin->vertices.data[vertex];
size_t taken = sv.num_weights < ES_FBX_MAX_WEIGHTS ? sv.num_weights : ES_FBX_MAX_WEIGHTS;
float total = 0.0f;
float values[ES_FBX_MAX_WEIGHTS] = { 0 };
for (size_t i = 0; i < taken; i++) {
ufbx_skin_weight sw = skin->weights.data[sv.weight_begin + i];
out_joints->joints[i] = (uint16_t)sw.cluster_index;
values[i] = (float)sw.weight;
total += values[i];
}
if (total <= 0.0f) return;
float *w = &out_weights->x;
for (size_t i = 0; i < taken; i++) w[i] = values[i] / total;
}
/**
* Expands one material part into vertex streams and re-indexes them.
*
* Attributes are read per index (a "corner"), which is how FBX stores them:
* a vertex split by a hard edge or a UV seam has several. `ufbx_generate_indices`
* 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 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;
out->has_normals = mesh->vertex_normal.exists;
out->has_uvs = mesh->vertex_uv.exists;
// uv_sets[0] IS vertex_uv; a second set is the one the engine could not carry.
out->has_uvs1 = mesh->uv_sets.count > 1 && mesh->uv_sets.data[1].vertex_uv.exists;
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_channel *channel = blend->channels.data[c];
const ufbx_blend_shape *shape = channel->target_shape;
if (!shape) continue;
// A progressive morph: the channel passes through shapes on its
// way to the last one. Only the last is carried, and a shape a
// reader drops without saying so is the deformation gone.
if (channel->keyframes.count > 1) {
warnf(w, "%s: shape \"%s\" passes through %zu in-between target(s);"
" only the final one is imported", label, channel->name.data,
channel->keyframes.count - 1);
}
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));
if (out->has_uvs) out->uvs = (es_vec2 *)malloc(corners * sizeof(es_vec2));
if (out->has_uvs1) out->uvs1 = (es_vec2 *)malloc(corners * sizeof(es_vec2));
if (out->has_colors) out->colors = (es_vec4 *)malloc(corners * sizeof(es_vec4));
if (out->has_skin) {
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))
|| (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;
}
size_t at = 0;
for (size_t f = 0; f < part->num_faces; f++) {
ufbx_face face = mesh->faces.data[part->face_indices.data[f]];
uint32_t tris = ufbx_triangulate_face(tri, tri_cap, mesh, face);
for (uint32_t t = 0; t < tris * 3; t++) {
uint32_t ix = tri[t];
if (at >= corners) break;
out->positions[at] = to_vec3(ufbx_get_vertex_vec3(&mesh->vertex_position, ix));
if (out->has_normals) {
out->normals[at] = to_vec3(ufbx_get_vertex_vec3(&mesh->vertex_normal, ix));
}
if (out->has_uvs) {
ufbx_vec2 uv = ufbx_get_vertex_vec2(&mesh->vertex_uv, ix);
out->uvs[at].x = (float)uv.x;
out->uvs[at].y = (float)uv.y;
}
if (out->has_uvs1) {
ufbx_vec2 uv = ufbx_get_vertex_vec2(&mesh->uv_sets.data[1].vertex_uv, ix);
out->uvs1[at].x = (float)uv.x;
out->uvs1[at].y = (float)uv.y;
}
if (out->has_colors) {
ufbx_vec4 c = ufbx_get_vertex_vec4(&mesh->vertex_color, ix);
out->colors[at].x = (float)c.x;
out->colors[at].y = (float)c.y;
out->colors[at].z = (float)c.z;
out->colors[at].w = (float)c.w;
}
if (out->has_skin) {
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[8];
size_t stream_count = 0;
streams[stream_count].data = out->positions;
streams[stream_count].vertex_count = at;
streams[stream_count++].vertex_size = sizeof(es_vec3);
if (out->has_normals) {
streams[stream_count].data = out->normals;
streams[stream_count].vertex_count = at;
streams[stream_count++].vertex_size = sizeof(es_vec3);
}
if (out->has_uvs) {
streams[stream_count].data = out->uvs;
streams[stream_count].vertex_count = at;
streams[stream_count++].vertex_size = sizeof(es_vec2);
}
if (out->has_uvs1) {
streams[stream_count].data = out->uvs1;
streams[stream_count].vertex_count = at;
streams[stream_count++].vertex_size = sizeof(es_vec2);
}
if (out->has_colors) {
streams[stream_count].data = out->colors;
streams[stream_count].vertex_count = at;
streams[stream_count++].vertex_size = sizeof(es_vec4);
}
if (out->has_skin) {
streams[stream_count].data = out->joints;
streams[stream_count].vertex_count = at;
streams[stream_count++].vertex_size = sizeof(es_joints);
streams[stream_count].data = out->weights;
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);
if (error.type != UFBX_ERROR_NONE) {
char message[UFBX_ERROR_INFO_LENGTH + 128];
ufbx_format_error(message, sizeof(message), &error);
warnf(w, "%s: %s", label, message);
es_part_free(out);
return 0;
}
out->vertex_count = unique;
out->index_count = at;
return 1;
}
/* -- Materials ---------------------------------------------------------- */
/**
* Which product a material map's texture became. FBX addresses image files
* through `ufbx_scene.texture_files[]`, already deduplicated, so a map carries
* that index plus the wrapping the texture asked for.
*/
static void json_texture_ref(es_writer *w, const ufbx_material_map *map) {
if (!map->texture || !map->texture_enabled || !map->texture->has_file
|| map->texture->file_index == UFBX_NO_INDEX) {
es_buf_text(&w->json, "null");
return;
}
const ufbx_texture *tex = map->texture;
es_buf_text(&w->json, "{");
json_key(&w->json, "file");
json_int(&w->json, tex->file_index);
es_buf_text(&w->json, ",");
json_key(&w->json, "wrapU");
json_int(&w->json, tex->wrap_u == UFBX_WRAP_CLAMP ? 1 : 0);
es_buf_text(&w->json, ",");
json_key(&w->json, "wrapV");
json_int(&w->json, tex->wrap_v == UFBX_WRAP_CLAMP ? 1 : 0);
es_buf_text(&w->json, ",");
// A uv transform is authored intent this import cannot carry: the engine
// samples the uvs as they are, so the reader says so rather than drawing
// the texture in the wrong place.
json_key(&w->json, "uvTransform");
es_buf_text(&w->json, tex->has_uv_transform ? "true" : "false");
es_buf_text(&w->json, "}");
}
/** One `ufbx_material_map` as a value/texture pair, or `null` when unset. */
static void json_material_map(es_writer *w, const char *key, const ufbx_material_map *map,
int components) {
json_key(&w->json, key);
if (!map->has_value && !map->texture) {
es_buf_text(&w->json, "null");
return;
}
es_buf_text(&w->json, "{");
json_key(&w->json, "value");
if (components <= 1) {
json_number(&w->json, map->value_real);
} else {
es_buf_text(&w->json, "[");
json_number(&w->json, map->value_vec4.x); es_buf_text(&w->json, ",");
json_number(&w->json, map->value_vec4.y); es_buf_text(&w->json, ",");
json_number(&w->json, map->value_vec4.z);
if (components > 3) {
es_buf_text(&w->json, ",");
json_number(&w->json, map->value_vec4.w);
}
es_buf_text(&w->json, "]");
}
es_buf_text(&w->json, ",");
json_key(&w->json, "hasValue");
es_buf_text(&w->json, map->has_value ? "true" : "false");
es_buf_text(&w->json, ",");
json_key(&w->json, "texture");
json_texture_ref(w, map);
es_buf_text(&w->json, "}");
}
/* -- Scene -------------------------------------------------------------- */
static es_buf g_result;
static char g_error[UFBX_ERROR_INFO_LENGTH + 256];
/** The mesh a node draws, skipping nodes whose geometry carries nothing. */
static int node_draws(const ufbx_node *node) {
return node->mesh && node->mesh->num_faces > 0;
}
/**
* A node's light, or nothing for a kind the engine has no light for. Area and
* volume lights are named, not dropped in silence.
*/
static void json_light(es_writer *w, const ufbx_scene *scene, const ufbx_light *light) {
const char *type = light->type == UFBX_LIGHT_POINT ? "\"point\""
: light->type == UFBX_LIGHT_DIRECTIONAL ? "\"directional\""
: light->type == UFBX_LIGHT_SPOT ? "\"spot\"" : NULL;
if (!type) {
warnf(w, "light \"%s\": an area or volume light is not imported", light->name.data);
return;
}
es_buf_text(&w->json, ",");
json_key(&w->json, "light");
es_buf_text(&w->json, "{");
json_key(&w->json, "type");
es_buf_text(&w->json, type);
es_buf_text(&w->json, ",");
json_key(&w->json, "color");
json_vec3(&w->json, light->color);
es_buf_text(&w->json, ",");
json_key(&w->json, "intensity");
json_number(&w->json, light->intensity);
// FBX states a reach only as far attenuation, in the file's units.
if (ufbx_find_bool(&light->props, "EnableFarAttenuation", false)) {
es_buf_text(&w->json, ",");
json_key(&w->json, "range");
json_number(&w->json, ufbx_find_real(&light->props, "FarAttenuationEnd", 0.0f)
* scene->metadata.geometry_scale);
}
if (light->type == UFBX_LIGHT_SPOT) {
es_buf_text(&w->json, ",");
json_key(&w->json, "innerAngle");
json_number(&w->json, light->inner_angle);
es_buf_text(&w->json, ",");
json_key(&w->json, "outerAngle");
json_number(&w->json, light->outer_angle);
}
es_buf_text(&w->json, "}");
}
static void json_camera(es_writer *w, const ufbx_camera *camera) {
const int perspective = camera->projection_mode == UFBX_PROJECTION_MODE_PERSPECTIVE;
es_buf_text(&w->json, ",");
json_key(&w->json, "camera");
es_buf_text(&w->json, "{");
json_key(&w->json, "projection");
es_buf_text(&w->json, perspective ? "\"perspective\"" : "\"orthographic\"");
es_buf_text(&w->json, ",");
if (perspective) {
json_key(&w->json, "yfov");
json_number(&w->json, camera->field_of_view_deg.y);
} else {
json_key(&w->json, "halfHeight");
json_number(&w->json, camera->orthographic_size.y * 0.5f);
}
es_buf_text(&w->json, ",");
json_key(&w->json, "near");
json_number(&w->json, camera->near_plane);
es_buf_text(&w->json, ",");
json_key(&w->json, "far");
json_number(&w->json, camera->far_plane);
es_buf_text(&w->json, ",");
json_key(&w->json, "aspect");
json_number(&w->json, camera->aspect_ratio);
es_buf_text(&w->json, "}");
}
static void write_nodes(es_writer *w, const ufbx_scene *scene) {
json_key(&w->json, "nodes");
es_buf_text(&w->json, "[");
for (size_t i = 0; i < scene->nodes.count; i++) {
const ufbx_node *node = scene->nodes.data[i];
if (i) es_buf_text(&w->json, ",");
es_buf_text(&w->json, "{");
json_key(&w->json, "name");
json_string(&w->json, node->name);
es_buf_text(&w->json, ",");
json_key(&w->json, "parent");
json_int(&w->json, node->parent ? (long long)node->parent->typed_id : -1);
es_buf_text(&w->json, ",");
json_key(&w->json, "translation");
json_vec3(&w->json, node->local_transform.translation);
es_buf_text(&w->json, ",");
json_key(&w->json, "rotation");
es_buf_text(&w->json, "[");
json_number(&w->json, node->local_transform.rotation.x); es_buf_text(&w->json, ",");
json_number(&w->json, node->local_transform.rotation.y); es_buf_text(&w->json, ",");
json_number(&w->json, node->local_transform.rotation.z); es_buf_text(&w->json, ",");
json_number(&w->json, node->local_transform.rotation.w);
es_buf_text(&w->json, "],");
json_key(&w->json, "scale");
json_vec3(&w->json, node->local_transform.scale);
es_buf_text(&w->json, ",");
json_key(&w->json, "mesh");
json_int(&w->json, node_draws(node) ? (long long)node->mesh->typed_id : -1);
es_buf_text(&w->json, ",");
// A helper node exists because a geometry transform or a non-standard
// inherit mode needed a place to live; naming it says why an entity the
// artist never made is in the prefab.
json_key(&w->json, "helper");
es_buf_text(&w->json, node->is_geometry_transform_helper || node->is_scale_helper
? "true" : "false");
if (node->light) json_light(w, scene, node->light);
if (node->camera) json_camera(w, node->camera);
es_buf_text(&w->json, "}");
}
es_buf_text(&w->json, "],");
}
/**
* Writes every mesh, split by material. Geometry is emitted per source mesh
* rather than per node: an instanced mesh is one product that several entities
* draw, which is what the prefab assembly already expects.
*/
static void write_meshes(es_writer *w, const ufbx_scene *scene) {
json_key(&w->json, "meshes");
es_buf_text(&w->json, "[");
int first = 1;
for (size_t m = 0; m < scene->meshes.count; m++) {
const ufbx_mesh *mesh = scene->meshes.data[m];
const ufbx_skin_deformer *skin = mesh->skin_deformers.count > 0
? mesh->skin_deformers.data[0] : NULL;
if (mesh->skin_deformers.count > 1) {
warnf(w, "mesh \"%s\": %zu skin deformers; only the first is imported",
mesh->name.data, mesh->skin_deformers.count);
}
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) {
warnf(w, "mesh \"%s\": %zu bones exceed the 65535 a joint index holds",
mesh->name.data, skin->clusters.count);
skin = NULL;
}
// A mesh with no material still has one part covering every face, so
// both cases walk the same loop.
size_t parts = mesh->material_parts.count;
for (size_t p = 0; p < parts; p++) {
const ufbx_mesh_part *part = &mesh->material_parts.data[p];
char label[256];
snprintf(label, sizeof(label), "mesh \"%s\"[%zu]", mesh->name.data, p);
es_part built;
if (!build_part(w, mesh, part, skin, blend, label, &built)) continue;
if (!first) es_buf_text(&w->json, ",");
first = 0;
es_buf_text(&w->json, "{");
json_key(&w->json, "name");
json_string(&w->json, mesh->name);
es_buf_text(&w->json, ",");
json_key(&w->json, "mesh");
json_int(&w->json, (long long)mesh->typed_id);
es_buf_text(&w->json, ",");
json_key(&w->json, "part");
json_int(&w->json, (long long)p);
es_buf_text(&w->json, ",");
json_key(&w->json, "material");
json_int(&w->json, p < mesh->materials.count && mesh->materials.data[p]
? (long long)mesh->materials.data[p]->typed_id : -1);
es_buf_text(&w->json, ",");
json_key(&w->json, "vertexCount");
json_int(&w->json, (long long)built.vertex_count);
es_buf_text(&w->json, ",");
json_key(&w->json, "positions");
json_slice(w, built.positions, built.vertex_count * sizeof(es_vec3));
es_buf_text(&w->json, ",");
json_key(&w->json, "normals");
if (built.has_normals) {
json_slice(w, built.normals, built.vertex_count * sizeof(es_vec3));
} else {
es_buf_text(&w->json, "null");
}
es_buf_text(&w->json, ",");
json_key(&w->json, "uvs");
if (built.has_uvs) {
json_slice(w, built.uvs, built.vertex_count * sizeof(es_vec2));
} else {
es_buf_text(&w->json, "null");
}
es_buf_text(&w->json, ",");
json_key(&w->json, "uvs1");
if (built.has_uvs1) {
json_slice(w, built.uvs1, built.vertex_count * sizeof(es_vec2));
} else {
es_buf_text(&w->json, "null");
}
es_buf_text(&w->json, ",");
json_key(&w->json, "colors");
if (built.has_colors) {
json_slice(w, built.colors, built.vertex_count * sizeof(es_vec4));
} else {
es_buf_text(&w->json, "null");
}
es_buf_text(&w->json, ",");
json_key(&w->json, "joints");
if (built.has_skin) {
json_slice(w, built.joints, built.vertex_count * sizeof(es_joints));
} else {
es_buf_text(&w->json, "null");
}
es_buf_text(&w->json, ",");
json_key(&w->json, "weights");
if (built.has_skin) {
json_slice(w, built.weights, built.vertex_count * sizeof(es_vec4));
} else {
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));
if (built.has_skin) {
es_buf_text(&w->json, ",");
json_key(&w->json, "skinJoints");
es_buf_text(&w->json, "[");
for (size_t c = 0; c < skin->clusters.count; c++) {
if (c) es_buf_text(&w->json, ",");
const ufbx_node *bone = skin->clusters.data[c]->bone_node;
json_int(&w->json, bone ? (long long)bone->typed_id : -1);
}
es_buf_text(&w->json, "],");
// The bind pose, one 4x4 per bone. ufbx keeps a 4x3 affine
// matrix in column-major order; the fourth row is implicit, and
// writing it out here is what makes the product a plain matrix
// the runtime can multiply.
json_key(&w->json, "inverseBindMatrices");
size_t count = skin->clusters.count;
float *matrices = (float *)calloc(count ? count * 16 : 1, sizeof(float));
if (matrices) {
for (size_t c = 0; c < count; c++) {
const ufbx_matrix *m = &skin->clusters.data[c]->geometry_to_bone;
float *dst = matrices + c * 16;
for (int col = 0; col < 4; col++) {
dst[col * 4 + 0] = (float)m->cols[col].x;
dst[col * 4 + 1] = (float)m->cols[col].y;
dst[col * 4 + 2] = (float)m->cols[col].z;
dst[col * 4 + 3] = col == 3 ? 1.0f : 0.0f;
}
}
json_slice(w, matrices, count * 16 * sizeof(float));
free(matrices);
} else {
es_buf_text(&w->json, "null");
}
}
es_buf_text(&w->json, "}");
es_part_free(&built);
}
}
es_buf_text(&w->json, "],");
}
static void write_materials(es_writer *w, const ufbx_scene *scene) {
json_key(&w->json, "materials");
es_buf_text(&w->json, "[");
for (size_t i = 0; i < scene->materials.count; i++) {
const ufbx_material *mat = scene->materials.data[i];
if (i) es_buf_text(&w->json, ",");
es_buf_text(&w->json, "{");
json_key(&w->json, "name");
json_string(&w->json, mat->name);
es_buf_text(&w->json, ",");
// Which shading model the file actually described. A Phong material has
// no metalness at all, and reporting it as one would invent a surface.
json_key(&w->json, "shader");
json_int(&w->json, (long long)mat->shader_type);
es_buf_text(&w->json, ",");
json_key(&w->json, "pbr");
es_buf_text(&w->json, mat->features.pbr.enabled ? "true" : "false");
es_buf_text(&w->json, ",");
json_key(&w->json, "twoSided");
es_buf_text(&w->json, mat->features.double_sided.enabled ? "true" : "false");
es_buf_text(&w->json, ",");
json_material_map(w, "baseColor", &mat->pbr.base_color, 3);
es_buf_text(&w->json, ",");
json_material_map(w, "baseFactor", &mat->pbr.base_factor, 1);
es_buf_text(&w->json, ",");
json_material_map(w, "roughness", &mat->pbr.roughness, 1);
es_buf_text(&w->json, ",");
json_material_map(w, "glossiness", &mat->pbr.glossiness, 1);
es_buf_text(&w->json, ",");
json_material_map(w, "metalness", &mat->pbr.metalness, 1);
es_buf_text(&w->json, ",");
json_material_map(w, "emissionColor", &mat->pbr.emission_color, 3);
es_buf_text(&w->json, ",");
json_material_map(w, "emissionFactor", &mat->pbr.emission_factor, 1);
es_buf_text(&w->json, ",");
json_material_map(w, "opacity", &mat->pbr.opacity, 1);
es_buf_text(&w->json, ",");
json_material_map(w, "normalMap", &mat->pbr.normal_map, 3);
es_buf_text(&w->json, ",");
json_material_map(w, "occlusion", &mat->pbr.ambient_occlusion, 1);
es_buf_text(&w->json, ",");
json_material_map(w, "specularColor", &mat->pbr.specular_color, 3);
es_buf_text(&w->json, "}");
}
es_buf_text(&w->json, "],");
}
static void write_textures(es_writer *w, const ufbx_scene *scene) {
json_key(&w->json, "textures");
es_buf_text(&w->json, "[");
for (size_t i = 0; i < scene->texture_files.count; i++) {
const ufbx_texture_file *file = &scene->texture_files.data[i];
if (i) es_buf_text(&w->json, ",");
es_buf_text(&w->json, "{");
json_key(&w->json, "filename");
json_string(&w->json, file->filename);
es_buf_text(&w->json, ",");
json_key(&w->json, "relativeFilename");
json_string(&w->json, file->relative_filename);
es_buf_text(&w->json, ",");
json_key(&w->json, "content");
if (file->content.size > 0) {
json_slice(w, file->content.data, file->content.size);
} else {
es_buf_text(&w->json, "null");
}
es_buf_text(&w->json, "}");
}
es_buf_text(&w->json, "],");
}
/**
* Every animation stack, baked. FBX rotates in Euler angles around pivots that
* the engine's Transform has no field for, so reading the curves as authored
* would place a limb somewhere the source never did — the bake is what turns all
* of it into the TRS keyframes a track can hold.
*/
static void write_animations(es_writer *w, const ufbx_scene *scene) {
json_key(&w->json, "animations");
es_buf_text(&w->json, "[");
int first = 1;
for (size_t s = 0; s < scene->anim_stacks.count; s++) {
const ufbx_anim_stack *stack = scene->anim_stacks.data[s];
ufbx_bake_opts opts;
memset(&opts, 0, sizeof(opts));
opts.trim_start_time = true;
opts.key_reduction_enabled = true;
// Rotation keys are left alone: the engine interpolates the four
// components and renormalizes, and reduction assumes a slerp — over a
// long merged segment the two paths are not the same arc.
opts.key_reduction_rotation = false;
ufbx_error error;
ufbx_baked_anim *bake = ufbx_bake_anim(scene, stack->anim, &opts, &error);
if (!bake) {
char message[UFBX_ERROR_INFO_LENGTH + 128];
ufbx_format_error(message, sizeof(message), &error);
warnf(w, "animation \"%s\": %s", stack->name.data, message);
continue;
}
if (bake->nodes.count == 0) {
ufbx_free_baked_anim(bake);
continue;
}
if (!first) es_buf_text(&w->json, ",");
first = 0;
es_buf_text(&w->json, "{");
json_key(&w->json, "name");
json_string(&w->json, stack->name);
es_buf_text(&w->json, ",");
json_key(&w->json, "duration");
// The stack's own playback range is what the file says the animation
// lasts, but an exporter that wrote no range leaves it at zero — and a
// clip that says it is zero seconds long plays nothing at all.
double duration = bake->playback_duration;
if (bake->key_time_max > duration) duration = bake->key_time_max;
json_number(&w->json, duration);
es_buf_text(&w->json, ",");
json_key(&w->json, "nodes");
es_buf_text(&w->json, "[");
for (size_t n = 0; n < bake->nodes.count; n++) {
const ufbx_baked_node *node = &bake->nodes.data[n];
if (n) es_buf_text(&w->json, ",");
es_buf_text(&w->json, "{");
json_key(&w->json, "node");
json_int(&w->json, (long long)node->typed_id);
const char *names[3] = { "translation", "rotation", "scale" };
size_t counts[3] = {
node->translation_keys.count, node->rotation_keys.count, node->scale_keys.count,
};
for (int channel = 0; channel < 3; channel++) {
es_buf_text(&w->json, ",");
json_key(&w->json, names[channel]);
size_t count = counts[channel];
if (count == 0) {
es_buf_text(&w->json, "null");
continue;
}
size_t comps = channel == 1 ? 4 : 3;
float *times = (float *)malloc(count * sizeof(float));
float *values = (float *)malloc(count * comps * sizeof(float));
if (!times || !values) {
free(times);
free(values);
es_buf_text(&w->json, "null");
warnf(w, "animation \"%s\": out of memory writing %s keys",
stack->name.data, names[channel]);
continue;
}
for (size_t k = 0; k < count; k++) {
if (channel == 1) {
ufbx_baked_quat key = node->rotation_keys.data[k];
times[k] = (float)key.time;
values[k * 4 + 0] = (float)key.value.x;
values[k * 4 + 1] = (float)key.value.y;
values[k * 4 + 2] = (float)key.value.z;
values[k * 4 + 3] = (float)key.value.w;
} else {
ufbx_baked_vec3 key = channel == 0
? node->translation_keys.data[k] : node->scale_keys.data[k];
times[k] = (float)key.time;
values[k * 3 + 0] = (float)key.value.x;
values[k * 3 + 1] = (float)key.value.y;
values[k * 3 + 2] = (float)key.value.z;
}
}
es_buf_text(&w->json, "{");
json_key(&w->json, "times");
json_slice(w, times, count * sizeof(float));
es_buf_text(&w->json, ",");
json_key(&w->json, "values");
json_slice(w, values, count * comps * sizeof(float));
es_buf_text(&w->json, "}");
free(times);
free(values);
}
es_buf_text(&w->json, "}");
}
es_buf_text(&w->json, "]}");
ufbx_free_baked_anim(bake);
}
es_buf_text(&w->json, "],");
}
/** What the file holds that this import has no place for. */
static void report_unimported(es_writer *w, const ufbx_scene *scene) {
for (size_t i = 0; i < scene->metadata.warnings.count; i++) {
const ufbx_warning *warning = &scene->metadata.warnings.data[i];
if (warning->count > 1) {
warnf(w, "%s (x%zu)", warning->description.data, warning->count);
} else {
warn(w, warning->description.data);
}
}
}
/**
* Parses `data` and leaves the blob in `g_result`.
*
* @param filename What the source is called, so a texture's relative path
* resolves the way the file meant it to.
* @return 1 on success; 0 leaves the reason in {@link es_fbx_error}.
*/
int es_fbx_load(const unsigned char *data, size_t size, const char *filename) {
es_buf_free(&g_result);
g_error[0] = '\0';
ufbx_load_opts opts;
memset(&opts, 0, sizeof(opts));
// The engine's world matches glTF's: right-handed, +Y up, one unit is one
// metre. Everything downstream — the prefab, the animation tracks, the
// import scale a user sets — is written against that.
opts.target_axes = ufbx_axes_right_handed_y_up;
opts.target_unit_meters = 1.0f;
opts.space_conversion = UFBX_SPACE_CONVERSION_MODIFY_GEOMETRY;
// FBX cameras look along +X and lights shine along -Y; the engine's, like
// glTF's, both face -Z. ufbx turns each such node so they do.
opts.target_camera_axes = ufbx_axes_right_handed_y_up;
opts.target_light_axes = ufbx_axes_right_handed_y_up;
// FBX lets geometry sit at an offset from its node with no node to hold it.
// Helper nodes turn that into hierarchy the prefab can express; modifying
// the geometry instead would be wrong for anything instanced.
opts.geometry_transform_handling = UFBX_GEOMETRY_TRANSFORM_HANDLING_HELPER_NODES;
opts.inherit_mode_handling = UFBX_INHERIT_MODE_HANDLING_HELPER_NODES;
// Helper nodes become entities in the prefab, and an unnamed entity is one
// nothing can address — an animation track resolves its target by name.
opts.geometry_transform_helper_name.data = "GeometryTransform";
opts.geometry_transform_helper_name.length = strlen("GeometryTransform");
opts.scale_helper_name.data = "ScaleHelper";
opts.scale_helper_name.length = strlen("ScaleHelper");
// Texture paths become project paths; a Windows-authored file spells them
// with backslashes, which no other reader here would resolve.
opts.path_separator = '/';
opts.generate_missing_normals = true;
opts.normalize_normals = true;
opts.clean_skin_weights = true;
// Blender writes PBR materials as legacy Phong in a known way; without this
// its roughness and metalness maps are invisible to the reader.
opts.use_blender_pbr_material = true;
// There is no filesystem here: images are resolved by the caller, which is
// also what lets it bring them into the project.
opts.load_external_files = false;
opts.ignore_missing_external_files = true;
if (filename && filename[0]) {
opts.filename.data = filename;
opts.filename.length = strlen(filename);
}
ufbx_error error;
ufbx_scene *scene = ufbx_load_memory(data, size, &opts, &error);
if (!scene) {
ufbx_format_error(g_error, sizeof(g_error), &error);
return 0;
}
es_writer w;
memset(&w, 0, sizeof(w));
es_buf_text(&w.json, "{");
json_key(&w.json, "fileFormat");
json_int(&w.json, (long long)scene->metadata.file_format);
es_buf_text(&w.json, ",");
json_key(&w.json, "creator");
json_string(&w.json, scene->metadata.creator);
es_buf_text(&w.json, ",");
write_nodes(&w, scene);
write_meshes(&w, scene);
write_materials(&w, scene);
write_textures(&w, scene);
write_animations(&w, scene);
report_unimported(&w, scene);
json_key(&w.json, "warnings");
es_buf_text(&w.json, "[");
es_buf_write(&w.json, w.warnings.data, w.warnings.size);
es_buf_text(&w.json, "]}");
ufbx_free_scene(scene);
uint32_t header[4] = {
ES_FBX_MAGIC, ES_FBX_BLOB_VERSION,
(uint32_t)w.json.size, (uint32_t)w.payload.size,
};
size_t pad = (4 - (w.json.size % 4)) % 4;
const unsigned char zeros[4] = { 0, 0, 0, 0 };
int ok = es_buf_write(&g_result, header, sizeof(header))
&& es_buf_write(&g_result, w.json.data, w.json.size)
&& (pad == 0 || es_buf_write(&g_result, zeros, pad))
&& (w.payload.size == 0 || es_buf_write(&g_result, w.payload.data, w.payload.size));
es_buf_free(&w.json);
es_buf_free(&w.payload);
es_buf_free(&w.warnings);
if (!ok) {
es_buf_free(&g_result);
snprintf(g_error, sizeof(g_error), "out of memory assembling the result");
return 0;
}
return 1;
}
const unsigned char *es_fbx_result_data(void) {
return g_result.data;
}
size_t es_fbx_result_size(void) {
return g_result.size;
}
const char *es_fbx_error(void) {
return g_error;
}
/** Hands the blob's memory back — an import per file would otherwise keep the
* largest one alive for the life of the process. */
void es_fbx_release(void) {
es_buf_free(&g_result);
}