Difference between revisions of "Lua API:Elements"

From The Powder Toy
Jump to: navigation, search
(Enter a short summary [b])
m (Reverted edits by HerpesMaster11 (talk) to last revision by jacob1)
Line 1: Line 1:
My name is Walter Hartwell White. I live at 308 Negra Arroyo Lane, Albuquerque, New Mexico, 87104. This is my confession. If you're watching this tape, I'm probably dead- murdered by my brother-in-law, Hank Schrader. Hank has been building a meth empire for over a year now, and using me as his chemist. Shortly after my 50th birthday, he asked that I use my chemistry knowledge to cook methamphetamine, which he would then sell using connections that he made through his career with the DEA. I was... astounded. I... I always thought Hank was a very moral man, and I was particularly vulnerable at the time - something he knew and took advantage of. I was reeling from a cancer diagnosis that was poised to bankrupt my family. Hank took me in on a ride-along and showed me just how much money even a small meth operation could make. And I was weak. I didn't want my family to go into financial ruin, so I agreed. Hank had a partner, a businessman named Gustavo Fring. Hank sold me into servitude to this man. And when I tried to quit, Fring threatened my family. I didn't know where to turn. Eventually, Hank and Fring had a falling-out. Things escalated. Fring was able to arrange - uh, I guess... I guess you call it a "hit" - on Hank, and failed, but Hank was seriously injured. And I wound up paying his medical bills, which amounted to a little over $177,000. Upon recovery, Hank was bent on revenge. Working with a man named Hector Salamanca, he plotted to kill Fring. The bomb that he used was built by me, and he gave me no option in it. I have often contemplated suicide, but I'm a coward. I wanted to go to the police, but I was frightened. Hank had risen to become the head of the Albuquerque DEA. To keep me in line, he took my children. For three months, he kept them. My wife had no idea of my criminal activities, and was horrified to learn what I had done. I was in hell. I hated myself for what I had brought upon my family. Recently, I tried once again to quit, and in response, he gave me this. [Walt points to the bruise on his face left by Hank in "Blood Money."] I can't take this anymore. I live in fear every day that Hank will kill me, or worse, hurt my family. All I could think to do was to make this video and hope that the world will finally see this man for what he really is.
+
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.
 +
== 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.
 +
 
 +
Returns -1 on failure (there are no free spaces to create a new element).
 +
 
 +
=== 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
 +
<syntaxhighlight lang="lua">
 +
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")
 +
</syntaxhighlight>
 +
In this example, the element properties for our new element (EXPL) are copied from WATR
 +
 
 +
<syntaxhighlight lang="lua">
 +
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)
 +
</syntaxhighlight>
 +
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 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:
 +
<syntaxhighlight lang="lua">
 +
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)
 +
</syntaxhighlight>
 +
== Constants ==
 +
Any of these constants can be accessed with elements.<constant name here>
 +
 
 +
=== Element identifiers ===
 +
All of the default element identifiers are prefixed with <code>DEFAULT_PT_</code>, for example, the identifier for WATR is <code>DEFAULT_PT_WATR</code>. 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 <tt>src/simulation/elements/</tt>.
 +
 
 +
=== Properties ===
 +
More info on the properties can be found here: [[Element_Properties]]
 +
; TYPE_PART
 +
; TYPE_LIQUID
 +
; TYPE_GAS
 +
; TYPE_SOLID
 +
; TYPE_ENERGY
 +
; PROP_CONDUCTS
 +
; PROP_BLACK
 +
; PROP_NEUTPENETRATE
 +
; PROP_NEUTABSORB
 +
; PROP_NEUTPASS
 +
; PROP_DEADLY
 +
; PROP_HOT_GLOW
 +
; PROP_LIFE
 +
; PROP_RADIOACTIVE
 +
; PROP_LIFE_DEC
 +
; PROP_LIFE_KILL
 +
; PROP_LIFE_KILL_DEC
 +
; PROP_SPARKSETTLE
 +
; PROP_NOAMBHEAT
 +
; PROP_DRAWONCTYPE
 +
; PROP_NOCTYPEDRAW
 +
 
 +
=== 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 ===
 +
set in parts[i].flags
 +
; FLAG_STAGNANT
 +
: Used by liquids and powders to speed up simulation by moving them less
 +
; FLAG_SKIPMOVE
 +
: Given to PHOT by PCLN and PBCN to fix gaps in lasers, only useable by energy particles
 +
; FLAG_WATEREQUAL
 +
: Used internally for water equalization
 +
; FLAG_MOVABLE
 +
: Can be used to re-enable moving sponge
 +
; FLAG_PHOTDECO
 +
: Re-enables deco on photons for compatibility. Defined as the same value as FLAG_MOVABLE (they only apply to different elements)
 +
 
 +
[[Category:Lua]]

Revision as of 04:54, 26 December 2022

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.

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.

Returns -1 on failure (there are no free spaces to create a new element).

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", 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

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 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)

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/.

Properties

More info on the properties can be found here: Element_Properties

TYPE_PART
TYPE_LIQUID
TYPE_GAS
TYPE_SOLID
TYPE_ENERGY
PROP_CONDUCTS
PROP_BLACK
PROP_NEUTPENETRATE
PROP_NEUTABSORB
PROP_NEUTPASS
PROP_DEADLY
PROP_HOT_GLOW
PROP_LIFE
PROP_RADIOACTIVE
PROP_LIFE_DEC
PROP_LIFE_KILL
PROP_LIFE_KILL_DEC
PROP_SPARKSETTLE
PROP_NOAMBHEAT
PROP_DRAWONCTYPE
PROP_NOCTYPEDRAW

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

set in parts[i].flags

FLAG_STAGNANT
Used by liquids and powders to speed up simulation by moving them less
FLAG_SKIPMOVE
Given to PHOT by PCLN and PBCN to fix gaps in lasers, only useable by energy particles
FLAG_WATEREQUAL
Used internally for water equalization
FLAG_MOVABLE
Can be used to re-enable moving sponge
FLAG_PHOTDECO
Re-enables deco on photons for compatibility. Defined as the same value as FLAG_MOVABLE (they only apply to different elements)