Resources
Load and inspect runtime-ready data produced from assets.
Use resources as the runtime-ready data that your systems request, inspect, query, and load.
Each stored resource has two parts:
- metadata, stored as an archived
SerializableResource - binary payload bytes, stored as resource data
The metadata contains the public ID, hashed UID, resource class, binary size, content hash, serialized typed model, optional stream descriptions, and queryable properties. The binary payload contains the actual bytes consumed by a renderer, audio system, or other runtime system.
Typed references
ResourceManager::request<T>().await returns a typed Reference<T>.
The reference contains the typed resource metadata and a reader for the payload.
This split lets you:
- Inspect metadata without loading the complete binary payload.
- Resolve dependencies recursively before uploading bytes.
- Choose how to read payload bytes.
For example, a material reference resolves shader references and parameter resources. A mesh reference resolves primitive materials and exposes stream descriptions for packed vertex and index data.
Storage
The Redb storage backend stores metadata in resources.db. It supports two payload storage modes:
filesstores each resource payload in a separate hash-named file. This mode is the default.packedstores every payload in a reusable range ofresources.packand records each resource offset inresources.db.
One mode applies to the whole resource store. The backend records that mode when it creates the store and discovers it when the store is reopened. It rejects a conflicting mode instead of mixing payload layouts.
Packed replacements use copy-on-write publication so an interrupted bake cannot replace valid metadata with partial bytes. After publication, the backend reuses the old range when no mapped reader still owns it. Deletion also returns its range. The allocator merges adjacent free ranges, chooses the smallest range that fits, and grows resources.pack only when no free range is large enough. When you reopen the store, it reconstructs free ranges from the live offsets in resources.db, which also recovers space left by an interrupted bake.
Use one backend instance for a resource directory while it can be updated. Drop read-only backends and their mapped resource backings before reopening the directory for writing.
Repeated rebuilds with changing payload sizes can split free space into many small ranges. The backend warns you when a pack of at least 64 MiB has at least 32 free ranges, at least 25 percent of the file is free, and no single range holds half of that free space. Delete the resource directory and bake the application resources again when you see this warning.
The backend converts resource URLs into stable resource IDs for storage lookup. The backend also maintains class and property indexes so BELD and editor tools can query resources without scanning and deserializing everything.
Every model exposes at least a name queryable property by default.
Specific models can add more queryable properties as editor and tooling needs grow.
Streams
Some resources contain multiple logical byte ranges in one payload. Meshes are the common example: positions, normals, UVs, triangle indices, meshlet data, and other streams can live in one packed buffer.
StreamDescription names those byte ranges. Provide stream read targets when you
need selected streams instead of the complete payload.
Loading bytes
The default load path requests backing storage from the reader. For file-backed resources, that storage can be a mapped file. Use an explicit buffer, boxed buffer, or stream target when you need ownership or preallocated memory.
Use the default target when the consumer can borrow the backing storage directly. Use explicit targets when the consumer needs a specific allocation, lifetime, or stream layout.