FFL.js

JavaScript bindings to use FFL, the Wii U Mii renderer decompilation, in Three.js.

Features

• Full rendering of Mii heads using the Wii U (FFLShaderMaterial) and Miitomo (LUTShaderMaterial) shaders.
• Implemented in JSDoc annotated JavaScript directly calling into the FFL library.
• Supports importing 3DS/Wii U Mii Data (FFLStoreData), Mii Studio data, and exporting FFLStoreData.
• Supported FFL features: Expressions, mipmaps, bounding box, partsTransform and model flags for headwear, FFLiVerifyReason, (head only) icon creation
• Tested with Three.js r109 up to r173 (Both included shaders work exclusively in sRGB)

There are currently two demos: demo-basic.html and demo-minimal.html, both of which are pretty underwhelming. Read TODOs further down for more plaannnnnsssss

Usage

This section is TBD because the library needs to be modularized - it's only made to work with browsers in global scope for now.

I recommend just looking at the demos to see how they call the library. For more help you can either look at the code, or, generate documentation with TypeDoc, install it and run: typedoc ffl.js

Building ffl-emscripten.js/.wasm

This library depends on FFL built for Emscripten (in WASM). NOTE that this is already included in the repository as of writing, but you may either need to rebuild it, or I may remove it at some point.

0. You will need to make sure emsdk is installed and you can build binaries with Emscripten. This is mostly left as an exercise to the reader, but don't forget to activate your emsdk environment before continuing.

1. Pull FFL and its dependencies. For simplicity, you can actually just pull FFL-Testing (active branch) which has the dependencies.

git clone -b renderer-server-prototype --recursive https://github.com/ariankordi/FFL-Testing

2. Recurse into ffl within FFL-Testing.

cd FFL-Testing/ffl

3. Build using CMake with Emscripten.

Note that the argument to -DCMAKE_TOOLCHAIN_FILE= has to be within your emsdk directory, so please change that in the command below:

cmake -S . -B build-em -DCMAKE_TOOLCHAIN_FILE=/path/to/emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -DFFL_WITH_RIO=../rio/ -DCMAKE_BUILD_TYPE=Release
 # Remember to find and fill in emsdk path:   ^^^^^^^^^
cmake --build build

(You may want to use -DFFL_NO_NINTEXUTILS=ON if you don't have it or want a smaller build but you will not be able to use resource (.dat) files for Wii U)

4. If that worked, find and copy the library.

• It should be sitting in build-em (or whatever folder you chose) as:
  • ffl-emscripten.js, ffl-emscripten.wasm
  • To build JS only you can use -DFFL_BUILD_WASM=OFF, which may be more convenient/compatible at 2x the size of the wasm binary.
  • Finally, if you want to pass other options to emcc, use -DCMAKE_EXE_LINKER_FLAGS="-s SINGLE_FILE=1", for example.

5. Finally, in order to use the library, you'll need an FFL resource such as FFLResHigh.dat, AFLResHigh_2_3.dat, etc.

• See the ffl or FFL-Testing repo to know how to acquire this.
• Currently the demos hardcode the location of the resource in meta#ffl-js-resource-fetch-path so you will need to change that. For now.

If you run into issues with dependencies here, see the FFL-Testing repo.

ESLint

The only reason this has package.json at the time of writing is for eslint, npm install and run: eslint

TODO

The big one is that the library needs to be modularized.

• End use of globals, pass instances around:
  • window.Module (Emscripten module)
    • Support async/promise Emscripten module (-s MODULARIZE=1)
  • window.FFLTextures (TextureManager)
  • _resourceDesc (FFLResourceDesc, currently allocated resource pointers)
  • Potential settings:
    • Debug options _noCharModelCleanupDebug, _displayRenderTexturesElement
    • Color space (FFLSetLinearGammaMode), scale (FFLSetScale), coordinate mode (FFLSetCoordinateMode)
• Export public functions, use UMD for now (Depends on above)

Improvements

• Throw errors with more specificity (See FFLSharp's approach for details)
  • Include reverse enum to string tables for FFLResult, FFLiVerifyReason
• Can someone harshly criticize my code? Style, naming conventions, ease of use and import, low quality sections...?
• (Eliminate all memory leaks? Most should be gone now tho. Strip console.debug?)

Wishlist

• Need more demos: body model, CharInfo editing, mass icons
• Refactor: Split code into files, export as ESM module, refactor to TypeScript(???)
• Resolve JSDoc formatting inconsistencies? (param order, add space after description?, line breaking, etc.)
• Port shaders to TSL and use NodeMaterial for WebGPURenderer support?????

Acknowledgements

• aboood40091/AboodXD for the FFL decompilation and port to RIO.
• Nathan Vander Wilt for struct-fu (this is using a fork).
• Mister F*cking Doob himself for Three.js.
• Nintendo for making FFL.