Skip to content

cocos/FBX-glTF-conv

Folders and files

NameName
Last commit message
Last commit date

Latest commit

8d2c454 Β· Nov 28, 2024
Nov 28, 2024
Nov 28, 2024
Nov 28, 2024
Nov 28, 2024
Sep 11, 2020
Dec 4, 2020
Nov 28, 2024
May 14, 2022
Nov 28, 2024
Dec 17, 2020
Nov 28, 2024
Feb 20, 2022
Nov 26, 2024

Repository files navigation

This branch is based on release-v1.0.0-alpha.49 which is the latest version used in cocos creator.

FBX-glTF-conv

This is a FBX to glTF file format converter.

Prerequisites

This project has been tested on:

  • Windows

  • macOS 10.13 or later

  • Ubuntu 22.04

    Ubuntu 20.04 is not supported.

How to use

You can find the latest release in releases page.

To convert, run the executable at command line:

> FBX-glTF-conv <source-FBX-file> --out <output-glTF-file>

There are some options, run the executable without any arguments:

> FBX-glTF-conv

This is a FBX to glTF file format converter.
Usage:
  FBX-glTF-conv [OPTION...] positional parameters

      --fbm-dir arg             The directory to store the embedded media.
      --out arg                 The output path to the .gltf or .glb file.
                                Defaults to
                                `<working-directory>/<FBX-filename-basename>
                                .gltf`
      --no-flip-v               Do not flip V texture coordinates.
      --unit-conversion arg     How to perform unit converseion.
                                  - `geometry-level` Do unit conversion at
                                geometry level.
                                  - `hierarchy-level` Do unit conversion at
                                hierarchy level.
                                  - `disabled` Disable unit conversion.
                                This may cause the generated glTF does't
                                conform to glTF specification. (default:
                                geometry-level)
      --no-texture-resolution   Do not resolve textures.
      --prefer-local-time-span  Prefer local time spans recorded in FBX
                                file for animation exporting. (default:
                                true)
      --animation-bake-rate arg
                                Animation bake rate(in FPS). (default: 30)
      --texture-search-locations arg
                                Texture search locations. These path shall
                                be absolute path or relative path from
                                input file's directory.
      --export-fbx-file-header-info
                                Export FBX file header info.
      --export-raw-materials    Export raw materials.
      --verbose                 Verbose output.
      --log-file arg            Specify the log file(logs are outputed as
                                JSON). If not specified, logs're printed to
                                console
      --image-path-mode arg     Specify the mode used to specify the image
                                path. Could be one of the following:
                                - absolute - Output the absolute path to
                                the path.
                                - relative - Output the relative path to
                                the path.
                                - prefer-relative - If the image is under
                                the the same or sub directory of glTF file,
                                output as relative. Otherwise output as
                                absolute.
                                - strip - Ingore all path information, only
                                output the file name.
                                - embedded - Embedded the image into Data
                                URI.
                                - copy - Copy the image to the output
                                directory and reference it with a relative
                                path.

Build

To build this tool, the followings are required:

This is a CMake project, just build it in normal CMake build process. However you need to indicate the FBXSDK's location and vcpkg toolchain file:

> cmake -DCMAKE_TOOLCHAIN_FILE="<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake" -DFbxSdkHome:STRING="<path-to-FBX-SDK-home>"

If problems encountered, you may file an issue or reference to the CI build script.

Why

This tool is essentially used as a part of the Cocos Creator. In former, Cocos Creator supports FBX file format through the excellent FBX2glTF.

But Cocos team has to find another approach because:

  • FBX2glTF store the glTF result files onto disk and Creator read the files. This is the only way that Creator can communicate with FBX2glTF. File system I/O is slow.
  • Author of FBX2glTF is tired.
  • FBX is complex and all exporters working for it are buggy. We usually need to fix strange issues. It's hard to sync fixes between Cocos and Facebook.

Features

  • πŸ—Έ Geometries

    • πŸ—Έ Meshes
  • πŸ—Έ Materials

    • πŸ—Έ Lambert and Phong
  • πŸ—Έ Textures and images

    • πŸ—Έ Image formats: JPEG, PNG
  • πŸ—Έ Skinning

    • βŒ› Cluster mode: additive
  • πŸ—Έ Blend shapes(Morph targets)

  • πŸ—Έ Animations

    • πŸ—Έ Node transform animations(Skeletal animations)

    • πŸ—Έ Blend shape animations(Morph animations)

  • πŸ—Έ Scene hierarchy

    • βŒ› FBX specific node inherit types: RrSs, Rrs
  • βŒ› Cameras

  • βŒ› Lights

πŸ—Έ Supported βŒ› Not finished

Thanks

Again, the FBX is complex and specification-less. In development, we often reference from or are inspired from the following predecessors: