Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-09-20 06:22:01 +00:00
Code Issues Projects Releases Packages Wiki Activity

Revert accidentally added asset docs (#15054)

Browse source 
Our branch protection rules were misconfigured, allowing me to push
directly to `origin/main` 😱 This is now resolved:


![image](https://github.com/user-attachments/assets/bb0ac59a-6998-42f7-80d6-8b3a865c6f53)

This PR reverts those accidental changes, which will get their own PR
momentarily...
This commit is contained in:
Alice Cecile 2024-09-05 10:24:24 -04:00 committed by GitHub
parent ba1f13fdc7
commit 5589f0da40
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 2 additions and 135 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
crates/bevy_asset/src/io/mod.rs
View file

@ -130,10 +130,7 @@ where
/// API, where asset bytes and asset metadata bytes are both stored and accessible for a given /// API, where asset bytes and asset metadata bytes are both stored and accessible for a given
/// `path`. This trait is not object safe, if needed use a dyn [`ErasedAssetReader`] instead. /// `path`. This trait is not object safe, if needed use a dyn [`ErasedAssetReader`] instead.
/// ///
/// This trait defines asset-agnostic mechanisms to interact with a storage system. /// Also see [`AssetWriter`].
/// For the per-asset-type saving/loading logic, see [`AssetSaver`](crate::saver::AssetSaver) and [`AssetLoader`](crate::loader::AssetLoader).
///
/// For a mirrored version of this trait that can write assets to storage, see [`AssetWriter`].
pub trait AssetReader: Send + Sync + 'static { pub trait AssetReader: Send + Sync + 'static {
/// Returns a future to load the full file data at the provided path. /// Returns a future to load the full file data at the provided path.
/// ///
@ -264,10 +261,7 @@ pub enum AssetWriterError {
/// API, where asset bytes and asset metadata bytes are both stored and accessible for a given /// API, where asset bytes and asset metadata bytes are both stored and accessible for a given
/// `path`. This trait is not object safe, if needed use a dyn [`ErasedAssetWriter`] instead. /// `path`. This trait is not object safe, if needed use a dyn [`ErasedAssetWriter`] instead.
/// ///
/// This trait defines asset-agnostic mechanisms to interact with a storage system. /// Also see [`AssetReader`].
/// For the per-asset-type saving/loading logic, see [`AssetSaver`](crate::saver::AssetSaver) and [`AssetLoader`](crate::loader::AssetLoader).
///
/// For a mirrored version of this trait that can read assets from storage, see [`AssetReader`].
pub trait AssetWriter: Send + Sync + 'static { pub trait AssetWriter: Send + Sync + 'static {
/// Writes the full asset bytes at the provided path. /// Writes the full asset bytes at the provided path.
fn write<'a>( fn write<'a>(

114
crates/bevy_asset/src/lib.rs
View file

@ -1,106 +1,3 @@
//! In the context of game development, an "asset" is a piece of multimedia content which must be loaded from disk and displayed in the game.
//! Typically, these are authored by artists and designers (in contrast to code),
//! are relatively large in size, and include everything from textures and models to sounds and music to levels and scripts.
//!
//! This presents two main challenges:
//! - assets take up a lot of memory: simply storing a copy for each instance of an asset in the game would be prohibitively expensive
//! - loading assets from disk is slow, and can cause the game to stutter or freeze if done in the middle of gameplay
//!
//! These problems play into each other: if assets are expensive to store in memory,
//! larger game worlds will need to load them from disk as needed, ideally without a loading screen!
//!
//! Unsurprisingly, the problem of non-blocking asset loading is done using `async`, where background tasks are used to load assets while the game is running.
//! Bevy coordinates these tasks using the [`AssetServer`], storing each loaded asset in a strongly-typed [`Assets<T>`] collection.
//! [`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`].
//! Note that this method does not attempt to reload the asset if it has already been loaded: as long as the asset hasn't been dropped,
//! calling [`AssetServer::load`] on the same path will return the same handle.
//! The handle that's returned 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.
//!
//! To avoid assets "popping" into existence, you may want to check that all of the required assets are loaded before transitioning to a new scene.
//! This can be done by checking the [`LoadState`] of the asset handle using [`AssetServer::is_loaded_with_dependencies`],
//! which will be [`LoadState::Loaded`] when the asset is ready to use.
//! Keep track of what you're waiting on using a [`HashSet`] or similar data structure,
//! poll in your update loop, and transition to the new scene when all assets are loaded.
//! Bevy's built-in states system can be very helpful for this!
//!
//! 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,
//! and are the primary way to interact with assets in Bevy.
//! As a user, you'll be working with handles a lot!
//!
//! The most important thing to know about handles is that they are reference counted: when you clone a handle, you're incrementing a reference count.
//! When the object holding the handle is dropped (generally because an entity was despawned), the reference count is decremented.
//! When the reference count hits zero, the asset it references is removed from the [`Assets`] collection.
//! To avoid incrementing the reference count, you can use the [`Handle::clone_weak`] method, which is marginally faster.
//!
//! This reference counting is a simple, laregely automatic way to avoid holding onto memory for game objects that are no longer in use.
//! However, it can lead to surprising behavior if you're not careful!
//!
//! There are two categories of problems to watch out for:
//! - never dropping a handle, causing the asset to never be removed from memory
//! - dropping a handle too early, causing the asset to be removed from memory while it's still in use
//!
//! The first problem is less critical for beginners, as for tiny games, you can often get away with simply storing all of the assets in memory at once,
//! and loading them all at the start of the game.
//! As your game grows, you'll need to be more careful about when you load and unload assets,
//! segmenting them by level or area, and loading them on-demand.
//! This problem generally arises when handles are stored in a persistent "zoo" or "manifest" of possible objects (generally in a resource),
//! which is convenient for easy access and zero-latency spawning, but can result in high but stable memory usage.
//!
//! The second problem is more concerning, and looks like your models or textures suddenly disappearing from the game.
//! Debugging reveals that the *entities* are still there, but nothing is rendering!
//! This is because the assets were removed from memory while they were still in use.
//! You were probably too aggressive with the use of weak handles: think through the lifetime of your assets carefully!
//! As soon as an asset is loaded, you must ensure that at least one strong handle is held to it until all matching entities are out of sight of the player.
//!
//! # Custom asset types
//!
//! While Bevy comes with implementations for a large number of common game-oriented asset types (often behind off-by-default feature flags!),
//! implementing a custom asset type can be useful when dealing with unusual, game-specific, or proprietary formats.
//!
//! Defining a new asset type is as simple as implementing the [`Asset`] trait.
//! This requires [`TypePath`] for metadata about the asset type,
//! and [`VisitAssetDependencies`] to track asset dependencies.
//! In simple cases, you can derive [`Asset`] and [`Reflect`] and be done with it: the required supertraits will be implemented for you.
//!
//! With a new asset type in place, we now need to figure out how to load it.
//! While [`AssetReader`](io::AssetReader) describes strategies to read assets from various sources,
//! [`AssetLoader`] is the trait that actually turns those into your desired format.
//! Generally, only) [`AssetLoader`] needs to be implemented for custom assets, as the [`AssetReader`](io::AssetReader) implementations are provided by Bevy.
//!
//! However, [`AssetLoader`] shouldn't be implemented for your asset type directly: instead, this is implemented for a "loader" type
//! that can store complex intermediate state, while your asset type is used as the [`AssetLoader::Asset`] associated type.
//! As the trait documentation explains, this allows various [`AssetLoader::Settings`] to be used to configure the loader.
//!
//! After the loader is implemented, it needs to be registered with the [`AssetServer`] using [`App::register_asset_loader`](AssetApp::register_asset_loader).
//! Once your asset type is loaded, you can use it in your game like any other asset type!
//!
//! If you want to save your assets back to disk, you should implement [`AssetSaver`](saver::AssetSaver) as well.
//! This trait mirrors [`AssetLoader`] in structure, and works in tandem with [`AssetWriter`](io::AssetWriter), which mirrors [`AssetReader`](io::AssetReader).
// FIXME(3492): remove once docs are ready // FIXME(3492): remove once docs are ready
#![allow(missing_docs)] #![allow(missing_docs)]
#![cfg_attr(docsrs, feature(doc_auto_cfg))] #![cfg_attr(docsrs, feature(doc_auto_cfg))]
@ -334,13 +231,6 @@ impl Plugin for AssetPlugin {
} }
} }
/// Declares that this type is an asset,
/// which can be loaded and managed by the [`AssetServer`] and stored in [`Assets`] collections.
///
/// Generally, assets are large, complex, and/or expensive to load from disk, and are often authored by artists or designers.
///
/// [`TypePath`] is largely used for diagnostic purposes, and should almost always be implemented by deriving [`Reflect`] on your type.
/// [`VisitAssetDependencies`] is used to track asset dependencies, and an implementation automatically generated when deriving [`Asset`].
#[diagnostic::on_unimplemented( #[diagnostic::on_unimplemented(
message = "`{Self}` is not an `Asset`", message = "`{Self}` is not an `Asset`",
label = "invalid `Asset`", label = "invalid `Asset`",
@ -348,10 +238,6 @@ impl Plugin for AssetPlugin {
)] )]
pub trait Asset: VisitAssetDependencies + TypePath + Send + Sync + 'static {} pub trait Asset: VisitAssetDependencies + TypePath + Send + Sync + 'static {}
/// This trait defines how to visit the dependencies of an asset.
/// For example, a 3D model might require both textures and meshes to be loaded.
///
/// Note that this trait is automatically implemented when deriving [`Asset`].
pub trait VisitAssetDependencies { pub trait VisitAssetDependencies {
fn visit_dependencies(&self, visit: &mut impl FnMut(UntypedAssetId)); fn visit_dependencies(&self, visit: &mut impl FnMut(UntypedAssetId));
} }

5
crates/bevy_asset/src/loader.rs
View file

@ -20,11 +20,6 @@ use thiserror::Error;
/// Loads an [`Asset`] from a given byte [`Reader`]. This can accept [`AssetLoader::Settings`], which configure how the [`Asset`] /// Loads an [`Asset`] from a given byte [`Reader`]. This can accept [`AssetLoader::Settings`], which configure how the [`Asset`]
/// should be loaded. /// should be loaded.
///
/// This trait defines asset-specific logic to convert serialized data into Rust types.
/// For asset-agnostic mechanisms to interact with a storage system, see [`AssetSaver`](crate::saver::AssetSaver) and [`AssetLoader`](crate::loader::AssetLoader).
///
/// For a mirrored version of this trait that can save assets, see [`AssetSaver`](crate::saver::AssetSaver).
pub trait AssetLoader: Send + Sync + 'static { pub trait AssetLoader: Send + Sync + 'static {
/// The top level [`Asset`] loaded by this [`AssetLoader`]. /// The top level [`Asset`] loaded by this [`AssetLoader`].
type Asset: Asset; type Asset: Asset;

5
crates/bevy_asset/src/saver.rs
View file

@ -8,11 +8,6 @@ use std::{borrow::Borrow, hash::Hash, ops::Deref};
/// Saves an [`Asset`] of a given [`AssetSaver::Asset`] type. [`AssetSaver::OutputLoader`] will then be used to load the saved asset /// Saves an [`Asset`] of a given [`AssetSaver::Asset`] type. [`AssetSaver::OutputLoader`] will then be used to load the saved asset
/// in the final deployed application. The saver should produce asset bytes in a format that [`AssetSaver::OutputLoader`] can read. /// in the final deployed application. The saver should produce asset bytes in a format that [`AssetSaver::OutputLoader`] can read.
///
/// This trait defines asset-specific logic to convert Rust types into serializable data.
/// For asset-agnostic mechanisms to interact with a storage system, see [`AssetSaver`](crate::saver::AssetSaver) and [`AssetLoader`](crate::loader::AssetLoader).
///
/// For a mirrored version of this trait that can load assets, see [`AssetLoader`](crate::loader::AssetLoader).
pub trait AssetSaver: Send + Sync + 'static { pub trait AssetSaver: Send + Sync + 'static {
/// The top level [`Asset`] saved by this [`AssetSaver`]. /// The top level [`Asset`] saved by this [`AssetSaver`].
type Asset: Asset; type Asset: Asset;

3
crates/bevy_asset/src/server/mod.rs
View file

@ -266,9 +266,6 @@ impl AssetServer {
/// it returns a "strong" [`Handle`]. When the [`Asset`] is loaded (and enters [`LoadState::Loaded`]), it will be added to the /// it returns a "strong" [`Handle`]. When the [`Asset`] is loaded (and enters [`LoadState::Loaded`]), it will be added to the
/// associated [`Assets`] resource. /// associated [`Assets`] resource.
/// ///
/// Note that if the asset at this path is already loaded, this function will return the existing handle,
/// and will not waste work spawning a new load task.
///
/// In case the file path contains a hashtag (`#`), the `path` must be specified using [`Path`] /// In case the file path contains a hashtag (`#`), the `path` must be specified using [`Path`]
/// or [`AssetPath`] because otherwise the hashtag would be interpreted as separator between /// or [`AssetPath`] because otherwise the hashtag would be interpreted as separator between
/// the file path and the label. For example: /// the file path and the label. For example: