bevyengine/bevy

bevy_gltf

glTF 2.0 loader. Loads meshes, materials, textures, animations, skinned skeletons, lights, cameras, and node hierarchies from .gltf and .glb files.

Purpose

glTF is the canonical interchange format for 3D content in the Bevy ecosystem. The Blender exporter, every modeling tool, and most third-party Bevy assets target it. bevy_gltf provides the asset loader plus types that surface glTF's structure to user code.

Directory layout

crates/bevy_gltf/src/
├── lib.rs           # GltfPlugin
├── loader/          # The actual loader
├── assets.rs        # Gltf, GltfNode, GltfMesh, GltfMaterialName, GltfPrimitive, GltfScene assets
├── label.rs         # Asset path labels (Mesh0, Material0, etc.)
├── vertex_attributes.rs  # Maps glTF attributes to bevy_mesh attributes
└── …

Key abstractions

Type	File	Description
`GltfPlugin`	`crates/bevy_gltf/src/lib.rs`	Registers loaders for `.gltf` / `.glb`.
`Gltf`	`crates/bevy_gltf/src/assets.rs`	Top-level asset; collections of scenes, meshes, materials, animations, etc.
`GltfScene`, `GltfNode`, `GltfMesh`, `GltfMaterialName`	`crates/bevy_gltf/src/assets.rs`	Sub-asset types for finer-grained loading.
`GltfAssetLabel`	`crates/bevy_gltf/src/label.rs`	Sub-asset path labels (e.g. `"models/foo.gltf#Mesh0/Primitive0"`).

How it works

graph LR
    File[.gltf or .glb] --> Loader[gltf::Gltf::open]
    Loader --> Buffers[Decode buffers]
    Buffers --> Meshes[Build bevy_mesh::Mesh per primitive]
    Buffers --> Textures[Decode + upload via bevy_image]
    Buffers --> Materials[Build StandardMaterial via bevy_pbr]
    Buffers --> Anims[Build AnimationClip via bevy_animation]
    Buffers --> Scene[Build Scene via bevy_scene]

The loader uses the gltf crate to parse the file, then maps each glTF concept onto Bevy types:

glTF mesh primitives → bevy_mesh::Mesh with proper attribute layouts (positions, normals, tangents, UVs, joints, weights, colors).
glTF materials → StandardMaterial from bevy_pbr.
glTF textures → Image from bevy_image, with proper sRGB / linear handling.
glTF nodes → entities with Transform and Parent/Children relationships.
glTF skinned animations → bevy_animation::AnimationClip.
glTF lights (KHR_lights_punctual) → PointLight/SpotLight/DirectionalLight from bevy_light.
glTF cameras → Camera + Projection from bevy_camera.

Loading produces a Gltf asset whose top-level Scene you typically spawn into the world via SceneRoot.

Integration points

Depends on: gltf, bevy_asset, bevy_scene, bevy_mesh, bevy_image, bevy_pbr, bevy_animation, bevy_camera, bevy_light, bevy_color, bevy_render (optional, behind bevy_render feature).
Depended on by: Most user apps loading 3D content.

Entry points for modification

Add support for a glTF extension: the loader pattern-matches on extension presence. Look for KHR_* strings in loader/.
Custom material from a glTF property: if StandardMaterial doesn't fit, the loader supports overriding the material type via GltfMaterialBuilder.
Vertex attribute mapping: vertex_attributes.rs is where attribute names become mesh attributes.