Byte Engine Docs

BELD command line

Look up every BELD command, flag, default, exit code, and output format, and the file extensions its handlers bake.

BELD bakes source assets into a resource store and inspects the result. This page specifies its command line. To use it, follow Use BELD; the store it writes is specified in the resource store reference.

Global options

OptionDefaultEffect
-s, --source <path>assetsThe source asset directory.
-d, --destination <path>resourcesThe resource store directory.
--color auto, always, or neverautoTerminal color.
--storage-mode files or packedA new store uses files; an existing store keeps its modeThe persistence mode. A value that differs from an existing store's mode is an error.
-V, --version; -h, --help

BELD reads the RUST_LOG environment variable for its log filter.

Commands

CommandArguments and flagsEffect
bake [ids...]--force; --config <path>, default config.json in the working directory; --memory-budget-mib <n>, default half the available memory and never below a quarter of the installed memory; --texture-compression none or metal-io-lz4; --dry-run; --format human or json; --payload none, typed, or base64, default noneBakes the given IDs, or every discovered asset. --force rebakes the selection and its dependencies. Only the render feature flags are read from the configuration. --dry-run bakes into memory and prints the result instead; see Dry runs.
listPrints one resource ID per line, read-only.
inspect <id or uid>--format human or json; --payload none, typed, or base64, default nonePrints one resource's metadata and model, read-only. A 32-character hexadecimal argument is tried as a UID first.
query <class> [property=value...]--limit <n>, --cursor <hex>, --format human or jsonLists resources of a class matching every predicate, read-only, with a cursor when more remain.
delete <ids...>Removes each resource.
clear, wipeRemoves every resource and payload, keeping the store's mode.

A bake discovers every supported file below the source directory, follows symbolic links with cycle detection, skips sidecars and unknown files, and leaves out the pipelines and shaders of render features the configuration turns off. Explicit IDs always bake. Up to 16 assets bake at once, and each is skipped when its stored resource is current with every source file it was baked from.

Dry runs

bake --dry-run bakes the given IDs and every resource they depend on into an empty in-memory store, prints that store, and discards it. It reads the source directory and the configuration, and it doesn't read, create, or write anything under the destination directory.

RuleEffect
IDsAt least one ID is required; a dry run doesn't discover assets.
--force, --texture-compressionRejected with exit code 2. Every dry run bakes from scratch, and payloads stay uncompressed.
--destination, --storage-modeNo effect.
--memory-budget-mib, --configApply as in a normal bake.
--format, --payloadAccepted on bake only with --dry-run.
Exit codeThe same as a normal bake of the same IDs.

Exit codes

CodeMeaning
0Success.
1The configuration couldn't be read, the store couldn't be opened or its mode didn't match, a command failed, at least one baked asset failed, or at least one delete failed.
2Invalid arguments.

Output formats

OutputShape
inspect, JSONAn object with id, uid, class, hash, size, stored_size, encoding, serialized_resource_size, properties, streams, and resource, the model as JSON. Each stream has name, size, and offset. Debug builds add trace, the bake messages. A failed asset with only a trace prints resource as null.
inspect, humankey: value lines, nested objects indented by two spaces, arrays as dashed items.
bake --dry-run, JSONAn object with resources, every stored resource in the inspect JSON shape ordered by ID, and failed, one object per requested ID that failed, with id and error. Debug builds add trace to both.
bake --dry-run, humanThe same object in the inspect human layout.
query, JSONAn object with resources, each with id, uid, class, and properties, and cursor, null on the last page.
query, humanEach ID on its own line with its properties indented, then the cursor when more pages exist.

A cursor is the hexadecimal encoding of the page token. Models with a JSON form are animation, audio, image, LUT, material, mesh, primitive, shader, skeleton, and variant; flipbooks, pipelines, and particle systems print an unsupported marker.

Logs go to standard error, so standard output carries only the command's output.

Payloads

--payload adds each stream's bytes to the inspect and bake --dry-run output. Any value other than none requires --format json; other combinations exit with code 2.

ValueEach stream adds
noneNothing.
typedencoding json, element, and data, an array of decoded elements, when the stream's layout appears in the next table. Otherwise the stream falls back to base64.
base64encoding base64 and data, the stream's decoded bytes as one padded base64 string in the standard alphabet.

A resource whose payload has no named streams but isn't empty, like audio or a LUT, prints one stream named payload that covers all of it. Bytes are always the decoded payload, never the stored compressed form. A payload stored with metal-io-lz4 compression can't be read on the CPU, so inspect exits with code 1.

ClassStreamelementEach element in data
MeshVertex.Position, Vertex.Normal, Vertex.Tangent, Vertex.BiTangent, Vertex.UV, Vertex.Color, Vertex.Joints, Vertex.WeightsThe vertex component format, such as vec3fAn array of the format's component count.
MeshVertexIndices, TriangleIndicesu16An integer.
MeshMeshletIndicesu8An integer.
MeshMeshletsmeshletAn object with vertex_count, triangle_count, center, radius, cone_apex, cone_cutoff, and cone_axis.
ImageEvery streamThe stream's texel format, such as RGBA8An array of channel values.
AudiopayloadframeAn array with one sample per channel.
LUTpayloadrgbAn array of three numbers.

Elements appear in stream order, and image texels appear row by row from the top-left texel. An image stream uses the format of the image-based lighting level it belongs to, or the image's own format.

Element typeValues
f and f16 vertex components; R16F and RGBA16F texels; LUT entriesThe shortest decimal that reads back as the same 32-bit float. Half-precision values widen to 32 bits first. NaN and infinities print as null.
u16 and i16 vertex components; u and i vertex componentsIntegers.
RG8, RGB8, RGBA8, and RGBA8SRGB texelsIntegers from 0 to 255, sRGB-encoded where the format is.
RG16, RGB16, and RGBA16 texelsIntegers from 0 to 65535.
BC5, BC5SNORM, BC7, and BC7SRGB texelsNo element; the stream falls back to base64.
8-bit audio samplesUnsigned integers from 0 to 255, centered on 128.
16-, 24-, and 32-bit audio samplesSigned integers of that width.

Handlers

ExtensionResource
bemaMaterial or variant
fbxMesh, skeleton, animation, materials, images
gltf, glbMesh, skeleton, animation, materials, images
pngImage
exrImage, linear, half-precision
iesImage, a photometric profile
environment.beadImage with image-based lighting maps
pipelinePipeline
flipbookFlipbook
particlesParticle system and its pipelines and shaders
lut, cubeLUT
wav, oggAudio
besl, with a .besl.bead sidecarShader

Extensions match regardless of case for FBX, EXR, IES, and environment maps.

On this page