Module pack 

The pack (.shuyipak, ADR-0007 §4, ADR-0023): the optimized format a game may ship in place of its loose files. shuyi bake turns the sources into one file, and the game lays it in its bundle like any other layer (Pack::into_layer), under its loose files or alone.

A pack holds every file of the bundle it was baked from, each at its own path:

• a baked file holds the assets read from its source, already in their binary form (postcard, one section per kind it was read as), so loading it parses no text. Packed is the format that reads one: a game registers it for every kind it bakes (Bake::register);
• every other file (a picture, a sound) holds its own bytes.

The file is a header (magic bytes, the VERSION, a checksum of the rest), an index (the stamp, the target, the fingerprint of its sources, and each file’s path, kinds, offset and sizes) and each file’s bytes, compressed with LZ4 when that makes them smaller.

A pack stands for its sources: its layer (Pack::into_layer) gives a bundle the fingerprint of the bundle it was baked from (Bundle::fingerprint), so a record made on the loose files plays on the pack as made with the same content.

The rules:

• Text stays the source. A pack is derived by Bake::bake, and Bake::check proves every asset read from it equal to the one read from its source.
• No migration. A pack of another VERSION, or baked for another stamp (the game’s word for the shapes of its own kinds), is refused with a message to bake it again.
• Never a panic. A pack cut short or changed anywhere is refused: the checksum covers every byte after the header, and every size is checked before anything is allocated for it.

The reader builds without std: a Playdate loads only packs (ADR-0008 §5).

Structs

Bake

What a game bakes into a pack: which assets of which kinds, the same way its loaders ask for them (asset as Formats::load, under as Formats::load_under), and its stamp. Every other file of the bundle goes into the pack as its own bytes.

Baked

What Bake::bake made: the pack, and what went into it.

BakedFile

One file of a Baked pack.

Pack

A pack’s files, read and unpacked: what a game lays in its bundle. A file the pack keeps as it is borrows the pack’s bytes ('a); only a compressed one is unpacked into memory of its own.

PackFile

One file of a Pack.

PackInfo

What a pack says of itself.

Packed

The format of a baked file of kind K in a pack: it reads the asset baked from the source, with no parsing of text. It claims no extension, and knows a baked file by its magic bytes, so the file keeps its source’s path (data/palette.ron) and code that asks for the asset doesn’t change. Bake::register registers it for every kind a game bakes.

Enums

Content

What goes into a pack at one path.

PackError

Why a pack was refused.

Constants

BAKED_MAGIC

The bytes a baked file in a pack starts with.

EXTENSION

A pack’s file extension, without the dot.

MAGIC

The bytes a pack starts with.

MAX_BAKED_BYTES

The most bytes a baked file has: 64 MiB, as the engine’s biggest sources (a PNG, a sound).

MAX_FILES

The most files a pack holds.

MAX_UNPACKED_BYTES

The most bytes a pack’s files add up to, unpacked: 1 GiB.

VERSION

The version of the pack format this engine reads and writes: the header, the index, and the binary form of the engine’s own kinds. A change to any of them makes it the next number, and a pack of another version is refused, never migrated.

Traits

Bakeable

A kind that can be baked: it has a binary form (serde, both ways), and two of it can be compared, for Bake::check.

Functions

info

What pack bytes says of itself, once its header, version and checksum are right: for a tool that looks at a pack without opening it.

length

How many bytes the pack at the start of bytes takes, by its header and its index: for a tool that looks for a pack inside a bigger file, such as a program that embeds one with include_bytes!. Nothing here is checked against the checksum: Pack::open the bytes it counts.

write

A pack of files (path → content), described by info. Each file’s bytes are compressed when that makes them smaller.