The Powder Toy: a falling-sand physics sandbox with air pressure, heat and a Lua API

What The Powder Toy simulates that a plain falling-sand toy does not

Most falling-sand games model particles and little else. The Powder Toy's README states that it simulates air pressure and velocity as well as heat, and the controls list confirms this is user-facing state: the I key inverts the pressure and velocity map, Ctrl + = resets it, Y cycles air modes, U toggles ambient heat, and N toggles Newtonian gravity. Those are not decoration. They mean a sealed chamber behaves differently from an open one, and a heat source changes what happens around it rather than only colouring pixels.

The audience follows from that. The README frames the game around building bombs, guns, realistic terrains, atomic power plants and even a CPU, then mining them to watch the result. This is a tool for people who enjoy constructing a machine and then stress-testing it, not for someone who wants a level-based puzzle with a win condition. The element list, the brush shapes cycled with TAB, and the copy/paste/cut and undo/redo bindings all point at long editing sessions on a single save.

How the simulation, saves and Lua API fit together

The repository is a C++ project built with Meson: meson.build and meson_options.txt sit at the top level, sources live under src/, and subprojects/ holds dependencies. The README lists the libraries the build pulls in, including SDL, Lua and LuaJIT, FFTW, bzip2, libpng, libcurl, mbedtls, JsonCpp and Mallangche. That mix tells you what the program does at runtime. SDL handles the window and input, libpng writes the screenshots bound to P or F2, libcurl and mbedtls back the online features, and Lua/LuaJIT runs the scripting layer the README advertises for automation and plugins.

Data flow is straightforward in outline. The simulation holds a grid whose cells are elements, and the brush writes elements into that grid while the pressure and velocity map and the heat field evolve alongside it. Saves and stamps are the persistence format; the README notes that Ctrl + I installs the game so saves and stamps can be opened by double clicking, which implies a file association rather than a sandboxed import dialog. Online saving requires a registered account on powdertoy.co.uk, so the save path is not purely local.

The Lua API is the part worth weighing. The README says you can automate your work or make plugins, but it does not document the API surface, versioning or stability. Treat scripting as a real capability with an undocumented contract, and read the wiki and cross-examples/ before assuming a script will survive an upgrade.

Installing The Powder Toy and drawing a first reaction

The README does not contain build or install commands. It says to get the latest version from the Powder Toy website and points to the Powder Toy Development Help section on the wiki for build instructions. So the honest first step is the download page, not a shell command. There is also a Steam listing for the game.

Once it runs, the README's instructions are one sentence: click on the elements with the mouse and draw in the field, like in MS Paint. A first session looks like this. Press E to bring up the element search, type a material name, and select it. Draw a line of it with the left mouse button. Press Space to pause if you want to place several elements before anything moves, then press Space again to resume.

# Build steps are not in the README; the wiki's
# "Powder Toy Development Help" section is the documented source.

The controls worth learning immediately are the brush toggles and the state resets. TAB switches between the circle, square and triangle brush. The bracket keys change brush size, and the mouse scroll wheel does the same. If a test goes wrong, Ctrl + Z undoes and Ctrl + Y redoes.

TAB        switch circle/square/triangle brush
[ ]        decrease / increase brush size
E          element search
Space      pause
Ctrl + Z   undo
Ctrl + Y   redo
I          invert pressure and velocity map

When you have something worth keeping, S saves a stamp and L loads the last saved stamp, while K opens the stamp library. The README notes that S, D and W behave differently when used with Ctrl while STK2 is out, so check the on-screen state before assuming a keypress did what you expected.

Where The Powder Toy stops being the right tool

The project is a desktop game, and the repository layout confirms it: there is an android/ directory, but no library target described in the README that another program could link against. If you need a physics engine to embed in an application, this is the wrong dependency. You would be adopting an SDL application with a GUI, a save format and an account system, and the GPL-3.0 licence travels with it.

There are smaller friction points too. Online features such as saving require a registered account, so an offline-only or air-gapped setup loses part of the advertised workflow. The README documents an enormous key map and no configuration file, which means preferences live in the game rather than in something you can version and check in. And the build instructions are off-repository: the README defers to the wiki, so a fresh clone plus meson.build is not a self-contained recipe. If you are evaluating the project for a reproducible build pipeline, that gap is the first thing you will hit.

The Powder Toy compared with a browser falling-sand sandbox

The obvious alternative is a browser-based falling-sand page, which is what several of the related searches point at. The difference is not cosmetic. A browser sandbox typically runs a particle grid in JavaScript or WebAssembly inside a tab, with no installer, no file association and no local save directory. The Powder Toy is a compiled C++ program using SDL, with libcurl and mbedtls for its online features, libpng for screenshots and LuaJIT for scripting. It also carries the air pressure, velocity and heat fields that the README describes, which a simpler particle toy usually omits.

That trade goes both ways. The browser version wins on access: nothing to install, nothing to register, no platform-specific build. The Powder Toy wins on simulation depth and on extensibility, at the cost of a download, an account for online saving, and a build path that lives on the wiki rather than in the repository. If your goal is to show someone a five-minute explosion, the browser tab is enough. If your goal is to build a machine, script it, and keep the save, the desktop program is the one with the API.

Maintenance, releases and the GPL-3.0 licence

The repository is not archived, and the last push was on 2026-09-09. Recent releases are v100.1.400 on 2026-08-08, v100.0.399 on 2026-06-23 and v100.0.398b on 2026-06-04, and changelog.txt sits at the top level. That is a steady release cadence with an in-repo changelog, which is the cheapest upgrade signal you can ask for: read changelog.txt before moving to a new tag rather than trusting the version number alone.

Upgrade cost is mostly about the save and stamp format and the Lua API. The README does not document format stability or a rollback path for saves, and it does not version the Lua API, so a script written against one release has no stated compatibility guarantee. Keep copies of saves you care about before upgrading.

The licence is GPL-3.0. The README states the source is distributed under the GNU General Public License and that you can modify the game yourself or help with development. If you distribute a modified build, the copyleft terms apply to that distribution. This is a description of the licence identifier in the repository, not legal advice; read the LICENSE file and the GPL-3.0 text for the actual terms.

Editorial conclusion

Adopt The Powder Toy if you want a desktop sandbox where air pressure, velocity and heat are first-class simulation state, or if you intend to script behaviour through the Lua API. Do not adopt it as an embeddable physics engine: it is a game with a GPL-3.0 licence, an SDL window and a save/stamp format of its own, and the repository README does not document a library interface or a rollback path. Before committing, verify the build route on the wiki, since the README only links to the development help page, and confirm the current release tag against the changelog.txt in the repository root.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. The-Powder-Toy/The-Powder-Toy on GitHub