The book

The book teaches Shuyi Engine one idea at a time: a quick start, then a chapter for each idea the engine rests on. You don't need to know Rust or to have made a game before. Each chapter says what its idea is for before it names it, explains the Rust its code uses, and shows what it looks like when something goes wrong.

The tutorial and the book are two ways in. The tutorial builds one whole game in order, a step at a time. The book takes one idea and looks at it from every side, so it's also where you come back to when you want to know how something works. If you have never programmed, start with the tutorial's Before you start. The tutorial's glossary lists the words of both.

Read the book in order the first time. Every chapter uses the same small game, Moon Garden: a row of plots, a handful of seeds, and some luck. Every piece of code in it, and every picture, is built and tested with the engine, so it works with the engine of the same day.

  1. Quick start: Install the tools, make a game with shuyi new, run it in a window and without one, and read what each file is for.
  2. A game and its screens: Screens on a stack, the transitions between them, the context they share, and text by key.
  3. Actions, never keys: Screens react to actions; the keymap file gives their keys and buttons; text names a key through the player's keymap.
  4. The frame and skins: A screen says what it shows as plain data, and a skin paints it; tests read the data.
  5. Assets and formats: Kinds of asset are plain types, formats are plugins that read them, the registry finds them by id in a bundle of layers.
  6. Rules as commands: A game's rules are a state that changes only through commands, deterministic, with a history and a hash.
  7. Saves and settings: Saves and settings go through the player's storage, in the profile in use; a save names its format's version.
  8. Testing: 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.
  9. Targets and export: 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.
  10. Tools for agents: One tool contract, offered as a CLI, an MCP server and Agent Skills, with a stable code on every error.
  11. Coming from another engine: The words of Godot, Unity, Bevy, GameMaker and PICO-8, and what each is in Shuyi Engine.

Appendices