The tutorial

This tutorial takes you from nothing to a finished small game: a box-pushing puzzle on a grid. You walk, you push a box, you put every box on a target, you undo a mistake, and the levels come from files you can edit.

You don't need to know how to program. If you have never written a line of code or made a game, you are who this was written for. Every word is explained the first time it comes up, and the glossary keeps them all in one place. If you already program, you can skim the parts about Rust and read the parts about Shuyi.

Along the way you will learn three things at once:

• How games work: frames, screens, input, rules, and why a game keeps what it draws apart from what is true.
• How Shuyi works: the parts the engine gives you, and what each is for.
• As much Rust as a Shuyi game needs, the language the game is written in, each piece explained on the line of the game that uses it.

Each step ends with a game that runs, and you can play it in your browser from that step's page, to see where you are going before you get there. Each step also has pictures of what you should see, and things to try: make this color blue, make this room twice as big, and see the picture of what happens. Trying them is the fastest way to learn what each line does.

Every piece of code on these pages comes from that step's real files, and those are built and tested each time the engine changes, as are the things to try. So what you read here works.

Take your time. The whole tutorial is a few evenings of reading and typing. Start here.

1. Before you start: What a program, a terminal and a game engine are, how to install what you need, and how to read these pages.
1. A new game: Make the project with shuyi new, run it, and read every file it wrote, line by line, as your first Rust.
2. A level on the board: A level as a text file, read through the format registry, held as the rules' state and drawn by the grid skin.
3. Walking: Commands and rules: the state changes only one way. Actions become commands, and walls refuse them.
4. Pushing: Push a box, win when every box is on a target, and test it through the Harness.
5. Undo: Actions of the game's own, and a History of commands that replays to take back a move.
6. Levels and a menu: A level list as a file, a menu screen, and a result handed back to it when a level is won.
7. Saving progress: The furthest level reached, kept in the player's storage, with a version so a later build can read it.
8. Polish: A moves counter from the history, and the engine's options and key-rebinding screens.
9. Bots, replays and a frame: 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.
10. Shipping it: Give the game its id, check it against its targets, build it for the web, and put it on Pages.
11. Glossary: Every word this tutorial uses, in one place, with a link to where it was explained.