Crate shuyi_platform 

Shuyi Engine’s platform boundary (ADR-0008 §2, ADR-0024): the Platform trait a backend implements, and App, which runs one frame of a game each time the backend’s own loop calls App::frame with its clock.

• Platform: the display a Frame is presented on, the player’s input, the system’s events (SystemEvent), the game’s Storage, the sound device (Audio) and the system keyboard (TextInput);
• audio::player: the rules of playing a game’s sounds and music, which every backend shares over its small Backend;
• App: the game’s screens and input state (shuyi_ui::Game), its fixed simulation steps (tick), suspend and resume, and the loading phase (Start, Card);
• BasicGame (basic): a game on the short path, described once for its binary, its tools and its tests, and the prelude such a game names;
• AppInfo (app_info): who a game is, its name, id, version, storage’s name and window’s icon (WindowIcon), as its shuyi.ron says;
• the headless backend, which plays scripted input and records what it was shown, and the test harness over it (the harness feature);
• crash: the report a backend’s panic hook writes through the game’s storage, and the last crash the game hears of at its next start (Setup::last_crash);
• script: the steps of a player’s input a tool plays (keys, buttons, an action by name, waits), and the one plan of their frames that the Harness, the live link and a capture’s plans play;
• session: a run recorded where the platform hands things to App (App::record), its text, and its playback on the headless backend;
• the live link’s wire and server (the link feature), which a backend’s listener runs so a tool reaches a running debug build;
• capture’s plans (the capture feature): the input a backend’s capture mode plays, and the frames it compares with the raster;
• heap::snapshot (the heap feature): the heap counter’s rows as a heap snapshot, for a backend that counts the heap.

The backends: shuyi-app (macroquad: desktop, the web, the Steam Deck), shuyi-playdate, and private crates for closed consoles. docs/platform-backends.md says how to write one. Nothing here touches a device: no window, file, sound card or clock.

Re-exports

pub use app::App;

pub use app::Card;

pub use app::CrashRecord;

pub use app::FrameOutcome;

pub use app::GameHash;

pub use app::Load;

pub use app::LookOf;

pub use app::Setup;

pub use app::Start;

pub use app::SystemHook;

pub use app_info::AppInfo;

pub use app_info::WindowIcon;

pub use audio::Audio;

pub use audio::AudioFrame;

pub use audio::Silent;

pub use audio::SoundRequest;

pub use basic::BasicGame;

pub use platform::DisplayInfo;

pub use platform::Frame;

pub use platform::Look;

pub use platform::Millis;

pub use platform::OneBitLook;

pub use platform::Platform;

pub use platform::Show;

pub use platform::SystemEvent;

pub use text_input::TextInput;

Modules

app

App: a whole game behind one call per frame, for the backend’s own loop (ADR-0008 §2, ADR-0024). The backend calls App::frame with its clock; App reads the system’s events and the input from the Platform, steps the game (Game: its screens and input state) and its fixed simulation steps (TickClock), hands the frame’s audio to the sound device and the frame to the display.

app_info

AppInfo: who a game is, the same on every target: the name players see, a reverse-DNS id, its version and build, its publisher, the name its saves are kept under (ADR-0059), and its window’s icon (WindowIcon, ADR-0061).

audio

Audio: the sound device a backend gives the engine, and the frame of audio App hands it (AudioFrame).

basic

BasicGame: a game on the short path (ADR-0036), described once for its binary, its tools and its tests. It holds what the engine can’t read from the game’s files: who it is (AppInfo), its files, its first screen and, if it has them, its console, its own part, every screen it can show, the modules it installs and its record of its play for a crash report. From it come its data (BasicGame::data), its context (BasicGame::ctx), its Game and how a backend starts it (BasicGame::start).

crash

Crash reports (ADR-0079): what a backend’s panic hook writes through the game’s Storage, and what the game hears of it at its next start (Setup::last_crash).

harness

A headless test driver for any game on the engine (game ADR-0007 layer 4): scripted key and controller-button presses and waits in, in frames of 1/60 s or by a tick stage’s fixed steps (Harness::steps), screen names, snapshots and the audio asked for out. No window, no clock, no sound card: it runs the game in an App on the HeadlessPlatform, through the same frame the devices run, and the headless backend’s Speaker says what music sounds, so a screen that keeps time with the music is tested too.

headless

HeadlessPlatform: a backend with no window, no clock, no heap counter and no memory tags (unless a test hands it them) and no sound card. It plays scripted input and system events, records the frames presented to it, keeps its storage in memory, and stands in for the music player (Speaker), so a screen that keeps time with the music is tested too.

heap

The heap counter’s rows as a HeapSnapshot (ADR-0046 §6), with the heap feature: the one conversion a backend that counts the heap makes in its Platform::heap_snapshot, so shuyi-app and a game’s tool program (shuyi-cli) give the same snapshot of the same counts. A backend reads its counter (shuyi_alloc_count::global::reading and rows, and shuyi_alloc_count::tags::overflowed) and hands the counts here.

link

The live link (ADR-0047): how a tool reaches a build that is already running, in a debug build with the backend’s link feature. The wire is JSON lines, one UTF-8 JSON object per line: the client sends a Request per line, and the build answers each with an Answer, in order. The first line must be a Request::Hello with the build’s token, or the connection is closed.

platform

Platform: what a backend gives the engine (ADR-0008 §2, ADR-0024), and the plain data that crosses it: the time (Millis), the display (DisplayInfo), a Frame to show and the system’s events (SystemEvent).

prelude

What a game on the short path names (ADR-0036), and the start types a game names when it leaves it. Anything else is named by its module’s path.

script

Input scripts: the steps of a player’s input a tool plays (keys, controller buttons, an action by name, waits in seconds, the crank, and the debug view’s channels turned on) and the one plan that turns them into frames of raw input events (frames). The Harness plays a Script (Script::play, the harness feature), the live link’s server plays a Play request’s steps, and a capture plan’s input steps are these (ticket 2566): a key press is written once.

session

Session records: everything the platform gave a game in one run, frame by frame, and its playback (ADR-0072). A record is taken where the platform hands things to App (App::record), so no game code records anything: the clock, the system’s events, the input, the system keyboard’s answers, the music’s position, the display, the platform’s facts and the store as it was handed over. Each frame also holds a hash of what happened in it, never of its picture.

text_input

TextInput: the system’s own keyboard, for a device where the player doesn’t type on keys (a console’s software keyboard, Steam’s on-screen one on the Steam Deck, which is the game’s to fill: its ticket 0903).

tick

TickClock: real time turned into fixed simulation steps (ADR-0003 §2): 60 a second, at most 4 in one frame, after which the game slows down rather than spiral. Whole nanoseconds, so it counts the same on every machine.

Structs

TextAsk

What a text box asks the system keyboard for.

Enums

TextAnswer

What the player did with the system keyboard.

Constants

WATCH_VAR

The variable cargo shuyi run --watch sets for the game it starts: the folder of the game’s files on disk, which a backend lays over the embedded ones and watches (ADR-0071).

Traits

Storage

A place to persist small named blobs of text (RON documents, typically): files on native, localStorage on web.