Bake application resources

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-engine

The 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-engine

Commit 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 --locked

On 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" \
  bake

With no IDs, BELD recursively discovers all supported source assets, including linked engine shaders, environment maps, meshes, materials, and audio. Unknown files and .bead sidecars are skipped. 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 4096

BELD 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.

Use packed storage when you want all binary payloads in one resources.pack file:

beld --source "$PWD/assets" --destination "$PWD/resources" \
  --storage-mode packed bake

The 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; currently 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 is not portable.

Check the baked output

Inspect the output before you package the application:

beld --destination "$PWD/resources" list
beld --destination "$PWD/resources" inspect scene.glb

Run beld bake again after changing a source asset or an engine asset processor. Baking requested IDs updates their generated output but does not 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.