Difference between revisions of "Lua API:Elements"

From The Powder Toy
Jump to: navigation, search
(Enter a short summary [alt-b])
 
m (Add menusections)
Line 5: Line 5:
 
=== elements.allocate ===  
 
=== elements.allocate ===  
 
  number elements.allocate(string group, string name)
 
  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)
+
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 ===  
 
=== elements.free ===  
Line 97: Line 97:
  
 
=== Menu sections ===
 
=== Menu sections ===
See <tt>src/simulation/SimulationData.h</tt> For menu sections (SC_*)
+
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

Revision as of 21:22, 15 September 2012

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