Bake application resources
Turn an application's source assets into deterministic runtime resources with BELD.
Use BELD to turn your source assets into the complete resource store that a release application loads.
Keep source assets separate from baked runtime resources:
my-app/
assets/ # authored source files and linked engine assets
byte-engine -> ../path/to/byte-engine/assets
resources/ # BELD output used by release builds
src/Keep engine-owned shaders in the engine crate. Expose them in your application's asset namespace with a directory symlink:
ln -s ../../Byte-Engine/crates/byte-engine/assets assets/byte-engineThe logical symlink path is retained in resource IDs, so assets/byte-engine/rendering/sky.besl becomes byte-engine/rendering/sky.besl. BELD follows linked files and directories and detects directory cycles. Broken or inaccessible links fail the bake instead of silently producing an incomplete release resource set.
The engine crate package includes its assets/ directory. For a registry dependency, vendor the resolved crate source and point the same application symlink at that vendored assets/ directory. This keeps the link target stable instead of depending on Cargo's registry cache layout:
cargo vendor --locked vendor
ln -s ../vendor/byte-engine/assets assets/byte-engineCommit both the vendor directory and symlink, or recreate them in the same bootstrap step in every developer and CI checkout. Install the matching BELD release so its handlers and resource formats stay aligned with the engine:
cargo install beld --version 0.2.0 --lockedOn Windows, the checkout must preserve directory symlinks. Enable Developer Mode or otherwise grant link creation permission, and make sure Git doesn't materialize the link as a plain text file. The current automated symlink coverage runs on Unix hosts.
Run BELD from your application directory. Pass absolute source and destination
directories. Asset IDs remain relative to assets/.
cd my-app
beld --source "$PWD/assets" --destination "$PWD/resources" \
bakeWith no IDs, BELD recursively discovers all supported source assets, including linked engine shaders, standalone .environment.bead assets, images, meshes, materials, and audio. Unknown files and BEAD sidecars are skipped, and .environment.bead files count as standalone assets rather than sidecars. A standalone .besl file is discovered only when its adjacent .besl.bead exists. This keeps material-internal BESL sources out of the standalone shader pass. Explicitly requesting a .besl file without its sidecar fails the bake.
BELD gives concurrent bake work a soft memory budget equal to half of the system memory available when the command starts. Override the budget in MiB when a CI runner or shared workstation needs more headroom:
beld --source "$PWD/assets" --destination "$PWD/resources" bake \
--memory-budget-mib 4096BELD pauses new independent work when the budget is full, while active bakes and their dependencies continue until they release memory. One large asset can temporarily exceed the budget. See Control bake memory for sizing guidance and the deadlock-safety reason for using a soft limit.
Use explicit IDs when a container fragment is required. Quote an ID containing a fragment so the shell preserves it:
beld --source "$PWD/assets" --destination "$PWD/resources" bake \
'character.glb#skeleton' \
'character.fbx#animations/Walk'The command writes the resource database and its payload files to resources/. These files, rather than the source assets/ directory, are what a release application reads. Their layout is specified in the resource store reference.
Use packed storage when you want all binary payloads in one resources.pack file:
beld --source "$PWD/assets" --destination "$PWD/resources" \
--storage-mode packed bakeThe default files mode writes one extensionless payload file per resource. Its basename contains the resource ID, decoded hash, and encoding. BELD records the selected mode and each resource's payload encoding in resources.db, and the application discovers them when opening the store. Clear the destination before changing its mode.
In packed mode, rebuilding or deleting a resource returns its old range to a coalescing free-space allocator after active mapped readers release it. BELD reuses the smallest suitable range and grows resources.pack only when none fits. If BELD warns that the pack is fragmented, delete the destination resource directory and run the bake again to produce a compact pack.
Shader payloads are target-native: BELD writes SPIR-V on Linux, DXIL on Windows, and Metal libraries on macOS. The authored shader sources remain BESL; only Metal lowers the task-payload features used by the visibility task and mesh stages. Run the matching BELD build on the platform targeted by the packaged application; a resource directory baked for another platform isn't portable.
Leave render features out of the bake
Use your project's config.json to leave optional render features out of
both the baked shaders and the running application. You can leave out
ground-truth ambient occlusion (GTAO), screen-space global illumination
(SSGI), and contact shadows. Put the file in the
application directory, next to assets/ and resources/:
{
"render": {
"gtao": { "enabled": false },
"ssgi": { "enabled": false },
"contact-shadows": { "enabled": false }
}
}BELD reads config.json from the current directory, so run it from the
application directory or pass --config:
beld --source "$PWD/assets" --destination "$PWD/resources" bake \
--config "$PWD/config.json"When you set a feature's enabled value to false, BELD bakes shaders without
its code and skips its pipelines:
| Feature | Code left out | Pipelines skipped |
|---|---|---|
render.gtao.enabled | GTAO occlusion in material shaders | gtao, gtao-blur-x, gtao-upscale |
render.ssgi.enabled | SSGI lighting and its diffuse light output in material shaders | ssgi-trace, ssgi-temporal |
render.contact-shadows.enabled | The contact-shadow filter in sun-visibility.besl | contact-shadows |
The application reads the same file at startup and doesn't create the left-out passes. Turning a left-out feature on at runtime logs a warning instead.
A missing file keeps every feature. The application also loads every other value
in config.json as a startup parameter, so {"render": {"debug": true}} sets
render.debug. Environment variables and command-line arguments still override
the file.
After you change a feature in config.json, run beld bake --force. Source
file versions don't record the configuration, so a normal bake keeps the
material shaders built with the old setting.
Check the baked output
Inspect the output before you package the application:
beld --destination "$PWD/resources" list
beld --destination "$PWD/resources" inspect scene.glbRun beld bake again after changing a source asset. BELD rebakes only the assets whose source files changed. After updating an engine asset processor or a feature in config.json, run beld bake --force instead, because those changes don't change source file versions. Baking requested IDs updates their generated output but doesn't remove unrelated old resources. Use beld clear only when you intentionally want to discard the entire resource directory.
Use resources in development and release
Debug applications can install an AssetManager and bake missing assets on demand. Release applications have no asset-processing fallback: they read the complete resources/ directory prepared by BELD and fail when a requested shader is absent. Keeping baking as an explicit pre-package step makes releases reproducible and avoids shipping source assets solely for runtime processing.
Next, build and bundle your application with the baked
resources/ directory.