Add docs to bevy_gltf about loading parts of a Gltf asset

crates/bevy_gltf/src/lib.rs

@@ -9,6 +9,100 @@
 //! for loading glTF 2.0 (a standard 3D scene definition format) files in Bevy.
 //!
 //! The [glTF 2.0 specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html) defines the format of the glTF files.
+//!
+//! # Quick Start
+//!
+//! Here's how to spawn a simple glTF scene
+//!
+//! ```
+//! # use bevy_ecs::prelude::*;
+//! # use bevy_asset::prelude::*;
+//! # use bevy_scene::prelude::*;
+//! # use bevy_transform::prelude::*;
+//!
+//! fn spawn_gltf(mut commands: Commands, asset_server: Res<AssetServer>) {
+//!     commands.spawn(SceneBundle {
+//!         // 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"),
+//!         // 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.
+//!
+//! ```
+//! # use bevy_ecs::prelude::*;
+//! # use bevy_asset::prelude::*;
+//! # use bevy_scene::prelude::*;
+//! # use bevy_transform::prelude::*;
+//! # use bevy_gltf::Gltf;
+//!
+//! // 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#Scene0");
+//!     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.
+//!
+//! 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`
 
 #[cfg(feature = "bevy_animation")]
 use bevy_animation::AnimationClip;