Use BELD

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

Install BELD before you run the commands on this page.

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

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.

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 does not 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.

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. For example, BELD uses a 6 GiB budget when 12 GiB is available at startup.

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 examples

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 currently supports string equality predicates over queryable properties. Every resource model gets a name property by default.

When to use it

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.