NEOLearn

glTF

Load glTF 2.0 models (.gltf and .glb) as scenes or as separate meshes, materials and animations, change them after they spawn, and read their names and extras.

Updated October 20, 2026

On this page

glTF 2.0 is the engine's 3D model format. A .gltf file (JSON with separate buffers and images) or .glb file (one binary file) can hold meshes, materials, textures, a node hierarchy, skins, cameras, lights and animations. NEO's own characters and props are glTF.

Spawn a model#

Load a scene from the file and add it to an entity with WorldAssetRoot:

src/main.rs
use neo::prelude::*;

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

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        WorldAssetRoot(asset_server.load(
            GltfAssetLabel::Scene(0).from_asset("models/helmet/FlightHelmet.gltf"),
        )),
        Transform::from_xyz(0.0, 0.0, -2.0),
    ));
    commands.spawn((
        DirectionalLight::default(),
        Transform::from_xyz(1.0, 2.0, 1.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.7, 0.7, 1.0).looking_at(Vec3::new(0.0, 0.3, -2.0), Vec3::Y),
    ));
}

The scene's nodes are spawned as children of that entity, with their transforms, meshes and materials. Move, hide or despawn the root entity to move, hide or despawn the whole model.

Example: cargo run --example load_gltf, from the engine core's workspace (the folder of the engine source that holds the neo crate's Cargo.toml).

Labels#

GltfAssetLabel names each part of a file. .from_asset(path) turns it into an asset path such as "model.glb#Scene0".

LabelString formLoads
Scene(i)Scene0A WorldAsset: the scene's whole node tree.
Node(i)Node0A GltfNode.
Mesh(i)Mesh0A GltfMesh, with all its primitives.
Primitive { mesh, primitive }Mesh0/Primitive0One primitive as a Mesh.
Material { index, is_scale_inverted }Material0A StandardMaterial.
DefaultMaterialDefaultMaterialThe material for primitives without one.
Texture(i)Texture0An Image.
Animation(i)Animation0An AnimationClip.
Skin(i)Skin0A GltfSkin.
InverseBindMatrices(i)InverseBindMatrices0A skin's inverse bind matrices.

A misspelt label never loads and reports nothing, so prefer GltfAssetLabel to strings.

The whole file: Gltf#

Load the file without a label to get a Gltf asset, which holds handles to every part, by index and by name:

Rust
use neo::gltf::Gltf;

#[derive(Resource)]
struct Helmet(Handle<Gltf>);

fn spawn_parts(
    mut commands: Commands,
    helmet: Res<Helmet>,
    gltfs: Res<Assets<Gltf>>,
    mut done: Local<bool>,
) {
    if *done {
        return;
    }
    let Some(gltf) = gltfs.get(&helmet.0) else { return };
    *done = true;
    commands.spawn(WorldAssetRoot(gltf.scenes[0].clone()));
    commands.spawn((
        WorldAssetRoot(gltf.named_scenes["Lenses_low"].clone()),
        Transform::from_xyz(1.0, 2.0, 3.0),
    ));
}

Gltf has scenes, meshes, materials, nodes, skins and animations, a named_* map for each, and default_scene.

Change a model after it spawns#

When a scene has finished spawning, its root entity gets a WorldInstanceReady event. Observe it to change the spawned entities, for example to swap a material:

Rust
use neo::{gltf::GltfMaterialName, world_serialization::WorldInstanceReady};

fn tint_leather(
    ready: On<WorldInstanceReady>,
    mut commands: Commands,
    children: Query<&Children>,
    parts: Query<(&MeshMaterial3d<StandardMaterial>, &GltfMaterialName)>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    for entity in children.iter_descendants(ready.entity) {
        let Ok((material, name)) = parts.get(entity) else { continue };
        if name.0 != "LeatherPartsMat" {
            continue;
        }
        let Some(original) = materials.get(material.id()) else { continue };
        let mut tinted = original.clone();
        tinted.base_color = Color::srgb(0.9, 0.3, 0.3);
        commands.entity(entity).insert(MeshMaterial3d(materials.add(tinted)));
    }
}

// app.add_observer(tint_leather);

The spawned entities carry what the file said about them:

ComponentWhat it holds
NameThe node's name, or a name made from the mesh and material for primitive entities.
GltfMeshName, GltfMaterialName, GltfSceneNameThe mesh, material and scene names.
GltfExtras, GltfMeshExtras, GltfMaterialExtras, GltfSceneExtrasThe glTF extras JSON, as a string in value. Use them to carry game data from your modelling tool.

Examples: cargo run --example edit_material_on_gltf, cargo run --example update_gltf_scene, cargo run --example load_gltf_extras, cargo run --example query_gltf_primitives.

Loader settings#

GltfLoaderSettings chooses what the loader keeps. Pass it with load_builder().with_settings(...):

FieldWhat it does
load_meshes, load_materialsRenderAssetUsages: keep the data on the GPU, in Assets<T> for your code, or both.
load_cameras, load_lights, load_animationsWhether to spawn the file's cameras and lights, and load its animations.
include_sourceKeep the parsed glTF document in Gltf::source.
default_sampler, override_samplerThe texture sampler to use.
convert_coordinatesRotate scenes or nodes so the file's forward matches the engine's.

GltfPlugin holds the app-wide defaults, and GltfPlugin::default().add_custom_vertex_attribute("_BARYCENTRIC", attribute) maps a custom glTF vertex attribute to a MeshVertexAttribute. Example: cargo run --example custom_gltf_vertex_attribute.

Textures and extensions#

Supported Khronos extensions include KHR_lights_punctual, KHR_materials_emissive_strength, KHR_materials_ior, KHR_materials_unlit, KHR_materials_volume and KHR_texture_transform (on the base colour texture only). KHR_materials_transmission, KHR_materials_specular, KHR_materials_clearcoat and KHR_materials_anisotropy need the matching pbr_*_textures feature, which NEO's builds don't turn on. Draco and meshopt compression, KHR_mesh_quantization, GPU instancing, sheen, iridescence and material variants aren't supported.

For your own extensions, the loader calls registered GltfExtensionHandlers while it reads a file. Examples: cargo run --example gltf_extension_animation_graph, cargo run --example gltf_extension_mesh_2d.

Animations and skins#

Skinned meshes load with their joints, and each animation loads as an AnimationClip you play with an AnimationPlayer. See glTF animation. Example: cargo run --example gltf_skinned_mesh.

Next steps#