Module blob 

The .cnb blob container format.

Layout of a blob binary:

[ 4 bytes magic ][ 4 bytes validity token ][ 8 bytes meta_len ][ meta_bytes ][ payload_bytes ... ]

The header is fixed at 16 bytes. The container is generic over its metadata type through BlobKind, which names the magic a file of that kind carries: BlobMeta is the cooked world, CacheMeta a segment of regenerable cache. The magic belongs to the type rather than to the encode and parse functions, so no file can be read as a kind it was not written for. The validity token is a value the writer stamps and the reader must match, with a meaning the kind owns: BlobMeta uses crate::SCHEMA_VERSION, CacheMeta its own index layout version.

meta_len is the byte length of the postcard-serialized metadata that follows: for BlobMeta, the component defs stream and the resource records stream. Everything after meta_len + meta_bytes is the raw payload section, addressed by the (blob_index, offset, length) fields inside each BlobAssetDef / ResourceRecord.

Blob 0 is the primary blob. It always holds the full metadata and may also hold payload bytes for assets packed before the size ceiling. Overflow payloads spill into blobs 1, 2, … as needed. All blobs share the same header format; only blob 0 carries non-empty metadata.

This module owns the format contract and nothing else: the record schema, the header consts, the kind trait, and the pure bytes <-> metadata transforms. It performs no I/O and holds no residency policy, so it never learns where blob files live or which of them are resident. Callers own both: concinnity_host::store reads the state root’s data/ layout into BlobData, concinnity-cook writes what encode_cnb returns. Being I/O-free is what lets a no_std client runtime decode blobs with its own byte source.

Nothing here needs to change when a new asset type is added.

Re-exports

pub use crate::ecs::PayloadLocator;

pub use crate::ecs::asset_id::AssetId;

Structs

BlobAssetDef

One component record in the blob’s def stream.

BlobMeta

The blob’s metadata section: the component stream, the resource stream, and the manifest summarizing them, postcard-serialized together as the block the header’s meta_len measures. Folding everything into one block keeps the 16-byte header and every payload-offset computation (payload_section_start, the lock’s payload_bytes) unchanged; only the block’s contents grew. Blob 0 carries the full metadata; overflow blobs carry an empty BlobMeta (whose default manifest is consistent with its empty streams).

CacheEntry

One cached artifact: which producer owns it, what it is valid for, and where its bytes sit in the payload section.

CacheMeta

A cache segment’s metadata block: the index of everything its payload section holds.

MeshBoundsRecord

Baked geometry summary of one static mesh payload, keyed by its unified mesh-source handle. Lets the runtime build draw records (AABB) and size geometry reservations (counts) without decoding the payload; a payload with no record decodes eagerly.

PhysicsBudgetRecord

The bodies a world’s physics reserves, counted by cook from the authored content and grouped by the kind of body the simulation builds for it. The runtime reserves exactly this at load and refuses to exceed it; debug builds re-derive it from the loaded components and assert the two agree.

ResourceRecord

One entry in the blob’s resource stream: a compiled resource addressed by its dense per-kind handle, carried alongside the component stream. resource_kind selects the per-kind table (ResourceKind as u8); handle is the dense index within that kind (== the record’s position within its kind). A payload resource (mesh, texture, audio clip) carries a PayloadLocator into the blob payload section; a data resource (a baked Material) carries its runtime bytes in data_bytes. Both fields are present so either shape round-trips; a given kind uses one branch (AudioClip uses payload).

SceneGroup

One scene’s exclusively-owned blob content: the resource-stream entries and payload-carrying component defs reachable only from that scene’s members. Content shared between scenes (or used outside any scene) belongs to no group and loads with the world. Groups are listed in scene declaration order; their payloads are packed into dedicated blobs after the global set.

WorldManifest

A verified summary of the blob’s shape, produced by cook from the final record streams and carried alongside them in the metadata block. The runtime trusts it (debug builds re-derive and assert it matches): the per-type counts pre-size the ECS columns before the bulk component load, and max_blob_index names the overflow files without scanning either stream. Anything further (type presence, feature flags) is deliberately not duplicated here: it is a counts lookup away.

Enums

AssetKind

The blob carries only components: every system is internal client code, constructed at runtime from world content, never serialized. This kind is kept as the single discriminator the blob format records per asset.

BlobError

Why a blob image did not parse or encode.

CacheEntryKind

Which producer an entry belongs to.

FrameError

Why a length-delimited postcard frame did not decode.

ResourceKind

The kinds of resource the runtime keeps in per-kind tables, one dense handle space per kind. The #[repr(u8)] discriminant is the resource stream’s resource_kind tag (like ComponentTag for components); cook writes it and the runtime selects the table by it. Order is the assignment order cook uses.

Constants

BLOB_MAGIC

The four magic bytes a cooked-world .cnb blob starts with, the BlobKind magic of BlobMeta. A cache segment carries CACHE_MAGIC instead.

CACHE_MAGIC

The four magic bytes a cache segment starts with, the BlobKind magic of CacheMeta.

CACHE_SEGMENT_VERSION

The validity token a cache segment’s header carries: the layout version of CacheMeta and of the payload addressing its entries use. postcard cannot tell a layout change from valid bytes, so a segment stamped with another value is regenerated whole rather than decoded.

HEADER_SIZE

Fixed blob header size, the same for every kind: magic (4) + validity token (4) + meta_len (8).

Traits

BlobKind

A .cnb container kind: a metadata type paired with the magic bytes that identify a file carrying it.

Functions

decode_exact

Decode bytes as a postcard frame of T, requiring T to consume every byte of it.

encode_cnb

Encode a blob image: the 16-byte header, the postcard-serialized metadata block, then the raw payload section.

encode_cnb_prefix

Everything an image carries before its payload section: the 16-byte header and the metadata block.

parse_cnb

Parse a blob image’s header and metadata block. Returns the metadata and the offset at which the payload section begins.

parse_payload_section_start

Payload-section offset read from the header alone, so a caller holding only the first HEADER_SIZE bytes can turn a PayloadLocator offset into an absolute file offset without loading the image.

payload_section

The payload section of a full blob image.