@comfyorg/fbx-exporter-three

FBX binary exporter for three.js scenes — Unity / Unreal / Maya / Blender / three.js's own FBXLoader all consume the output cleanly.

• Self-contained: TypeScript source, ships ESM .js + .d.ts. Only runtime dep is fflate (zlib).
• One-shot or async: parseSync when textures are DataTextures or absent; parseAsync when textures need canvas-based encoding (HTMLImageElement / ImageBitmap / render targets).
• Tool presets: threejs, unity, unreal, blender, maya — picks the right axis convention + unit scale for the target.
• Covers: meshes, multi-UV layers, materials, textures (PNG-embedded), skinning, animation (TRS + morph), morph targets, lights, cameras.

Install

npm install @comfyorg/fbx-exporter-three

Peer deps: three >= 0.160 (required), @types/three >= 0.160 (optional, only if you're using TypeScript).

TypeScript

Source is written in TypeScript; published dist/ ships ESM .js + .d.ts. Public types include FBXExporter, FBXExportOptions, FBXPreset, FBXAxis, FBXExporterPlugin.

Quickstart

import * as THREE from 'three';
import { FBXExporter } from '@comfyorg/fbx-exporter-three';
import { writeFileSync } from 'node:fs';

const scene = new THREE.Scene();
scene.add(new THREE.Mesh(
  new THREE.BoxGeometry(1, 1, 1),
  new THREE.MeshStandardMaterial({ color: 0x6688ff }),
));

const exporter = new FBXExporter();
const bytes = exporter.parseSync(scene);

writeFileSync('cube.fbx', bytes);

The result is a binary FBX (Kaydara FBX Binary magic) you can drop straight into Unity, Unreal, Blender, Maya, or load back with FBXLoader.

API

class FBXExporter

const exporter = new FBXExporter();

parseSync(input, options?) → Uint8Array

Build an FBX in one call. Use this for static scenes, scenes that only have DataTextures, or when you've already encoded all your textures.

parseAsync(input, options?) → Promise<Uint8Array>

Same as parseSync but awaits async texture encoding paths — HTMLImageElement, ImageBitmap, canvas/render-target textures all need canvas.toBlob() which is async. Use this whenever your materials reference textures loaded via TextureLoader (any environment with a canvas API).

const bytes = await new FBXExporter().parseAsync(scene);

register(callback) / unregister(callback)

Plugin hook in the style of three.js's GLTFExporter. The callback receives sceneData (the collected scene plan) after collection and texture encoding, before serialization:

exporter.register((sceneData) => {
  // e.g. swap pre-encoded PNG bytes into texture entries
  for (const [tex, entry] of sceneData.textures.textures) {
    if (tex.userData.preEncodedPng) entry.imageBytes = tex.userData.preEncodedPng;
  }
});

Convenience exports

import {
  FBXExporter,
  PRESETS,            // tool preset table
  resolvePreset,      // merge user options onto a preset
  encodeRGBA8PNG,     // pure-JS PNG encoder used internally
} from '@comfyorg/fbx-exporter-three';

Feature coverage

Tool presets

// Use a preset:
exporter.parseSync(scene, { preset: 'unreal' });

// Or set axes directly:
exporter.parseSync(scene, { axisUp: 'Z', axisForward: 'X' });

// Mix: preset defaults + selective override:
exporter.parseSync(scene, { preset: 'unity', unitScale: 100 });

Examples

Skinned + animated character

import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { FBXExporter } from '@comfyorg/fbx-exporter-three';

const gltf = await new GLTFLoader().loadAsync('character.glb');
const scene = gltf.scene;
scene.animations = gltf.animations;  // wire so the exporter finds them

const bytes = await new FBXExporter().parseAsync(scene);

Textures from disk (Node)

const tex = new THREE.DataTexture(rgbaPixels, w, h, THREE.RGBAFormat);
tex.needsUpdate = true;
material.map = tex;

const bytes = new FBXExporter().parseSync(scene);  // embeds PNG-encoded RGBA

Saving to file

import { writeFileSync } from 'node:fs';
writeFileSync('out.fbx', bytes);

Saving in the browser

const blob = new Blob([bytes], { type: 'application/octet-stream' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'out.fbx';
a.click();
URL.revokeObjectURL(url);

Known limitations

• bakeSpaceTransform: true only pre-multiplies the axis matrix into vertex positions + normals. Object Lcl transforms, cluster matrices, animation curves, and light/camera transforms are NOT baked. The flag is only safe for single-mesh-at-origin scenes; leave it false otherwise — modern importers (Unity, Unreal, Blender, Maya) honour GlobalSettings.UpAxis so axis conversion happens on import.
• light.target.position for DirectionalLight / SpotLight round-trips via a synthetic LookAtProperty Model + OP connection.
• Output is always binary FBX (Kaydara FBX Binary magic). ASCII FBX is not implemented.

How it works (brief)

┌───────────────────┐   ┌──────────────┐   ┌──────────────┐
│ three.js Scene    │ → │ SceneCollect │ → │ FBXElem tree │ → encodeBinaryFBX → Uint8Array
└───────────────────┘   └──────────────┘   └──────────────┘
                              │                    │
                  builds UIDs, dedupes      one writer per FBX
                  geometries / mats /       record kind (Geometry,
                  textures, plans OO/OP     Material, Skin Deformer,
                  connection graph         AnimStack, …)

Testing

npm test

446 unit tests covering the binary layer, scene collection, every Object kind (Mesh / Material / Texture / Skin / Animation / Morph / Light / Camera), axis/unit conversion, the public-options surface.

Real-asset E2E tests (test/e2e-*.test.mjs) aren't part of npm test — they read large binary inputs from test/_assets/ which is gitignored. Drop your own assets in that folder and run them individually:

node --import tsx test/e2e-1-obj.test.mjs           # raw .obj round-trip
node --import tsx test/e2e-2-xbot.test.mjs          # Mixamo skinned + animated character
node --import tsx test/e2e-3-testTexture.test.mjs   # OBJ + MTL + PNG textures
node --import tsx test/e2e-4-threejs-models.test.mjs  # 7 three.js example glTFs

test/m5-bindpose-recovery.test.mjs IS in npm test but skips gracefully when test/_assets/Xbot.glb isn't there — drop in any skinned glTF to enable it.

License

MIT. See LICENSE.

Published under @comfyorg.