From a4b51d71f14ff4aea66700bed908cf029995574e Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Thu, 5 Sep 2024 09:51:51 -0400 Subject: [PATCH] Basic practical overview --- crates/bevy_asset/src/lib.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/crates/bevy_asset/src/lib.rs b/crates/bevy_asset/src/lib.rs index c547f627c3..ce4a6d858d 100644 --- a/crates/bevy_asset/src/lib.rs +++ b/crates/bevy_asset/src/lib.rs @@ -14,6 +14,28 @@ //! [`Handle`]s serve as an id-based reference to entries in the [`Assets`] collection, allowing them to be cheaply shared between systems, //! and providing a way to initialize objects (generally entities) before the required assets are loaded. //! +//! ## Loading and using assets +//! +//! The [`AssetServer`] is the main entry point for loading assets. +//! Typically, you'll use the [`AssetServer::load`] method to load an asset from disk, which returns a [`Handle`]. +//! This handle will be used to instantiate various [`Component`](bevy_ecs::prelude::Component)s that require asset data to function, +//! which will then be spawned into the world as part of an entity. +//! +//! If we later want to manipulate this asset data (such as for displaying a death animation), we have three options: +//! +//! 1. Despawn the entity and spawn a new one with the new asset data. +//! 2. Change what the handle is pointing to. +//! 3. Use the [`Assets`] collection to directly modify the asset data. +//! +//! The first option is the simplest, but can be slow if done frequently, +//! and can lead to frustrating bugs as references to the old entity (such as what is targeting it) and other data on the entity are lost. +//! Generally, this isn't a great strategy. +//! +//! The second option is the most common: just query for the component that holds the handle, and mutate it, pointing to the new asset. +//! +//! The third option has different semantics: rather than modifying the asset data for a single entity, it modifies the asset data for *all* entities using this handle. +//! While this might be what you want, it generally isn't! +//! //! ## Handles and reference counting //! //! [`Handle`] (or their untyped counterpart [`UntypedHandle`]) are used to reference assets in the [`Assets`] collection,