Crate shuyi_assets 

Shuyi Engine’s assets: the bundle of files a game embeds, laid in layers the game gives (bundle), errors that name a file, line and column (error), and RON files read with those errors (ron). On top of them, the kinds of file every game has: images (image) and their one-bit versions (bitmap), a font atlas (font), named colours (palette, ink) and their one-bit patterns (onebit), lights (lighting), the audio manifest (audio) and the credits (credits); the .map text format of a grid map (grid_map) and a tileset’s terrain tiles (tileset); keymap files, generic over a game’s actions (keymap); and the text of a story game: languages (lang), a names table (names), dialogue scripts (dialogue), voice clips by line (voice), tips (tip) and word wrap for text boxes (text); and cinematics, timed shots of a game’s own kinds (cinematic); and export targets’ profiles (target). Each is a pure parser; the game names its files, says what its own rules add, and reads them from its bundle.

Formats are plugins (format, ADR-0007): each kind of asset is a plain type, the parsers above are formats of their kinds, and a game registers its own kinds and formats beside the engine’s in a Formats registry, then asks it for an asset by id. A game may ship its assets baked into one pack (.shuyipak), proven equal to its sources. A value read through the registry can reload when its files change on disk (hot).

For tests, behind the golden feature: golden tables (golden), values a build gives pinned in a file, the same on every platform.

Re-exports

pub use bundle::Bundle;

pub use bundle::Files;

pub use bundle::Layer;

pub use error::ContentError;

pub use error::ContentErrors;

pub use error::line_of;

pub use format::AssetKind;

pub use format::AssetPath;

pub use format::DecodeCx;

pub use format::Encode;

pub use format::Format;

pub use format::Formats;

pub use format::Limits;

pub use grid_map::GridMap;

pub use grid_map::MapFeature;

pub use grid_map::MapFormat;

pub use grid_map::MapLook;

pub use ron::parse_ron;

Modules

audio

The audio manifest: every sound and music cue a game can play, the music pools, and the credits for every third-party work. Screens name cues; the platform layer plays the files.

bitmap

One-bit pictures (game ADR-0085): the file a one-bit screen draws in place of a PNG, made ahead of time by convert so the device never decodes a PNG. Pixels are packed one bit a pixel in rows, the Playdate’s own bitmap layout: each row stride bytes, a byte’s highest bit its left pixel, a set bit white.

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.

cinematic

Cinematic files: a list of shots and when each starts, over a length of time (ticket 1113; game ADR-0060). The engine reads the file’s frame and checks its times; what a shot shows is the game’s own (S), checked by the game (ShotCheck) and played by shuyi_ui::cinematic.

credits

The credits: every third-party work a game uses, for its credits screen. Music and sounds are credited in the audio manifest (crate::audio); everything else (fonts, bought art, vendored software) in a credits file. merge makes the two one list, so nothing is typed twice.

dialogue

Dialogue scripts (.dlg files): scenes of portraits, speech, narration, reply choices and music changes. parse_dlg turns a file into scenes, check_scene and check_duplicates validate them against the game’s SceneRules, and print_scene writes a scene back out. Every line that shows text has a LineId. Lines in an @if block play only while a character is there (Present).

error

Content errors: every problem names the file and, when known, the line and column, so a broken asset can be fixed without reading Rust. An error of a class the tools know carries its problem Code (codes), which shuyi explain prints the page of.

fnv

The word-wise FNV-1a hash the pack’s checksum and a bundle’s fingerprint share: FNV-1a’s constants over 64-bit words (the last few bytes one at a time), each step followed by a shift that folds the high bits into the low ones. Each step is a bijection of the hash so far, so any one word changed changes it. Every integer is a u64, whatever the platform. A frame’s snapshot hashes a painted picture with it too (ADR-0078).

font

A bitmap font atlas: a grid of fixed-size glyph cells in one image, and a glyph map (a RON file) from char to cell index. The game names the two files and the glyphs it needs. As a format (ADR-0007), the glyph map is a sidecar read with the PNG beside it (FontAtlasRon). Once the atlas and the game’s text both load, undrawn finds every character of the text the atlas can’t draw.

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.

grid_map

The .map text format of a grid map: a RON header, a --- line, then one character per tile, top row first.

hot

Values that reload (ADR-0071). A Hot value is an asset decoded through the registry by id, which remembers every file its decode asked for: the file itself, the files its format read through DecodeCx (an atlas’s picture, a level’s tileset) and its import settings, found or not. When the platform says files changed, Hot::refresh decodes it again if one of them did. If the new decode fails, the old value stays and the errors come back (Reload::Failed), so a broken file never takes a running game down.

image

The image table: every PNG in a Bundle the game names, by bundle path, with its size. Screens name a picture by an ImageId from this table; the platform layer decodes and draws it. Only each file’s header is read here, never its pixels.

import_settings

Import settings (ADR-0057): how one file, or every file of a folder, is read or baked. A file’s own settings are beside it, its full name kept (images/hero.png.meta); a folder’s defaults are in its _folder.meta, for every file in it and below it. A settings file is RON, a struct of sections, each read by the step it is named after: (onebit: (dither: bayer), indexed: (group: "ui")).

ink

One-bit inks and their palette (the Playdate’s, game ADR-0074): a palette file of inks gives each colour name an Ink instead of an RGB value. It loads as a PaletteDef like any other, each colour being its ink’s reserved code, so screens and skins draw with it unchanged and a one-bit renderer reads the codes back as inks.

keymap

The keymap file format, generic over a game’s ActionSet (game ADR-0015, game ADR-0031, game ADR-0034, tickets 1106 and 1107): Keys and Chords, controller Buttons and ButtonChords (two buttons together), the named Layouts a file lists, and KeymapDef, a validated keymap file: each layout’s default keys, the keys that work before a layout is chosen, the default buttons, key-repeat timings and the sticks’ thresholds.

lang

Languages: the source language’s screen text by key (en/ui.ron), and the packs that overlay it (<tag>/): their screen text (ui.ron), the game’s data text (data.ron: names, and whatever else the game hands over by key) and the dialogue’s lines and captions (dialogue/*.ron).

lighting

Lights: named recipes for shading pictures, read from a RON file of name: (grey: 0.35, tint: (0.62, 0.56, 0.46)) entries. Look data only: a game’s rules never see it. As a format (ADR-0007): LightingRon.

names

A names table: every display name of a story (characters, places, factions, terms) by stable id, so a rename is one line. Text refers to a name with a token, {n:<id>} (or {N:<id>} for a capital first letter), filled in by Names::substitute when it is shown. As a format (ADR-0007): NamesRon.

onebit

One-bit output by role (ADR-0008 §4): a fixed set of 8 × 8 Patterns, and the pattern map (palette@onebit.ron, beside the palette) that gives each of a skin’s palette roles a foreground and a background pattern, with the groups of roles that tell things apart and must stay distinct. As a format (ADR-0007): PatternMapRon. check is what shuyi check --target checks of a one-bit target; the renderer that draws with the map is shuyi_ui::frame::onebit.

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.

palette

Named colours: a palette file ({"name": "#RRGGBB", ...}) that all drawing code refers to by name. The game says which names it needs; a theme is another palette file with exactly the names of the default one (theme_problems). As a format (ADR-0007): PaletteRon.

ron

Reading RON assets with file:line:col errors. As a format (ADR-0007), Ron reads any kind that serde reads: a game’s own data tables.

target

Export targets as data (ADR-0008 §1): a TargetProfile says what a target’s display shows, how fast it runs, what the player can press, what a game may spend there, and which platform backend builds it. The engine’s profiles are the files of targets/ at the repository’s root (playdate.ron, steam-deck.ron, …); a game adds one, or overrides one by its id, with a file of its own. As a format (ADR-0007): TargetRon.

text

Word wrap for text boxes, the one the checks and the boxes share.

tileset

A tileset’s terrain tiles (game ADR-0052): the pictures a grid map’s sprite skin paints its ground with. For each look a map may ask for (outdoors, indoors), a tile for every terrain and the layers painted over those tiles. A layer’s picture is chosen from the tiles around it, so a terrain grid alone says what the map looks like: a map file only ever names terrain.

tip

One-time contextual tips: what triggers each and what it says. The game’s own type names its triggers; its screens decide when one has happened and remember which tips were seen. A tip’s text names keys with placeholders ({Confirm}), filled in with the player’s keys when shown. A tip may keep its instructions apart from its text (how): a game whose tips are spoken by a recorded voice keeps the keys there, since a clip made ahead of time can’t say a key the player rebound.

voice

Voice clips: a manifest that lists every clip by dialogue line id, and a cast that says which voice says each speaker’s lines. A game ships its clips beside it, so nothing here reads a file: the game reads the text and these functions parse and validate it.