Module format 

Formats are plugins (ADR-0007, ADR-0019). An asset kind is a plain type (AssetKind): an image’s size, a palette, a dialogue file’s scenes. A format is a value that reads one kind from the bytes of one file (Format). Formats holds the formats of every kind; the engine’s standard ones are there from the start (Formats::standard), and a game registers its own kinds and formats at start-up. Code that uses an asset asks for its kind by id (Formats::load) and never sees which file it came from.

The rules of the registry:

• Lookup. For each file, the formats of the kind whose sniff says yes are tried first, in the order they were registered, then the one that claims the file’s extension. The first that decodes the file gives the asset; when none does, the errors are the first one’s.
• Conflicts. Within one kind, two formats may not have the same id or claim the same extension: Formats::register refuses the second with a message naming both, and Formats::replace puts it in place of the first. Different kinds may claim one extension (every RON file is .ron).
• Limits. A file bigger than its format’s max_bytes, or than the registry’s own Limits, is refused before it is decoded.
• One file. A format reads one file, and the files it names through DecodeCx. A check against another kind of asset (a scene against the game’s characters, a cinematic against its music) runs after, on the assets loaded.

A format may read settings for its file (ADR-0057, import_settings): a section of the .meta file beside it, or of a folder’s _folder.meta (DecodeCx::import_settings). The registry knows each section’s type (Formats::register_import_settings) and checks every settings file of a bundle (Formats::check_import_settings); no format may claim meta.

A front end may watch every decode the registry makes (watch_decodes): its kind, its file, its size and whether it read, told before and after each, on the thread that decodes. A debug build tags what each decode allocates with its kind this way, so the heap counter says what the game holds of each kind of asset.

Structs

AssetPath

Where a file is: its path in the bundle (relative to a layer’s root, /-separated), and the name errors show it by (base/images/a.png).

DecodeCx

What a format has besides the file it decodes: the limits, and the bundle the file is in, for the files it names (a sidecar’s picture, a manifest’s sounds). Without a bundle, every file named is missing.

DecodeWatch

What is told of every decode the registry makes, once set (watch_decodes): two plain functions, called on the thread that decodes. Build it with DecodeWatch::new (ADR-0039).

Decoded

One decode the registry made (Formats::decode), as a DecodeWatch is told it. Build it with Decoded::new (ADR-0039).

Formats

The formats of every kind (module docs).

Limits

How much a decoding may read, beyond each format’s own max_bytes.

Enums

RegisterError

Why a format, or a section of import settings, could not be registered. More reasons may come (ADR-0039).

Constants

DEFAULT_MAX_BYTES

The most bytes a format reads unless it says otherwise (Format::max_bytes): 16 MiB.

NOT_FOUND

What a file asked for and missing is told.

TEXT_MAX_BYTES

The most bytes the engine’s text formats read: 4 MiB, forty times the biggest text file of the game the engine was carved from.

Traits

AssetKind

A kind of asset: the plain type a Format reads into. The engine’s kinds are its own types (ImageInfo, PaletteDef, DialogueFile…); a game makes one of each of its data tables.

Encode

A format that can also write its kind: what tools and an optimized format derived from a source (ADR-0007 §4) use.

Format

A file format: reads one AssetKind from a file’s bytes.

Functions

decode_with

format’s asset in bytes (the file file), unless the file is bigger than format or cx allow.

join

name inside dir ("" for the root).

text

The text of a text format’s file bytes, or the error that it isn’t valid UTF-8.

watch_decodes

Tells watch of every decode any registry makes from now on (Formats::decode, so Formats::load and the rest): before as it starts, with its kind, and after once it is decided, with before’s token, the file and whether it read. For a front end that tags, logs or tallies what it loads. Set once: a second call gives its watch back and changes nothing.