ASB asset readme

README.md

asb

asb is the reference implementation of an asset packing format.

asb format

The asb format, or "asset binary" format, is a specification of how to store assets efficiently in binary form. It is designed to be appended to other asb files. Files are keyed by path, which is saved in the asset as a 64-bit unique ID. Multiple assets with the same ID are considered to store the same logical asset. The application using asb must decide which version of the asset to use, depending on where it is located on disk.

(bytes: description)

--- ASSET
u32: length of asset, in bytes, including this length value
--- PREAMBLE
u32: length of preamble, in bytes, including this length value
u8: `asb` version
u64: asset ID
u16: asset version (incremented every time the asset is edited.)
u32: asset type
u8: asset type version
u32: reserved
--- HEADER
u32: length of header, in bytes, including this length value

u16: length of this key-value pair, in bytes, including this length value
u16: unique key
?: value
...
u16: length of this key-value pair, in bytes, including this length value
u16: unique key
?: value
--- DATA
?: value

The number one priority is very quick reading of assets, especially when indexing.

API

Very generally, APIs should implement the following actions:

• Writing an asset to disk
• Reading an asset from disk
• Indexing a list of assets stored in a single file, for faster by-ID asset loading in the future

asbResult asbAssetInit(AsbAsset *asset)

Initializes the asset to default values. The newly initialized asset is not valid, and must be populated with real data.

Returns ASB_SUCCESS.

size_t asbAssetWrite(AsbAsset *asset, FILE *f)

If f is not NULL, writes the binary format of asset to the file. Returns number of bytes written (or number of bytes that would be written, if f is NULL.

asbResult asbAssetGetById(AsbAsset *asset, FILE *f)

Reads the asset from f (assumed to be a valid file for reading) into asset.

asbResult asbAssetRead(AsbAsset *asset, FILE *f)

Reads the asset from f (assumed to be a valid file for reading) into asset.