The Elements API Methods and constants for modifying and creating elements.

Methods

elements.allocate

number elements.allocate(string group, string name)

Creates a new element where group is the name of the mod or script and name is the name of the element, combined, they must make a unique identifier in the form GROUP_PT_NAME (for example, elements.allocate("mymod", "virus") would create the identifier MYMOD_PT_VIRUS). The return value is the ID of the new element. this function also creates a constant value identifier in the elements table (elements.MYMOD_PT_VIRUS is defined as the elements new ID)

elements.free

nil elements.free(number elementID)

Free a previously allocated element to be used later, elementID must be a non-default element (i.e you cannot free the default WATR element)

elements.loadDefault

nil elements.loadDefault()

Resets all elements to the original state

nil elements.loadDefault(number elementID)

Reset an element to its original state before modification

elements.element

table elements.element(number elementID)

Returns a table populated with all of an elements properties (Name, Description, etc)

nil elements.element(number elementID, table properties)

Reads 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(elements.WIKI_PT_EXPL, elements.element(elements.DEFAULT_PT_WATR))
elements.property(elements.WIKI_PT_EXPL, "Name", "EXPL")
elements.property(elements.WIKI_PT_EXPL, "Description", "This is an example element from the Wiki")

In this example, the element properties for our new element (EXPL) are copied from WATR

elements.property

object elements.property(number elementID, string property)

Gets the value of an element property

nil elements.property(number elementID, string property, object value)

Sets the value of an element property

Constants

Element identifiers

All of the default element identifiers are prefixed with DEFAUL_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/

State

There are just 3 constants for element state (Used in the "State" property of elements)

ST_NONE

Used by some "unusual" elements such as Photons

ST_SOLID

ST_LIQUID

ST_GAS

These values do not alter the physical properties of elements, but instead are used internally for identification

Type

These are used in the element "Properties" property and can alter some behaviour (such as interaction with portals, walls, etc)

TYPE_PART

Describes particulate elements such as powders

TYPE_LIQUID

TYPE_GAS

TYPE_SOLID

TYPE_ENERGY

Energy type particles may pass through others and won't create black holes when stacked.

These values do not alter the physical properties of elements, but instead are used internally for identification

Properties

PROP_CONDUCTS

Automatic behaviour, allows an element to conduct SPRK, requires PROP_LIFE_DEC

PROP_BLACK

Elements with this property absorb photons of any colour

PROP_NEUTPENETRATE

Elements with this property allow neutrons to penetrate

PROP_NEUTABSORB

Element will absorb neutrons

PROP_NEUTPASS

Element can be displaced by neutrons (observe behaviour of wood with neutrons)

PROP_DEADLY

Element will kill stickmen and fighters

PROP_HOT_GLOW

Element will glow red when it approaches it's melting point.

PROP_LIFE

Unused

PROP_RADIOACTIVE

Unused

PROP_LIFE_DEC

The "life" property of particles will be reduced by 1 every frame

PROP_LIFE_KILL

Particles will be destroyed when the "life" property is less than or equal to zero

PROP_LIFE_KILL_DEC

When used with PROP_LIFE_DEC, particles will be destroyed when the "life" property is decremented to 0

PROP_SPARKSETTLE

Allows sparks/embers to contact without being destroyed

PROP_NOAMBHEAT

Prevents particles from exchanging heat with the air when ambient heat is enabled.

Menu sections

These are used for the menusection property

SC_WALL

SC_ELEC

SC_POWERED

SC_FORCE

SC_EXPLOSIVE

SC_GAS

SC_LIQUID

SC_POWDERS

SC_SOLIDS

SC_NUCLEAR

SC_SPECIAL

SC_LIFE

SC_TOOL

SC_DECO

SC_CRACKER and SC_CRACKER2 are not accessible from lua or in the game, but have id numbers of 14 and 15