113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
# bevy_ufbx
|
|
|
|
FBX asset loader for [Bevy](https://bevyengine.org) powered by [ufbx](https://github.com/ufbx/ufbx).
|
|
|
|
## Bevy compatibility
|
|
|
|
| bevy | bevy_ufbx |
|
|
|------|-----------|
|
|
| 0.18 | 0.18 |
|
|
| 0.17 | 0.17 |
|
|
|
|
## Installation
|
|
|
|
```toml
|
|
[dependencies]
|
|
bevy = "0.18"
|
|
bevy_ufbx = "0.18"
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```rust
|
|
use bevy::prelude::*;
|
|
use bevy_ufbx::FbxPlugin;
|
|
|
|
fn main() {
|
|
App::new()
|
|
.add_plugins(DefaultPlugins)
|
|
.add_plugins(FbxPlugin)
|
|
.add_systems(Startup, setup)
|
|
.run();
|
|
}
|
|
|
|
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
|
|
commands.spawn(Camera3d::default());
|
|
commands.spawn(SceneRoot(
|
|
asset_server.load("character.fbx#Scene0"),
|
|
));
|
|
}
|
|
```
|
|
|
|
## Loading with custom settings
|
|
|
|
```rust
|
|
use bevy_ufbx::{Fbx, FbxLoaderSettings};
|
|
|
|
fn setup(asset_server: Res<AssetServer>) {
|
|
asset_server.load_with_settings::<Fbx, FbxLoaderSettings>(
|
|
"environment.fbx",
|
|
|s| {
|
|
s.load_cameras = false;
|
|
s.load_lights = false;
|
|
},
|
|
);
|
|
}
|
|
```
|
|
|
|
### `FbxLoaderSettings` fields
|
|
|
|
| Field | Type | Default | Description |
|
|
|----------------------|----------------------|-------------------------------|---------------------------------------------|
|
|
| `load_meshes` | `RenderAssetUsages` | `RenderAssetUsages::default()` | Which worlds the mesh is available in |
|
|
| `load_materials` | `RenderAssetUsages` | `RenderAssetUsages::default()` | Which worlds the material is available in |
|
|
| `load_cameras` | `bool` | `true` | Import cameras from the FBX |
|
|
| `load_lights` | `bool` | `true` | Import lights from the FBX |
|
|
| `include_source` | `bool` | `false` | Keep raw bytes in the loaded asset |
|
|
| `convert_coordinates`| `bool` | `false` | Remap axes to Bevy's right-handed Y-up space|
|
|
|
|
## Asset labels
|
|
|
|
Individual sub-assets can be addressed with `#Label` path suffixes:
|
|
|
|
| Label | Type | Description |
|
|
|-------------------|---------------------|-----------------------------------------|
|
|
| `Scene{N}` | `Scene` | Scene hierarchy (N = scene index) |
|
|
| `Mesh{N}` | `Mesh` | Triangulated mesh |
|
|
| `Material{N}` | `StandardMaterial` | PBR material |
|
|
| `Node{N}` | `FbxNode` | Transform node |
|
|
| `Skin{N}` | `FbxSkin` | Skeletal skin |
|
|
| `DefaultMaterial` | `StandardMaterial` | Fallback material when none is present |
|
|
|
|
```rust
|
|
let scene = asset_server.load::<Scene>("model.fbx#Scene0");
|
|
let mesh = asset_server.load::<Mesh>("model.fbx#Mesh0");
|
|
let material = asset_server.load::<StandardMaterial>("model.fbx#Material0");
|
|
```
|
|
|
|
## Supported features
|
|
|
|
- Triangle meshes with positions, normals, and UVs
|
|
- Multi-material meshes (face groups per material)
|
|
- PBR materials (base color, metallic, roughness, normal, emission, AO)
|
|
- Texture mapping, including `.fbm` embedded texture folders
|
|
- Skeletal skinning data (bone weights / bind poses)
|
|
- Scene hierarchy (node transforms)
|
|
- Directional, point, and spot lights
|
|
|
|
## Limitations
|
|
|
|
- Animation curves are parsed but **not yet forwarded to Bevy's animation system**
|
|
- Cameras are not imported into Bevy camera components
|
|
- NURBS and subdivision surfaces are not supported (ufbx triangulates on load)
|
|
|
|
## Example
|
|
|
|
```sh
|
|
cargo run --example load_fbx -- my_model.fbx
|
|
```
|
|
|
|
## License
|
|
|
|
Licensed under either of [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE) at your option.
|