How to make a TPT Element

This is a followup from this tutorial, and will teach you the basics of how to write your very own TPT element. It doesn't, however, bother explaining what various functions do, or what properties mean. You can use my very own Lua reference (update pending), or the wiki for just that.

Setup

To start off, let's pick a namespace. A namespace is something that makes elements unique to you, even if they use the same name. Use your username, it's the most convenient.

The element name you pass to elements.allocate is usually 4 letters, however there's no limit to it being more. This is not the name displayed in the element menu.

Check out the following entries in the reference:

elements.allocate

-- let's make an element called ELEM! 
local element_id = elements.allocate("tutorial-thing", "ELEM")

if element_id == -1 then
  -- no more element slots left, how do we handle this error? up to you!
end

This concludes the entire setup. We now have an element ID that we can use later to set all our element properties.

Cloning an element's properties

Before defining our own properties, we could use elem.element to return us the property table of any existing element, so that we could simply modify the properties we want.

local t = elem.element(elem.DEFAULT_PT_DMND)
elem.element(element_id, t)

Basic properties

We can define basic properties of the element here. We can do it by calling elem.property on the element repeatedly, or as an alternative defining all our properties at once and setting them in one fell swoop.

elem.property(element_id, "Name", "ELEM")
elem.property(element_id, "Colour", 0xFF00FF00)
-- ...

Or, alternatively, we can use the elem.element function with our own table:

elem.element(element_id, {
  Name = "ELEM",
  Colour = 0xFF00FF00,
  MenuVisible = 1,
  MenuSection = elem.SC_WALLS,
  Properties = bit.bor(elem.TYPE_PART, elem.PROP_BLACK, elem.PROP_LIFE_DEC),
  Advection = 0.25
})

((can anyone confirm that this leaves other previously set values intact?))

Update function

Adding a function as a property is as easy as adding any other property, since functions are considered first-class values.

Here's an overview of how to write an update function. Pardon the illegibility, lol

elem.property(element_id, "Update", function(i, x, y, ss, nt) 
  -- code here
end)

Graphics function

As easy as the update function, with a bit of a twist. [Here's my overview][gfx] again on how this is done.

elem.property(element_id, "Graphics", function(i, r, g, b)
  -- code here
end)

[gfx]: http://boxmein.net/tptelements/lua-reference.html#properties.Graphics



...And what a short tutorial that was! Have fun making TPT elements and other 
kinds of mods for Powder Toy. Be sure to [check out the wiki][wk] on how to do
other cool stuff using TPT-specific functionality!

[wk]: http://powdertoy.co.uk/Wiki/W/Powder_Toy_Lua_API.html