Difference between revisions of "Lua API:Elements"

From The Powder Toy
Jump to: navigation, search
(Add NUM_MENUSECTIONS)
(Add PROP_PHOTPASS and remove PROP_BLACK (99.0))
Line 126: Line 126:
 
; TYPE_ENERGY
 
; TYPE_ENERGY
 
; PROP_CONDUCTS
 
; PROP_CONDUCTS
; PROP_BLACK
+
; PROP_PHOTPASS
 
; PROP_NEUTPENETRATE
 
; PROP_NEUTPENETRATE
 
; PROP_NEUTABSORB
 
; PROP_NEUTABSORB

Revision as of 01:26, 27 November 2024

The elements API contains methods and constants for creating and modifying elements.

The shorter alias elem is also available.

Unless stated otherwise, all functions raise errors if supplied with parameters that disagree with their descriptions.

Methods

elements.allocate

Create a new element.

elemNumber = elements.allocate(group, iname)
  • group: string without underscores (_), the group the element belongs to; gets uppercased by the function
  • iname: string without underscores (_), the internal name of the element; gets uppercased by the function
  • elemNumber: the positive element number allocated for the element created, or -1 on error, if there are no free element numbers left

group should be something unique to your script, and should be the same across the entire script. It is common to use a simpler version of your username or the script’s name, for example if your script is called Ultimate Chemistry Pack v3, you might use "CHEMPACK3" as the group name.

iname should be unique to the element within your script, and should ultimately resemble the Name property of the element. For example, if your element’s name is C-6 you should use C6 as the internal name.

The resulting element identifier must be unique across all scripts in use at any point in time. Elements that seem like built-in elements, i.e. ones in the group DEFAULT, cannot be created. Note that, as stated above, both group and iname get uppercased, so elements.allocate("CheMpaCk3", "c6") is equivalent to elements.allocate("CHEMPACK3", "C6").

Make the choice such that it is convenient to refer to your element via an elements.[group]_PT_[iname] constant. While it is perfectly possible to type elem["Ultimate Chemistry Pack v3_PT_C-6"], it is much more convenient to type elem.CHEMPACK3_PT_C6.

The new element is created with all the default properties, and will not be visible until you modify it to show up in the menu.

elements.property

Query or update a property of an element.

propValue = elements.property(elemNumber, propName) -- query variant
elements.property(elemNumber, propName, propValue) -- update variant
elements.property(elemNumber, "Update", propValue, [runWhen]) -- special update variant for the Update property
  • elemNumber: number of the element whose property is to be queried or updated
  • propName: string, name of the property to be queried or updated
  • propValue: various types, value of the property to be queried or updated
  • runWhen: number, specifies when the update function should be run, one of:
    • elements.UPDATE_AFTER: run before the built-in update function, this is the default
    • elements.UPDATE_REPLACE: run instead of the built-in update function
    • elements.UPDATE_BEFORE: run after the built-in update function

For more information on what properties there are to use in elements.property, and how to use them, see this page: Element_Properties.

When working with the "MenuSection" or the "Properties" property, use one of the provided constants.

The "Identifier" property is read-only and cannot be set.

Several event callback functions are implemented, such as "Update" and "Graphics". To set these, use a function for propValue. 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 event callbacks for the new element. For help on creating these, see Element_Properties#Callback_functions.

elements.element

Query all or update multiple properties of an element.

elemProps = elements.element(elemNumber) -- query variant
elements.element(elemNumber, elemProps) -- update variant
  • elemNumber: number of the element whose properties are to be queried or update
  • elemProps: table that maps property names to property values

The keys and values of elemProps are the same as the propName and propValue parameters of elements.property. The query variant returns all properties of the element in elemProps with the same caveats as elements.property. The update variant accepts any subset of properties, only updates the ones present in the table, applying the same checks as elements.property.

This function is commonly used to base an element off another element by first copying all properties of the source element and applying them to the new element, and then customizing the new element a bit afterwards:

local purpleGold = elem.allocate("EXAMPLE", "PGLD")
assert(purpleGold ~= -1, "ran out of element numbers")
elem.element(purpleGold, elem.element(elem.DEFAULT_PT_GOLD))
elem.property(purpleGold, "Name", "PGLD")
elem.property(purpleGold, "Color", 0x8040FF)

elements.exists

Check whether a number is a real element number and refers to an element.

exists = elements.exists(elemNumber)
  • elemNumber: number of the element to be checked
  • exists: boolean, true if elemNumber refers to an element

If an element exists, there exists a corresponding elements.[group]_PT_[iname] constant, and conversely, if there exists such a constant, there exists a corresponding element.

elements.free

Free a previously allocated element.

elements.free(elemNumber)
  • elemNumber: number of the element to be freed

The element number is freed and can used later by another script. Built-in elements, i.e. elements in the group DEFAULT, cannot be freed.

elements.getByName

Find an element by name, the Name property.

elementNumber = elements.getByName(name)
  • name: string, the name to find the element by
  • elemNumber: positive number of the element name refers to, or -1 on error if no such element exists

This function converts a human-friendly element name to an element number, essentially the same way the PROP tool or the console works.

elements.loadDefault

Restore the set of elements to its initial state at startup.

elements.loadDefault()

This frees all elements created and resets all properties of all built-in elements to their defaults.

Constants

elements.[group]_PT_[iname]

watrNumber = elements.DEFAULT_PT_WATR

There are two ways to refer to elements: element numbers and element identifiers, which are strings of the form "[group]_PT_[iname]". Both [group] and [iname] can be any string without underscores (_). All built-in elements are in group DEFAULT. For example, the identifier of WATR is "DEFAULT_PT_WATR", because WATR belongs to the group DEFAULT and its internal name is WATR. This is different from the Name property.

These constants map element identifiers to element numbers. The element number of WATR is 2, so elements.DEFAULT_PT_WATR is also 2.

Properties

These constants should be used when setting "Properties". More info on the properties can be found here: Element_Properties#.Property_Constants

TYPE_PART
TYPE_LIQUID
TYPE_GAS
TYPE_SOLID
TYPE_ENERGY
PROP_CONDUCTS
PROP_PHOTPASS
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_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
NUM_MENUSECTIONS