shuyi_platform/
lib.rs

1//! Shuyi Engine's platform boundary (ADR-0008 §2, ADR-0024): the
2//! [`Platform`] trait a backend implements, and [`App`], which runs one
3//! frame of a game each time the backend's own loop calls
4//! [`App::frame`] with its clock.
5//!
6//! - [`Platform`]: the display a [`Frame`] is presented on, the player's
7//!   input, the system's events ([`SystemEvent`]), the game's
8//!   [`Storage`], the sound device ([`Audio`]) and the system keyboard
9//!   ([`TextInput`]);
10//! - [`audio::player`]: the rules of playing a game's sounds and music, which
11//!   every backend shares over its small [`Backend`](audio::player::Backend);
12//! - [`App`]: the game's screens and input state ([`shuyi_ui::Game`]), its
13//!   fixed simulation steps ([`tick`]), suspend and resume, and the
14//!   loading phase ([`Start`], [`Card`]);
15//! - [`BasicGame`] ([`basic`]): a game on the short path, described once
16//!   for its binary, its tools and its tests, and the [`prelude`] such a
17//!   game names;
18//! - [`AppInfo`] ([`app_info`]): who a game is, its name, id, version,
19//!   storage's name and window's icon ([`WindowIcon`]), as its `shuyi.ron`
20//!   says;
21//! - the [`headless`] backend, which plays scripted input and records what
22//!   it was shown, and the test `harness` over it (the `harness`
23//!   feature);
24//! - [`crash`]: the report a backend's panic hook writes through the
25//!   game's storage, and the last crash the game hears of at its next
26//!   start ([`Setup::last_crash`]);
27//! - [`script`]: the steps of a player's input a tool plays (keys,
28//!   buttons, an action by name, waits), and the one plan of their frames
29//!   that the Harness, the live link and a capture's plans play;
30//! - [`session`]: a run recorded where the platform hands things to [`App`]
31//!   ([`App::record`]), its text, and its playback on the headless backend;
32//! - the live `link`'s wire and server (the `link` feature), which a
33//!   backend's listener runs so a tool reaches a running debug build;
34//! - `capture`'s plans (the `capture` feature): the input a backend's
35//!   capture mode plays, and the frames it compares with the raster;
36//! - `heap::snapshot` (the `heap` feature): the heap counter's rows as a
37//!   heap snapshot, for a backend that counts the heap.
38//!
39//! The backends: `shuyi-app` (macroquad: desktop, the web, the Steam Deck),
40//! `shuyi-playdate`, and private crates for closed consoles.
41//! `docs/platform-backends.md` says how to write one. Nothing here touches
42//! a device: no window, file, sound card or clock.
43#![cfg_attr(not(feature = "std"), no_std)]
44
45extern crate alloc;
46
47/// What `std`'s prelude gives for free, for the `no_std` build.
48mod alloc_prelude {
49    pub use alloc::borrow::ToOwned;
50    pub use alloc::boxed::Box;
51    pub use alloc::string::{String, ToString};
52    pub use alloc::vec::Vec;
53}
54
55pub mod app;
56pub mod app_info;
57pub mod audio;
58pub mod basic;
59#[cfg(feature = "capture")]
60pub mod capture;
61pub mod crash;
62#[cfg(any(test, feature = "harness"))]
63pub mod harness;
64pub mod headless;
65#[cfg(feature = "heap")]
66pub mod heap;
67#[cfg(feature = "link")]
68pub mod link;
69pub mod platform;
70pub mod script;
71pub mod session;
72pub mod text_input;
73pub mod tick;
74
75pub use app::{
76    App, Card, CrashRecord, FrameOutcome, GameHash, Load, LookOf, Setup, Start, SystemHook,
77};
78pub use app_info::{AppInfo, WindowIcon};
79pub use audio::{Audio, AudioFrame, Silent, SoundRequest};
80pub use basic::BasicGame;
81pub use platform::{DisplayInfo, Frame, Look, Millis, OneBitLook, Platform, Show, SystemEvent};
82pub use shuyi_ui::storage::Storage;
83pub use text_input::{TextAnswer, TextAsk, TextInput};
84
85/// The variable `cargo shuyi run --watch` sets for the game it starts: the
86/// folder of the game's files on disk, which a backend lays over the
87/// embedded ones and watches (ADR-0071).
88pub const WATCH_VAR: &str = "SHUYI_WATCH";
89
90/// What a game on the short path names (ADR-0036), and the start types a
91/// game names when it leaves it. Anything else is named by its module's
92/// path.
93pub mod prelude {
94    pub use shuyi_assets::keymap::{ActionSet, UiAction};
95    pub use shuyi_assets::{Bundle, ContentError, Layer};
96    pub use shuyi_ui::frame::glyph_buffer::{BoxStyle, Cell, GlyphBuffer, Rect};
97    pub use shuyi_ui::frame::{ConsoleSpec, EngineColor, Rgb};
98    pub use shuyi_ui::module::{Hook, Install, Module};
99    pub use shuyi_ui::screens::print_centred;
100    pub use shuyi_ui::{
101        BasicData, Ctx, FrameInput, Game, GameData, GameHooks, Screen, ScreenResult, Transition,
102    };
103
104    pub use crate::{AppInfo, BasicGame, Card, Look, Setup, Start};
105}
shuyi_platform/lib.rs

shuyi_platform/
lib.rs
