Module bundle 

The asset bundle: the files a game embeds in its binary, read from layers the game gives, in order. A file is read from the first layer that has it, so a layer laid over another replaces its files at the same paths and adds its own; a listing merges every layer’s files.

A layer may also come from outside the binary: Layer::owned takes files handed in at run time (a player’s mod, a level they made), kept for the life of the program, so a game’s loaders read them as they read its own. shuyi-app’s read_folder reads a folder on disk into one.

Two flags shape a layer. A private layer holds files that may not be handed out (bought art): Bundle::is_private tells a tool which shown names come from one. A test layer holds the files of the tests and debug tools, which a build that ships leaves out: test layers are read after every other layer, and story_only hides them from a thread.

A layer may also name the files it leaves out on purpose (Layer::leaving_out): a smaller build (a handheld’s) that keeps only what it uses. Bundle::left_out lets a loader tell such a file from one that is missing.

A layer may be for a target (ADR-0008 §4): assets@playdate is assets’ layer for the Playdate, used only when baking or running for it. Bundle::for_target lays it right above assets, so any file there (a hand-drawn one-bit hero.png, a settings file) replaces the one at the same path, and leaves out every other target’s.

A bundle’s fingerprint stands for the content that ships, the same on every platform: what a record or a save is stamped with (shuyi_core::made).

The game registers its bundle once (install or get_or_install), and its loaders read files as &'static data from it. A front end can watch every file read, to log or time what it loads; with std, reading makes one thread read another bundle (a test of a smaller build’s bundle), and recording lists the files a stretch of code read on its thread.

In a debug build a file of a run-time layer may change on disk: Bundle::replace takes its new bytes, and hot values decode again.

Structs

Bundle

The layers a game reads its files from.

Layer

One layer of the bundle.

LayerError

A layer that could not be made (Layer::owned): one of its paths was refused.

LoadFile

One file of a folder, as Bundle::load_each hands it to a parser.

NotText

A file that is not valid UTF-8: what Bundle::load_each turns into the loader’s own error type.

OwnedFiles

The files of a layer handed in at run time (Layer::owned), with checked paths, kept for the life of the program so every read of them is &'static. With std a file can be replaced (Layer::replace); its old bytes stay, so what was read of them stays valid.

Enums

BadPath

Why a path handed to Layer::owned was refused: a layer’s paths are relative to its root and /-separated, as every read names them.

Files

Where a layer’s files are.

Constants

TARGET_MARK

What a layer’s name puts between the name of the layer it is laid over and the target it is for: assets@playdate (Bundle::for_target).

Functions

get_or_install

The process-wide bundle, installing the one make builds if none is. When two threads race to install, one bundle wins and both get it. Inside reading, the bundle this thread reads instead, and nothing is installed.

install

Makes bundle the process-wide bundle. Done once: a second call gives its bundle back and changes nothing.

installed

The process-wide bundle, once installed; inside reading, the bundle this thread reads instead.

reading

Runs f with this thread reading bundle instead of the installed one (installed, get_or_install): for a test of another build’s bundle (a handheld’s smaller one) in a process that installed the whole. Other threads are never affected.

recording

What f gives, and the paths Bundle::bytes found while it ran on this thread (also through Bundle::file and the formats that read a bundle). Unlike watch, it is scoped, and more than one tool can use it at once. Nested, the outer call sees the inner one’s reads too. Bundle::has records nothing.

shown_under

Whether shown (a human-facing name) names a file under the layer named name: base/x.png is under base, bases/x.png and base are not.

story_only

Runs f with the test layers of every bundle hidden from this thread: each answers as it does in a build that ships. For the tests that check what such a build holds.

target_layer_name

The name of layer’s layer for target: assets@playdate for assets and playdate.

watch

Tells watcher of every file any bundle reads from now on (Bundle::bytes and Bundle::file), on the thread that reads it: for a front end that logs or times what it loads. Set once: a second call gives its watcher back and changes nothing.

Type Aliases

Watcher

What is told of every file read (watch): its path, and whether the bundle has it.