Byte Engine Docs
Resources

Use BELD

Bake, inspect, and query resources with BELD.

Use BELD to bake, inspect, query, and delete Byte Engine resources.

Install BELD before you run the commands on this page. Every flag, default, exit code, and output format is in the BELD command line reference.

It reads source assets from an assets directory and writes processed resources to a resources directory. By default those paths are assets and resources, but both are configurable.

beld --source assets --destination resources bake

Run the commands

beld bake processes asset IDs into resources. If you omit the IDs, BELD finds every supported source file below the source directory. It follows symlinks, preserves their logical paths as resource IDs, rejects broken links, and avoids directory cycles. BELD ignores .bead sidecars and unknown files. A standalone .besl source needs an adjacent .besl.bead file for discovery. BELD processes the discovered IDs in deterministic path order and runs independent asset work concurrently.

BELD skips an asset when its stored resource is current with every source file it was baked from, so running beld bake again only processes what changed. Use --force to rebake the selected assets anyway, together with the textures, materials, and other resources they depend on. Force a bake after you update BELD's asset processors or change --texture-compression, because BELD only tracks source file versions:

beld --source assets --destination resources bake --force

To bake only selected assets, provide their IDs explicitly:

beld --source assets --destination resources bake mesh.glb character.fbx material.bema

By default, BELD stores each binary payload in a separate file. Use packed storage when you want one payload file for packaging or distribution:

beld --source assets --destination resources --storage-mode packed bake

BELD records the selected mode in the resource database. Later bake, inspect, query, and delete commands discover that mode automatically. If the destination already exists, --storage-mode must match it. Clear the destination before selecting another mode.

Quote glTF or FBX subresource IDs so the shell doesn't treat their fragment as a comment:

beld --source assets --destination resources bake \
  'character.glb#skeleton' \
  'character.fbx#animations/Walk'

beld list prints stored resource IDs.

beld inspect prints metadata for a resource ID or UID. Use --format json when editor tooling or scripts need structured output. In development builds, the output also includes the resource's bake trace. You can inspect a failed asset by ID even when it produced no resource. In that case, the output contains resource: null and the trace that explains the failure.

beld query filters resources by class and indexed properties. The first equality predicate can use the property index, and paged results print a cursor when more results are available. In development builds, every human-readable and JSON query result includes its bake trace. Release builds omit trace storage and output.

beld delete removes resources by ID.

beld clear and beld wipe remove the resources directory and recreate it.

BELD continues baking after an individual asset fails, but the command exits with status 1 if any selected asset failed. A successful command logs the total elapsed bake time and success/failure counts.

Check what a bake produces

Use a dry run to see the resources an asset bakes into without writing them to your resources directory. BELD bakes the asset and everything it depends on in memory, prints the result, and leaves the destination untouched:

beld --source assets bake --dry-run --format json character.glb

Add --payload typed to include each stream's data as JSON values, such as vertex positions, texels, audio frames, and LUT entries. Use --payload base64 when you need the exact bytes. Both need --format json:

beld --source assets bake --dry-run --format json --payload typed character.glb \
  | jq '.resources[] | select(.class == "Mesh") | .streams[] | select(.name == "Vertex.Position") | .data[:3]'

Animation clips already print their keyframes under resource.tracks, so you don't need --payload to read them. Name the clip's ID to bake it:

beld --source assets bake --dry-run --format json 'character.fbx#animations/Walk'

To read the data of a resource you already baked, add the same --payload option to beld inspect. Logs go to standard error, so you can redirect the output to a file or pipe it to another tool. The payloads reference lists every stream format.

Control bake memory

BELD limits how much memory concurrent bake work can reserve. By default, the soft memory budget is half of the system memory available when beld bake starts, and never less than a quarter of the installed memory. For example, BELD uses a 6 GiB budget when 12 GiB is available at startup, and a 4 GiB budget on a 16 GiB machine under memory pressure.

Set an explicit budget in MiB when you need predictable behavior in CI, on a shared workstation, or on a dedicated bake machine:

beld --source assets --destination resources bake \
  --memory-budget-mib 4096

When the budget is full, BELD pauses new independent bake work. Active bakes and their dependencies continue so they can finish and release memory. BELD logs when it pauses and resumes.

The budget is soft rather than a strict process-memory cap. One large asset or active work can temporarily exceed it. This avoids a deadlock where every worker holds memory while waiting for another worker to release memory. Use a lower value to leave more memory for other applications, or a higher value when the bake machine has dedicated capacity.

Query resources

beld query Material
beld query Image name=textures/hero_albedo.png
beld query Variant --limit 20
beld inspect material.bema --format json

The query system supports string equality predicates over queryable properties. Every resource model gets a name property by default.

Choose when to use BELD

Use BELD when you need deterministic resource output:

  • Prepare assets before a release build.
  • Inspect the resources that an asset produced.
  • Check shader reflection metadata.
  • Rebuild resources after you change a processor.
  • Delete stale resources while you debug asset import.

During development, applications can also lazily bake assets at request time. BELD is still useful because it gives you a direct, scriptable view of the same resource storage.

Next, use BELD to bake your application's resources.

On this page