Hi!

TPT mods are created by first thinking up what you want to add to TPT. Most people add elements and there are numerous guides to do it.

To add elements or modify how the game works, you need to do some programming. To start off, the easiest would be for you to not poke around in the game's source code - instead make a Lua mod. Lua is a simple programming language and TPT supports it by letting you load Lua mods while the game is playing.

The Lua language

To write a Lua mod, you first need to get yourself acquainted with the Lua programming language. If you're good at Math, here's a Crash Course in Lua. If you're more advanced and want to start quick, hit up the official Programming in Lua, 1st Ed. online book. For code examples, you can use the lua-users Wiki Lua Tutorial. Simply click through any link to find code examples and short (but maybe complicated) examples on what they do.

All of the tutorials above focus on the Lua language, which by itself is used in a lot of places other than Powder Toy. In TPT more specifically, there's a bunch of special functions that you can call that will interact with and control the TPT program.

The Lua - TPT interface

To make an element in TPT, you need to prepare a bunch of data and call functions that will tell TPT how to work with your element. If we'd put all the functions together into one big pile, we would call that pile the Application Programming Interface or API. This is what you'll use to make your Lua script interact with TPT.

The Lua interface in TPT is documented in the wiki and if you're looking for a specific function and how to call it, the Lua reference will come in handy.

Examples

After you sort-of know how Lua looks like, make sure to check out as many examples of different TPT mods in the TPT Script Server and try to understand, modify and load them.

You can load scripts into TPT by moving the saved script files into the TPT folder, opening TPT and writing

dofile("myscript.lua")

. This will load your mod and it'll apply all the changes.

Tinkering

To play around with the TPT Lua API, open the developer console and try random TPT Lua functions in there. Practice changing properties of existing elements - make diamond hot pink, rename FIRE to FYRE, make IRON into a liquid, etcetera.

Coding

For a quick start in creating a TPT element, you can use the TPTElements code editor that automatically fills up some of the code for you. To save what you've written in there, you have to copy-paste it into Notepad (or TextEdit, gedit, or similar plain text editor). For example, I would save my first script as "script.lua" (select All Files in the notepad save menu to keep the file extension! Otherwise it'll add a .txt in the end)

After you've saved your first Lua script, you can load it into TPT by moving your save file into the TPT folder, opening TPT and writing

dofile("myscript.lua")

. This will load your mod and it'll apply all the changes.

And that's it! If you have any questions regarding how to write TPT mods, make sure to join the chat at IRC and ask away.