Bevy FBX

A Bevy plugin for loading FBX files using the ufbx library.

Features

✅ Mesh Loading: Load 3D meshes with vertices, normals, UVs, and indices
✅ Material Support: Enhanced PBR material loading with texture application
✅ Texture Application: Automatic application of textures to StandardMaterial
- Base color (diffuse) textures
- Normal maps
- Metallic/roughness textures
- Emission textures
- Ambient occlusion textures
✅ Skinning Data: Complete skinning support with joint weights and inverse bind matrices
✅ Node Hierarchy: Basic scene graph support
⚠️ Animations: Framework in place, temporarily disabled due to ufbx API compatibility

Usage

Enable the Feature

FBX support is an optional feature in Bevy. Add it to your Cargo.toml:

[dependencies]
bevy = { version = "0.16", features = ["fbx"] }

Loading FBX Files

use bevy::prelude::*;
use bevy::fbx::FbxAssetLabel;

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    // Load an FBX file
    let fbx_handle: Handle<bevy::fbx::Fbx> = asset_server.load("models/my_model.fbx");

    // Spawn the FBX scene
    commands.spawn(SceneRoot(fbx_handle));
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .run();
}

Accessing Individual Assets

use bevy::fbx::{Fbx, FbxAssetLabel};

fn access_fbx_assets(
    fbx_assets: Res<Assets<Fbx>>,
    fbx_handle: Handle<Fbx>,
) {
    if let Some(fbx) = fbx_assets.get(&fbx_handle) {
        // Access meshes
        for mesh_handle in &fbx.meshes {
            println!("Found mesh: {:?}", mesh_handle);
        }

        // Access materials
        for material_handle in &fbx.materials {
            println!("Found material: {:?}", material_handle);
        }

        // Access skins (for skeletal animation)
        for skin_handle in &fbx.skins {
            println!("Found skin: {:?}", skin_handle);
        }

        // Access animation clips
        for animation_handle in &fbx.animation_clips {
            println!("Found animation: {:?}", animation_handle);
        }
    }
}

Asset Labels

You can load specific parts of an FBX file using asset labels:

// Load a specific mesh by index
let mesh: Handle<Mesh> = asset_server.load("model.fbx#Mesh0");

// Load a specific material by index
let material: Handle<StandardMaterial> = asset_server.load("model.fbx#Material0");

// Load a specific skin by index
let skin: Handle<bevy::fbx::FbxSkin> = asset_server.load("model.fbx#Skin0");

// Load a specific animation by index
let animation: Handle<AnimationClip> = asset_server.load("model.fbx#Animation0");

Supported FBX Features

Geometry: Triangulated meshes with positions, normals, UVs
Materials: Enhanced PBR properties with automatic texture application
- Base color, metallic, roughness, emission values
- Automatic extraction from FBX material properties
Textures: Complete texture support with automatic application to StandardMaterial
- Base color (diffuse) textures → base_color_texture
- Normal maps → normal_map_texture
- Metallic textures → metallic_roughness_texture
- Roughness textures → metallic_roughness_texture
- Emission textures → emissive_texture
- Ambient occlusion textures → occlusion_texture
Skinning: Joint weights, indices, and inverse bind matrices
Hierarchy: Node transforms and basic parent-child relationships

Limitations

Animations: Framework in place but temporarily disabled due to ufbx API compatibility
Complex Materials: Advanced material features beyond PBR are not supported
FBX-Specific Features: Some proprietary FBX features may not be available
Performance: Large files may have performance implications during loading
Texture Formats: Only common image formats supported by Bevy are loaded

Examples

See examples/3d/load_fbx.rs for a complete example of loading and displaying FBX files.

Technical Details

This plugin uses the ufbx library, which provides:

Fast and reliable FBX parsing
Support for FBX versions 6.0 and later
Memory-safe C API with Rust bindings
Comprehensive geometry and animation support

The plugin follows Bevy's asset loading patterns and integrates seamlessly with the existing rendering pipeline.

4.4 KiB Raw Blame History