140 lines
4.4 KiB
Markdown
140 lines
4.4 KiB
Markdown
# Bevy FBX
|
|
|
|
A Bevy plugin for loading FBX files using the [ufbx](https://github.com/ufbx/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`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
bevy = { version = "0.16", features = ["fbx"] }
|
|
```
|
|
|
|
### Loading FBX Files
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
// 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](https://github.com/ufbx/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.
|