Byte Engine Docs

Asset formats

Look up the source formats Byte Engine bakes, how asset IDs and fragments name them, and the fields of each hand-written format.

An asset is a source file that Byte Engine bakes into one or more resources. This page lists the formats the standard setup accepts, how their IDs and fragments are written, and the fields of the formats you write by hand. To write those files, follow Author assets. To add a format or change a handler, read Asset processing.

Asset IDs

Asset IDs are written as resource-style paths. The file extension is part of the ID when selecting an asset handler, and a fragment can identify a sub-asset when a container format exposes many resources. For example, a glTF asset can produce mesh, skeleton, animation, material, image, and generated shader resources.

Source formats

The standard graphics setup bakes these formats:

  • PNG and EXR images
  • .environment.bead environment maps
  • glTF and GLB meshes, embedded images, skeletons, and skeletal animation clips
  • FBX meshes, skeletons, and skeletal animation clips
  • .bema materials and variants
  • .bemx material graphs, which .bema materials name
  • .pipeline GPU pipeline descriptions
  • .flipbook image sequences with a playback rate
  • .particles GPU particle systems, which bake into generated shaders and pipelines
  • LUT assets
  • WAV and OGG audio
  • standalone .besl shaders with .besl.bead stage metadata

JSON5

Byte Engine expects JSON5 wherever an asset format or sidecar uses JSON. Write comments and trailing commas in .bead, .bema, .bemx, and JSON glTF asset files. JSON5 also supports unquoted object keys, single-quoted strings, and other authoring conveniences.

Use ordinary JSON when you need compatibility with a tool that doesn't support JSON5. Otherwise, use comments to explain non-obvious asset settings and keep trailing commas so later edits produce smaller diffs. Read the JSON5 specification for the complete syntax.

Flipbooks

A .flipbook file is a JSON5 object with these fields:

FieldValue
frames_per_secondThe playback rate.
imagesThe image asset IDs, in playback order.

Baking a flipbook bakes its images and produces a Flipbook resource whose images are in playback order.

Detail levels

Mesh processing simplifies every rigid primitive into coarser detail levels, each with about half the triangles of the one before, until a level stops getting smaller, fits in about two meshlets, or reaches the level limit. Every level uses the primitive's own vertices. Each level records an error: the estimated largest distance, in model units, between it and full detail. The renderer draws the coarsest level whose error covers at most a pixel. Skinned primitives keep full detail only.

A model's BEAD file tunes its levels with a lods object:

KeyDefaultMeaning
enabledtruefalse keeps full detail only.
max_levels8Levels per primitive, counting full detail, from 1 to 8.
max_error0.25The largest error of a level, as a fraction of the primitive's largest extent.
lock_bordersfalsetrue 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. Each primitive is simplified on its own, so neighbors at different levels can otherwise pull apart by up to the sum of their errors. Locked borders simplify less.

Image settings

Every image gets a full mip chain by default, and albedo and normal maps are also block-compressed: normal maps to BC5, other compressed images to BC7. An image's BEAD file can change either step with an object of these keys:

KeyDefaultMeaning
mipstruefalse stores only the authored size, with no smaller levels.
compressiontrue for albedo and normal maps, false otherwiseWhether the image is block-compressed.

Every key is optional, and a key left out keeps its default. Packed metallic-roughness maps and half-float images, such as EXR, are never block-compressed, so compression has no effect on them. A standalone PNG or EXR reads the object from its image key. A glTF, GLB, or FBX model reads it from its images key and applies it to every image the model contains.

Turn mips off for images drawn at their authored size, such as UI art, and compression off for images whose exact colors matter more than their memory.

Environment maps

A standalone .environment.bead file generates image-based lighting from a high-precision source image. It's a JSON5 object with these fields:

FieldValue
$schemaOptional. byte-engine/schemas/environment.bead.schema.json, for editor completion.
sourceThe ID of the source image, relative to the application's assets/ directory. The image doesn't need to be a supported standalone image asset.

Use a full-sphere, 2:1 latitude-longitude image with at least 16-bit integer or floating-point precision. The environment decoder accepts EXR, Radiance HDR, 16-bit PNG, high-precision TIFF and PNM, and farbfeld sources. It rejects 8-bit images so quantization doesn't become baked lighting or reflections. The decoder converts supported nonlinear source metadata to linear light before it generates the lighting maps. Author TIFF and PNM sources in linear light because their decoders don't expose reliable transfer metadata. Untagged PNG and farbfeld sources are interpreted as sRGB.

Baking the environment asset retains the source image and adds a diffuse irradiance cubemap and eight roughness-prefiltered specular levels. The visibility renderer loads the complete set when the asset is selected as the world environment.

Sidecars

A sidecar is a JSON5 file named after the asset with .bead appended, next to it. A missing sidecar means defaults; one that can't be read fails the bake.

A file named .bead in a directory holds directory defaults: sidecar keys for every asset in that directory and the directories below it. An asset's settings are the .bead files from the asset root down to its own directory, then its sidecar, each merged over the ones before it. Objects merge key by key, and any other value replaces the one before it. A directory default that can't be read fails the bake of every asset that reads sidecars below it. Directory defaults don't make an asset discoverable the way an adjacent .besl.bead does.

Only these handlers read sidecars:

AssetKeyValue
glTF, GLB, FBXdefault_resourcemesh or animation, which the bare ID bakes as. Skeletons always need the #skeleton fragment.
glTF, GLB, FBXlodsThe detail level settings listed under Detail levels. Unknown keys fail the bake.
glTF, GLB, FBXimagesThe image settings for every image the model contains. Unknown keys fail the bake.
PNG, EXRimageThe image settings for the image. Unknown keys fail the bake.
glTF, GLB, FBXasset.<material name>.assetThe ID of a .bema variant to use for that material. Unnamed glTF materials can't be overridden; unnamed FBX materials use the key default.
FBXskeletonThe ID of the skeleton to bake against, instead of the file's own.
BESLstage, workgroup, maximum_mesh_threadgroups, maximum_vertices, maximum_primitives, layoutsThe stage metadata and layout layers specified in the BESL interface. The sidecar is required.

Every hand-written format has a JSON schema under the engine's assets/schemas directory: bema.schema.json, bemx.schema.json, besl.bead.schema.json, environment.bead.schema.json, image.bead.schema.json for the image sidecar, model.bead.schema.json for the model sidecar, and particles.schema.json.

Pipelines

A .pipeline file is strict JSON describing one GPU pipeline. Its name is free text and its type selects the fields:

typeFieldsDefaults
computeshader, the shader's asset ID; push_constants, a list of ranges with offset and size.No push constants.
rastershaders, a list of shader IDs; push_constants; vertex_elements, each with name, format, and binding; attachments, each with format, an optional layer, and blend; face_winding; cull_mode; fill_mode; depth_write.clockwise, back, solid, and depth writes on.
FieldValues
Vertex and attachment formatfloat, float2, float3, float4, u16, u32, rgba8_unorm, rgba16_unorm, rgba16_float, rg11b10_float, depth16, depth32
blendnone, alpha, premultiplied
face_windingclockwise, counter_clockwise
cull_modenone, front, back
fill_modesolid, wireframe

Baking a pipeline bakes each named shader.

Color lookup tables

A .lut or .cube file is a text table with TITLE, LUT_1D_SIZE or LUT_3D_SIZE, optional DOMAIN_MIN and DOMAIN_MAX, and comments starting with #. It bakes to a one- or three-dimensional LUT whose entry count is the size or the size cubed.

Skeletal models

glTF, GLB, and FBX use one import-neutral skeletal representation. A Skeleton stores transform nodes in parent-before-child order and preserves each node's rest-local translation, rotation, and scale. An Animation stores sparse translation, rotation, and scale curves against those dense node indices and references the skeleton it was authored for. Missing curves deliberately fall back to the skeleton's rest pose, which gives CPU animation sampling and blending a stable pose.

A mesh with skins or node animation references the same skeleton, and each primitive retains its dense transform-node index. This lets an animation graph apply rigid node motion without reconstructing source-file node ownership. Skinned meshes additionally store one skin binding per imported mesh instance. Each binding maps the palette-local indices in the Vertex.Joints stream to skeleton nodes and pairs them with adjusted inverse-bind matrices. The adjusted matrices account for the bind-pose transform already flattened into imported vertices, so a CPU-generated global pose can write a GPU palette as global_joint * adjusted_inverse_bind without reopening the source file. Rigid primitives have no skin binding, and mixed rigid/skinned source files retain primitive-local joint and weight stream offsets. FBX vertices without authored cluster weights use a mesh-node fallback palette entry, so they continue following animated mesh ancestors instead of freezing in bind space.

Container fragments address the generated subresources consistently:

  • character.glb#skeleton or character.fbx#skeleton selects the transform hierarchy.
  • character.glb#animation or character.fbx#animation selects the first clip.
  • character.glb#animations/0 selects a clip by zero-based index.
  • character.glb#animations/Walk selects a clip by exact name.

Without a fragment, FBX and glTF containers use a content-only default that's identical in debug baking and BELD:

  • A container with any mesh bakes as Mesh.
  • A container without meshes and with exactly one animation bakes as Animation and stores its dependency as #skeleton.
  • Containers with neither an uncontested mesh nor a single animation require an explicit fragment.

A sibling BEAD manifest can override the first two choices with "default_resource": "mesh" or "default_resource": "animation". An animation override still requires exactly one clip. Skeleton resources never become the unfragmented default and must always be requested through #skeleton.

The importers normalize weights to a fixed four-influence vertex format. FBX matrix-linear and rigid skins are supported. Files that require multiple layered skin deformers or dual-quaternion skinning are rejected instead of being approximated silently. glTF morph-weight channels aren't part of the skeletal clip representation and a selected clip containing them is rejected explicitly. Animated rigid or skinned mesh nodes must have an invertible bind transform because their vertices are stored in flattened bind space. The importers reject zero-scale bind transforms rather than irreversibly discarding geometry that a later animation would make visible.

The visibility renderer accepts complete global poses and uploads their derived skin palettes. Sampling, blending, and the animation graph that produce those poses are specified in the animation reference.

FBX

An FBX asset ID that defaults to a mesh bakes every polygon-mesh instance into one Mesh resource. The importer normalizes axes and authored units, triangulates polygon faces, preserves material parts, transforms instance geometry, and emits position, normal, tangent-frame, color, UV, joint, and weight streams when the source provides them. Meshes without authored UVs receive a zero-filled UV stream because the visibility renderer requires that stream even for untextured materials.

FBX material names can be mapped to existing variants in a sibling .fbx.bead file, using the same asset.<material-name>.asset shape as other model overrides. Without an override, the importer generates a material variant from constant base color, opacity, metalness, roughness, emission, and double-sided values. FBX material texture maps aren't imported yet.

FBX animation stacks are baked through the format's pivot, layer, and rotation-order rules before becoming engine curves:

  • character.fbx#animation selects the first animation stack.
  • character.fbx#animations/0 selects a stack by zero-based index.
  • character.fbx#animations/Walk selects a stack by exact name.

On this page