Load resources in debug builds
Load and process resources on demand in debug builds.
Use on-demand asset processing to shorten your debug development loop.
When a ResourceManager has an AssetManager installed, a missing or stale resource can be baked from its source asset during request().
Change an asset, run the application, and let Byte Engine produce the resource
when the application first requests it.
In release-style workflows, resources should already be baked. The runtime path can then read processed resources from storage without depending on source assets or asset processors.
Request flow
When you request a resource, Byte Engine follows this path:
- The caller asks the resource manager for a typed resource ID.
- The storage backend tries to read the processed resource.
- If an asset manager exists, it compares the stored source versions with the current assets.
- If the resource is missing or stale, the asset manager bakes the source asset.
- The baked resource is stored, read back, and solved into a typed
Reference<T>. - The caller loads payload bytes when it is ready.
Solving is recursive. A material can resolve shaders and parameter resources. A mesh can resolve material variants. The caller receives a resource tree that is already connected through typed references.
Cache invalidation
The Redb storage backend writes a .resource-management-version marker in the resources directory.
That marker is derived from the resource-management code hash.
When the signature changes, the backend deletes stale resources so old processed data does not silently survive processor changes.
Release applications open a matching store without writing to it.
If the marker does not match, the application clears the store before it reads resources.
Rebuild the directory with the matching BELD build before packaging.
Each baked resource also records the source versions used to produce it.
For local files, a version includes the file size and modification time.
It covers the source asset, its optional .bead file, directly loaded files such as glTF buffers and images, and transitive asset dependencies.
During a debug request, Byte Engine re-bakes only the resource whose recorded versions changed.
The payload hash remains separate. It identifies the baked resource data and does not decide whether a source asset is stale.
Allocation shape
The bake path accepts an allocator for generation-time buffers. BELD uses one arena per asset task. Several handlers keep decode and processing work inside the same task because allocator-backed source bytes cannot safely cross arbitrary thread boundaries.
This allocation pattern keeps asset processing practical without making temporary decode and import data long-lived.
Inspect bake messages
In a debug build, call ResourceManager::resource_trace after an asset bake.
The returned trace keeps information, warning, and error items under the requested resource ID.
It also keeps handler errors from failed bakes, even though resource storage has no successful resource to return.
Trace items stay in memory and are replaced the next time the same ID is baked. They do not enter the resource database or a release application.
Choose between lazy loading and BELD
Lazy processing is convenient, but it can hide work in the first frame that touches an asset. Use BELD when startup time, deterministic packaging, or editor feedback matters.
If a resource does not load in a debug build, check these items in order:
- the source asset path and extension
- whether the correct asset handler is installed
- whether dependent assets can also be baked
- whether the resources directory was invalidated and rebuilt
- whether the requested resource type matches the resource class stored in the cache