Byte Engine Docs

Startup parameters

Look up where startup parameters come from, how config.json, BE_ variables, and --name=value arguments set them, and every parameter the engine reads with its type, default, and effect.

An application starts with a list of named text parameters. This page specifies where they come from, how names and values are parsed, and every parameter the engine reads. The same project file feeds BELD, which reads the render feature flags from it; see Bake application resources.

Sources

Four sources are read in this order, and a later source replaces an earlier value with the same name:

OrderSourceRule
1The parameters the application passes in codeUsed as given.
2The project's config.jsonFound under the Cargo package directory in a debug build, otherwise beside the executable, never in the working directory. Nested objects flatten into dotted names, so a nested render, gtao, enabled and a single render.gtao.enabled key set the same parameter. Strings pass through; booleans and numbers become their text. Arrays, null, and a top-level value that isn't an object are errors, and a file that exists but can't be read or parsed stops startup. A missing file sets nothing.
3Environment variables starting with BE_The name drops BE_, replaces __ with ., replaces _ with -, and lowercases, so BE_PHYSICS__STEP_LANES sets physics.step-lanes. The value is used as is. A name containing a literal underscore can't be set this way.
4Process arguments starting with --The text after the dashes splits on =: the name is the first part and the value is the second part only, so --a=b=c sets a to b. Without = the value is empty. Every such argument becomes a parameter, and unknown names are accepted.

The final list is logged at the info level, values included. Lookup is an exact, case-sensitive match on the full name.

Values

A value is text that the reader converts:

ReaderAccepts
Booleantrue, TRUE, or 1 for true; false, FALSE, or 0 for false. A lenient reader counts any other text as false. A strict reader stops startup.
NumberThe type's own syntax. Unless the table says the value is ignored, an unparsable value stops startup with an error that names the parameter.
Runtime settingDelivered as a configuration event. A boolean accepts only true or false. A value that fails to parse is reported as not set through the inspector and doesn't stop startup. The same names can be changed later through the inspector.

Application

NameTypeDefaultEffect
log.leveltrace, debug, info, warn, error, or off; other text means offNot set, so the logger's own level applies, which RUST_LOG setsCaps the log level that prints.
tracePresence only; the value is ignoredAbsentPrints every tracing span and event at debug level or above to standard output.
messages.capacityBytes67,108,864The message bus storage.
resources.pathPath, relative to the working directoryresources under the application directoryWhere the resource store lives.
assets-pathPathassets under the application directoryThe source asset directory for on-demand baking. Debug builds only.
max-frame-ratePositive frames per second; invalid is ignoredNone, uncappedThe minimum interval between presented frames.
simulation-ratePositive steps per second; invalid is ignoredNone; the stepped loop uses 60The fixed simulation step. See Time and ticks.
render-on-demandLenient booleanfalseRenders only when something changed and waits in the window system while idle.
kill-afterTick countNoneCloses the application after that many ticks, without waiting while idle. Debug builds only; a release build ignores it.
metrics-outPathNoneWrites the metrics when the application closes: every retained tick as NDJSON when the extension is ndjson, otherwise the summary as JSON.
debug.streamslog, stdout, stderr, or a pathNone, so no stream opensWhere every entity data stream writes its records. See Debug data streams.
debug.streams.changes-onlyLenient booleanfalseWrites a data stream record only when the system's key for it changed.
inspector.portPort number6680The HTTP inspector's port on both loopback addresses. When the default is in use, the inspector serves on a free port the system picks and logs it as a warning; a port you set that is in use stops startup.
physics.step-lanesbodies:lanes pairs separated by commas, each lane count at least 12 lanes from 512 bodies and up to 4 from 4,000, never more than the fastest cores' threadsHow many lanes a physics step runs on, by body count. 0:1 keeps every step on the calling thread. See Physics.
artnet.bind-addressIPv4 address; invalid keeps the default0.0.0.0The Art-Net worker's bind address, with the dmx feature.
artnet.poll-targetIPv4 address; invalid keeps the default255.255.255.255Where Art-Net polls and output go.

Graphics device

Booleans here are lenient.

NameDefaultEffect
render.debugtrue in debug buildsGraphics API validation. When the instance can't be created with validation, the engine logs a warning and retries with every debug option off.
render.debug.dumpfalseAPI call dump.
render.debug.extendedfalseGPU-assisted validation.
render.debug.labelsThe value of render.debugObject labels and command debug groups.
render.ghi.features.mesh-shadingtrueRequests mesh shading from the device.
render.pipeline-cache.pathNone, so the driver manages its cacheA pipeline cache file. A missing file is fine; pipelines compiled during the run are appended when the renderer closes.

Renderer and loader

NameTypeDefaultEffect
render.startup.defer-sink-setupLenient booleanfalsePresents the first window frame before building the sink render pipelines.
render.swapchain.imagesPositive count; invalid or 0 is ignoredThe backend's choiceThe swapchain image count each window requests.
render.pipeline-compilation.threadsCount; invalid is ignoredHalf the available parallelism, clamped to 1 through 4Pipeline compilation threads.
render.loading.batch-windowMilliseconds, finite and zero or more; invalid is ignored4How long an upload batch collects requests. See the loading timeline.

Render features

These are strict booleans, read at startup and by BELD from config.json. They decide what the bake builds into the shaders and what the runtime creates; a feature left out of the bake stays off whatever a runtime setting asks.

NameDefaultEffect
render.gtao.enabledtrueGround-truth ambient occlusion in material shaders, its pipelines, and its pass.
render.ssgi.enabledtrueScreen-space global illumination and its pipelines.
render.contact-shadows.enabledtrueThe contact-shadow trace in the sun visibility resolve and its pipeline.

Visibility pipeline

Every value here is validated, and a bad one stops startup.

NameTypeDefaultEffect
render.shadow-maps.budget-mbPositive MiB128Shadow-map memory shared by every shadow-casting light.
render.shadow-maps.update-texelsPositive texels16,777,216Shadow-map texels drawn each frame. See shadow map updates.
render.geometry.vertex-capacityPositive count262,144Scene-wide vertices: every resident mesh's, plus each posed skinned instance's own.
render.geometry.vertex-index-capacityPositive count524,288Meshlet-local vertex indices.
render.geometry.triangle-capacityPositive count524,288Triangles.
render.geometry.meshlet-capacity1 through 16,777,2168,192Meshlets.
render.geometry.skinning-vertex-capacityPositive count262,144Bind-pose vertices for GPU skinning.
render.directional-shadows.distancePositive meters100How far directional shadow cascades reach.
render.directional-shadows.split-blend0 through 10.8The share of logarithmic versus even cascade splits.
render.directional-shadows.fittingreceivers or frustumreceiversWhat each cascade covers.
render.directional-shadows.resolutionA positive multiple of 162,048Cascade texels per side.

Runtime settings

These arrive as runtime settings, so a bad value is reported rather than fatal, and the inspector can change them while the application runs.

NameAcceptsDefaultEffect
render.pass.<name>enabled or bypassedenabledSwitches a render pass between its prepare and bypass paths. An update for a pass not installed yet waits for it.
render.gtao.radiusFinite number, zero or more1The ambient occlusion search radius in world units.
render.gtao.samples-per-ray1 through 324Samples along each ray.
render.gtao.radial-raysAn even number from 2 through 326Ray directions.
render.contact-shadows.distanceFinite number, zero or more0.15The reach of each contact-shadow ray in world units.
render.lod.biasFinite number, zero or more1Scales the on-screen error allowed when selecting a detail level.
render.lod.forceA level number, or offoffDraws one detail level for every mesh.
render.motion-blur.taps1 through 328Motion blur sample taps.

The enabled names of the three render features double as runtime settings with the same meaning. Pass names a default setup can install are bloom, motion-blur, smaa, lens-flare, exponential-height-fog, atmosphere sky (with a space), ui, and debug-meshes; a pass exists only when its setup function ran.

Other process inputs

InputEffect
RUST_LOGThe logger's filter, which log.level then caps.
CARGO_MANIFEST_DIRIn a debug build, the application directory that config.json, resources, and assets resolve against.
BYTE_ENGINE_D3D12_SDK_PATHOverrides the Direct3D 12 Agility SDK path on Windows.

There are no audio.* parameters; set gain in each audio graph.

Rust API

On this page