Crate bevy::gltf

Plugin providing an AssetLoader and type definitions for loading glTF 2.0 (a standard 3D scene definition format) files in Bevy.

The glTF 2.0 specification defines the format of the glTF files.

Quick Start

Here’s how to spawn a simple glTF scene

fn spawn_gltf(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(SceneBundle {
        // This is equivalent to "models/FlightHelmet/FlightHelmet.gltf#Scene0"
        // The `#Scene0` label here is very important because it tells bevy to load the first scene in the glTF file.
        // If this isn't specified bevy doesn't know which part of the glTF file to load.
        scene: asset_server.load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf")),
        // You can use the transform to give it a position
        transform: Transform::from_xyz(2.0, 0.0, -5.0),
        ..Default::default()
    });
}

Loading parts of a glTF asset

Using Gltf

If you want to access part of the asset, you can load the entire Gltf using the AssetServer. Once the Handle<Gltf> is loaded you can then use it to access named parts of it.

// Holds the scene handle
#[derive(Resource)]
struct HelmetScene(Handle<Gltf>);

fn load_gltf(mut commands: Commands, asset_server: Res<AssetServer>) {
    let gltf = asset_server.load("models/FlightHelmet/FlightHelmet.gltf");
    commands.insert_resource(HelmetScene(gltf));
}

fn spawn_gltf_objects(
    mut commands: Commands,
    helmet_scene: Res<HelmetScene>,
    gltf_assets: Res<Assets<Gltf>>,
    mut loaded: Local<bool>,
) {
    // Only do this once
    if *loaded {
        return;
    }
    // Wait until the scene is loaded
    let Some(gltf) = gltf_assets.get(&helmet_scene.0) else {
        return;
    };
    *loaded = true;

    commands.spawn(SceneBundle {
        // Gets the first scene in the file
        scene: gltf.scenes[0].clone(),
        ..Default::default()
    });

    commands.spawn(SceneBundle {
        // Gets the scene named "Lenses_low"
        scene: gltf.named_scenes["Lenses_low"].clone(),
        transform: Transform::from_xyz(1.0, 2.0, 3.0),
        ..Default::default()
    });
}

Asset Labels

The glTF loader let’s you specify labels that let you target specific parts of the glTF.

Be careful when using this feature, if you misspell a label it will simply ignore it without warning.

You can use GltfAssetLabel to ensure you are using the correct label.

Modules

• prelude
  The bevy_gltf prelude.

Structs

• Gltf
  Representation of a loaded glTF file.
• GltfExtras
  Additional untyped data that can be present on most glTF types at the primitive level.
• GltfLoader
  Loads glTF files with all of their data as their corresponding bevy representations.
• GltfLoaderSettings
  Specifies optional settings for processing gltfs at load time. By default, all recognized contents of the gltf will be loaded.
• GltfMaterialExtras
  Additional untyped data that can be present on most glTF types at the material level.
• GltfMesh
  A glTF mesh, which may consist of multiple GltfPrimitives and an optional GltfExtras.
• GltfMeshExtras
  Additional untyped data that can be present on most glTF types at the mesh level.
• GltfNode
  A glTF node with all of its child nodes, its GltfMesh, Transform and an optional GltfExtras.
• GltfPlugin
  Adds support for glTF file loading to the app.
• GltfPrimitive
  Part of a GltfMesh that consists of a Mesh, an optional StandardMaterial and GltfExtras.
• GltfSceneExtras
  Additional untyped data that can be present on most glTF types at the scene level.

Enums

• GltfAssetLabel
  Labels that can be used to load part of a glTF
• GltfError
  An error that occurs when loading a glTF file.