Add module and supporting documentation to bevy_assets
#15056
Conversation
This reverts commit 5589f0d.
alice-i-cecile
added
C-Docs
alice-i-cecile
requested review from
cart,
janhohenheim,
rparrett,
TrialDragon and
mweatherley
There was a problem hiding this comment.
Gonna look into it in more detail later, but this a great place to add docs! I've seen so many beginners struggle with Handle<T> and Assets<T>, so it will be great to have a place to point to :)
This doesn't add any docs for how to do asset preprocessing, right? I feel like that's the one part of the asset plugin that I have never been able to grok.
Linking #3492
| @@ -266,6 +266,9 @@ impl AssetServer { | |||
| /// it returns a "strong" [`Handle`]. When the [`Asset`] is loaded (and enters [`LoadState::Loaded`]), it will be added to the | |||
| /// associated [`Assets`] resource. | |||
| /// | |||
| /// Note that if the asset at this path is already loaded, this function will return the existing handle, | |||
There was a problem hiding this comment.
Relevant context: This is a (already documented) problem, since different loader settings on the same asset don't work :/.
There was a problem hiding this comment.
#11111 is the relevant issue.
There was a problem hiding this comment.
Something I think is missing is a more detailed talk of Assets<T> vs asset "existing" vs disk. Especially for RenderAsset and RenderAssetUsages, where it may not exist in Assets but is still a "valid" asset, and generally Handle vs AssetServer vs Assets and how they play together (you can allocate a handle without an asset yet, or you can add an asset manually to Assets without going through AssetServer and have it tracking the asset, or you can go through AssetServer).
Probably also mention that AssetServer and Assets are resources, e.g. wrap them in Res to use in a system.
Once we're happy with the content, I'd like to view this on rustdocs and check how it's looking, maybe introduce some subsections and clean up the formatting.
We probably also want some example code blocks on each of the major structs, and maybe a crate-level diagram of the major types like we have with bevy_color.
Lots of ways to improve things - our docs are pretty crappy imo, but bevy_color is really great and the standard we should try and meet :) (with lots of hard work as a community, eventuallllly I want to tackle rendering)
alice-i-cecile
added
S-Ready-For-Final-Review
alice-i-cecile
added
the
M-Needs-Release-Note
There was a problem hiding this comment.
Some minor things I think we should fix, but otherwise good to go.
I still think the things I mentioned in #15056 (review) are very important, particularly the first two paragraphs about asset lifecycles for different workflows, and calling out that Assets is a Res/ResMut somewhere in the docs explicitly. We can leave it to a followup if you want though, maybe open a tracking issue?
| @@ -130,7 +130,10 @@ where | |||
| /// 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. | |||
| /// | |||
| /// Also see [`AssetWriter`]. | |||
| /// This trait defines asset-agnostic mechanisms to read bytes from a storage system. | |||
There was a problem hiding this comment.
The first and second paragraphs seem like they should be combined somehow? It feels a bit duplicated to me.
There was a problem hiding this comment.
I agree, but I don't immediately see a good way to do this, so I'm going to merge as is <3
| @@ -261,7 +264,10 @@ pub enum AssetWriterError { | |||
| /// 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. | |||
| /// | |||
| /// Also see [`AssetReader`]. | |||
| /// This trait defines asset-agnostic mechanisms to write bytes to a storage system. | |||
| /// For the per-asset-type saving/loading logic, see [`AssetSaver`](crate::saver::AssetSaver) and [`AssetLoader`](crate::loader::AssetLoader). | |||
Co-authored-by: JMS55 <[email protected]>
| //! 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. | ||
| //! In short: [`Handle`]s are not the assets themselves, they just tell how to look them up! |
There was a problem hiding this comment.
| //! In short: [`Handle`]s are not the assets themselves, they just tell how to look them up! | |
| //! In short: [`Handle`]s are not the assets themselves, they just tell how to look them up! |
| //! In short: [`Handle`]s are not the assets themselves, they just tell how to look them up! | |
| //! In short: [`Handle`]s are not the assets themselves, but serve as a "bookmark" to easily retrieve or manipulate the asset. |
If people still remember what a bookmark is, of course 🙂
There was a problem hiding this comment.
Hmm, I think that terminology is a bit confusing :)
I don't feel qualified to write this.
Good call, done :) I trust that users will know how to use |
…15058) # Objective Asset processing (added as part of #8624) is a powerful, high-impact feature, but has been widely underused (and underdeveloped) due to poor developer understanding. ## Solution In this PR, I've documented what asset processing is, why it's useful, and pointed users to the two primary entry points. While I would like substantially more involved practical examples for how to perform common asset-processing tasks, I've split them out from this PR for ease of review (and actually submitting this for review before the weekend). We should add bread crumbs from the module docs to these docs, but whether we add that here or in #15056 depends on which gets merged first. --------- Co-authored-by: Carter Anderson <[email protected]>
# Objective Add examples for manipulating sprites and meshes by either mutating the handle or direct manipulation of the asset, as described in #15056. Closes #3130. (The previous PR suffered a Git-tastrophe, and was unceremoniously closed, sry! 😅 ) --------- Co-authored-by: Jan Hohenheim <[email protected]>
|
Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1686 if you'd like to help out. |
Objective
Bevy's asset system is powerful and generally well-designed but very opaque.
Beginners struggle to discover how to do simple tasks and grok the fundamental data models, while more advanced users trip over the assorted traits and their relation to each other.
Reverts #15054 ;)
Solution
This PR adds module documentation to
bevy_assets, tweaking the associated documentation on the items as needed to provide further details and bread crumbs.If you have ideas for other important, hard-to-discover patterns or functionality in this crate, please let me know.
That said, I've left out a section on asset preprocessing which should eventually go here. That is substantially more uncertain, and requires both more time to investigate and more expertise to review.