glTF labels: add enum to avoid misspelling and keep up-to-date list documented

crates/bevy_gltf/src/lib.rs

@@ -22,9 +22,10 @@
 //!
 //! 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("models/FlightHelmet/FlightHelmet.gltf#Scene0"),
+//! 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()
@@ -91,18 +92,7 @@
 //!
 //! Be careful when using this feature, if you misspell a label it will simply ignore it without warning.
 //!
-//! Here's the list of supported labels (`{}` is the index in the file):
-//!
-//! - `Scene{}`: glTF Scene as a Bevy `Scene`
-//! - `Node{}`: glTF Node as a `GltfNode`
-//! - `Mesh{}`: glTF Mesh as a `GltfMesh`
-//! - `Mesh{}/Primitive{}`: glTF Primitive as a Bevy `Mesh`
-//! - `Mesh{}/Primitive{}/MorphTargets`: Morph target animation data for a glTF Primitive
-//! - `Texture{}`: glTF Texture as a Bevy `Image`
-//! - `Material{}`: glTF Material as a Bevy `StandardMaterial`
-//! - `DefaultMaterial`: as above, if the glTF file contains a default material with no index
-//! - `Animation{}`: glTF Animation as Bevy `AnimationClip`
-//! - `Skin{}`: glTF mesh skin as Bevy `SkinnedMeshInverseBindposes`
+//! You can use [`GltfAssetLabel`] to ensure using the correct label.
 
 #[cfg(feature = "bevy_animation")]
 use bevy_animation::AnimationClip;
@@ -113,7 +103,7 @@ mod vertex_attributes;
 pub use loader::*;
 
 use bevy_app::prelude::*;
-use bevy_asset::{Asset, AssetApp, Handle};
+use bevy_asset::{Asset, AssetApp, AssetPath, Handle};
 use bevy_ecs::{prelude::Component, reflect::ReflectComponent};
 use bevy_pbr::StandardMaterial;
 use bevy_reflect::{Reflect, TypePath};
@@ -124,6 +114,12 @@ use bevy_render::{
 };
 use bevy_scene::Scene;
 
+/// The `bevy_gizmos` prelude.
+pub mod prelude {
+ #[doc(hidden)]
+ pub use crate::{Gltf, GltfAssetLabel, GltfExtras};
+}
+
 /// Adds support for glTF file loading to the app.
 #[derive(Default)]
 pub struct GltfPlugin {
@@ -251,3 +247,90 @@ pub struct GltfExtras {
  /// Content of the extra data.
  pub value: String,
 }
+
+/// Labels that can be used to load part of a glTF
+pub enum GltfAssetLabel {
+ /// `Scene{}`: glTF Scene as a Bevy `Scene`
+ Scene(usize),
+ /// `Node{}`: glTF Node as a `GltfNode`
+ Node(usize),
+ /// `Mesh{}`: glTF Mesh as a `GltfMesh`
+ Mesh(usize),
+ /// `Mesh{}/Primitive{}`: glTF Primitive as a Bevy `Mesh`
+ Primitive {
+ /// Index of the mesh for this primitive
+ mesh: usize,
+ /// Index of this primitive in its parent mesh
+ primitive: usize,
+ },
+ /// `Mesh{}/Primitive{}/MorphTargets`: Morph target animation data for a glTF Primitive
+ MorphTarget {
+ /// Index of the mesh for this primitive
+ mesh: usize,
+ /// Index of this primitive in its parent mesh
+ primitive: usize,
+ },
+ /// `Texture{}`: glTF Texture as a Bevy `Image`
+ Texture(usize),
+ /// `Material{}`: glTF Material as a Bevy `StandardMaterial`
+ Material {
+ /// Index of this material
+ index: usize,
+ /// Used to set the [`Face`](bevy_render::render_resource::Face) of the material, useful if it is used with negative scale
+ is_scale_inverted: bool,
+ },
+ /// `DefaultMaterial`: as above, if the glTF file contains a default material with no index
+ DefaultMaterial,
+ /// `Animation{}`: glTF Animation as Bevy `AnimationClip`
+ Animation(usize),
+ /// `Skin{}`: glTF mesh skin as Bevy `SkinnedMeshInverseBindposes`
+ Skin(usize),
+}
+
+impl std::fmt::Display for GltfAssetLabel {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self {
+ GltfAssetLabel::Scene(index) => f.write_str(&format!("Scene{index}")),
+ GltfAssetLabel::Node(index) => f.write_str(&format!("Node{index}")),
+ GltfAssetLabel::Mesh(index) => f.write_str(&format!("Mesh{index}")),
+ GltfAssetLabel::Primitive { mesh, primitive } => {
+ f.write_str(&format!("Mesh{mesh}/Primitive{primitive}"))
+ }
+ GltfAssetLabel::MorphTarget { mesh, primitive } => {
+ f.write_str(&format!("Mesh{mesh}/Primitive{primitive}/MorphTargets"))
+ }
+ GltfAssetLabel::Texture(index) => f.write_str(&format!("Texture{index}")),
+ GltfAssetLabel::Material {
+ index,
+ is_scale_inverted,
+ } => f.write_str(&format!(
+ "Material{index}{}",
+ if *is_scale_inverted {
+ " (inverted)"
+ } else {
+ ""
+ }
+ )),
+ GltfAssetLabel::DefaultMaterial => f.write_str("DefaultMaterial"),
+ GltfAssetLabel::Animation(index) => f.write_str(&format!("Animation{index}")),
+ GltfAssetLabel::Skin(index) => f.write_str(&format!("Skin{index}")),
+ }
+ }
+}
+
+impl GltfAssetLabel {
+ /// Use this label to load an asset
+ /// ```
+ /// # use bevy_ecs::prelude::*;
+ /// # use bevy_asset::prelude::*;
+ /// # use bevy_scene::prelude::*;
+ /// # use bevy_gltf::prelude::*;
+ ///
+ /// fn load_gltf_scene(asset_server: Res<AssetServer>) {
+ /// let gltf_scene: Handle<Scene> = asset_server.load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf"));
+ /// }
+ /// ```
+ pub fn from_asset(&self, path: impl Into<AssetPath<'static>>) -> AssetPath<'static> {
+ path.into().with_label(self.to_string())
+ }
+}

crates/bevy_gltf/src/loader.rs

@@ -1,3 +1,4 @@
+use crate::GltfAssetLabel;
 use crate::{vertex_attributes::convert_attribute, Gltf, GltfExtras, GltfNode};
 #[cfg(feature = "bevy_animation")]
 use bevy_animation::{AnimationTarget, AnimationTargetId};
@@ -316,8 +317,10 @@ async fn load_gltf<'a, 'b, 'c>(
  );
  }
  }
- let handle = load_context
- .add_labeled_asset(format!("Animation{}", animation.index()), animation_clip);
+ let handle = load_context.add_labeled_asset(
+ GltfAssetLabel::Animation(animation.index()).to_string(),
+ animation_clip,
+ );
  if let Some(name) = animation.name() {
  named_animations.insert(name.into(), handle.clone());
  }
@@ -1415,12 +1418,16 @@ fn load_node(
 
 /// Returns the label for the `mesh`.
 fn mesh_label(mesh: &gltf::Mesh) -> String {
- format!("Mesh{}", mesh.index())
+ GltfAssetLabel::Mesh(mesh.index()).to_string()
 }
 
 /// Returns the label for the `mesh` and `primitive`.
 fn primitive_label(mesh: &gltf::Mesh, primitive: &Primitive) -> String {
- format!("Mesh{}/Primitive{}", mesh.index(), primitive.index())
+ GltfAssetLabel::Primitive {
+ mesh: mesh.index(),
+ primitive: primitive.index(),
+ }
+ .to_string()
 }
 
 fn primitive_name(mesh: &gltf::Mesh, primitive: &Primitive) -> String {
@@ -1434,28 +1441,29 @@ fn primitive_name(mesh: &gltf::Mesh, primitive: &Primitive) -> String {
 
 /// Returns the label for the morph target of `primitive`.
 fn morph_targets_label(mesh: &gltf::Mesh, primitive: &Primitive) -> String {
- format!(
- "Mesh{}/Primitive{}/MorphTargets",
- mesh.index(),
-  primitive.index()
- )
+ GltfAssetLabel::MorphTarget {
+ mesh: mesh.index(),
+ primitive: primitive.index(),
+ }
+ .to_string()
 }
 
 /// Returns the label for the `material`.
 fn material_label(material: &Material, is_scale_inverted: bool) -> String {
  if let Some(index) = material.index() {
- format!(
- "Material{index}{}",
- if is_scale_inverted { " (inverted)" } else { "" }
- )
+ GltfAssetLabel::Material {
+ index,
+ is_scale_inverted,
+ }
+ .to_string()
  } else {
- "MaterialDefault".to_string()
+ GltfAssetLabel::DefaultMaterial.to_string()
  }
 }
 
 /// Returns the label for the `texture`.
 fn texture_label(texture: &gltf::Texture) -> String {
- format!("Texture{}", texture.index())
+ GltfAssetLabel::Texture(texture.index()).to_string()
 }
 
 fn texture_handle(load_context: &mut LoadContext, texture: &gltf::Texture) -> Handle<Image> {
@@ -1501,16 +1509,16 @@ fn texture_handle_from_info(
 
 /// Returns the label for the `node`.
 fn node_label(node: &Node) -> String {
- format!("Node{}", node.index())
+ GltfAssetLabel::Node(node.index()).to_string()
 }
 
 /// Returns the label for the `scene`.
 fn scene_label(scene: &gltf::Scene) -> String {
- format!("Scene{}", scene.index())
+ GltfAssetLabel::Scene(scene.index()).to_string()
 }
 
 fn skin_label(skin: &gltf::Skin) -> String {
- format!("Skin{}", skin.index())
+ GltfAssetLabel::Skin(skin.index()).to_string()
 }
 
 /// Extracts the texture sampler data from the glTF texture.

crates/bevy_internal/src/prelude.rs

@@ -66,3 +66,7 @@ pub use crate::gilrs::*;
 #[doc(hidden)]
 #[cfg(feature = "bevy_state")]
 pub use crate::state::prelude::*;
+
+#[doc(hidden)]
+#[cfg(feature = "bevy_gltf")]
+pub use crate::gltf::prelude::*;

examples/2d/custom_gltf_vertex_attribute.rs

@@ -42,7 +42,13 @@ fn setup(
  mut materials: ResMut<Assets<CustomMaterial>>,
 ) {
  // Add a mesh loaded from a glTF file. This mesh has data for `ATTRIBUTE_BARYCENTRIC`.
- let mesh = asset_server.load("models/barycentric/barycentric.gltf#Mesh0/Primitive0");
+ let mesh = asset_server.load(
+ GltfAssetLabel::Primitive {
+ mesh: 0,
+ primitive: 0,
+ }
+ .from_asset("models/barycentric/barycentric.gltf"),
+ );
  commands.spawn(MaterialMesh2dBundle {
  mesh: Mesh2dHandle(mesh),
  material: materials.add(CustomMaterial {}),

examples/3d/anti_aliasing.rs

@@ -282,7 +282,8 @@ fn setup(
 
  // Flight Helmet
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0"),
+ scene: asset_server
+ .load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf")),
  ..default()
  });
 

examples/3d/atmospheric_fog.rs

@@ -72,7 +72,8 @@ fn setup_terrain_scene(
 
  // Terrain
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/terrain/Mountains.gltf#Scene0"),
+ scene: asset_server
+ .load(GltfAssetLabel::Scene(0).from_asset("models/terrain/Mountains.gltf")),
  ..default()
  });
 

examples/3d/clearcoat.rs

@@ -149,7 +149,8 @@ fn spawn_coated_glass_bubble_sphere(
 fn spawn_golf_ball(commands: &mut Commands, asset_server: &AssetServer) {
  commands
  .spawn(SceneBundle {
- scene: asset_server.load("models/GolfBall/GolfBall.glb#Scene0"),
+ scene: asset_server
+ .load(GltfAssetLabel::Scene(0).from_asset("models/GolfBall/GolfBall.glb")),
  transform: Transform::from_xyz(1.0, 1.0, 0.0).with_scale(Vec3::splat(SPHERE_SCALE)),
  ..default()
  })

examples/3d/color_grading.rs

@@ -382,13 +382,16 @@ fn add_camera(commands: &mut Commands, asset_server: &AssetServer, color_grading
 fn add_basic_scene(commands: &mut Commands, asset_server: &AssetServer) {
  // Spawn the main scene.
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/TonemappingTest/TonemappingTest.gltf#Scene0"),
+ scene: asset_server.load(
+ GltfAssetLabel::Scene(0).from_asset("models/TonemappingTest/TonemappingTest.gltf"),
+ ),
  ..default()
  });
 
  // Spawn the flight helmet.
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0"),
+ scene: asset_server
+ .load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf")),
  transform: Transform::from_xyz(0.5, 0.0, -0.5)
  .with_rotation(Quat::from_rotation_y(-0.15 * PI)),
  ..default()

examples/3d/deferred_rendering.rs

@@ -80,7 +80,8 @@ fn setup(
  });
 
  // FlightHelmet
- let helmet_scene = asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0");
+ let helmet_scene = asset_server
+ .load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf"));
 
  commands.spawn(SceneBundle {
  scene: helmet_scene.clone(),

examples/3d/depth_of_field.rs

@@ -88,7 +88,10 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>, app_settings: R
 
  // Spawn the scene.
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/DepthOfFieldExample/DepthOfFieldExample.glb#Scene0"),
+ scene: asset_server.load(
+ GltfAssetLabel::Scene(0)
+ .from_asset("models/DepthOfFieldExample/DepthOfFieldExample.glb"),
+ ),
  ..default()
  });
 

examples/3d/irradiance_volumes.rs

@@ -516,16 +516,19 @@ fn handle_mouse_clicks(
 
 impl FromWorld for ExampleAssets {
  fn from_world(world: &mut World) -> Self {
- let fox_animation = world.load_asset("models/animated/Fox.glb#Animation1");
+ let fox_animation =
+ world.load_asset(GltfAssetLabel::Animation(1).from_asset("models/animated/Fox.glb"));
  let (fox_animation_graph, fox_animation_node) =
  AnimationGraph::from_clip(fox_animation.clone());
 
  ExampleAssets {
  main_sphere: world.add_asset(Sphere::default().mesh().uv(32, 18)),
- fox: world.load_asset("models/animated/Fox.glb#Scene0"),
+ fox: world.load_asset(GltfAssetLabel::Scene(0).from_asset("models/animated/Fox.glb")),
  main_sphere_material: world.add_asset(Color::from(SILVER)),
- main_scene: world
- .load_asset("models/IrradianceVolumeExample/IrradianceVolumeExample.glb#Scene0"),
+ main_scene: world.load_asset(
+ GltfAssetLabel::Scene(0)
+ .from_asset("models/IrradianceVolumeExample/IrradianceVolumeExample.glb"),
+ ),
  irradiance_volume: world.load_asset("irradiance_volumes/Example.vxgi.ktx2"),
  fox_animation_graph: world.add_asset(fox_animation_graph),
  fox_animation_node,

examples/3d/lightmaps.rs

@@ -14,7 +14,8 @@ fn main() {
 
 fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/CornellBox/CornellBox.glb#Scene0"),
+ scene: asset_server
+ .load(GltfAssetLabel::Scene(0).from_asset("models/CornellBox/CornellBox.glb")),
  ..default()
  });
 

examples/3d/load_gltf.rs

@@ -47,7 +47,8 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
  ..default()
  });
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0"),
+ scene: asset_server
+ .load(GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf")),
  ..default()
  });
 }

examples/3d/reflection_probes.rs

@@ -98,7 +98,7 @@ fn setup(
 // Spawns the cubes, light, and camera.
 fn spawn_scene(commands: &mut Commands, asset_server: &AssetServer) {
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/cubes/Cubes.glb#Scene0"),
+ scene: asset_server.load(GltfAssetLabel::Scene(0).from_asset("models/cubes/Cubes.glb")),
  ..SceneBundle::default()
  });
 }

examples/3d/split_screen.rs

@@ -29,7 +29,7 @@ fn setup(
  });
 
  commands.spawn(SceneBundle {
- scene: asset_server.load("models/animated/Fox.glb#Scene0"),
+ scene: asset_server.load(GltfAssetLabel::Scene(0).from_asset("models/animated/Fox.glb")),
  ..default()
  });