Author assets
Write the material, flipbook, environment-map, and detail-level files that BELD bakes.
Write the source files that describe your content in JSON5, next to the images, models, audio, and shaders that your tools produce. This page shows one of each. Their fields and allowed values are in the asset formats, .bema files, and BEMX graphs references.
Declare a material
A material is two files: a .bemx graph that computes its surface, and a
.bema file that names the graph and gives its parameters their values.
Write the graph as a list of named nodes. Each input names the node that drives it, or holds a constant. This graph tints a texture by a color parameter:
{
nodes: [
{ name: "albedo", node: "image", texture: "albedo_map", type: "color3" },
{ name: "tint", node: "parameter", parameter: "color", type: "color4" },
{ name: "tint_rgb", node: "swizzle", in: "tint", channels: "rgb" },
{ name: "tinted", node: "multiply", in1: "albedo", in2: "tint_rgb" },
{ name: "surface", node: "surface", base_color: "tinted", roughness: 0.6 },
],
}Then declare the material. Its variables supply the parameters the graph reads, by name:
{
"domain": "World",
"type": "Surface",
"graph": "materials/tinted.bemx",
"variables": [
{
"name": "albedo_map",
"data_type": "Texture2D",
"type": "Static",
"value": "textures/bricks.png"
},
{
"name": "color",
"data_type": "vec4f",
"type": "Static",
"value": "Purple"
}
]
}A variant names its parent material and replaces the values it changes:
{
"parent": "materials/base.bema",
"variables": [
{
"name": "albedo_map",
"value": "textures/tiles.png"
},
{
"name": "color",
"value": "Red"
}
],
"transparency": "Opaque"
}Baking a material generates its shader from the graph for the active render
pipeline and bakes the textures its variables reference. Variants share their
parent's shader. At runtime, request the processed Material, Variant,
Shader, and Image resources rather than the .bema file.
Change a parameter at runtime
A Static variable's value is compiled into the material's shader. To change a
float, vec3f, or vec4f variable from code instead, mark it Dynamic; its
value becomes the default:
{
"name": "color",
"data_type": "vec4f",
"type": "Dynamic",
"value": [1, 1, 1, 1]
}Then send a SetMaterialParameter on the world's material parameter route,
either for one entity or for every entity that uses a material:
use byte_engine::rendering::SetMaterialParameter;
let parameters = app.world().channel::<SetMaterialParameter>();
// Only this entity turns red.
parameters.send(SetMaterialParameter::new(handle, "color", [1.0, 0.0, 0.0, 1.0]));
// Every entity drawn with this variant turns blue, unless it set `color` itself.
parameters.send(SetMaterialParameter::material("materials/tiles.bema", "color", [0.0, 0.0, 1.0, 1.0]));A value set on an entity stays until you set it again or delete the entity, and a value sent before the material finishes loading applies once it does. Variants that differ only in dynamic values share one pipeline. A variant can leave a dynamic variable out to keep its parent's default.
Declare a flipbook
List an image sequence and its playback rate in a .flipbook file:
{ "frames_per_second": 12, "images": ["char/run0.png", "char/run1.png"] }Baking the flipbook bakes its images too. Request it as
resource_management::resources::flipbook::Flipbook; its images arrive
solved, in playback order, ready to load. To pick the image a frame shows,
sample the loaded images with byte_engine::animation::flipbook::Flipbook and
the time that PipelineManager::prepare receives, so playback follows the
frame clock instead of the simulation rate.
Create an environment map
Create a standalone .environment.bead asset when you want image-based
lighting from a high-precision source image, such as a full-sphere EXR. For
studio.exr, create studio.environment.bead:
{
$schema: "byte-engine/schemas/environment.bead.schema.json",
source: "studio.exr",
}Baking it retains the source image and adds a diffuse irradiance cubemap and
eight roughness-prefiltered specular levels. Select studio.environment.bead
as the world environment and the visibility renderer loads the complete set.
Tune detail levels
Mesh processing builds detail levels for every rigid primitive, and the
renderer draws the coarsest level whose error covers at most a pixel. To tune
them for one model, add a lods object to its BEAD file, for example
Sponza.gltf.bead:
{
lods: {
enabled: true, // false keeps full detail only
max_levels: 8, // levels per primitive, counting full detail; 1 to 8
max_error: 0.25, // largest error of a level, as a fraction of the primitive's largest extent
lock_borders: false, // true keeps open borders in place
},
}Every key is optional. Set lock_borders to true when a model's primitives
meet along a border, as when one surface is split by material, and gaps show
between them at a distance. Locked borders simplify less.
Choose image mips and compression
Every image gets a mip chain, and albedo and normal maps are also
block-compressed. Images drawn at their authored size, such as UI art, don't
need the smaller levels. To change either step for one PNG or EXR, add an
image object to its BEAD file, for example icons/heart.png.bead:
{
$schema: "byte-engine/schemas/image.bead.schema.json",
image: {
mips: false, // store only the authored size
compression: false, // keep exact colors instead of BC7
},
}Every key is optional; a key you leave out keeps its default. For a glTF, GLB,
or FBX model, add the same keys under images in the model's BEAD file to
change every image the model contains. The
image settings reference lists the
defaults.