# Shuyi Engine

> An open-source 2D game engine in Rust, built so that a person and their coding agent can make, run, see, test and replay a game without a window and without guessing.

A game's state changes only through commands (turn games) or inputs per fixed step (real-time games), so the same seed and the same inputs give the same game on every platform. Data, maps, dialogue and test snapshots are plain text. The `shuyi` tool contract makes a game, runs it headless, shows its screen and replays it, as JSON on the command line or as tools over MCP. Games depend on the `shuyi` crate alone. The engine is early and not yet released, and its API still moves; it is under MIT or Apache-2.0.

Start with *Quick start*, under *The book*. Each code block in the book is built and tested with the engine at the same commit.

This copy documents Shuyi Engine 0.1.0 at commit [`f6af4b5`](https://github.com/Zafnok/shuyi-engine/commit/f6af4b515ab153095f3e1056c4bd60269c67909f), of 2026-11-07. It follows the `main` branch and changes with each merge, so a game on a released version reads its version's copy, under *Released versions*. Each page listed under Learn's sections, but the tutorial's, which teaches people from nothing, is also in one file, [llms-full.txt](https://zafnok.github.io/shuyi-engine/llms-full.txt): 218242 bytes, about 54560 tokens.

## Learn

- [Learn](https://zafnok.github.io/shuyi-engine/learn/index.md): The book, the tutorial and the API docs of Shuyi Engine.

## The book

- [The book](https://zafnok.github.io/shuyi-engine/learn/book/index.md): Shuyi Engine, a chapter for each idea it is built on, from installing it to shipping a game.
- [Quick start](https://zafnok.github.io/shuyi-engine/learn/book/quick-start/index.md): Install the tools, make a game with shuyi new, run it in a window and without one, and read what each file is for.
- [A game and its screens](https://zafnok.github.io/shuyi-engine/learn/book/games-and-screens/index.md): Screens on a stack, the transitions between them, the context they share, and text by key.
- [Actions, never keys](https://zafnok.github.io/shuyi-engine/learn/book/actions/index.md): Screens react to actions; the keymap file gives their keys and buttons; text names a key through the player's keymap.
- [The frame and skins](https://zafnok.github.io/shuyi-engine/learn/book/frame-and-skins/index.md): A screen says what it shows as plain data, and a skin paints it; tests read the data.
- [Assets and formats](https://zafnok.github.io/shuyi-engine/learn/book/assets-and-formats/index.md): Kinds of asset are plain types, formats are plugins that read them, the registry finds them by id in a bundle of layers.
- [Rules as commands](https://zafnok.github.io/shuyi-engine/learn/book/rules-as-commands/index.md): A game's rules are a state that changes only through commands, deterministic, with a history and a hash.
- [Saves and settings](https://zafnok.github.io/shuyi-engine/learn/book/saves-and-settings/index.md): Saves and settings go through the player's storage, in the profile in use; a save names its format's version.
- [Testing](https://zafnok.github.io/shuyi-engine/learn/book/testing/index.md): The Harness plays a game with no window, bots play its rules, records replay with a hash per step, and a frame is text or a PNG.
- [Targets and export](https://zafnok.github.io/shuyi-engine/learn/book/targets-and-export/index.md): Each target says what its hardware can do, shuyi check --target holds a game to it, shuyi web builds the browser's page, and shuyi export packages the game for players.
- [Tools for agents](https://zafnok.github.io/shuyi-engine/learn/book/tools-for-agents/index.md): One tool contract, offered as a CLI, an MCP server and Agent Skills, with a stable code on every error.
- [Coming from another engine](https://zafnok.github.io/shuyi-engine/learn/book/from-another-engine/index.md): The words of Godot, Unity, Bevy, GameMaker and PICO-8, and what each is in Shuyi Engine.
- [Fast compiles](https://zafnok.github.io/shuyi-engine/learn/book/fast-compiles/index.md): How long a new game takes to rebuild, and the setup in its Cargo.toml behind it.

## Problem codes

- [Problem codes](https://zafnok.github.io/shuyi-engine/learn/errors/index.md): Every error Shuyi Engine's tools give, by its code: what it means and how to fix it.
- [SH0001: The command's arguments or input are wrong](https://zafnok.github.io/shuyi-engine/learn/errors/sh0001/index.md)
- [SH0002: No game is running in the MCP session](https://zafnok.github.io/shuyi-engine/learn/errors/sh0002/index.md)
- [SH0003: No module of that name is built in the game's engine](https://zafnok.github.io/shuyi-engine/learn/errors/sh0003/index.md)
- [SH0004: The build closed the link at its hello: the token is wrong](https://zafnok.github.io/shuyi-engine/learn/errors/sh0004/index.md)
- [SH0005: The JSON Pointer names no value in the scene's data](https://zafnok.github.io/shuyi-engine/learn/errors/sh0005/index.md)
- [SH1001: No shuyi.ron here or in a folder above](https://zafnok.github.io/shuyi-engine/learn/errors/sh1001/index.md)
- [SH1002: shuyi.ron doesn't read, or lacks what the command needs](https://zafnok.github.io/shuyi-engine/learn/errors/sh1002/index.md)
- [SH1003: A piece of the toolchain is missing](https://zafnok.github.io/shuyi-engine/learn/errors/sh1003/index.md)
- [SH1004: The game doesn't depend on the engine through the shuyi crate](https://zafnok.github.io/shuyi-engine/learn/errors/sh1004/index.md)
- [SH1005: No build is listening at the address](https://zafnok.github.io/shuyi-engine/learn/errors/sh1005/index.md)
- [SH1006: The build speaks another link version than this shuyi](https://zafnok.github.io/shuyi-engine/learn/errors/sh1006/index.md)
- [SH2001: A text file's syntax is wrong](https://zafnok.github.io/shuyi-engine/learn/errors/sh2001/index.md)
- [SH2002: A text file isn't valid UTF-8](https://zafnok.github.io/shuyi-engine/learn/errors/sh2002/index.md)
- [SH2003: A file isn't there](https://zafnok.github.io/shuyi-engine/learn/errors/sh2003/index.md)
- [SH2004: Several files could be the asset](https://zafnok.github.io/shuyi-engine/learn/errors/sh2004/index.md)
- [SH2005: No format reads the file](https://zafnok.github.io/shuyi-engine/learn/errors/sh2005/index.md)
- [SH2006: A file is bigger than its format reads](https://zafnok.github.io/shuyi-engine/learn/errors/sh2006/index.md)
- [SH2007: The pack differs from its sources](https://zafnok.github.io/shuyi-engine/learn/errors/sh2007/index.md)
- [SH2008: A name in the file isn't one it may use](https://zafnok.github.io/shuyi-engine/learn/errors/sh2008/index.md)
- [SH2009: Something given once is given twice](https://zafnok.github.io/shuyi-engine/learn/errors/sh2009/index.md)
- [SH2010: A number or a size is out of range](https://zafnok.github.io/shuyi-engine/learn/errors/sh2010/index.md)
- [SH2101: The game's code or text names a key](https://zafnok.github.io/shuyi-engine/learn/errors/sh2101/index.md)
- [SH2102: A screen's text is written in its code](https://zafnok.github.io/shuyi-engine/learn/errors/sh2102/index.md)
- [SH2103: The rules use what keeps them from being pure and deterministic](https://zafnok.github.io/shuyi-engine/learn/errors/sh2103/index.md)
- [SH2104: The rules depend on a screen, device or tool crate](https://zafnok.github.io/shuyi-engine/learn/errors/sh2104/index.md)
- [SH3001: The game's tools don't offer the operation](https://zafnok.github.io/shuyi-engine/learn/errors/sh3001/index.md)
- [SH3002: The game's tools failed](https://zafnok.github.io/shuyi-engine/learn/errors/sh3002/index.md)
- [SH3003: No such target, or the target profiles don't load](https://zafnok.github.io/shuyi-engine/learn/errors/sh3003/index.md)
- [SH3004: A file the operation reads or writes can't be](https://zafnok.github.io/shuyi-engine/learn/errors/sh3004/index.md)
- [SH3005: The game's tool program didn't build, or stopped before it answered](https://zafnok.github.io/shuyi-engine/learn/errors/sh3005/index.md)
- [SH3006: The build's link is busy, closed, or answered what shuyi can't read](https://zafnok.github.io/shuyi-engine/learn/errors/sh3006/index.md)
- [SH3007: The record was made by another build or with other content](https://zafnok.github.io/shuyi-engine/learn/errors/sh3007/index.md)
- [SH3008: The target's check found errors, so nothing was exported](https://zafnok.github.io/shuyi-engine/learn/errors/sh3008/index.md)
- [SH3009: The built program holds a path of the build machine](https://zafnok.github.io/shuyi-engine/learn/errors/sh3009/index.md)
- [SH3010: The target has no exporter, or no run step, yet](https://zafnok.github.io/shuyi-engine/learn/errors/sh3010/index.md)
- [SH3011: The export's build, or writing its package, failed](https://zafnok.github.io/shuyi-engine/learn/errors/sh3011/index.md)
- [SH3012: The final package holds what the game's disclosure part doesn't allow](https://zafnok.github.io/shuyi-engine/learn/errors/sh3012/index.md)

## The tutorial

- [The tutorial](https://zafnok.github.io/shuyi-engine/learn/tutorial/index.md): Make a whole game from nothing: a box-pushing puzzle, step by step. No programming experience needed.
- [Before you start](https://zafnok.github.io/shuyi-engine/learn/tutorial/00-start/index.md): What a program, a terminal and a game engine are, how to install what you need, and how to read these pages.
- [A new game](https://zafnok.github.io/shuyi-engine/learn/tutorial/01-new/index.md): Make the project with shuyi new, run it, and read every file it wrote, line by line, as your first Rust.
- [A level on the board](https://zafnok.github.io/shuyi-engine/learn/tutorial/02-board/index.md): A level as a text file, read through the format registry, held as the rules' state and drawn by the grid skin.
- [Walking](https://zafnok.github.io/shuyi-engine/learn/tutorial/03-walk/index.md): Commands and rules: the state changes only one way. Actions become commands, and walls refuse them.
- [Pushing](https://zafnok.github.io/shuyi-engine/learn/tutorial/04-push/index.md): Push a box, win when every box is on a target, and test it through the Harness.
- [Undo](https://zafnok.github.io/shuyi-engine/learn/tutorial/05-undo/index.md): Actions of the game's own, and a History of commands that replays to take back a move.
- [Levels and a menu](https://zafnok.github.io/shuyi-engine/learn/tutorial/06-levels/index.md): A level list as a file, a menu screen, and a result handed back to it when a level is won.
- [Saving progress](https://zafnok.github.io/shuyi-engine/learn/tutorial/07-save/index.md): The furthest level reached, kept in the player's storage, with a version so a later build can read it.
- [Polish](https://zafnok.github.io/shuyi-engine/learn/tutorial/08-polish/index.md): A moves counter from the history, and the engine's options and key-rebinding screens.
- [Bots, replays and a frame](https://zafnok.github.io/shuyi-engine/learn/tutorial/09-test/index.md): The game's own tools: a scene a program can read, a bot that plays, a replay that catches a change, and a frame kept as a test.
- [Shipping it](https://zafnok.github.io/shuyi-engine/learn/tutorial/10-ship/index.md): Give the game its id, check it against its targets, build it for the web, and put it on Pages.
- [Glossary](https://zafnok.github.io/shuyi-engine/learn/tutorial/glossary/index.md): Every word this tutorial uses, in one place, with a link to where it was explained.

## Contract

- [The tool contract](https://raw.githubusercontent.com/Zafnok/shuyi-engine/f6af4b515ab153095f3e1056c4bd60269c67909f/docs/contract.md): the operations an agent, CI or a person runs on a game, each with a typed input and a typed answer, on the command line or over MCP
- [Its schemas, version 40](https://zafnok.github.io/shuyi-engine/contract/schemas/v40/index.md): the JSON Schema of each operation's input and answer

## API

- [`shuyi`](https://zafnok.github.io/shuyi-engine/api/shuyi/index.html): rustdoc's HTML. Shuyi Engine's front door: the default engine's crates under short names, the prelude a game names, and one cargo feature per module, each off by default
- [`shuyi_alloc_count`](https://zafnok.github.io/shuyi-engine/api/shuyi_alloc_count/index.html): rustdoc's HTML. Shuyi Engine's heap counter: CountingAlloc, a global allocator around another that counts live bytes, their peak and the calls, in total and by memory tag, and the one counting allocator every debug build of a game on shuyi-app and of its tool program runs on
- [`shuyi_app`](https://zafnok.github.io/shuyi-engine/api/shuyi_app/index.html): rustdoc's HTML. Shuyi Engine's macroquad backend: the window, blitting, keyboard and controllers, the audio player and storage behind shuyi-platform's Platform, and the loop that drives its App on desktop and the web
- [`shuyi_assets`](https://zafnok.github.io/shuyi-engine/api/shuyi_assets/index.html): rustdoc's HTML. 
- [`shuyi_cli`](https://zafnok.github.io/shuyi-engine/api/shuyi_cli/index.html): rustdoc's HTML. Shuyi Engine's tools: the tool contract (new, check, run, scene, replay, bots, import, doctor, with JSON), and frame-png, font-atlas, check-keys, check-text, check-skills, lang-status, web and private-assets, run on a project its shuyi.ron describes
- [`shuyi_core`](https://zafnok.github.io/shuyi-engine/api/shuyi_core/index.html): rustdoc's HTML. Shuyi Engine's core: the seeded RNG, the simulation traits and the tactics kit
- [`shuyi_platform`](https://zafnok.github.io/shuyi-engine/api/shuyi_platform/index.html): rustdoc's HTML. Shuyi Engine's platform boundary: the Platform trait every backend implements, App, which runs one frame of a game for the backend's own loop, the headless backend, and the test Harness over it
- [`shuyi_playdate`](https://zafnok.github.io/shuyi-engine/api/shuyi_playdate/index.html): rustdoc's HTML. Shuyi Engine's Playdate backend: the update callback, the d-pad, A, B and the crank, the 1-bit display with changed rows, storage on the SDK's files, and sound on its sample and file players, behind shuyi-platform's Platform, for a game built by shuyi export playdate
- [`shuyi_sound`](https://zafnok.github.io/shuyi-engine/api/shuyi_sound/index.html): rustdoc's HTML. Shuyi Engine's sound core: decoded samples (`Pcm`), a bounded `Source` of them, an integer mixer, and optional WAV and Ogg Vorbis adapters over permissive libraries. Independent of the engine's other crates, no I/O and no device
- [`shuyi_sound_out`](https://zafnok.github.io/shuyi-engine/api/shuyi_sound_out/index.html): rustdoc's HTML. Shuyi Engine's sound output: hands a mix of 16-bit samples to the system, through CPAL natively and a Web Audio worklet of its own in the browser, with an output that discards it for a machine with no sound
- [`shuyi_ui`](https://zafnok.github.io/shuyi-engine/api/shuyi_ui/index.html): rustdoc's HTML. Shuyi Engine's UI: the frame (glyph console, sprites, backdrop, named colors, snapshots, one-bit renderer), input (actions, keymaps, repeat, controllers, saved bindings, help keys), screens on a stack, the context they share, the frame loop and the tactics kit's grid map

## Released versions

None yet.

## Optional

- [The ADRs](https://raw.githubusercontent.com/Zafnok/shuyi-engine/f6af4b515ab153095f3e1056c4bd60269c67909f/docs/adr/README.md): why each technical choice was made, a record each
- [The roadmap](https://raw.githubusercontent.com/Zafnok/shuyi-engine/f6af4b515ab153095f3e1056c4bd60269c67909f/docs/ROADMAP.md): the order the work is done in, and what is parked