Module 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.

A game starts in a loading phase (Start): the first frame shows a Card the game gives, the next loads the game behind it, and the frames after run it. On SystemEvent::Suspend the game’s hook saves, App stops stepping and the device holds the audio (Audio::suspend); on SystemEvent::Resume the audio comes back and App forgets the time it was away, so a sleep never becomes a burst of catch-up steps, and tells the game (Game::set_resumed), so a tick stage forgets the presses it kept from before and every key and button held before the suspend is let go (a key may come up while suspended, unheard); one still down counts once it is pressed again. On SystemEvent::FocusLost the game lets go of what is held at once (Game::forget_held_input), for the same reason, and until SystemEvent::FocusGained App applies the game’s Background policy (ADR-0077): paused, the game isn’t updated and its last frame is shown again, and the time away is forgotten as after a resume; muted, its audio goes to the device at volume 0.

App keeps the log (ADR-0030): at the end of every frame it takes the lines the game logged (Ctx::log), stamps them with the frame’s number and keeps the last LOG_LINES for tests, tools and the backend’s sinks (App::take_new_log).

In debug builds App also measures each frame (ADR-0046) with the platform’s clock (Platform::clock), and keeps the last PERF_FRAMES records beside the log (App::perf, App::take_new_perf). With the platform’s memory tags (Platform::memory_scopes) it tags what each part of a frame allocates: load (the game’s load), paint (presenting the game’s frame), perf (its record), and app for the rest; the game’s own frame tags update, draw and its spans.

App also records a run, when told (App::record, ADR-0072): it notes each value where it reads it from the Platform, since only it sees the order of a frame’s calls, the keyboard’s handshake and the load.

Structs

App

A game run one frame at a time by a backend’s loop.

Setup

What the platform gives a game as it loads: what goes into its context (ctx). A backend with more to give (the voice manifest it read) adds it with Start::before_load.

Start

How a game starts: the card shown while it loads, the load, where its look is and its hook for the system’s events. Built with Start::new, its optional parts set by the methods named for them (ADR-0039).

Enums

Card

What the screen shows while the game’s data loads, from the first frame (a slow device takes seconds to load a game, and shows nothing until a frame is drawn). Drawn by the backend with what it has of its own, since the game’s font isn’t loaded yet.

FrameOutcome

What a frame tells the backend’s loop.

Type Aliases

CrashRecord

The game’s record of its play as text, in the format its tools’ replay reads, for a crash report (Start::crash_record); None when it has none (no stage is open).

GameHash

The game’s own state hash, for the frame’s hash (Start::state_hash).

Load

A game’s load: its data read and its game made from the Setup, or why it can’t start (shown instead of the game).

LookOf

Where a game’s frame finds what it is painted with, in its data.

SystemHook

The game’s hook for the system’s events: it hears each one after App has done its part. On SystemEvent::Suspend, QuitRequested and LowBattery it is where the game saves what it hasn’t; on FocusLost, whose held input App has let go of and whose GameSettings::BACKGROUND it applies, it may do more (open a pause menu).