Crate shuyi_cli 

Shuyi Engine’s tools, shuyi: the tool contract’s operations (new, check, lint, modules, add, run, scene, replay, playtest, autobalance, import, bake, export, doctor, explain, attach, each with --json; contract), the exporters export runs (export), the contract as an MCP server with a session (mcp, mcp install; mcp), and frame-png, font-atlas, app-info, glyph-tiles, check-keys, check-text, check-skills, lang-status, web and private-assets, each a module of library functions with a thin wrapper here; bench, which plays the game’s benchmark scenarios and gates them against its targets’ budgets (docs/targets/README.md); the engine’s modules as modules and add read them (catalog); templates made of parts, which new composes (template); the engine’s skill pack, which new copies into a game and check-skills checks (skills); the notices a package carries (notices); and the pool of threads the slow ones play on (pool).

They run on a project: the folder holding a shuyi.ron (project), which says what each command scans and builds; new, doctor, explain, attach, schema and check-skills need none. The commands that run the game itself get what they need from it (GameTools) in a program of its own that calls main_with, and shuyi runs that program (shuyi.ron’s game) for them. A game on the short path gives BasicTools (basic).

A CLI tool prints to stdout by design, so print_stdout is allowed here.

Re-exports

pub use basic::BasicTools;

pub use game::AutobalancePlan;

pub use game::GameArg;

pub use game::GameAudio;

pub use game::GameBake;

pub use game::GameLang;

pub use game::GameOption;

pub use game::GameTools;

pub use game::OneBitSkin;

pub use game::PlaytestPlan;

pub use game::Tunable;

pub use game::check_start;

pub use game::game_arg;

pub use project::Project;

pub use serde_json;

Modules

app_info

Who the game is: shuyi.ron’s app part (AppPart, ADR-0059), its rules (problems, which check --target reports), and app-info, which writes it as the Rust constant the game’s binary compiles (rust, run) and the window’s icons, downscaled from the game’s one icon (downscale, ADR-0061) or drawn per size (ADR-0069).

basic

BasicTools: the GameTools of a game on the short path (ADR-0036), from its BasicGame: frame-png, lang-status, the contract’s check, run and scene (a session with no scene, or one played from a session record), the font atlas check checks the text against, and the controls check --target checks. A game that adds a scene, a record, bots, importers or a bake writes its own GameTools and calls these methods for the rest.

catalog

The engine’s modules as the tools read them (ADR-0009 §2, §4, §6), for modules and add (crate::contract::modules, crate::contract::add):

check_keys

check-keys: fails when game code or player text names a key directly instead of going through an Action and the player’s keymap. Controller buttons are treated like keys.

check_text

check-text: counts the player-facing text still written as string literals in the screens’ source (CheckText::dir), instead of asked for by key with ctx.text("screen.thing") from the game’s language file. It fails when the count is above CheckText::max_literals.

codec

PNG files as RGBA8 pixels, for the tools that read and write pictures.

contract

The tool contract (ADR-0005 §1, ADR-0022): the operations an agent, CI or a person runs on a game, each a library function with a typed input and output that serde reads and writes and JSON schemas describe. The CLI (shuyi <op> [--json]) is one surface over them; the MCP server (shuyi mcp, crate::mcp) is another, where each is a tool and a session keeps one game running between calls.

export

The exporters export runs (crate::contract::export): one per target, each building the game with the target’s Rust triple and writing its package (Exporter). windows writes a zip, linux a tar.gz, macos a folder holding a signed .app, web a folder and its zip, and playdate a .pdx and its zip. Every package carries NOTICES.txt (notices), and the Windows and macOS ones a note for players on opening an unsigned program (HOW-TO-OPEN.txt).

font_atlas

font-atlas [--no-text] [--wide [<set>=]<wide.bdf>]... <font.bdf>... <out-dir>: turns a BDF bitmap font into a font atlas (atlas.png + atlas.ron, read as shuyi_assets::font::FontAtlasDef) and its one-bit copy for a one-bit screen (atlas_1bit.bin). It keeps the glyphs the font has of ATLAS_RANGES, of the characters the game’s text uses and of the glyphs the project requires (AtlasChars): when shuyi.ron names a game tool program, font-atlas runs in it and reads the game’s text (--no-text: the ranges and the required glyphs only). Further BDF files add glyphs the first lacks (a game’s own, e.g. controller button shapes). The atlas must have the glyphs the project requires (crate::project::FontAtlas::required_glyphs); a character the text uses that the fonts lack is named, and check fails on it.

frame_png

frame-png: renders a frame of a game in the test Harness to a PNG without a window, for looking at a skin, a picture or a mockup. Never a gate: snapshots stay text.

game

What the commands that run the game need from it: GameTools.

glyph_tiles

glyph-tiles: a tileset made from the font’s glyphs, for a game that wants a sprite skin before it has art (as the game’s test-tileset does): each tile is a square of a palette color with up to a few glyphs stamped on it, centred, in another; a tile with no background is clear but for its glyphs (a piece drawn over the ground). Tiles are laid out in the order shuyi.ron lists them, columns to a row, so tile i is at column i % columns, row i / columns.

lang_status

lang-status <tag>: what a language pack of the game lacks: the missing keys (no entry), the stale ones (an entry made from source text that has since changed) and the orphaned dialogue entries (their line was reworded or cut, so it has a new id or none), each with the untranslated line of its scene nearest to what it translated. All show in the game as a shorter tag’s pack or the source language has them (Lang::chain) and fail no gate; this lists them for whoever translates. After the screen text’s missing and stale keys come its entries too long for their place: wider than their key’s max_cells in the source’s ui.ron (Lang::overflow), measured with the font atlas’s wide glyphs. They fail no gate either. Screen text comes first, then the data’s, then the dialogue’s, each with its counts. Test text (the test*.dlg scenes, data ids starting with test) is left out, and counted, except in the report of the test pack (code test); --only and --file narrow the report. The game gives its languages (crate::GameTools::lang).

mcp

shuyi mcp: the tool contract as an MCP server over stdio (ADR-0005 §2, ADR-0031), and shuyi mcp install, which registers it with the agents it finds (install).

notices

NOTICES.txt: the notices a package of a game owes for the works in it, written beside the game. shuyi web writes one into the web build (crate::web). It lists the crates compiled in (crates), the web shell’s files and the game’s own license texts (game_texts), then each license text once (write()).

pool

A pool of threads for the tools that play many slow tries (playtest, and later autobalance): every item of a work list run on one of n threads and timed, the answers given back in the list’s order, so what is made of them never depends on the thread count. The clock is the tools’; the core never reads one.

private_assets

private-assets [--library | --pin]: fetches the files a game may not hand out (bought art, say) from a private repository, checked out into a git-ignored folder of the project (PrivateAssets::checkout) at the commit the project’s pin file names (PrivateAssets::pin_file).

project

The project file, shuyi.ron, at a game’s root: who the game is (its app part), which paths each check scans, the game’s tool program (for the commands that run the game), the font atlas’s rules, the web build’s package, the game’s own license texts and the private repository’s settings, and the targets the game ships on. A command whose part is missing says so.

skills

The engine’s skill pack (ADR-0005 §2, ADR-0043): skills/<name>/SKILL.md folders in the open Agent Skills format, each with a worked example (example.ron, a script of contract commands) unless it waits for work still to come.

template

Templates as data (ADR-0013 §3): a folder with a template.ron and the files of its parts, which shuyi new turns into a new game.

test_card

The test card, a generated test image for sprite items (it lives with the raster in shuyi-ui). The test card: a public test image for sprite items, generated, not art, so the same code always makes the same pixels. The raster’s and frame-png’s tests paint it, and a game may write it into its test files.

watch

run --watch: the game’s window program, in a debug build (so with its debug tools on), with the folder of its files on disk laid over the embedded ones and watched (ADR-0071). It isn’t an operation of the contract: it plays nothing headless and answers nothing, and it runs until the player closes the window.

web

web [--release] [--<feature>...]: builds the game’s binary (crate::project::Web) for wasm32-unknown-unknown and packages it with the web shell into the project’s web.dist folder: the page (web/index.html, with the game’s title and binary written in), the vendored JS loaders (web/mq_js_bundle.js, and web/sapp_jsutils.js with web/quad-storage.js for localStorage) and the engine’s own plugins (web/gamepad.js for controllers, web/page-files.js for the files the page hands the game, and the rest). The shell is built into this tool; see web/README.md, which also says how a game’s binary gets the link argument these plugins need. Each --<feature> turns on a feature of the game’s package that web.features lists (a debug build’s tools, say). The game’s music tracks (.ogg in web.music, not embedded) are copied beside the page into a folder of the same name, which exists even when there are none; its voice clips (web.voice, .ogg and .ron) are copied the same way when there is such a folder.

Constants

COMMANDS

The commands of shuyi that aren’t operations of the contract (Op::ALL), as usage lists them: with the contract’s operations and the MCP session’s tools, the commands a skill may name (skills::check).

Functions

main_with

Runs the command args on the project of the working folder, with the game’s tools if this is the game’s tool program, and returns the exit code: 0 for success, 1 for a failed check or step, 2 for wrong arguments (SH0nnn), 3 for a setup to fix before running it again (SH1nnn: no project, a project file that lacks what the command needs, no game tool program, cargo that doesn’t start).

run

Runs the command args on project, with the game’s tools if they are at hand (otherwise a command that runs the game runs the game’s tool program), and returns the exit code (see main_with).

usage

The usage text, with command as the tool’s name.