Difference between revisions of "Element Properties"

From The Powder Toy
Jump to: navigation, search
m (Enter a short summary [b])
m (→‎Callback functions)
(13 intermediate revisions by 7 users not shown)
Line 29: Line 29:
 
| '''Diffusion'''|| How much the particle "wiggles" around (think {{MaterialBtn|GAS}} or {{MaterialBtn|HYGN}}). Set at 0, except for gasses, which is a positive number. Up to 3 (or higher) for a large amount of wiggle, GAS is 0.75f, HYGN is 3.00f.
 
| '''Diffusion'''|| How much the particle "wiggles" around (think {{MaterialBtn|GAS}} or {{MaterialBtn|HYGN}}). Set at 0, except for gasses, which is a positive number. Up to 3 (or higher) for a large amount of wiggle, GAS is 0.75f, HYGN is 3.00f.
 
|-
 
|-
−
| '''HotAir'''|| How much the particle increases the pressure by. Mostly used by gasses, but {{MaterialBtn|VENT}}/{{MaterialBtn|VACU}} have theirs at (-)0.010f, and certain cold/hot materials (e.g. {{MaterialBtn|DRIC}}) have a slight positive/negative value. Usually it's an extremely small number, sometimes as small as 0.000001f.
+
| '''HotAir'''|| How much the particle increases the pressure by. Mostly used by gasses, but {{MaterialBtn|VENT}}/{{MaterialBtn|VACU}} have theirs at (-)0.010f, and certain hot/cold materials (e.g. {{MaterialBtn|DRIC}}) have a slight positive/negative value. Usually it's an extremely small number, sometimes as small as 0.000001f.
 
|-
 
|-
 
| '''Falldown'''|| How does the particle move? 0 = solid, gas, or energy particle, 1 = powder, 2 = liquid.
 
| '''Falldown'''|| How does the particle move? 0 = solid, gas, or energy particle, 1 = powder, 2 = liquid.
Line 50: Line 50:
 
|-
 
|-
 
| '''Properties'''|| Does this element have special properties? At the minimum you need to put the state here too, see below for possible properties (add them together with +).
 
| '''Properties'''|| Does this element have special properties? At the minimum you need to put the state here too, see below for possible properties (add them together with +).
 +
|-
 +
| '''CarriesTypeIn'''|| Does this element carry particle types in properties besides .type? For example, STOR carries type in both .ctype and .tmp. This is a bitflag, set via <code>(1U << FIELD_CTYPE)</code> (C++) or <code>bit.lshift(1, sim.FIELD_CTYPE)</code> (Lua)
 
|-
 
|-
 
| '''LowPressure'''|| If the element drops below this pressure it will transition (set to IPL to never transition).
 
| '''LowPressure'''|| If the element drops below this pressure it will transition (set to IPL to never transition).
Line 70: Line 72:
 
|-
 
|-
 
| '''Graphics'''|| The graphics function, This controls any fancy effects. If your element is only one solid color, you don't need this.
 
| '''Graphics'''|| The graphics function, This controls any fancy effects. If your element is only one solid color, you don't need this.
 +
|-
 +
| '''Create'''|| The create function, This runs a function ONCE when the element is placed/created by something else.
 +
|-
 +
| '''ChangeType'''|| The particle change/kill function. This runs when a particle of the element has its type changed or is destroyed (i.e. has its part changed to NONE). This also runs once when a particle is created.
 +
|}
 +
 +
== Callback functions ==
 +
 +
=== Update ===
 +
number Update(number index, number x, number y, number surround_space, number nt)
 +
Allows you to replace an element's update function. This function is called once every frame for each particle of the assigned element. It is used to define behaviors, interactions, reactions, and dynamic properties of the element.
 +
The function arguments are as follows:
 +
{|
 +
| '''index'''|| The index of the particle currently being updated. This is a unique identifier for each particle.
 +
|-
 +
| '''x, y'''|| The coordinates of the particle currently being updated, measured from the top left of the field. These are the same as the coordinates displayed in the top right of the HUD.
 +
|-
 +
| '''surround_space'''|| This is the number of particles with the same TYPE property in the Moore neighborhood surrounding the particle. Used primarily for GoL type elements.
 +
|-
 +
| '''nt'''|| This is the number of empty spaces in the Moore neighborhood surrounding the particle.
 +
|}
 +
(see Moore neighborhood[https://en.wikipedia.org/wiki/Moore_neighborhood])
 +
 +
The Update function should return nothing if the particle persists, or -1 if the particle is destroyed/killed.
 +
 +
=== Graphics ===
 +
tuple<number> Graphics(number index, number colr, number colg, number colb)
 +
Allows you to replace an element's graphics function. This function is called to determine the visuals and any special effects given to a particle. Depending on its return values, it may be called once every frame for each particle of the assigned element or only once on creation of each particle of the assigned element.
 +
 +
Function arguments:
 +
{|
 +
| '''index'''|| The index of the particle currently being updated. This is a unique identifier for each particle.
 +
|-
 +
| '''colr/g/b'''|| (3 arguments) The red, green, and blue color components of the element. This does not count deco color.
 +
|}
 +
 +
Return values:
 +
{|
 +
| '''cache'''|| Set this to 1 if you don't ever want the function to be called again. Increases performance, but don't do this if you need the way your element looks to change depending on its properties.
 +
|-
 +
| '''pixel_mode'''|| This is a binary flag set used to add special display properties to the element. See the table below for what values you can use and what they do.
 +
|-
 +
| '''cola/r/g/b'''|| (4 values) These set the argb display color of the particle. However, they do not override deco color in most situations. They can be any integer 0-255.
 +
|-
 +
| '''firea/r/g/b'''|| (4 values) These set the fire colors, but pixel_mode needs to be set to 0x00022000 for them to work. They can be any integer 0-255.
 +
|}
 +
 +
The pixel mode values in [https://powdertoy.co.uk/Wiki/W/Lua_API:Renderer.html the <code>ren</code> table] you can use are:
 +
<pre>
 +
PMODE_NONE 0x00000000 --prevents anything from being drawn
 +
PMODE_FLAT 0x00000001 --draw a basic pixel, overwriting the color under it. Doesn't support cola.
 +
PMODE_BLOB 0x00000002 --adds a blobby effect, like you were using blob (5) display mode
 +
PMODE_BLUR 0x00000004 --used in liquids in fancy display mode
 +
PMODE_GLOW 0x00000008 --Glow effect, used in elements like DEUT and TRON in fancy display mode
 +
PMODE_SPARK 0x00000010 -- used for things such as GBMB at first, dimmer than other modes
 +
PMODE_FLARE 0x00000020 --BOMB and other similar elements, brighter than PMODE_SPARK
 +
PMODE_LFLARE 0x00000040 --brightest spark mode, used when DEST hits something
 +
PMODE_ADD 0x00000080 --like PMODE_FLAT, but adds color to a pixel, instead of overwriting it.
 +
PMODE_BLEND 0x00000100 --basically the same thing as PMODE_ADD, but has better OpenGL support
 +
PSPEC_STICKMAN 0x00000200 --does nothing, because the stickmen won't get drawn unless it actually is one
 +
 +
NO_DECO 0x00001000 --prevents decoration from showing on the element (used in LCRY)
 +
DECO_FIRE 0x00002000 --Allow decoration to be drawn on using the fire effect (gasses have this set)
 +
 +
FIRE_ADD 0x00010000 --adds a weak fire effect around the element (ex. LAVA/LIGH)
 +
FIRE_BLEND 0x00020000 --adds a stronger fire effect around the element, default for gasses
 +
 +
EFFECT_GRAVIN 0x01000000 --adds a PRTI effect. Might take some coding in an update function to get it to work properly, PRTI uses life and ctype to create the effects
 +
EFFECT_GRAVOUT 0x02000000 --adds a PRTO effect. Might take some coding in an update function to get it to work properly, PRTO uses life and ctype to create the effects
 +
 +
</pre>
 +
 +
You can combine them in any way you want, you probably need more than one anyway. Radioactive elements default to PMODE_FLAT+PMODE_GLOW, liquids to PMODE_FLAT+PMODE_BLUR, and gasses to FIRE_BLEND+DECO_FIRE, with a firea of 125 and firer/g/b of colr/g/b divided by 2
 +
 +
See this for a picture of what they look like: https://powdertoy.co.uk/Wiki/W/File:Particle_Drawing_Modes.png.html
 +
 +
=== Create ===
 +
none Create(number index, number x, number y, number type, number v)
 +
Allows you to replace an element's creation function. This function is called whenever a particle of the element is placed.
 +
 +
Function arguments:
 +
{|
 +
| '''index'''|| The index of the particle currently being updated. This is a unique identifier for each particle.
 +
|-
 +
| '''x, y'''|| The coordinates of the particle currently being updated, measured from the top left of the field. These are the same as the coordinates displayed in the top right of the HUD.
 +
|-
 +
| '''type'''|| The TYPE property of the particle being placed. This is only necessary if the function serves multiple elements.
 +
|-
 +
| '''v'''|| This is an extra numeric property passed in sim.partCreate as part of the id number (currently bits 9 and above, counting from 0). It is effectively an extra multipurpose parameter for Create functions to handle however they like.
 +
|}
 +
 +
=== ChangeType ===
 +
none ChangeType(number index, number x, number y, number type, number new_type)
 +
Allows you to replace an element's response to change. This function is called whenever a particle of the element is created, changed to another type (such as GLAS -> BGLA), or destroyed. Note that if the element is changed to another type the particle will call the function once, and from that point onward use the function provided by the new type.
 +
 +
The function arguments are as follows:
 +
{|
 +
| '''index'''|| The index of the particle currently being updated. This is a unique identifier for each particle.
 +
|-
 +
| '''x, y'''|| The coordinates of the particle currently being updated, measured from the top left of the field. These are the same as the coordinates displayed in the top right of the HUD.
 +
|-
 +
| '''type'''|| This is the previous TYPE of the element. In the case of a new particle, this is 0, aka NONE.
 +
|-
 +
| '''new_type'''|| This is the new TYPE of the element. In the case of a particle being destroyed, this is 0, aka NONE.
 
|}
 
|}
  

Revision as of 16:21, 8 May 2024

Each element in TPT has properties associated with it that apply to all particles of that type on the screen. This is a list of all those properties (for use in both C++ and Lua)

Properties

Identifier Identifier string, used for lua and internal stuff. Formatted like DEFAULT_PT_XXXX.
Name Name, it is recommended to use 4 letters or less. 5 or more will probably not fit on the buttons. (SPWN2 previously showed as "S..." but now the name just overflows outside of the button)
Color Default color, in hexadecimal (RRGGBB). In the deco editor, it will tell you the color in hex, ignore the initial FF, and use the 6 digits after for this. The initial FF is the alpha or transparency part of 32-bit color.
MenuVisible If it's visible in the menu, if 0 then it is hidden. By default is 0.
MenuSection The menu section it's in. See below for a list of possible values.
Enabled If 0, it cannot be created or seen in any way, not even lua. It will just disappear if somehow created. Used for removed elements, you should leave this 1.
Advection How much the particle is accelerated by moving air. Normally 0 for solids, and up to 1 for other elements. It can be negative, ANAR.png and DEST.png do this so they go towards pressure.
AirDrag How much air the particle generates in the direction of travel. Generally is very small, 0.04f creates a lot of positive air (- creates negative pressure)..
AirLoss How much the particle slows down moving air (although not as big an effect as a wall). 1 = no effect, 0 = maximum effect. Solids are generally above 0.90f, along with most other elements too.
Loss How much velocity the particle loses each frame. 1 = no loss, .5 = half loss. Solids have it at 0. Only a few have it at 1, like energy particles, and old moving sponge.
Collision Velocity is multiplied by this when the particle collides with something. Energy particles have it at -0.99f, everything else is -0.01f or 0.0f. This property does not do much at all.
Gravity How fast the particle falls. A negative number means it floats. Generally very small, most gasses are negative, everything else is usually less than 0.04f.
Diffusion How much the particle "wiggles" around (think GAS.png or HYGN.png). Set at 0, except for gasses, which is a positive number. Up to 3 (or higher) for a large amount of wiggle, GAS is 0.75f, HYGN is 3.00f.
HotAir How much the particle increases the pressure by. Mostly used by gasses, but VENT.png/VACU.png have theirs at (-)0.010f, and certain hot/cold materials (e.g. DRIC.png) have a slight positive/negative value. Usually it's an extremely small number, sometimes as small as 0.000001f.
Falldown How does the particle move? 0 = solid, gas, or energy particle, 1 = powder, 2 = liquid.
Flammable Does it burn? 0 = no, higher numbers = higher "burnage". Something like 20 is WOOD, while C-4 is 1000. Some are a few thousand for almost instant burning.
Explosive Does it explode? 0 = no, 1 = when touching fire, 2 = when touching fire or when pressure > 2.5. Yes, those are the only options, see FIRE.cpp or somewhere in Simulation.cpp to modify how they work. You MUST set the Flammable property also for this to have any effect.
Meltable Does it melt? 1 or higher = yes, 0 = no. This is actually only used when heat sim is off, to make it actually melt use element transitions.
Hardness How much does acid affect it? 0 = no effect, higher numbers = higher effect. Generally goes up to about 50.
Weight Heavier elements sink beneath lighter ones. 1 = Gas. 2 = Light, 98 = Heavy (liquids 0-49, powder 50-99). 100 = Solid. -1 is energy (NEUT.png, PHOT.png etc).
Temperature What temperature does it have when spawned? Temperature is in Kelvin (Kelvin = degrees C + 273.15). R_TEMP+273.15f gives room temperature.
HeatConduct 0 - no heat transfer, 255 - maximum heat transfer speed.
Description A short one-two sentence description of the element, shown when you mouse over it in-game.
Properties Does this element have special properties? At the minimum you need to put the state here too, see below for possible properties (add them together with +).
CarriesTypeIn Does this element carry particle types in properties besides .type? For example, STOR carries type in both .ctype and .tmp. This is a bitflag, set via (1U << FIELD_CTYPE) (C++) or bit.lshift(1, sim.FIELD_CTYPE) (Lua)
LowPressure If the element drops below this pressure it will transition (set to IPL to never transition).
LowPressureTransition The element to transition into when pressure is below the threshold (set to NT to never transition).
HighPressure If the element goes above this pressure it will transition (set to IPH to never transision).
HighPressureTransition The element to transition into when pressure is above the threshold (set to NT to never transition).
LowTemperature If the element drops below this temperature it will transition (set to ITL to never transition).
LowTemperatureTransition The element to transition into when temperature is below the threshold (set to NT to never transition).
HighTemperature If the element goes above this temperature it will transition (set to ITH to never transition).
HighTemperatureTransition The element to transition into when temperature is above the threshold (set to NT to never transition).
Update The update function. This is what controls how your element reacts with other elements.
Graphics The graphics function, This controls any fancy effects. If your element is only one solid color, you don't need this.
Create The create function, This runs a function ONCE when the element is placed/created by something else.
ChangeType The particle change/kill function. This runs when a particle of the element has its type changed or is destroyed (i.e. has its part changed to NONE). This also runs once when a particle is created.

Callback functions

Update

number Update(number index, number x, number y, number surround_space, number nt)

Allows you to replace an element's update function. This function is called once every frame for each particle of the assigned element. It is used to define behaviors, interactions, reactions, and dynamic properties of the element. The function arguments are as follows:

index The index of the particle currently being updated. This is a unique identifier for each particle.
x, y The coordinates of the particle currently being updated, measured from the top left of the field. These are the same as the coordinates displayed in the top right of the HUD.
surround_space This is the number of particles with the same TYPE property in the Moore neighborhood surrounding the particle. Used primarily for GoL type elements.
nt This is the number of empty spaces in the Moore neighborhood surrounding the particle.

(see Moore neighborhood[1])

The Update function should return nothing if the particle persists, or -1 if the particle is destroyed/killed.

Graphics

tuple<number> Graphics(number index, number colr, number colg, number colb)

Allows you to replace an element's graphics function. This function is called to determine the visuals and any special effects given to a particle. Depending on its return values, it may be called once every frame for each particle of the assigned element or only once on creation of each particle of the assigned element.

Function arguments:

index The index of the particle currently being updated. This is a unique identifier for each particle.
colr/g/b (3 arguments) The red, green, and blue color components of the element. This does not count deco color.

Return values:

cache Set this to 1 if you don't ever want the function to be called again. Increases performance, but don't do this if you need the way your element looks to change depending on its properties.
pixel_mode This is a binary flag set used to add special display properties to the element. See the table below for what values you can use and what they do.
cola/r/g/b (4 values) These set the argb display color of the particle. However, they do not override deco color in most situations. They can be any integer 0-255.
firea/r/g/b (4 values) These set the fire colors, but pixel_mode needs to be set to 0x00022000 for them to work. They can be any integer 0-255.

The pixel mode values in the ren table you can use are: 

PMODE_NONE	0x00000000 --prevents anything from being drawn
PMODE_FLAT	0x00000001 --draw a basic pixel, overwriting the color under it. Doesn't support cola.
PMODE_BLOB	0x00000002 --adds a blobby effect, like you were using blob (5) display mode
PMODE_BLUR	0x00000004 --used in liquids in fancy display mode
PMODE_GLOW	0x00000008 --Glow effect, used in elements like DEUT and TRON in fancy display mode
PMODE_SPARK	0x00000010 -- used for things such as GBMB at first, dimmer than other modes
PMODE_FLARE	0x00000020 --BOMB and other similar elements, brighter than PMODE_SPARK
PMODE_LFLARE	0x00000040 --brightest spark mode, used when DEST hits something
PMODE_ADD	0x00000080 --like PMODE_FLAT, but adds color to a pixel, instead of overwriting it.
PMODE_BLEND	0x00000100 --basically the same thing as PMODE_ADD, but has better OpenGL support
PSPEC_STICKMAN	0x00000200 --does nothing, because the stickmen won't get drawn unless it actually is one

NO_DECO		0x00001000 --prevents decoration from showing on the element (used in LCRY)
DECO_FIRE	0x00002000 --Allow decoration to be drawn on using the fire effect (gasses have this set)

FIRE_ADD	0x00010000 --adds a weak fire effect around the element (ex. LAVA/LIGH)
FIRE_BLEND	0x00020000 --adds a stronger fire effect around the element, default for gasses

EFFECT_GRAVIN	0x01000000 --adds a PRTI effect. Might take some coding in an update function to get it to work properly, PRTI uses life and ctype to create the effects
EFFECT_GRAVOUT	0x02000000 --adds a PRTO effect. Might take some coding in an update function to get it to work properly, PRTO uses life and ctype to create the effects

You can combine them in any way you want, you probably need more than one anyway. Radioactive elements default to PMODE_FLAT+PMODE_GLOW, liquids to PMODE_FLAT+PMODE_BLUR, and gasses to FIRE_BLEND+DECO_FIRE, with a firea of 125 and firer/g/b of colr/g/b divided by 2

See this for a picture of what they look like: https://powdertoy.co.uk/Wiki/W/File:Particle_Drawing_Modes.png.html

Create

none Create(number index, number x, number y, number type, number v)

Allows you to replace an element's creation function. This function is called whenever a particle of the element is placed.

Function arguments:

index The index of the particle currently being updated. This is a unique identifier for each particle.
x, y The coordinates of the particle currently being updated, measured from the top left of the field. These are the same as the coordinates displayed in the top right of the HUD.
type The TYPE property of the particle being placed. This is only necessary if the function serves multiple elements.
v This is an extra numeric property passed in sim.partCreate as part of the id number (currently bits 9 and above, counting from 0). It is effectively an extra multipurpose parameter for Create functions to handle however they like.

ChangeType

none ChangeType(number index, number x, number y, number type, number new_type)

Allows you to replace an element's response to change. This function is called whenever a particle of the element is created, changed to another type (such as GLAS -> BGLA), or destroyed. Note that if the element is changed to another type the particle will call the function once, and from that point onward use the function provided by the new type.

The function arguments are as follows:

index The index of the particle currently being updated. This is a unique identifier for each particle.
x, y The coordinates of the particle currently being updated, measured from the top left of the field. These are the same as the coordinates displayed in the top right of the HUD.
type This is the previous TYPE of the element. In the case of a new particle, this is 0, aka NONE.
new_type This is the new TYPE of the element. In the case of a particle being destroyed, this is 0, aka NONE.

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

.Property Constants

These are used for the Properties property.

TYPE_PART
Used in powders.
TYPE_LIQUID
Used in liquids.
TYPE_SOLID
Used in solids / misc elements.
TYPE_GAS
Used in gases.
TYPE_ENERGY
Used in energy particles.
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 can be displaced by neutrons (observe behavior of wood with neutrons to see).
PROP_NEUTABSORB
Element will absorb neutrons.
PROP_NEUTPASS
Element will allow neutrons to pass through it.
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
Element will have a radioactive glow, like URAN or PLUT. Also, deadly to stickmen.
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.
PROP_DRAWONCTYPE
Set its ctype to another element if the element is drawn upon it (like what CLNE does).
PROP_NOCTYPEDRAW
When this element is drawn upon other elements, do not set ctype (like STKM for CLNE).
Retrieved from "https://powdertoy.co.uk/Wiki/index.php?title=Element_Properties&oldid=9267"