0.12 Bevy Asset V2

content/news/2023-10-21-bevy-0.12/index.md

@@ -15,9 +15,351 @@ Since our last release a few months ago we've added a _ton_ of new features, bug
 
 <!-- more -->
 
-## Feature Name
+## Bevy Asset V2
 
-<div class="release-feature-authors">authors: @author</div>
+<div class="release-feature-authors">authors: @cart</div>
+
+Asset pipelines are a central part of the gamedev process. Bevy's old asset system was suitable for some classes of app, but it had a number of limitations that prevented it from serving the needs of other classes, especially higher end 3D apps.
+
+Bevy Asset V2 is a completely new asset system that learns from the best parts of Bevy Asset V1 while adding support for a number of important scenarios: **Asset Importing/Preprocessing**, **Asset Meta Files**, **Multiple Asset Sources**, **Recursive Asset Dependency Load Events**, **Async Asset I/O**, **Faster and More Featureful Asset Handles**, and more!
+
+Most existing user-facing asset code will either require no changes at all, or minimal changes. Custom [`AssetLoader`] or [`AssetReader`] code will need to change slightly, but generally the changes should be very minimal. Bevy Asset V2 (despite being a completely new implementation) largely just expands what Bevy is capable of.
+
+[`AssetLoader`]: https://dev-docs.bevyengine.org/bevy/asset/trait.AssetLoader.html
+[`AssetReader`]: https://dev-docs.bevyengine.org/bevy/asset/io/trait.AssetReader.html
+
+### Asset Preprocessing
+
+![image process diagram](image_process.png)
+
+Asset preprocessing is the ability to take an input asset of a given type, process it in some way (generally during development time), and then use the result as the final asset in your application. Think of it as an "asset compiler".
+
+This enables a number of scenarios:
+
+* **Reduce Work In Released Apps**: Many assets aren't _composed_ in their ideal form for release. Scenes might be defined in a human-readable text format that is slower to load. Images might be defined in formats that require more work to decode and upload to the GPU, or take up more space on the GPU when compared to GPU-friendly formats (ex: PNG images vs Basis Universal). Preprocessing enables developers to convert to release-optimal formats ahead of time, making apps start up faster, take up fewer resources, and perform better. It also enables moving computation work that _would_ have been done at runtime to development time. For example, generating mipmaps for images.
+* **Compression**: Minimize the disk space and/or bandwidth that an asset takes up in deployed apps
+* **Transformation**: Some "asset source files" aren't in the right format by default. You can have an asset of type `A` and transform it into type `B`.
+
+If you are building an app that tests the limits of your hardware with optimal formats ... or you just want to cut down on startup / loading times, asset preprocessing is for you.
+
+For an in-depth technical breakdown of the implementation we chose, check out the [Bevy Asset V2 pull request](https://github.com/bevyengine/bevy/pull/8624).
+
+### Enabling Processing
+
+To enable processing, just configure your [`AssetPlugin`] like this:
+
+```rust
+app.add_plugins(DefaultPlugins.set(
+    AssetPlugin {
+        mode: AssetMode::Processed,
+        ..default()
+    }
+))
+```
+
+This will configure the asset system to look for assets in the `imported_assets` folder instead of the `assets` "source folder". During development, enable the `asset_processor` cargo feature flag like this:
+
+```sh
+cargo run --features bevy/asset_processor
+```
+
+This will start the [`AssetProcessor`] in parallel with your app. It will run until all assets are read from their source (defaults to the `assets` folder), processed, and the results have been written to their destination (defaults to the `imported_assets` folder). This pairs with asset hot-reloading. If you make a change, this will be detected by the [`AssetProcessor`], the asset will be reprocessed, and the result will be hot-reloaded in your app.
+
+[`AssetPlugin`]: https://dev-docs.bevyengine.org/bevy/asset/struct.AssetPlugin.html
+[`AssetProcessor`]: https://dev-docs.bevyengine.org/bevy/asset/processor/struct.AssetProcessor.html
+
+### Incremental and Dependency Aware
+
+**Bevy Asset V2** will only process assets that have changed. To accomplish this, it computes and stores hashes of each asset source file:
+
+```rust
+hash: (132, 61, 201, 41, 85, 80, 72, 189, 132, 81, 252, 156, 4, 227, 196, 207),
+```
+
+It also tracks the asset dependencies used when processing an asset. If a dependency has changed, the dependant asset will also be re-processed!
+
+### Transactional and Reliable
+
+**Bevy Asset V2** uses write-ahead logging (a technique commonly used by databases) to recover from crashes / forced exists. Whenever possible it avoids full-reprocessing and only reprocesses incomplete transactions.
+
+The [`AssetProcessor`] can close (either intentionally or unintentionally) at any point in time and it will pick up right where it left off!
+
+If a Bevy App asks to load an asset that is currently being processed (or re-processed), the load will asynchronously wait until both the processed asset and its meta file have been written. This ensures that a loaded asset file and meta file always "match" for a given load.
+
+### Asset Meta Files
+
+Assets now support (optional) `.meta` files. This enables configuring things like:
+
+* **The asset "action"**
+  * `Load`, `Process`, `Ignore`, etc
+* **[`AssetLoader`] settings**
+  * You can use meta files to set any [`AssetLoader`] you want
+  * Configure loader settings like "how to filter an image", "adjusting the up axis in 3D scenes", etc
+* **[`Process`] settings** (if using the `Process` action)
+  * You can use meta files to set any [`Process`] implementation you want
+  * Configure processor settings like "what type of compression to use", "whether or not to generate mipmaps", etc
+
+A meta file for an unprocessed image looks like this:
+
+```rust
+(
+    meta_format_version: "1.0",
+    asset: Load(
+        loader: "bevy_render::texture::image_loader::ImageLoader",
+        settings: (
+            format: FromExtension,
+            is_srgb: true,
+        ),
+    ),
+)
+```
+
+A meta file for an image configured to be processed looks like this:
+
+```rust
+(
+    meta_format_version: "1.0",
+    asset: Process(
+        processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>",
+        settings: (
+            loader_settings: (
+                format: FromExtension,
+                is_srgb: true,
+            ),
+            saver_settings: (),
+        ),
+    ),
+)
+```
+
+If the asset processor is enabled, meta files will be automatically generated for assets.
+
+The final "output" metadata for the processed image looks like this:
+
+```rust
+(
+    meta_format_version: "1.0",
+    processed_info: Some((
+        hash: (132, 61, 201, 41, 85, 80, 72, 189, 132, 81, 252, 156, 4, 227, 196, 207),
+        full_hash: (81, 90, 244, 190, 16, 134, 202, 154, 3, 211, 78, 199, 216, 21, 132, 216),
+        process_dependencies: [],
+    )),
+    asset: Load(
+        loader: "bevy_render::texture::image_loader::ImageLoader",
+        settings: (
+            format: Format(Basis),
+            is_srgb: true,
+        ),
+    ),
+)
+```
+
+This is what is written to the `imported_assets` folder.
+
+Note that the `Process` asset mode has changed to `Load`. This is because in the released app, we will load the final processed image "normally" like any other image asset. Note that in this case, the input and the output asset _both_ use [`ImageLoader`]. However the processed asset _can_ use a different loader if the context demands it.
+
+Also note the addition of the `processed_info` metadata. This is used to determine if an asset needs to be reprocessed. `hash` is a combined hash of the asset source file and the asset meta file. This can be used to detect if the asset has changed. `process_dependencies` contains information (and hashes) of any asset dependencies used to produce the final processed asset. `full_hash` is a combination of `hash` and `processed_info` data to quickly determine if an asset has changed.
+
+The final processed asset and metadata files can be viewed and interacted with like any other file. However they are intended to be read-only. Configuration should happen on the _source asset_, not the _final processed asset_.
+
+[`Process`]: https://dev-docs.bevyengine.org/bevy/asset/processor/trait.Process.html
+[`ImageLoader`]: https://dev-docs.bevyengine.org/bevy/render/texture/struct.ImageLoader.html
+
+### `CompressedImageSaver`
+
+![processed sponza](processed_sponza.png)
+<div style="font-size: 1.0rem" class="release-feature-authors">Sponza scene with textures processed into Basis Universal (with mipmaps) using Bevy Asset V2</div>
+
+**Bevy 0.12** ships with a barebones [`CompressedImageSaver`] that writes images to [Basis Universal](https://github.com/BinomialLLC/basis_universal) (a GPU-friendly image interchange format) and generates mipmaps. This can be enabled with the `basis-universal` cargo feature.
+
+[`CompressedImageSaver`]: https://dev-docs.bevyengine.org/bevy/render/texture/struct.CompressedImageSaver.html
+
+### Preprocessing is Optional!
+
+In future Bevy releases we will likely recommended enabling processing for the majority of apps. We don't _yet_ recommend it for most use cases for a few reasons:
+
+1. Most of our built-in assets don't have processors implemented for them yet. The [`CompressedImageSaver`] is the only built-in processor and it has a bare-minimum set of features.
+2. We have not implemented "asset migrations" yet. Whenever an asset changes its settings format (which is used in meta files), we need to be able to automatically migrate existing asset meta files to the new version.
+3. As people adopt processing, we expect some flux as we respond to feedback.
+
+Despite (eventually) recommending that most people enable asset processing, we also acknowledge that Bevy is used in a variety of applications. Asset processing introduces additional complexity and workflow changes that some people will not want!
+
+This is why Bevy offers two asset modes:
+
+* [`AssetMode::Unprocessed`]: Assets will be loaded directly from the asset source folder (defaults to `assets`) without any preprocessing. They are assumed to be in their "final format". This is the mode/workflow Bevy users are currently used to.
+* [`AssetMode::Processed`]: Assets will be pre-processed at development time. They will be read from their source folder (defaults to `assets`) and then written to their destination folder (defaults to `imported_assets`).
+
+To enable this, Bevy uses a novel approach to assets: the difference between a processed and unprocessed asset is perspective. They both use the same `.meta` format and they use the same [`AssetLoader`] interface.
+
+A [`Process`] implementation can be defined using arbitrary logic, but we heavily encourage using the [`LoadAndSave`] [`Process`] implementation. [`LoadAndSave`] takes any [`AssetLoader`] and passes the results to an [`AssetSaver`].
+
+That means if you already have an [`ImageLoader`], which loads images, all you need to do is write some `ImageSaver` which will write the image in some optimized format. This both saves development work and makes it easy to support both processed and unprocessed scenarios.
+
+[`AssetMode::Unprocessed`]: https://dev-docs.bevyengine.org/bevy/asset/enum.AssetMode.html
+[`AssetMode::Processed`]: https://dev-docs.bevyengine.org/bevy/asset/enum.AssetMode.html
+[`LoadAndSave`]: https://dev-docs.bevyengine.org/bevy/asset/processor/struct.LoadAndSave.html
+[`AssetSaver`]: https://dev-docs.bevyengine.org/bevy/asset/saver/trait.AssetSaver.html
+
+### Built To Run Anywhere
+
+Unlike many other asset processors in this space, Bevy Asset V2's [`AssetProcessor`] is intentionally architected to run on any platform. It doesn't use platform-limited databases or require the ability/permission to run a networked server. It can be deployed alongside a released app if your application logic requires processing at runtime.
+
+One notable exception: we still need to make a few changes before it can run on the web, but it was built with web support in mind.
+
+### Recursive Asset Dependency Load Events
+
+The [`AssetEvent`] enum now has an [`AssetEvent::LoadedWithDependencies`] variant. This is emitted when an [`Asset`], its dependencies, and all descendant / recursive dependencies have loaded.
+
+This makes it easy to wait until an [`Asset`] is "fully loaded" before doing something.
+
+[`AssetEvent`]: https://dev-docs.bevyengine.org/bevy/asset/enum.AssetEvent.html
+
+### Multiple Asset Sources
+
+It is now possible to register more than one [`AssetSource`] (which replaces the old monolithic "asset provider" system).
+
+Loading from the "default" [`AssetSource`] looks exactly like it does in previous Bevy versions:
+
+```rust
+sprite.texture = assets.load("path/to/sprite.png");
+```
+
+But in **Bevy 0.12** you can now register named [`AssetSource`] entries. For example you could register a `remote` [`AssetSource`] that loads assets from an HTTP server:
+
+```rust
+sprite.texture = assets.load("remote://path/to/sprite.png");
+```
+
+Features like hot-reloading, meta files, and asset processing are supported across all sources.
+
+You can register a new [`AssetSource`] like this:
+
+```rust
+// reads assets from the "other" folder, rather than the default "assets" folder
+app.register_asset_source(
+    // This is the "name" of the new source, used in asset paths.
+    // Ex: "other://path/to/sprite.png"
+    "other",
+    // This is a repeatable source builder. You can configure readers, writers,
+    // processed readers, processed writers, asset watchers, etc.
+    AssetSource::build()
+        .with_reader(|| Box::new(FileAssetReader::new("other")))
+    )
+)
+```
+
+[`AssetSource`]: https://dev-docs.bevyengine.org/bevy/asset/io/struct.AssetSource.html
+
+### Embedded Assets
+
+One of the features motivating **Multiple Asset Sources** was improving our "embedded-in-binary" asset loading. The old `load_internal_asset!` approach had a number of issues (see the relevant section in [this PR](https://github.com/bevyengine/bevy/pull/9885)).
+
+The old system looked like this:
+
+```rust
+pub const MESH_SHADER_HANDLE: Handle<Shader> = Handle::weak_from_u128(3252377289100772450);
+
+load_internal_asset!(app, MESH_SHADER_HANDLE, "mesh.wgsl", Shader::from_wgsl);
+```
+
+This required a lot of boilerplate and didn't integrate cleanly with the rest of the asset system. The [`AssetServer`] was not aware of these assets, hot-reloading required a special-cased second [`AssetServer`], and you couldn't load assets using an [`AssetLoader`] (they had to be constructed in memory). Not ideal!
+
+To prove out the **Multiple Asset Sources** implementation, we built a new `embedded` [`AssetSource`], which replaces the old `load_interal_asset!` system with something that naturally fits into the asset system:
+
+```rust
+// Called in `crates/bevy_pbr/src/render/mesh.rs`
+embedded_asset!(app, "mesh.wgsl");
+
+// later in the app
+let shader: Handle<Shader> = asset_server.load("embedded://bevy_pbr/render/mesh.wgsl");
+```
+
+That is a lot less boilerplate than the old approach!
+
+And because the `embedded` source is just like any other asset source, it can support hot-reloading cleanly ... unlike the old system. To hot-reload assets embedded in the binary (ex: to get live updates on a shader you have embedded in the binary), just enable the new `embedded_watcher` cargo feature.
+
+Much better!
+
+### Extendable
+
+Almost everything in **Bevy Asset V2** can be extended with trait impls:
+
+* **[`Asset`]**: Define new asset types
+* **[`AssetReader`]**: Define custom [`AssetSource`] read logic
+* **[`AssetWriter`]**: Define custom [`AssetSource`] write logic
+* **[`AssetWatcher`]**: Define custom [`AssetSource`] watching / hot-reloading logic
+* **[`AssetLoader`]**: Define custom load logic for a given [`Asset`] type
+* **[`AssetSaver`]**: Define custom save logic for a given [`Asset`] type
+* **[`Process`]**: Define fully bespoke processor logic (or use the more opinionated [`LoadAndSave`] [`Process`] impl)
+
+[`Asset`]: https://dev-docs.bevyengine.org/bevy/asset/trait.Asset.html
+[`AssetWatcher`]: https://dev-docs.bevyengine.org/bevy/asset/io/trait.AssetWatcher.html
+
+### Async Asset I/O
+
+The new [`AssetReader`] and [`AssetWriter`] APIs are async! This means naturally async backends (like networked APIs) can directly call `await` on futures.
+
+The filesystem impls (such as [`FileAssetReader`]) offload file IO to a separate thread and the future resolves when the file operation has finished.
+
+[`AssetWriter`]: https://dev-docs.bevyengine.org/bevy/asset/io/trait.AssetWriter.html
+[`FileAssetReader`]: https://dev-docs.bevyengine.org/bevy/asset/io/file/struct.FileAssetReader.html
+
+### Improved Hot-Reloading Workflow
+
+Previous versions of Bevy required manually enabling asset hot-reloading in your app code (in addition to enabling the `filesystem_watcher` cargo feature):
+
+```rust
+// Enabling hot reloading in old versions of Bevy
+app.add_plugins(DefaultPlugins.set(AssetPlugin::default().watch_for_changes()))
+```
+
+This was suboptimal because released versions of apps generally don't want filesystem watching enabled.
+
+In **Bevy 0.12** we've improved this workflow by making the new `file_watcher` cargo feature enable file watching in your app by default. During development, just run your app with the feature enabled:
+
+```sh
+cargo run --features bevy/file_watcher
+```
+
+When releasing, just omit that feature. No code changes required!
+
+```sh
+cargo build --release
+```
+
+### Better Asset Handles
+
+Asset handles now use a single `Arc` at their core to manage the lifetime of an asset. This simplifies the internals significantly and also enables us to make more asset information available directly from handles.
+
+Notably, in **Bevy 0.12** we use this to provide direct [`AssetPath`] access from the [`Handle`]:
+
+```rust
+// Previous version of Bevy
+let path = asset_server.get_handle_path(&handle);
+
+// Bevy 0.12
+let path = handle.path();
+```
+
+Handles now also use a smaller / cheaper-to-look-up [`AssetIndex`] internally, which uses generational indices to look up assets in dense storage.
+
+[`AssetPath`]: https://dev-docs.bevyengine.org/bevy/asset/struct.AssetPath.html
+[`Handle`]: https://dev-docs.bevyengine.org/bevy/asset/enum.Handle.html
+[`AssetIndex`]: https://dev-docs.bevyengine.org/bevy/asset/struct.AssetIndex.html
+
+### True Copy on Write Asset Paths
+
+The [`AssetServer`] and [`AssetProcessor`] do a lot of [`AssetPath`] cloning (across many threads). In previous versions of Bevy, [`AssetPath`] was backed by Rust's [`Cow`] type. However in Rust, cloning an "owned" [`Cow`] results in a clone of the internal value. This is _not_ the "clone on write" behavior we want for [`AssetPath`]. We use [`AssetPath`] across threads, so we _need_ to start with an "owned" value.
+
+To prevent all of this cloning and re-allocating of strings, we've built our own [`CowArc`] type, which [`AssetPath`] uses internally. It has two tricks up its sleeve:
+
+1. The "owned" variant is an `Arc<str>`, which we can cheaply clone without reallocating the string.
+2. Almost _all_ [`AssetPath`] values defined in code come from a `&'static str`. We've created a special [`CowArc::Static`] variant that retains this static-ness, meaning we do _zero_ allocations even when turning a borrow into an "owned [`AssetPath`]".
+
+[`Cow`]: https://doc.rust-lang.org/std/borrow/enum.Cow.html
+[`AssetServer`]: https://dev-docs.bevyengine.org/bevy/asset/struct.AssetServer.html
+[`CowArc`]: https://dev-docs.bevyengine.org/bevy/utils/enum.CowArc.html
+[`CowArc::Static`]: https://dev-docs.bevyengine.org/bevy/utils/enum.CowArc.html#variant.Static
 
 ## <a name="what-s-next"></a>What's Next?