@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.

| Option | Type | Default | Notes | |---|---|---|---| | preset | 'threejs' \| 'unity' \| 'unreal' \| 'blender' \| 'maya' | 'threejs' | Picks axis + unit defaults. | | axisUp | 'X' \| 'Y' \| 'Z' \| '-X' \| '-Y' \| '-Z' | preset | Overrides preset. | | axisForward | same | preset | Overrides preset. | | unitScale | number | preset | Written to GlobalSettings.UnitScaleFactor. | | bakeSpaceTransform | boolean | false | Pre-multiplies axis matrix into geometry. See limitation note below. | | version | number | 7400 | FBX version (7400 / 7500 supported). | | fps | number | 24 | Animation frame rate. | | embedTextures | boolean | true | When false, textures are referenced by file path instead of embedded. | | animations | AnimationClip[] | auto | If omitted, we collect from input.animations (the convention used by GLTFLoader / FBXLoader). | | includeAnimations | boolean | true | Set false to export a static T-pose only (skips AnimStack/Curve nodes entirely). | | onlyVisible | boolean | false | Skip Object3Ds whose .visible is false. | | objectFilter | (o: Object3D) => boolean | — | Generic predicate — return false to skip an object. Composes with onlyVisible. | | customProperties | boolean | false | Emit each Object3D's userData as user-defined Properties70 entries. Maps booleans → p_bool, integers → p_integer, floats → p_double, strings → p_string, length-3 number arrays → p_vector_3d; other JS values get JSON-stringified into a p_string. | | creator | string | @comfyorg/fbx-exporter-three - <ver> | Custom string written to FBX Creator metadata. |

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

| three.js input | FBX output | |---|---| | Mesh + BufferGeometry (positions / normals / vertex colors) | Geometry + LayerElementNormal / LayerElementColor / LayerElementMaterial | | Multiple UV sets — attributes.uv / uv1 / uv2 / uv3 (used for lightmap / AO) | Multiple LayerElementUV nodes with distinct TypedIndex + per-set Layer entries | | MeshStandardMaterial / MeshPhongMaterial / MeshBasicMaterial | Material with FbxSurfacePhong shading model | | Texture (DataTexture, HTMLImage, canvas) | Texture + Video with embedded PNG bytes | | Group, Object3D | Model (Null) | | SkinnedMesh + Skeleton + Bone | Deformer (Skin) + Deformer (Cluster) per bone + Pose (BindPose) + Model (LimbNode) per bone | | AnimationClip (position / rotation / scale tracks) | AnimationStack + AnimationLayer + AnimationCurveNode + AnimationCurve | | Morph targets (morphAttributes.position) | Geometry (Shape) per morph + Deformer (BlendShape) + Deformer (BlendShapeChannel) | | Morph animation (compound morphTargetInfluences track) | Per-channel AnimationCurveNode driving DeformPercent | | PointLight / DirectionalLight / SpotLight | NodeAttribute (Light) — light.target.position round-trips via LookAtProperty | | PerspectiveCamera / OrthographicCamera | NodeAttribute (Camera) | | Axis / unit conversion | GlobalSettings.UpAxis / FrontAxis / UnitScaleFactor |

Tool presets

| Preset | UpAxis | FrontAxis | UnitScale | Bake | Use when… | |---|---|---|---|---|---| | threejs (default) | Y | Z | 1 | off | Round-tripping through FBXLoader. | | unity | Y | Z | 1 | off | Importing into Unity (it respects file axes). | | unreal | Z | X | 1 | off | Importing into Unreal Editor. Unreal's importer handles axis conversion when GlobalSettings declares it. | | blender | Y | Z | 100 | off | Files for Blender. UnitScale=100 because Blender stores meters but FBX canonical unit is centimeters. | | maya | Y | Z | 100 | off | Same as Blender. |

// 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.