The FBX converter is a command-line tool to convert from FBX to native Harfang scene.

Usage: fbx-convert <input> [-o <output_dir>]


The following options are available:


  • -o,-out <dir>: Output directory for the converted resource files.
  • -test-import: Perform conversion but do not output any file.


  • -base-resource-path <dir>: Transform references to assets in this directory to be relative.
  • -prefix <str>: Specify the file system prefix from which relative assets are to be loaded from.


  • -material-policy <policy>: Material file import policy. 1
  • -geometry-policy <policy>: Geometry file import policy. 1
  • -texture-policy <policy>: Texture file import policy. 1
  • -scene-policy <policy>: Scene file import policy. 1


  • -scale <float>: Factor used to scale the scene nodes.
  • -geometry-scale <float>: Factor used to scale exported geometries.
  • -fix-geometry-orientation: Bake a 90° rotation on the X axis of exported geometries.
  • -max_smoothing_angle <float>: Maximum smoothing angle between two faces when computing vertex normals.
  • -recalculate-normal: Recreate the vertex normals of exported geometries.
  • -recalculate-tangent: Recreate the vertex tangent frames of exported geometries.
  • -calculate-normal-if-missing: Compute missing vertex normals.
  • -calculate-tangent-if-missing: Compute missing vertex tangents
  • -detect-geometry-instances: Detect and optimize geometry instances.

Toolchain integration

  • -finalizer-script: Path to the Lua finalizer script.


  • -h,-help: Display help message.

A word on scale

When working with assets from different sources it is not uncommon to encounter considerable scale differences for similar objects. To compensate for this the importer can adjust both the scene scale and the geometry scale. As a rule of thumb, even if the imported scene looks on scale, you should make sure that the geometry itself uses a correct scale.

Failing to do so will pose many problems for example when sharing animations between models.

Finalizer script

After processing a resource the converter can call a Lua script to finalize it before it is saved to disk. The following script demonstrate all the available hooks.

-- Finalizer script example for the FBX converter.

function FinalizeMaterial(mat, name, geo_name)
    print("Finalizer called for material "" in geometry "..geo_name)

function FinalizeGeometry(geo, name)
    print("Finalizer called for geometry "

function FinalizeNode(node)
    print("Finalizer called for node "..node:GetName())

function FinalizeScene(scene)
    print("Finalizer called for scene")

Return code

The executable returns 1 if no error occurred, 0 otherwise. To notify the caller about the conversion result the converter sends special markers to the standard output:

  • [TestImport: OK] if the import test went well.
  • [TestImport: KO] if the import test failed.
  • [ImportScene: OK] if the import succeeded.
  • [ImportScene: KO] if the import failed.


Import scene.fbx to ./export, overwrite existing geometry, skip everything else if it exists:

fbx-convert scene.fbx -o export -texture-policy overwrite

Import scene.fbx to ./export, only import scene, skip everything else:

fbx-convert scene.fbx -o export -material-policy skip_always -geometry-policy skip_always -texture-policy skip_always

Import scene.fbx to ./export. The ./export folder will be mounted as @assets at runtime and the scene loaded through that mount point (see The file system).

fbx-convert scene.fbx -o export -base-resource-path . -prefix @assets

Autodesk FBX SDK Notice

This software contains Autodesk® FBX® code developed by Autodesk, Inc. Copyright 2014 Autodesk, Inc. All rights, reserved.

Such code is provided "as is" and Autodesk, Inc. disclaims any and all warranties, whether express or implied, including without limitation the implied warranties of merchantability, fitness for a particular purpose or non-infringement of third party rights. In no event shall Autodesk, Inc. be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of such code.

  1. The following policies are available: skip, overwrite, rename and skip_always. The default policy is skip