FBX to VRMA Converter

🧠 TPMJS Tool Registry & AI Agent Use

This package is discoverable and usable by AI agents and tool runners via the TPMJS Tool Registry. To use in AI workflows, simply install from npm and invoke the CLI or import as a Node.js module. For more, see tpmjs.com.

To publish as a TPMJS tool:

• Ensure the tpmjs-tool keyword is in your package.json (already included)
• Publish to npm: npm publish
• Your tool will appear on tpmjs.com within 15 minutes

For best AI compatibility, keep your CLI and API usage clear and documented. See TPMJS publishing guide for more info.

Convert FBX animation files to VRMA (VRM Animation) format for use with VRM models in web applications.

English README | 日本語 README

🎯 Features

• 🎬 FBX to VRMA Conversion: Convert FBX animations to VRMA format
• 🎭 Mixamo Support: Automatic bone mapping for Mixamo animations
• 🔧 Embedded Buffers: No external dependencies required
• ✅ VRM Compatible: Full compatibility with @pixiv/three-vrm-animation
• 🧪 Validation Tools: Built-in validation and testing

🚀 Quick Start

Prerequisites

• Node.js 18+
• macOS, Windows, or Linux
• FBX2glTF binary (see installation below)

Installation

1. Clone the Repository

git clone https://github.com/tk256ailab/fbx2vrma-converter.git
cd fbx2vrma-converter
npm install
./setup.sh  # Download FBX2glTF binary

2. Download FBX2glTF Binary

Method 1: Automatic Setup (Recommended)

Run the setup script to automatically download the correct binary for your platform:

# macOS/Linux
./setup.sh

# Windows (Command Prompt)
setup.bat

# Windows (PowerShell)
.\setup.bat

Method 2: Manual Download

If the setup script fails, manually download the binary:

1. Go to FBX2glTF Releases
2. Click on the latest release (v0.9.7)
3. Download the appropriate binary:
   • macOS: FBX2glTF-darwin-x64
   • Windows: FBX2glTF-windows-x64.exe
   • Linux: FBX2glTF-linux-x64
4. Place the binary in your project directory
5. Make it executable (macOS/Linux): chmod +x FBX2glTF-darwin-x64

3. Verify Installation

# Test the binary works
./FBX2glTF-darwin-x64 --help   # macOS
./FBX2glTF-windows-x64.exe --help   # Windows
./FBX2glTF-linux-x64 --help    # Linux

Basic Usage

# Convert an FBX file to VRMA
node fbx2vrma-converter.js -i input.fbx -o output.vrma

# With custom framerate
node fbx2vrma-converter.js -i input.fbx -o output.vrma --framerate 60

Example

# Convert Mixamo animation
node fbx2vrma-converter.js -i examples/SittingLaughing.fbx -o SittingLaughing.vrma

📋 Command Line Options

Options:
  -i, --input <path>      Input FBX file path (required)
  -o, --output <path>     Output VRMA file path (required)
  --fbx2gltf <path>       Path to FBX2glTF binary (default: ./FBX2glTF-darwin-x64)
  --framerate <fps>       Animation framerate (default: 30)
  -h, --help              Display help information
  -V, --version           Display version number

Note: Make sure to specify the correct FBX2glTF binary path for your platform:

• macOS: --fbx2gltf ./FBX2glTF-darwin-x64
• Windows: --fbx2gltf ./FBX2glTF-windows-x64.exe
• Linux: --fbx2gltf ./FBX2glTF-linux-x64

🎭 How It Works

1. FBX Conversion: Uses FBX2glTF to convert FBX to glTF format
2. Animation Enhancement: Analyzes and improves animation timing data
3. Buffer Embedding: Embeds binary data to create self-contained files
4. VRMA Generation: Converts to VRMA format with proper VRM extensions
5. Bone Mapping: Maps Mixamo bones to VRM humanoid specification

🔧 Technical Details

Supported Bone Mapping

The converter automatically maps Mixamo bone names to VRM humanoid bones:

• mixamorig:Hips → hips
• mixamorig:Spine → spine
• mixamorig:Spine1 → chest
• mixamorig:Spine2 → upperChest
• mixamorig:Neck → neck
• mixamorig:Head → head
• And many more...

VRMA Format

The generated VRMA files include:

• VRMC_vrm_animation extension v1.0
• Embedded binary buffers
• Proper animation timing metadata
• Humanoid bone mappings

🧪 Testing

The converted VRMA files are compatible with:

• @pixiv/three-vrm-animation v3.4.1+
• Three.js r177+
• Modern web browsers

📁 Project Structure

fbx2vrma/
├── fbx2vrma-converter.js    # Main converter script
├── README.md                # This file
├── README-jp.md            # Japanese documentation
├── package.json            # Node.js dependencies
├── LICENSE                 # MIT License
└── .gitignore             # Git ignore rules

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FBX2glTF - FBX to glTF conversion
• @pixiv/three-vrm - VRM support for Three.js
• Mixamo - Animation source

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include sample files if possible

Mainly created using Claude Code