Difference between revisions of "Lua API:Elements"

From The Powder Toy
Jump to: navigation, search
m (add missing flag constants)
(use elements.allocate return value in the examples)
Line 31: Line 31:
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
 
local myNewElement = elements.allocate("wiki", "expl")
 
local myNewElement = elements.allocate("wiki", "expl")
elements.element(elements.WIKI_PT_EXPL, elements.element(elements.DEFAULT_PT_WATR))
+
elements.element(myNewElement, elements.element(elements.DEFAULT_PT_WATR))
elements.property(elements.WIKI_PT_EXPL, "Name", "EXPL")
+
elements.property(myNewElement, "Name", "EXPL")
elements.property(elements.WIKI_PT_EXPL, "Description", "This is an example element from the Wiki")
+
elements.property(myNewElement, "Description", "This is an example element from the Wiki")
 
</syntaxhighlight>
 
</syntaxhighlight>
 
In this example, the element properties for our new element (EXPL) are copied from WATR
 
In this example, the element properties for our new element (EXPL) are copied from WATR
  
Player Example:
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
-- RadioActiveLua
+
local star = elements.allocate("ELEMENT", "STAR")
local STAR = elements.allocate("ELEMENT", "STAR")
+
elements.element(star, elements.element(elements.DEFAULT_PT_DMND))
elements.element(elements.ELEMENT_PT_STAR, elements.element(elements.DEFAULT_PT_DMND))
+
elements.property(star, "Name", "STAR")
elements.property(elements.ELEMENT_PT_STAR, "Name", "STAR")
+
elements.property(star, "Description", "STAR. Enough Pressure Makes It Explode Into LAVA.")
elements.property(elements.ELEMENT_PT_STAR, "Description", "STAR. Enough Pressure Makes It Explode Into LAVA.")
+
elements.property(star, "Colour", 0xFFFFFF)
elements.property(elements.ELEMENT_PT_STAR, "Colour", 0xFFFFFF)
+
elements.property(star, "MenuSection", 9)
elements.property(elements.ELEMENT_PT_STAR, "MenuSection", 9)
+
elements.property(star, "HotAir", -0.009)
elements.property(elements.ELEMENT_PT_STAR, "HotAir", -0.009)
+
elements.property(star, "Weight", 333)
elements.property(elements.ELEMENT_PT_STAR, "Weight", 333)
+
elements.property(star, "Temperature", 4556)
elements.property(elements.ELEMENT_PT_STAR, "Temperature", 4556)
+
elements.property(star, "HighPressure", 200)
elements.property(elements.ELEMENT_PT_STAR, "HighPressure", 200)
+
elements.property(star, "HighPressureTransition", elements.DEFAULT_PT_LAVA)
elements.property(elements.ELEMENT_PT_STAR, "HighPressureTransition", elements.DEFAULT_PT_LAVA)
 
 
local function graphics1(i, colr, colg, colb)  
 
local function graphics1(i, colr, colg, colb)  
     return 1,0x00010000,255,100,155,210,255,255,255,255
+
     return 1,ren.FIRE_ADD,255,100,155,210,255,255,255,255
 
end
 
end
tpt.graphics_func(graphics1,STAR)
+
tpt.graphics_func(graphics1, star)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
Another Example, from an actual script. For more info on graphics functions, see the legacy api page
  
 
=== elements.property ===
 
=== elements.property ===

Revision as of 04:25, 2 May 2014

The Elements API Methods and constants for modifying and creating elements. If you want to add an update function or graphics function, see the Legacy API, specifically the functions tpt.element_func and tpt.graphics_func

Methods

elements.allocate

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.

elements.free

elements.free(number elementID)

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)

elements.loadDefault

elements.loadDefault()

Resets all elements to the original state. This will also erase any elements created with any scripts, only the default elements will be available.

elements.loadDefault(number elementID)

Reset an element to its original state before it was modified

elements.element

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", 9)
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
tpt.graphics_func(graphics1, star)

Another Example, from an actual script. For more info on graphics functions, see the legacy api page

elements.property

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

Properties

After creating an element, you can modify any of these properties. Be sure to set Name, Description, and MenuVisible at least.

Name

Name of your element

Colour
Color

These two are the same thing, just use whichever one you like

MenuVisible

Set this to 1 so the element shows up

MenuSection

Set this to one of the menusection constants listed below

Advection
AirDrag

Larger this value , larger air pressure it creates from your particle falling down

AirLoss

Defines air friction , 1 = no air friction.

Loss

1 for no friction , 0.1 for high friction.

Collision
Gravity
Diffusion
HotAir

How much it will increase the pressure around it every frame

Falldown

0 = solid, gas, or energy particle, 1 = powder, 2 = liquid

Flammable

The higher the value, the faster it will burn (on contact with FIRE, SPRK, etc). Extremely high values increase the temperature too.

Explosive

0 = does not explode, 1 = when touching fire, 2 = when touching fire or when pressure > 2.5

Meltable
Hardness

1/Resistance to acid; larger this value = less acid resistance.

Weight

Weight of your particle, if you set your particle weight at 47000 it can deform Titanium.

Temperature

starting temperature, in Kelvin

HeatConduct

Heat conductivity , larger this value = faster heat conductivity to your particle.

Description
State

Use the state constants listed below

Properties

See the property constants listed below. You can set multiple of these, just add them together with + or use the bit api to do this. Be sure to use the Type constants here too, or else it may not act as expected with things like walls.

LowPressure
LowPressureTransition
HighPressure
HighPressureTransition
LowTemperature
LowTemperatureTransition
HighTemperature
HighTemperatureTransition
Update
Graphics

These last two 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 for the new element.

Constants

Any of these constants can be accessed with elements.<constant name here>

Element identifiers

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/

States

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. Powders use the solid state.

Types

These are used in the element "Properties" property and can alter some behavior (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.

Properties

PROP_CONDUCTS
Allows an element to automatically conduct SPRK, requires PROP_LIFE_DEC
PROP_BLACK
Elements with this property absorb photons of any color
PROP_NEUTPENETRATE
Elements with this property allow neutrons to go through it
PROP_NEUTABSORB
Element will absorb neutrons
PROP_NEUTPASS
Element can be displaced by neutrons (observe behavior of wood with neutrons to see)
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. If already at 0 it will be fine.
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_SENSOR
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 15 and 16

Flags

FLAG_STAGNANT

Used by liquids and powders to speed up simulation by moving them less

FLAG_SKIPMOVE

Given to PHOT by PLCN and PBCN to fix gaps in lasers, only useable by energy particles

FLAG_MOVABLE

Can be used to re-enable moving sponge