Written in C++ and using SDL, The Powder Toy is a desktop version of the classic 'falling sand' physics sandbox, it simulates air pressure and velocity as well as heat.
Go to file
Tamás Bálint Misius 8e6faddd2f
Sanitize the Lua API
Mostly in terms of consistency of spelling (o/ou, z/s, upper/lowercase), placement (which table a function/variable is in), and getter/setter functionality (a ton of settings weren't possible to query). All of this is done, or at least is intended to be done, in a backwards-compatible manner; code that worked without errors in 97.0 should work correctly from now on also.

Also punt off duplicated and deprecated features to eventcompat.lua, renamed to just compat.lua, where they are more concisely implemented and more maintainable than on the C++ side.

Note that this means that functionality added since 97.0 is not necessarily preserved, and also that code that worked with errors may or may not keep working with errors, and it highly likely will not produce the same errors. In the future, errors coming from compat.lua should be attempted to be resolved first and foremost by migrating user code to new APIs.

List of notable, included, but not entirely relevant changes, which should probably have been done in separate commits:

 - add an enum for simulation deco spaces, there still are a few things that need such enums though
 - move clamping to Brush::SetRadius, meaning that nothing can set bogus brush sizes from now on, not even Lua
 - have LuaLuna install constructor functions in the interface table, rather than pollute _G with equivalent callable tables

The old APIs now work in accordance with existing documentation on the Wiki, though they retain weird unintended behaviour, such as accepting fewer arguments than documented. I also intend to give new APIs a thorough look later, and possibly organize C++-side code into separate TUs based on which API table it implements.

A list list of API changes follows. "status" is to be interpreted thus:

 - added: new API, the "related" API may be the limited functionality deprecated equivalent the new one is meant to extend
 - deprecated: retained for compatibility (see above), implemented in compat.lua via the "related" API, possibly meant to be removed from existing documentation, or at least very visibly marked deprecated
 - aliases: retained for compatibility (see above), implemented in compat.lua as an alias to the "related" API, possibly meant to be removed from existing documentation, or at least very visibly marked deprecated
 - renamed: not retained for compatibility because it was added after 97.0, the replacement is the "related" API
 - removed: no replacement available, see "note" for reason
 - unchanged: unchanged but noteworthy

 name                      | status     | related                 | note
---------------------------|------------|-------------------------|--------------
 Button                    | deprecated | ui.button               |
 Checkbox                  | deprecated | ui.checkbox             |
 Label                     | deprecated | ui.label                |
 ProgressBar               | deprecated | ui.progressBar          |
 Slider                    | deprecated | ui.slider               |
 Textbox                   | deprecated | ui.textbox              |
 Window                    | deprecated | ui.window               |
 bz2.COMPRESS_LIMIT        | added      | bz2.compressLimit       | identical
 bz2.COMPRESS_NOMEM        | added      | bz2.compressNomem       | identical
 bz2.DECOMPRESS_BAD        | added      | bz2.decompressBad       | identical
 bz2.DECOMPRESS_EOF        | added      | bz2.decompressEof       | identical
 bz2.DECOMPRESS_LIMIT      | added      | bz2.decompressLimit     | identical
 bz2.DECOMPRESS_NOMEM      | added      | bz2.decompressNomem     | identical
 bz2.DECOMPRESS_TYPE       | added      | bz2.decompressType      | identical
 bz2.compressLimit         | deprecated | bz2.COMPRESS_NOMEM      |
 bz2.compressNomem         | deprecated | bz2.COMPRESS_LIMIT      |
 bz2.compressOk            | removed    |                         | bz2.compress never actually returned this
 bz2.decompressBad         | deprecated | bz2.DECOMPRESS_NOMEM    |
 bz2.decompressEof         | deprecated | bz2.DECOMPRESS_LIMIT    |
 bz2.decompressLimit       | deprecated | bz2.DECOMPRESS_TYPE     |
 bz2.decompressNomem       | deprecated | bz2.DECOMPRESS_BAD      |
 bz2.decompressOk          | removed    |                         | bz2.decompress never actually returned this
 bz2.decompressType        | deprecated | bz2.DECOMPRESS_EOF      |
 elem.FLAG_MOVABLE         | deprecated | sim.FLAG_MOVABLE        |
 elem.FLAG_PHOTDECO        | deprecated | sim.FLAG_PHOTDECO       |
 elem.FLAG_SKIPMOVE        | deprecated | sim.FLAG_SKIPMOVE       |
 elem.FLAG_STAGNANT        | deprecated | sim.FLAG_STAGNANT       |
 elem.PROP_DRAWONCTYPE     | deprecated | 0                       |
 elem.ST_GAS               | deprecated | 0                       |
 elem.ST_LIQUID            | deprecated | 0                       |
 elem.ST_NONE              | deprecated | 0                       |
 elem.ST_SOLID             | deprecated | 0                       |
 elem.getByName            | added      | tpt.element             | only converts names to IDs
 evt.AFTERSIM              | added      | evt.aftersim            | identical
 evt.AFTERSIMDRAW          | added      | evt.aftersimdraw        | identical
 evt.BEFORESIM             | added      | evt.beforesim           | identical
 evt.BEFORESIMDRAW         | added      | evt.beforesimdraw       | identical
 evt.BLUR                  | added      | evt.blur                | identical
 evt.CLOSE                 | added      | evt.close               | identical
 evt.KEYPRESS              | added      | evt.keypress            | identical
 evt.KEYRELEASE            | added      | evt.keyrelease          | identical
 evt.MOUSEDOWN             | added      | evt.mousedown           | identical
 evt.MOUSEMOVE             | added      | evt.mousemove           | identical
 evt.MOUSEUP               | added      | evt.mouseup             | identical
 evt.MOUSEWHEEL            | added      | evt.mousewheel          | identical
 evt.TEXTEDITING           | added      | evt.textediting         | identical
 evt.TEXTINPUT             | added      | evt.textinput           | identical
 evt.TICK                  | added      | evt.tick                | identical
 evt.aftersim              | deprecated | evt.AFTERSIM            |
 evt.aftersimdraw          | deprecated | evt.AFTERSIMDRAW        |
 evt.beforesim             | deprecated | evt.BEFORESIM           |
 evt.beforesimdraw         | deprecated | evt.BEFORESIMDRAW       |
 evt.blur                  | deprecated | evt.BLUR                |
 evt.close                 | deprecated | evt.CLOSE               |
 evt.getModifiers          | added      | evt.getmodifiers        | identical
 evt.getmodifiers          | deprecated | evt.getModifiers        |
 evt.keypress              | deprecated | evt.KEYPRESS            |
 evt.keyrelease            | deprecated | evt.KEYRELEASE          |
 evt.mousedown             | deprecated | evt.MOUSEDOWN           |
 evt.mousemove             | deprecated | evt.MOUSEMOVE           |
 evt.mouseup               | deprecated | evt.MOUSEUP             |
 evt.mousewheel            | deprecated | evt.MOUSEWHEEL          |
 evt.textediting           | deprecated | evt.TEXTEDITING         |
 evt.textinput             | deprecated | evt.TEXTINPUT           |
 evt.tick                  | deprecated | evt.TICK                |
 ren.FIRE_SPARK            | added      |                         | was missing
 ren.colourMode            | deprecated | ren.colorMode           |
 ren.debugHUD              | deprecated | ren.debugHud            |
 ren.decorations           | added      | tpt.decorations_enable  | works with booleans
 ren.fireSize              | added      | tpt.setfire             | also a getter, takes intensity only
 ren.hud                   | added      | tpt.hud                 | works with booleans
 ren.useDisplayPreset      | added      | tpt.display_mode        | identical
 sim.AIR_NOUPDATE          | added      | sim.AIR_NO_UPDATE       | identical
 sim.AIR_NO_UPDATE         | renamed    | sim.AIR_NOUPDATE        |
 sim.AIR_PRESSUREOFF       | added      | sim.AIR_PRESSURE_OFF    | identical
 sim.AIR_PRESSURE_OFF      | renamed    | sim.AIR_PRESSUREOFF     |
 sim.AIR_VELOCITYOFF       | added      | sim.AIR_VELOCITY_OFF    | identical
 sim.AIR_VELOCITY_OFF      | renamed    | sim.AIR_VELOCITYOFF     |
 sim.BRUSH_CIRCLE          | added      | sim.CIRCLE_BRUSH        | identical
 sim.BRUSH_NUM             | renamed    | sim.NUM_DEFAULTBRUSHES  |
 sim.BRUSH_SQUARE          | added      | sim.SQUARE_BRUSH        | identical
 sim.BRUSH_TRIANGLE        | added      | sim.TRI_BRUSH           | identical
 sim.CIRCLE_BRUSH          | renamed    | sim.BRUSH_CIRCLE        |
 sim.FLAG_MOVABLE          | added      | elem.FLAG_MOVABLE       | identical
 sim.FLAG_PHOTDECO         | added      | elem.FLAG_PHOTDECO      | identical
 sim.FLAG_SKIPMOVE         | added      | elem.FLAG_SKIPMOVE      | identical
 sim.FLAG_STAGNANT         | added      | elem.FLAG_STAGNANT      | identical
 sim.MAX_PARTS             | added      | sim.NPART               | identical
 sim.NPART                 | renamed    | sim.MAX_PARTS           |
 sim.NUM_AIRMODES          | added      | sim.NUM_AIR_MODES       | identical
 sim.NUM_AIR_MODES         | renamed    | sim.NUM_AIRMODES        |
 sim.NUM_BRUSHES           | added      |                         | specifies the range of valid ui.brushID inputs
 sim.NUM_DEFAULTBRUSHES    | added      | sim.BRUSH_NUM           | identical
 sim.NUM_EDGEMODES         | added      | sim.NUM_EDGE_MODES      | identical
 sim.NUM_EDGE_MODES        | renamed    | sim.NUM_EDGEMODES       |
 sim.NUM_GRAVMODES         | added      | sim.NUM_GRAV_MODES      | identical
 sim.NUM_GRAV_MODES        | renamed    | sim.NUM_GRAVMODES       |
 sim.NUM_PARTS             | deprecated | sim.partCount           |
 sim.NUM_WALLS             | added      |                         | specifies the range of valid sim.wallMap inputs
 sim.SQUARE_BRUSH          | renamed    | sim.BRUSH_SQUARE        |
 sim.TRI_BRUSH             | renamed    | sim.BRUSH_TRIANGLE      |
 sim.ambientHeatSim        | added      | tpt.ambient_heat        | works with booleans
 sim.canMove               | added      | sim.can_move            | identical
 sim.can_move              | deprecated | sim.canMove             |
 sim.decoColour            | deprecated | sim.decoColor           |
 sim.decoSpace             | added      | tpt.decoSpace           | identical, but a function
 sim.elecMap               | added      | tpt.set_elecmap         | also a getter
 sim.ensureDeterminism     | unchanged  |                         | undocumented
 sim.fanVelocityX          | added      | tpt.set_wallmap         | also a getter, sets fan velocity separately
 sim.fanVelocityY          | added      | tpt.set_wallmap         | also a getter, sets fan velocity separately
 sim.frameRender           | added      | sim.framerender         | identical
 sim.framerender           | deprecated | sim.frameRender         |
 sim.golSpeedRatio         | added      | sim.gspeed              | identical
 sim.gravMap               | deprecated | various                 |
 sim.gravityField          | added      | sim.graMap              | gravity simulation output
 sim.gravityMass           | added      | sim.graMap              | also a getter, gravity simulation input
 sim.gspeed                | deprecated | sim.golSpeedRatio       |
 sim.hash                  | unchanged  |                         | undocumented
 sim.heatSim               | added      | tpt.heat                | works with booleans
 sim.neighbours            | deprecated | sim.neighbors           |
 sim.newtonianGravity      | added      | tpt.newtonian_gravity   | works with booleans
 sim.partCount             | added      | tpt.NUM_PARTS           | identical, but a function
 sim.partNeighbours        | deprecated | see sim.partNeighbors   |
 sim.paused                | added      | tpt.set_pause           | works with booleans
 sim.randomSeed            | added      | sim.randomseed          | identical, undocumented
 sim.randomseed            | renamed    | sim.randomSeed          | undocumented
 sim.resetGravityField     | added      | tpt.reset_gravity_field | identical
 sim.resetSpark            | added      | tpt.reset_spark         | identical
 sim.resetVelocity         | added      | tpt.reset_velocity      | identical
 sim.wallMap               | added      | tpt.set_wallmap         | also a getter, doesn't set fan velocity
 sim.waterEqualisation     | deprecated | sim.waterEqualization   |
 sim.waterEqualization     | unchanged  |                         | still works with ints, not worth the trouble
 socket.getTime            | added      | socket.gettime          | identical
 socket.gettime            | deprecated | socket.getTime          |
 tpt.active_menu           | deprecated | ui.activeMenu           |
 tpt.ambient_heat          | deprecated | sim.ambientHeatSim      |
 tpt.brushID               | deprecated | ui.brushID              |
 tpt.brushx                | deprecated | ui.brushRadius          |
 tpt.brushy                | deprecated | ui.brushRadius          |
 tpt.create                | deprecated | various                 |
 tpt.debug                 | added      | tpt.setdebug            | identical
 tpt.decoSpace             | deprecated | sim.decoSpace           |
 tpt.decorations_enable    | deprecated | ren.decorations         |
 tpt.delete                | deprecated | various                 |
 tpt.display_mode          | deprecated | ren.useDisplayPreset    |
 tpt.drawCap               | added      | tpt.setdrawcap          | identical
 tpt.drawline              | deprecated | gfx.drawLine            |
 tpt.drawpixel             | deprecated | gfx.drawPixel           |
 tpt.drawrect              | deprecated | gfx.drawRect            |
 tpt.drawtext              | deprecated | gfx.drawText            |
 tpt.el                    | deprecated | various                 |
 tpt.element               | deprecated | various                 |
 tpt.element_func          | deprecated | elem.property           |
 tpt.eltransition          | deprecated | various                 |
 tpt.fillrect              | deprecated | gfx.fillRect            |
 tpt.fpsCap                | added      | tpt.setfpscap           | identical
 tpt.getPartIndex          | deprecated | various                 |
 tpt.getUserName           | added      | tpt.get_name            | identical
 tpt.get_clipboard         | deprecated | plat.clipboardCopy      |
 tpt.get_elecmap           | deprecated | sim.elecMap             |
 tpt.get_name              | deprecated | tpt.getUserName         |
 tpt.get_numOfParts        | deprecated | sim.partCount           |
 tpt.get_property          | deprecated | sim.partProperty        |
 tpt.get_wallmap           | deprecated | sim.wallMap             |
 tpt.graphics_func         | deprecated | elem.property           |
 tpt.heat                  | deprecated | sim.heatSim             |
 tpt.hud                   | deprecated | ren.hud                 |
 tpt.menu_enabled          | deprecated | ui.menuEnabled          |
 tpt.mousex                | deprecated | ui.mousePosition        |
 tpt.mousey                | deprecated | ui.mousePosition        |
 tpt.newtonian_gravity     | deprecated | sim.newtonianGravity    |
 tpt.next_getPartIndex     | deprecated | various                 |
 tpt.num_menus             | deprecated | ui.numMenus             |
 tpt.parts                 | deprecated | various                 |
 tpt.perfectCircleBrush    | deprecated | ui.perfectCircleBrush   |
 tpt.reset_gravity_field   | deprecated | sim.resetGravityField   |
 tpt.reset_spark           | deprecated | sim.resetSpark          |
 tpt.reset_velocity        | deprecated | sim.resetVelocity       |
 tpt.selecteda             | deprecated | ui.activeTool           |
 tpt.selectedl             | deprecated | ui.activeTool           |
 tpt.selectedr             | deprecated | ui.activeTool           |
 tpt.selectedreplace       | deprecated | ui.activeTool           |
 tpt.set_clipboard         | deprecated | plat.clipboardPaste     |
 tpt.set_console           | deprecated | ui.console              |
 tpt.set_elecmap           | deprecated | sim.elecMap             |
 tpt.set_gravity           | deprecated | sim.gravityMass         |
 tpt.set_pause             | deprecated | sim.paused              |
 tpt.set_pressure          | deprecated | sim.pressure            |
 tpt.set_property          | deprecated | sim.partProperty        |
 tpt.set_wallmap           | deprecated | sim.wallMap             |
 tpt.setdebug              | deprecated | tpt.debug               |
 tpt.setdrawcap            | deprecated | tpt.drawCap             |
 tpt.setfire               | deprecated | ren.fireSize            |
 tpt.setfpscap             | deprecated | tpt.fpsCap              |
 tpt.setwindowsize         | deprecated | ui.windowSize           |
 tpt.start_getPartIndex    | deprecated | various                 |
 tpt.textwidth             | deprecated | gfx.textSize            |
 tpt.toggle_pause          | deprecated | sim.paused              |
 tpt.watertest             | deprecated | sim.waterEqualization   |
 ui.MOUSEUP_BLUR           | added      | ui.MOUSE_UP_BLUR        | identical
 ui.MOUSEUP_DRAWEND        | added      | ui.MOUSE_UP_DRAW_END    | identical
 ui.MOUSEUP_NORMAL         | added      | ui.MOUSE_UP_NORMAL      | identical
 ui.MOUSE_UP_BLUR          | deprecated | ui.MOUSEUP_BLUR         |
 ui.MOUSE_UP_DRAW_END      | deprecated | ui.MOUSEUP_DRAWEND      |
 ui.MOUSE_UP_NORMAL        | deprecated | ui.MOUSEUP_NORMAL       |
 ui.NUM_TOOLINDICES        | added      |                         | specifies the range of valid ui.activeTool inputs
 ui.activeMenu             | added      | tpt.active_menu         | identical
 ui.activeTool             | added      | tpt.selectedl, ...      | identical, but a function
 ui.brushID                | added      | tpt.brushID             | identical, but a function
 ui.brushRadius            | added      | tpt.brushx, tpt.brushy  | identical, but a function
 ui.button                 | added      | Slider:new              | standalone function
 ui.checkbox               | added      | Textbox:new             | standalone function
 ui.console                | added      | tpt.set_console         | works with booleans
 ui.label                  | added      | ProgressBar:new         | standalone function
 ui.menuEnabled            | added      | tpt.menu_enabled        | identical
 ui.mousePosition          | added      | tpt.mousex, tpt.mousey  | identical, but a function
 ui.numMenus               | added      | tpt.num_menus           | identical
 ui.perfectCircleBrush     | added      | tpt.perfectCircleBrush  | identical
 ui.progressBar            | added      | Window:new              | standalone function
 ui.slider                 | added      | Button:new              | standalone function
 ui.textbox                | added      | Label:new               | standalone function
 ui.window                 | added      | Checkbox:new            | standalone function
 ui.windowSize             | added      | tpt.setwindowsize       | also a getter
2024-01-21 11:30:24 +01:00
.github Hopefully fix msys2 workflows 2024-01-20 23:35:53 +01:00
android Auto-detect lldb client/server paths 2024-01-13 22:47:07 +01:00
cross-examples Some native clipboard support for some platforms 2023-12-13 21:49:35 +01:00
resources Add global characters 2024-01-11 18:30:35 +01:00
src Sanitize the Lua API 2024-01-21 11:30:24 +01:00
subprojects Migrate mingw builds to msys2 ucrt, update tpt-libs 2024-01-12 17:05:00 +01:00
.gitattributes Strip whitespace from files in repo (#553) 2018-04-03 21:46:01 -04:00
.gitignore Ignore ignore/ 2021-12-08 14:33:28 +01:00
changelog.txt Make changelog.txt only necessary for mods, not vanilla snapshots 2021-04-17 22:05:08 -04:00
fonttool.py Merge data/ into resources/ 2022-12-25 11:13:46 +01:00
LICENSE Add missing license file (GPLv3) 2012-05-24 19:01:00 +01:00
meson_options.txt Snapshot 358 2024-01-14 21:26:45 +01:00
meson.build Remove meson warning about mingw and lto 2024-01-13 22:51:32 +01:00
README.md Add ctrl+e shortcut to cycle through edge modes 2023-10-05 21:34:09 -04:00

The Powder Toy - January 2023

Get the latest version from the Powder Toy website.

To use online features such as saving, you need to register an account. You can also visit the official TPT forum.

Have you ever wanted to blow something up? Or maybe you always dreamt of operating an atomic power plant? Do you have a will to develop your own CPU? The Powder Toy lets you to do all of these, and even more!

The Powder Toy is a free physics sandbox game, which simulates air pressure and velocity, heat, gravity and a countless number of interactions between different substances! The game provides you with various building materials, liquids, gases and electronic components which can be used to construct complex machines, guns, bombs, realistic terrains and almost anything else. You can then mine them and watch cool explosions, add intricate wirings, play with little stickmen or operate your machine. You can browse and play thousands of different saves made by the community or upload your own we welcome your creations!

There is a Lua API you can automate your work or even make plugins for the game. The Powder Toy is free and the source code is distributed under the GNU General Public License, so you can modify the game yourself or help with development.

Build instructions

See the Powder Toy Development Help section on the main page of the wiki.

Thanks

  • Stanislaw K Skowronek - Designed the original
  • Simon Robertshaw
  • Skresanov Savely
  • cracker64
  • Catelite
  • Victoria Hoyle
  • Nathan Cousins
  • jacksonmj
  • Felix Wallin
  • Lieuwe Mosch
  • Anthony Boot
  • Me4502
  • MaksProg
  • jacob1
  • mniip
  • LBPHacker

Libraries and other assets used

Instructions

Click on the elements with the mouse and draw in the field, like in MS Paint. The rest of the game is learning what happens next.

Controls

Key Action
TAB Switch between circle/square/triangle brush
Space Pause
Q / Esc Quit
Z Zoom
S Save stamp (use with Ctrl when STK2 is out)
L Load last saved stamp
K Stamp library
0-9 Set view mode
P / F2 Save screenshot as .png
E Bring up element search
F Pause and step to next frame
G Increase grid size
Shift + G Decrease grid size
H Show/Hide HUD
Ctrl + H / F1 Show intro text
D / F3 Debug mode (use with Ctrl when STK2 is out)
I Invert Pressure and Velocity map
W Cycle gravity modes (use with Ctrl when STK2 is out)
Y Cycle air modes
Ctrl + E Cycle edge modes
B Enter decoration editor menu
Ctrl + B Toggle decorations on/off
N Toggle Newtonian Gravity on/off
U Toggle ambient heat on/off
Ctrl + I Install powder toy, for loading saves/stamps by double clicking
Backtick Toggle console
= Reset pressure and velocity map
Ctrl + = Reset Electricity
[ Decrease brush size
] Increase brush size
Alt + [ Decrease brush size by 1
Alt + ] Increase brush size by 1
Ctrl + C/V/X Copy/Paste/Cut
Ctrl + Z Undo
Ctrl + Y Redo
Ctrl + Cursor drag Rectangle
Shift + Cursor drag Line
Middle click Sample element
Alt + Left click Sample element
Mouse scroll Change brush size
Ctrl + Mouse scroll Change vertical brush size
Shift + Mouse scroll Change horizontal brush size
Shift + R Horizontal mirror for selected area when pasting stamps
Ctrl + Shift + R Vertical mirror for selected area when pasting stamps
R Rotate selected area counterclockwise when pasting stamps

Command Line

Command Description Example
scale:SIZE Change window scale factor scale:2
kiosk Fullscreen mode
proxy:SERVER[:PORT] Proxy server to use proxy:wwwcache.lancs.ac.uk:8080
open FILE Opens the file as a stamp or game save
ddir DIRECTORY Directory used for saving stamps and preferences
ptsave:SAVEID Open online save, used by ptsave: URLs ptsave:2198
disable-network Disables internet connections
disable-bluescreen Disable bluescreen handler
redirect Redirects output to stdout.txt / stderr.txt
cafile:CAFILE Set certificate bundle path cafile:/etc/ssl/certs/ca-certificates.crt
capath:CAPATH Set certificate directory path capath:/etc/ssl/certs