Crate shuyi_ui 

Shuyi Engine’s UI, independent of any window or platform (game ADR-0004). So far:

• the frame every screen draws into (a console of glyph cells the game sizes, pictures, a backdrop, colors by name, the text form the snapshot tests read and the one-bit renderer);

• input: a game’s actions from keys and controller buttons through a keymap, held keys and repeat, the player’s saved bindings and the names of keys in help text;

• basic: BasicData, a ready-made GameData read from the files every game on the short path has;

• screens on a stack, the context they share (ctx: Ctx, with the game’s part in it, GameData) and the frame loop (game: Game), a stage’s rules run in fixed steps (tick: TickDriver), with the player’s settings and profiles, storage, audio requests and the music, and text placeholders;

• the frame_cap: the most frames a second the platform shows, the game’s default and the player’s setting, asked for and confirmed by the platform’s report;

• a module from outside the default engine joining a running Game: its hooks and its state on the Ctx;

• a toy game to try things on (the toy feature); the test Harness that drives a game without a window is shuyi_platform::harness;

• the system_keyboard a text box may ask the platform for;

• the platform_facts: where the game runs, which screens read instead of a cfg! (Ctx::platform);

• the engine’s log: lines with a level, a category and a frame, given through Ctx::log;

• perf: frame times and the spans a game marks (Ctx::span), as data, in debug builds;

• the float methods core lacks, for the no_std build (float);

• ease: shuyi_core’s integer ease curves for a skin that works in floats.

• widgets screens are built from (that module lists them);

• screens any game can use, with the game’s rows (that module lists them);

• dialogue: a .dlg scene played one text box at a time;

• one-time tips and which have been shown;

• the developer’s debug screens;

• a hurry clock for something timed the player can hurry by holding a key and finish with a press;

• cinematics: a timeline of a game’s shots, each frame drawn from the time alone;

• the tactics kit’s grid map: a scene of the visible tiles generic over the game’s units, the glyph and sprite skins that paint it (the game’s units by its own painter), the tile camera, the virtual cursor, a path that follows it and how long a walk is shown.

Re-exports

pub use basic::BasicData;

pub use ctx::Ctx;

pub use ctx::GameData;

pub use ctx::IdleMotion;

pub use ctx::KeyPrompt;

pub use ctx::Keyboard;

pub use game::FrameOutput;

pub use game::Game;

pub use game::GameHooks;

pub use game::RawInputEvent;

pub use game::ScreenHook;

pub use hurry::HurryClock;

pub use platform_facts::PlatformFacts;

pub use screen::FrameInput;

pub use screen::Screen;

pub use screen::ScreenResult;

pub use screen::ScreenStack;

pub use screen::Transition;

Modules

audio

Audio as data: screens ask for sounds and music through Ctx::audio; Game hands the requests, and the MusicState’s commands, to the platform in each FrameOutput. Nothing here plays anything, so screens stay testable without a sound card.

basic

BasicData: a ready-made GameData for a game on the short path (ADR-0036). It reads the files every such game has from its bundle, through the format registry (BasicData::formats): the English screen text, the keymap, the palette with the engine’s colours, the font atlas and every picture. A part of the game’s own rides along in BasicData::own. It has no sounds, no voices (()), no settings of the game’s own (()) and one palette. A game that needs more writes its own GameData, as before.

cinematic

Plays a cinematic (shuyi_assets::cinematic, ticket 1113; the game’s game ADR-0060): a Timeline says which shot a time falls in and how far through it, and a CinematicPlayer has the shot draw itself there. What a shot shows is the game’s: its shot kinds implement ShotPainter.

ctx

Ctx: what every screen shares, passed &mut to Screen::update and & to Screen::draw. The engine’s services (text by key in the player’s language, the keys and the names help text gives them, the player’s settings and profiles, sounds, music and voices, storage) and the game’s own part, Ctx::game, whose type says what the engine reads from the game’s data (GameData).

debug

The developer’s debug screens: a menu of the game’s tools (DebugMenuScreen, with the game’s and its modules’ DebugEntrys), the glyph sampler that shows every glyph of the font and every color of the palette (GlyphSamplerScreen), the scene camera over a picture of the game’s (SceneCameraScreen), and the hint that names the Debug key (hint). Debug tools are in English only.

dialogue

Dialogue: a scene of the .dlg format played one text box at a time (player, with the game’s own lines and tokens through DialogueHooks) and the text box it is read in (text_box: its pages, typing and look). A game’s dialogue screen puts them together with its portraits and whatever it draws behind the talk.

ease

Ease curves for a skin that works in floats: ease_f32 eases through shuyi_core’s integer curves (shuyi_core::ease), so a curve is the same on every machine.

float

The float methods core lacks, from libm, for the no_std build (game ADR-0070 §3): import Float and Round only without std. With std the standard methods are called, so the numbers stay exactly what they were; the tests below hold the two together. A game built on the engine without std imports them too.

frame

The frame (game ADR-0003): the GlyphBuffer console every screen draws into, ConsoleSpec cells big, with its pictures and rectangles (Items, in Layers) and its Backdrop; colors by name (Rgb, Palette); the text form snapshot tests read (snapshot); fitting the console to a window (console), a shot to a backdrop (cinema) and a picture to an area (portrait); pictures a skin paints at run time (painted, ADR-0078); the debug view’s shapes (gizmo, ADR-0085), drawn by the integer pixel rules of shape; and the one-bit renderer (onebit); with the raster feature, the software painter whose picture every backend must match (raster).

frame_cap

The frame cap: the most frames a second the platform shows (FrameCap), 60 unless the game or the player says otherwise, so a simple game doesn’t run as fast as it can and keep a CPU core busy (fans, heat, the battery).

game

Game: a whole game’s UI behind one call per frame. The platform feeds it raw key and controller-button events and the frame time and shows the buffer it returns; a test drives it the same way without a window.

grid

The tactics kit’s map (game ADR-0038, game ADR-0088): a screen says what is on the visible part of a grid map as a MapScene (plain data), and a GridSkin says how it looks. The skin paints the ground (each tile’s terrain, flashing where it just changed), the ranges by their names, the path, the cursor and the threat arrows; the units are the game’s own view of them, painted by the game’s UnitPainter between the skin’s layers.

hurry

HurryClock: the time of something timed that the player can hurry by holding a key and finish with a press (ticket 2312): a text box typing out, a tally counting up, a fight played back.

input

Keyboard and controller input as a game’s actions (game ADR-0006, game ADR-0034), generic over its ActionSet (tickets 1106 and 1107): a data-driven Keymap from chords and controller buttons to actions (keymap), and InputState (state), which turns presses and releases plus frame time into the actions screens see, including repeat for held repeatable keys and buttons. FrameInput (frame) is one frame’s input as a screen sees it.

log

The engine’s log (ADR-0030): lines with a level, a category and the frame they were given in, kept in a LogRing of the last LOG_LINES.

module

Module: a piece from outside the default engine that joins a running Game (ADR-0040).

perf

Frame times and spans as data (ADR-0046), in debug builds: what the platform’s App measures of each frame and keeps in a PerfRing of the last PERF_FRAMES FrameRecords, for tests, tools and agents.

platform_facts

PlatformFacts: where the game runs, as its screens see it (Ctx::platform). A fact is constant for a run: the platform’s backend says them before the game loads, read from its target’s profile (TargetProfile) or from the system.

profiles

Player profiles: a profile holds a player’s options, keys and saves, whatever the game keeps for each player. Each of those keeps the Storage key it would have without profiles, inside the profile: a profile’s key is its id’s prefix and that key (p1-settings, p2-slot_03, ProfileId::key). ProfileStore is the Storage of the current profile, and the computer’s own storage under it.

screen

Screens and the screen stack: the shape every screen of a game has.

screens

Screens any game can use, each with rows, entries or a legend the game gives: the layout_picker, the key_bindings screen, the options screen and the player profiles screen. Each says what it shows as plain data (a view) and a skin paints it (glyph for glyphs).

settings

The player’s settings: the engine’s (how fast dialogue text is revealed, whether the game fills the screen, the color theme, the music and sound volumes, the frame cap and the layout picked) and the game’s own (Settings::game, a GameSettings). Ctx loads them with its storage, from one record under SETTINGS_KEY in the profile in use, whose form the game decides (GameSettings::to_ron); it saves them when they change (Ctx::change_settings). Key bindings are saved apart.

storage

Persistence: a game’s saves and the player’s settings go through Storage, so the UI stays pure. The platform supplies the real implementation (files, the browser’s localStorage, a console’s own files); MemoryStorage is for tests and the test harness.

system_keyboard

The system’s own keyboard for a text box (ticket 3003): a console’s, or Steam’s on-screen one on the Steam Deck. A screen asks for it through Ctx::system_keyboard, the platform’s App opens it (shuyi_platform::TextInput), and the player’s answer comes back in a later frame. Where the platform has none, a screen reads typed keys (FrameInput::text) or spells on a letter grid, as before.

text

Filling in a text’s placeholders: {name} by a value the caller gives (fill_values), or by what the caller looks up for it, such as the key the player has for an action (fill, Ctx::text_with).

tick

A stage’s rules in fixed steps (ADR-0003 §2): TickDriver steps a TickSim as many times as a frame has steps due (FrameInput::ticks), gives each step what the player did since the last one, and hands each step’s events on once. ActionIds turns a game’s action into the id a step’s input holds, and back.

tips

One-time tips: which have been shown (TipsSeen), kept in Storage under TIPS_SEEN_KEY (the player profile’s), and forgetting them all (reset_tips). When a tip shows, and where, is the game’s; a tip’s {Action} placeholders are filled like any text (Ctx::text_with).

widgets

Reusable pieces screens are built from: a menu, the ListCursor that moves its focus (and any other list’s), a question over the screen (Ask), a name typed or spelled on a letter grid (name_entry) and word_wrap for text boxes. Each widget says what it shows as plain data (a view) and a skin paints it (menu::glyph and ask::glyph for glyphs).

Constants

DEBUG_TOOLS

Whether this build offers the developer’s tools: debug builds, and release builds with the debug-tools feature. Then the keys of the actions no player can rebind (a debug key) stay out of the player’s reach; otherwise those keys are free to bind.