Module processor

Asset processing in Bevy is a framework for automatically transforming artist-authored assets into the format that best suits the needs of your particular game.

You can think of the asset processing system as a “build system” for assets. When an artist adds a new asset to the project or an asset is changed (assuming asset hot reloading is enabled), the asset processing system will automatically perform the specified processing steps on the asset. This can include things like creating lightmaps for baked lighting, compressing a .wav file to an .ogg, or generating mipmaps for a texture.

Its core values are:

1. Automatic: new and changed assets should be ready to use in-game without requiring any manual conversion or cleanup steps.
2. Configurable: every game has its own needs, and a high level of transparency and control is required.
3. Lossless: the original asset should always be preserved, ensuring artists can make changes later.
4. Deterministic: performing the same processing steps on the same asset should (generally) produce the exact same result. In cases where this doesn’t make sense (steps that involve a degree of randomness or uncertainty), the results across runs should be “acceptably similar”, as they will be generated once for a given set of inputs and cached.

Taken together, this means that the original asset plus the processing steps should be enough to regenerate the final asset. While it may be possible to manually edit the final asset, this should be discouraged. Final post-processed assets should generally not be version-controlled, except to save developer time when recomputing heavy asset processing steps.

Usage

Asset processing can be enabled or disabled in AssetPlugin by setting the AssetMode.
Enable Bevy’s file_watcher feature to automatically watch for changes to assets and reprocess them.

To register a new asset processor, use AssetProcessor::register_processor. To set the default asset processor for a given extension, use AssetProcessor::set_default_processor. In most cases, these methods will be called directly on App using the AssetApp extension trait.

If a default asset processor is set, assets with a matching extension will be processed using that processor before loading.

For an end-to-end example, check out the examples in the examples/asset/processing directory of the Bevy repository.

Defining asset processors

Bevy provides two different ways to define new asset processors:

• LoadTransformAndSave + AssetTransformer: a high-level API for loading, transforming, and saving assets.
• Process: a flexible low-level API for processing assets in arbitrary ways.

In most cases, LoadTransformAndSave should be sufficient.

Structs

AssetProcessor

A “background” asset processor that reads asset values from a source AssetSource (which corresponds to an AssetReader / AssetWriter pair), processes them in some way, and writes them to a destination AssetSource.

AssetProcessorData

Internal data stored inside an AssetProcessor.

LoadTransformAndSave

A flexible Process implementation that loads the source Asset using the L AssetLoader, then transforms the L asset into an S AssetSaver asset using the T AssetTransformer, and lastly saves the asset using the S AssetSaver.

LoadTransformAndSaveSettings

Settings for the LoadTransformAndSave Process::Settings implementation.

ProcessContext

Provides scoped data access to the AssetProcessor. This must only expose processor data that is represented in the asset’s hash.

ProcessorAssetInfos

The “current” in memory view of the asset space. This is “eventually consistent”. It does not directly represent the state of assets in storage, but rather a valid historical view that will gradually become more consistent as events are processed.

ProcessorTransactionLog

A “write ahead” logger that helps ensure asset importing is transactional.

WriteLogError

An error that occurs when writing to the ProcessorTransactionLog fails.

Enums

InitializeError

An error that occurs when initializing the AssetProcessor.

LogEntryError

An error that occurs when validating individual ProcessorTransactionLog entries.

ProcessError

An error that is encountered during Process::process.

ProcessResult

The (successful) result of processing an asset

ProcessStatus

The final status of processing an asset

ProcessorState

The current state of the AssetProcessor.

ReadLogError

An error that occurs when reading from the ProcessorTransactionLog fails.

ValidateLogError

An error that occurs when validating the ProcessorTransactionLog fails.

Traits

ErasedProcessor

A type-erased variant of Process that enables interacting with processor implementations without knowing their type.

Process

Asset “processor” logic that reads input asset bytes (stored on ProcessContext), processes the value in some way, and then writes the final processed bytes with Writer. The resulting bytes must be loadable with the given Process::OutputLoader.

Type Aliases

LoadAndSaveDeprecated

A flexible Process implementation that loads the source Asset using the L AssetLoader, then saves that L asset using the S AssetSaver.

LoadAndSaveSettingsDeprecated

Settings for the LoadAndSave Process::Settings implementation.