The Elements API contains methods and constants for modifying and creating elements. If you want to add an update function or graphics function, use Update and Graphics properties. See the properties section for an example.
number elements.allocate(string group, string name)
Use this function to create a new element. This function will return the id of your element, and create a unique identifier that can be used to modify the properties later. The identifier is in the form GROUP_PT_NAME, where group is the name of the mod or script (or just anything unique, like your username), and name is the name of the element. For example, elements.allocate("mymod", "virus") would create the identifier MYMOD_PT_VIRUS.
The identifier is added as a constant in the elements table, so elements.MYMOD_PT_VIRUS would be equivalent to the new element's id, and can be used as the elementID argument to any of the functions below.
The new element is created with all the default properties, and won't be visible until you modify it to show up in the menu.
Returns -1 on failure (there are no free spaces to create a new element).
Free a previously allocated element, so it will disappear from the game. The element id will be freed and can used later by another script. elementID must be a non-default element (i.e you cannot free the default WATR element)
Resets all elements to the original state. This will also erase any elements created with any scripts, only the default elements will be available.
Reset an element to its original state before it was modified
table elements.element(number elementID)
Returns a table containing all of an element's properties (Name, Description, etc)
elements.element(number elementID, table properties)
Sets the properties from the given table onto the element.
These two functions are useful for copying or templating from already present elements, for example
local myNewElement = elements.allocate("wiki", "expl") elements.element(myNewElement, elements.element(elements.DEFAULT_PT_WATR)) elements.property(myNewElement, "Name", "EXPL") elements.property(myNewElement, "Description", "This is an example element from the Wiki")
In this example, the element properties for our new element (EXPL) are copied from WATR
local star = elements.allocate("ELEMENT", "STAR") elements.element(star, elements.element(elements.DEFAULT_PT_DMND)) elements.property(star, "Name", "STAR") elements.property(star, "Description", "STAR. Enough Pressure Makes It Explode Into LAVA.") elements.property(star, "Colour", 0xFFFFFF) elements.property(star, "MenuSection", elem.SC_SOLIDS) elements.property(star, "HotAir", -0.009) elements.property(star, "Weight", 333) elements.property(star, "Temperature", 4556) elements.property(star, "HighPressure", 200) elements.property(star, "HighPressureTransition", elements.DEFAULT_PT_LAVA) local function graphics1(i, colr, colg, colb) return 1,ren.FIRE_ADD,255,100,155,210,255,255,255,255 end elements.property(star, "Graphics", graphics1)
Another Example, from an actual script. For more info on graphics functions, see the legacy api page
object elements.property(number elementID, string property)
Gets the value of an element property
elements.property(number elementID, string property, object value)
Sets the value of an element property
After creating an element, you can modify many properties. Be sure to at a minimum set set Name, Description, Color, MenuVisible, and MenuSection.
For more information on what properties there are to use in elements.property, and how to use them, see this page: Element_Properties
"Update" and "Graphics" are special properties, these can be used to set the update functions or graphics functions. Use a function as the value of the property to set. They are not included in the tables created with elements.element, and the functions can't be returned with elements.property either. This means copying all of an elements properties using elements.element will not set these two for the new element. For help on creating graphics function, see Lua#tpt.graphics_func
Here are some examples:
local function funcUpdate(i,x,y,s,nt) for r in sim.neighbors(x,y,1,1) do if sim.partProperty(r, "type") == elem.DEFAULT_PT_COAL then sim.partChangeType(r, elem.DEFAULT_PT_GOLD) end end end local function funcGraphics(i, colr, colg, colb) return 1,ren.FIRE_ADD,255,colr,colg,colb,255,100,0,255 end elements.property(ELEM, "Update", funcUpdate) elements.property(ELEM, "Graphics", funcGraphics)
Any of these constants can be accessed with elements.<constant name here>
All of the default element identifiers are prefixed with
DEFAULT_PT_, for example, the identifier for WATR is
DEFAULT_PT_WATR. Do not assume all elements identifiers are the same as their names, TNT has the identifier BANG, for example. To find an elements identifier, you can check the source file for any given element in src/simulation/elements/.
More info on the properties can be found here: Element_Properties
These are used for the menusection property
SC_CRACKER and SC_CRACKER2 are not accessible from lua or in the game, but have id numbers of 15 and 16
set in parts[i].flags
- Used by liquids and powders to speed up simulation by moving them less
- Given to PHOT by PCLN and PBCN to fix gaps in lasers, only useable by energy particles
- Used internally for water equalization
- Can be used to re-enable moving sponge
- Re-enables deco on photons for compatibility. Defined as the same value as FLAG_MOVABLE (they only apply to different elements)