Asset processing
Implement and debug Byte Engine asset handlers and source formats.
Use this page when you add a source format, change an asset handler, or diagnose the data that a handler produces. Read the resource-management reference first if you need the distinction between assets and resources.
The formats the handlers accept, with their asset IDs, fragments, and sidecar settings, are listed in the asset formats reference.
When you edit a glTF or FBX file and rebake it, unchanged generated shaders are reused instead of compiled again.
A generated shader compiles again only when its material graph, the render pipeline's shader generator, the shader backend, or the installed shader compiler changes.
To force every stored shader to compile again, call AssetManager::rebuild_resources_baked_before and then AssetManager::bake_if_stale.
Asset handlers
An AssetHandler bakes one family of source files. The asset manager selects a
handler from the asset type or extension.
Handlers store the requested resource through their BakeContext after all generated dependencies are ready.
The context keeps source resolution, recursive baking, allocator-aware resource writes, and storage errors consistent across formats.
Each stored resource contains typed metadata plus the binary payload that consumers later upload, stream, decode, or play.
When your handler needs adjacent .bead settings, call context.load_sidecar(id) explicitly.
context.resolve(id) returns only the source bytes and asset type. BESL, FBX, glTF, PNG, and EXR handlers request sidecars. Other handlers read their sources independently.
let (source, asset_type) = context.resolve(id).await?;
let settings = context.load_sidecar(id).await?;The sidecar helper parses JSON5, merges the directory defaults under the sidecar, and returns None when none of those files exist.
It records each file's ID as a dependency, including its absence, so creating, editing, or removing any of them makes the resource stale.
A sidecar that your handler doesn't request has no effect on baking or freshness.
Custom source backends provide the same utility through StorageBackend::load_sidecar, which reads each file with StorageBackend::load_bead; implement version for individual files and return AssetVersion::missing() only when a file doesn't exist.
Directory defaults
A .bead file in a directory gives sidecar keys to every asset below it, so a folder of animation clips names its skeleton once instead of repeating it in a sidecar per clip.
Settings that depend on where an asset is used, not on its contents, belong in the folder: a clip carries its own copy of the joint hierarchy, not a link to the rig it was authored for, so the bake can't infer the rig from the file.
StorageBackend::load_sidecar builds the settings, and nothing else does.
It reads the root's .bead, then each directory's down to the asset's own, then the asset's sidecar, each through StorageBackend::load_bead, and merges every file over the ones before it: objects key by key and recursively, any other value by replacement.
Handlers see one merged object and can't tell which file a key came from, so a key means the same whether it's set per asset or per directory.
Keep these rules when you change it:
- Every file the merge consults is a bake dependency, present or absent.
TrackingStorageBackendoverridesload_bead, notload_sidecar, so each layer goes throughtrackedon its own. The watcher needs nothing extra, since a change toanims/.beadreports that ID and the resources that depend on it rebake. - The more specific file wins. Don't stop at the first file found; layers combine, so a sidecar can override one key of its directory's
imagesobject and keep the rest. - Directory defaults configure assets; they don't select them. Discovery still asks for an adjacent sidecar, through
AssetSource::has_sidecar, so a folder default doesn't turn every.beslbelow it into a standalone shader. A.beadfile has no asset type, so discovery never offers it as an asset. - Handlers read keys by name and ignore keys they don't know, which a folder shared by different formats relies on. Strict parsing belongs to each key's value, such as
lodsorimages, never the whole object.
directory_defaults_merge_under_the_sidecar_from_the_root_down in storage_backend.rs guards the order and the merge, and lazy_baking_reuses_fresh_assets_and_rebakes_changed_sources_and_sidecars in manager.rs guards freshness when a directory default is created or edited.
Trace asset baking
Use BakeContext::info, BakeContext::warn, or BakeContext::error when a handler needs to explain a bake decision or problem.
Pass format_args!(...) when the message includes values so release builds don't allocate a temporary string for the terminal log.
Debug builds keep these ordered items in a resource trace under the requested resource ID. The latest bake replaces older items for that ID. An error remains in the trace when the handler fails before it can store the resource, so an editor can explain the failure without treating the asset as successfully baked. For example, the FBX handler records one information item with the number of degenerate triangles, quads, and other polygons it culled.
Read the trace through AssetManager::resource_trace or, after installing the asset manager, ResourceManager::resource_trace.
Call ResourceTrace::items for one ID or ResourceTrace::resource_ids to find IDs with messages.
The trace is an in-memory development tool: release builds don't expose it, and trace items are never stored as production resources.
Processing
Asset processing turns source data into engine data.
Image processing decodes pixels, infers semantics from names such as albedo, normal, roughness, or emissive, chooses gamma, and can convert to GPU-friendly formats.
Standalone PNG data textures, such as normal or roughness maps, stay linear even when an image editor added sRGB metadata.
For color textures, supported sRGB or linear PNG metadata overrides the filename default. An unsupported transfer function falls back to the inferred semantic.
EXR images keep their linear HDR values in an RGBA16F image and don't generate lighting maps by default.
By default every image gets a full mip chain, whatever its source format, and albedo and normal maps are also block-compressed. Lookup tables such as IES intensity maps keep one uncompressed level. Byte Engine filters 8-bit levels on the GPU and also compresses color textures to BC7 there, with a BESL kernel that uses the same search as the CPU encoder's fast profile. Sixteen-bit and half-float chains, and every chain without a compatible GPU, are filtered and compressed on the CPU, at comparable quality.
A glTF metallic-roughness texture that every material in the file reads only through its green and blue channels is stored as a two-channel RG8 image, or RG16 from a sixteen-bit source, holding roughness in red and metallic in green. The generated materials read those channels, so the image samples the same values it did with all four channels. An image that a material also reads through another channel, such as an occlusion-roughness-metallic texture, keeps all its channels. This layout is part of the image fragment's contract: a hand-written material that samples model.gltf#images/<index> for metallic and roughness must read red and green.
Mesh processing normalizes vertex layout, packs streams, creates meshlets, records bounding boxes, associates primitives with material variants, and preserves primitive skin bindings.
Mesh processing also builds detail levels. It simplifies each primitive into coarser versions, 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 and is stored as extra meshlets after the full-detail ones, so levels add vertex indices, triangles, and meshlets but no 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.
One processor per resource type
Every resource type has one processor, and every handler that produces that type uses it. A handler's job ends once it has decoded its source into the type's canonical source and chosen its settings: an ImageSource with a Semantic, gamma, and ImageProcessorSettings for images, MeshPrimitiveSource values for meshes, an AudioDescription with samples for audio. The processor decides everything after that. For images, that's channel packing, the mip chain, block compression, environment lighting, the stream layout, and the stored Image metadata.
This keeps two rules true, so preserve them when you change a handler or a processor:
- The same pixels with the same semantic and settings bake to the same image, whether they came from a PNG, an EXR, or a glTF or FBX texture. A step such as mip generation can't be present for one format and missing for another.
- A handler holds no processing backend. The asset manager owns the
ImageProcessor, which holds the mip and environment-lighting generators, and handlers reach it throughBakeContext::image_processor. Install GPU backends once withAssetManager::set_image_processor; a new manager processes on the CPU.
To add an image format, decode it into an ImageSource and call ImageProcessor::process_in, then name the result with ProcessedImage::into_asset and store it. Don't build an Image yourself. The Semantic decides the stored format and channel packing. ImageProcessorSettings decides the optional steps: whether the image gets a mip chain and whether it's block-compressed. Start from ImageProcessorSettings::for_semantic for a sampled texture, or ImageProcessorSettings::LOOKUP for a table read at exact coordinates. Authors override these through the asset's sidecar: read it with image_settings, which takes the image key for a standalone image or the images key for a model, so every format honors the same image settings. When your decoder writes into a buffer it owns, hand that buffer over with ImageProcessor::process_owned_in instead of lending it. When the decoded bytes already are the stored format, the processor keeps the buffer as the stored image and filters the mip chain into it after the base level, so the pixels are never copied. Reserve ImageProcessor::in_place_capacity bytes before decoding: the bake arena can't grow a buffer without copying it, and memory it frees isn't reused until the bake ends. The PNG, EXR, and IES handlers work this way.
When your handler knows metadata the pixels don't carry, such as the IES photometric scale, set it on ProcessedImage::image before storing.
When a step should apply to more images, add it to the processor, not to the handlers that need it. If a processor needs a backend, such as a GPU worker, the asset manager owns it the way it owns the image processor.
The image processor tests cover format, packing, mip, and compression decisions against ImageSource inputs. Handler tests cover decoding and the semantic, gamma, and settings each format chooses.
When you write a mesh importer, pass a MeshLodSettings to MeshProcessorSession::new; MeshLodSettings::default() gives the defaults listed under detail levels.
Have each MeshPrimitiveSource return a material slot, an index into a material list you resolve separately. Geometry doesn't depend on material contents, so you can process primitives while their materials and textures bake, as the glTF and FBX handlers do. Pass the resolved materials, in slot order, to the session's finish call.
Material and standalone shader processing compile BESL to platform-native shader artifacts and store reflected interface metadata such as descriptor names, slots, access, and workgroup size.
Allocation shape
The bake path accepts an allocator for generation-time buffers. BELD uses one arena per asset task. Several handlers keep decode and processing work inside the same task because allocator-backed source bytes can't safely cross arbitrary thread boundaries.
This allocation pattern keeps asset processing practical without making temporary decode and import data long-lived.