Difference between revisions of "Lua API:Simulation"

From The Powder Toy
Jump to: navigation, search
(Add type parameter to simulation.neighbors)
m (Fix some stuff)
 
(27 intermediate revisions by 5 users not shown)
Line 2: Line 2:
  
 
== Methods ==
 
== Methods ==
 +
 +
=== simulation.addCustomGol ===
 +
nil sim.addCustomGol(string rule, string name, number color1, number color2)
 +
Adds a custom game of life type with the specified rule, name, and colors. Rule strings use B#/S#/# notation ([https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life#Variations more detail]). Colors are used when fading between multiple states. Names and rules cannot be duplicates.
 +
 +
nil sim.addCustomGol(number rule, string name, number color1, number color2)
 +
Same as above, but takes a binary representation of the rule instead of a string. Bits 0-8 list stay values (starting at 0), bits 9-16 list begin values (starting at 1), and bits 17-20 are the number of states (decimal value added to 2). This is also how GOL rules are stored as ctypes.
  
 
=== simulation.adjustCoords ===
 
=== simulation.adjustCoords ===
Line 44: Line 51:
 
Returns a value on the ambient heat map (the temperature of the air at that point).  
 
Returns a value on the ambient heat map (the temperature of the air at that point).  
  
  nil sim.ambientHeat(number x, number y, number temp, [number width, number height])
+
  nil sim.ambientHeat(number x, number y, [number width, number height], number temp)
 
Sets values on the ambient heat map.  
 
Sets values on the ambient heat map.  
 +
 +
=== simulation.ambientHeatSim ===
 +
sim.ambientHeatSim(enabled)
 +
enabled = sim.ambientHeat()
 +
* <code>enabled</code>: Flag that specifies whether ambient heat is enabled or not.
 +
 +
=== simulation.brush ===
 +
function sim.brush(number x, number y, [number brushWidth, number brushHeight], [number brushID])
 +
Returns an iterator over positions inside the specified brush.
 +
 +
If width, height or ID is not provided, will use values of the current brush selected by user.
 +
 +
Example:
 +
for x, y in sim.brush(300, 200, 100, 50, 0) do
 +
  sim.partCreate(-1, x, y, elem.DEFAULT_PT_DUST)
 +
end
 +
 +
=== simulation.can_move ===
 +
simulation.can_move(number movingElementID, number obstacleElementID, number method)
 +
Decides what a particle does when it hits another particle while moving. Method is one of the following:
 +
* 0: bounce off the obstacle
 +
* 1: swap places with the obstacle
 +
* 2: move over the obstacle
 +
 +
number simulation.can_move(number movingElementID, number obstacleElementID)
 +
Returns what a particle does when it hits another particle while moving, a method like above.
 +
 +
=== simulation.clearRect ===
 +
nil sim.clearRect(number x, number y, number width, number height)
 +
Clears all particles in a rectangle starting at x, y down and to the right width and height pixels respectively.
  
 
=== simulation.clearSim ===
 
=== simulation.clearSim ===
Line 78: Line 115:
 
=== simulation.createWalls ===
 
=== simulation.createWalls ===
 
  number sim.createWalls(number x, number y, [number rx], [number ry], [number walltype])
 
  number sim.createWalls(number x, number y, [number rx], [number ry], [number walltype])
Does something
+
Does something. Probably with walls :/
 +
 
 +
=== simulation.customGravity ===
 +
number, number sim.customGravity()
 +
Returns the current custom gravity settings as x and y values. Left and up are negative x and negative y respectively.
 +
 
 +
nil sim.customGravity(number x, number y)
 +
Sets the custom gravity x and y values. Gravity mode must be set to "custom" to have any effect (see [[#simulation.gravityMode|sim.gravityMode]]).
 +
 
 +
nil sim.customGravity(number y)
 +
Sets the custom gravity y value and sets the x value to 0.
  
 
=== simulation.decoBox ===
 
=== simulation.decoBox ===
Line 109: Line 156:
 
rx and ry describe the radius of the brush used. Default radius is 5, 5.
 
rx and ry describe the radius of the brush used. Default radius is 5, 5.
 
tool refers to decoration tools.
 
tool refers to decoration tools.
 +
 +
=== simulation.decoSpace ===
 +
Controls the color space used by smudge tool.
 +
 +
sim.decoLine(colorSpace)
 +
colorSpace sim.decoLine()
 +
* <code>space</code>: The color space, can be one of these constants:
 +
** <code>DECOSPACE_SRGB</code>: Standard SRGB color space
 +
** <code>DECOSPACE_LINEAR</code>: Linear color space
 +
** <code>DECOSPACE_GAMMA22</code>: Gamma 2.2
 +
** <code>DECOSPACE_GAMMA18</code>: Gamma 1.8
 +
** <code>NUM_DECOSPACES</code>: The total number of color spaces
  
 
=== simulation.deleteStamp ===
 
=== simulation.deleteStamp ===
Line 120: Line 179:
 
  nil sim.edgeMode(number mode)
 
  nil sim.edgeMode(number mode)
 
Sets the current Edge Mode to mode. 0 means normal, 1 creates a wall all the way round the edge of the simulation.  
 
Sets the current Edge Mode to mode. 0 means normal, 1 creates a wall all the way round the edge of the simulation.  
 +
 +
=== simulation.elecMap ===
 +
Interface with the elec map, which is a [[Lua_API:Simulation#Constants_2|CELL-sized]] map used to control powered walls like E-Wall and Detector.
 +
 +
value sim.elecMap(x, y)
 +
sim.elecMap(x, y, value)
 +
sim.elecMap(x, y, w, h, value)
 +
* <code>value</code>: Elec map value. This is an integer that controls for how many frames wall electricity is active in this cell, 0 if there is no power.
 +
* <code>x</code>: x position of the cell
 +
* <code>y</code>: y position of the cell
 +
* <code>w</code>: width (cell count) of the area to set
 +
* <code>h</code>: height (cell count) of the area to set
  
 
=== simulation.elementCount ===
 
=== simulation.elementCount ===
 
  number sim.elementCount(number type)
 
  number sim.elementCount(number type)
 
Returns the number of particles of the specified type in the simulation.
 
Returns the number of particles of the specified type in the simulation.
 +
 +
=== simulation.ensureDeterminism ===
 +
boolean sim.ensureDeterminism()
 +
nil sim.ensureDeterminism(boolean flag)
 +
 +
'''Upcoming in version 98.0'''
 +
 +
Fetch or set ensureDeterminism flag. When this flag is set, extra data is included in saves to ensure simulation RNG state is saved, along with other items needed to guarantee proper determinism upon loading the save. This is only useful for debugging, as different builds of the game may do things slightly differently on different machines. Further, Newtonian gravity is not deterministic with this flag enabled even in debugging scenarios.
 +
 +
=== simulation.fanVelocityX ===
 +
Interface with the fan velocity map, which is a [[Lua_API:Simulation#Constants_2|CELL-sized]] map used to control fan velocity.
 +
 +
value sim.fanVelocityX(x, y)
 +
sim.fanVelocityX(x, y, value)
 +
sim.fanVelocityX(x, y, w, h, value)
 +
* <code>value</code>: Fan X velocity, a floating point value
 +
* <code>x</code>: x position of the cell
 +
* <code>y</code>: y position of the cell
 +
* <code>w</code>: width (cell count) of the area to set
 +
* <code>h</code>: height (cell count) of the area to set
 +
 +
=== simulation.fanVelocityY ===
 +
Interface with the fan velocity map, which is a [[Lua_API:Simulation#Constants_2|CELL-sized]] map used to control fan velocity.
 +
 +
value sim.fanVelocityY(x, y)
 +
sim.fanVelocityY(x, y, value)
 +
sim.fanVelocityY(x, y, w, h, value)
 +
* <code>value</code>: Fan Y velocity, a floating point value
 +
* <code>x</code>: x position of the cell
 +
* <code>y</code>: y position of the cell
 +
* <code>w</code>: width (cell count) of the area to set
 +
* <code>h</code>: height (cell count) of the area to set
 +
 +
=== simulation.floodDeco ===
 +
nil sim.floodDeco(number x, number y, number r, number g, number b, number a)
 +
Flood fills the color at position x, y with another color. Note: Color at position includes console overlay.
  
 
=== simulation.floodParts ===
 
=== simulation.floodParts ===
Line 141: Line 248:
  
 
=== simulation.getSaveID ===
 
=== simulation.getSaveID ===
  number sim.getSaveID()
+
  number, number sim.getSaveID()
Returns the SaveID of the currently loaded save or nil if the simulation is not a downloaded save.
+
Returns the save ID and the history offset of the currently loaded save or nil if the simulation is not a downloaded save. The history offset can be used with loadSave.
 +
 
 +
=== simulation.gravityField ===
 +
Check the gravity output map, which is a [[Lua_API:Simulation#Constants_2|CELL-sized]] map that controls the output of Newtonian Gravity calculation.
 +
 
 +
x-strength y-strength sim.gravityField(x, y)
 +
* <code>x-strength</code>: X strength of the gravity field at this location
 +
* <code>y-strength</code>: Y strength of the gravity field at this location
 +
* <code>x</code>: x position of the cell
 +
* <code>y</code>: y position of the cell
 +
 
 +
=== simulation.gravityMass ===
 +
Interface with the gravity input map, which is a [[Lua_API:Simulation#Constants_2|CELL-sized]] map that controls the input to the Newtonian Gravity calculation. The larger the value, the greater the mass / attraction to this location.
 +
 
 +
strength sim.gravityMass(x, y)
 +
sim.gravityMass(x, y, strength)
 +
sim.gravityMass(x, y, w, h, strength)
 +
* <code>strength</code>: Strength of the input gravity at this location
 +
* <code>x</code>: x position of the cell
 +
* <code>y</code>: y position of the cell
 +
* <code>w</code>: width (cell count) of the area to set
 +
* <code>h</code>: height (cell count) of the area to set
  
 
=== simulation.gravMap ===
 
=== simulation.gravMap ===
 +
'''DEPRECATED IN 98.0, replaced by sim.gravityMass and sim.gravityField'''
 +
 
  number sim.gravMap(number x, number y)
 
  number sim.gravMap(number x, number y)
  nil sim.gravMap(number x, number y, [number width, number height, [number value]])
+
  nil sim.gravMap(number x, number y, [number width, number height,] number value)
 
Returns the newtonian gravity at the given coordinates in the simulation. If given a value, will set the newtonian gravity at those coordinates. Width and height refer to the rectangle of affected cells, starting with the coords. If not given, they will default to 1,1.
 
Returns the newtonian gravity at the given coordinates in the simulation. If given a value, will set the newtonian gravity at those coordinates. Width and height refer to the rectangle of affected cells, starting with the coords. If not given, they will default to 1,1.
  
Line 173: Line 303:
 
|2
 
|2
 
|Radial gravity
 
|Radial gravity
 +
|-
 +
|3
 +
|Custom gravity (see [[#simulation.customGravity|sim.customGravity]])
 
|}
 
|}
  
Line 181: Line 314:
 
  nil sim.gspeed(number newSpeed)
 
  nil sim.gspeed(number newSpeed)
 
Sets the current GoL speed. This is the number of frames between GoL updates. Default is one, larger numbers make it slower.
 
Sets the current GoL speed. This is the number of frames between GoL updates. Default is one, larger numbers make it slower.
 +
 +
=== simulation.hash ===
 +
number simulation.hash()
 +
 +
'''Upcoming in version 98.0'''
 +
 +
Returns a 32-bit int represending the hash of the simulation's current state. Nearly all state is included, including particles, air, gravity, frame count, and rng state. Frame count's inclusion means that the hash changes every frame, even while paused).
 +
 +
=== simulation.heatSim ===
 +
enabled = sim.heatSim()
 +
sim.heatSim(enabled)
 +
* <code>heatSim</code>: boolean flag that specifies whether heat simulation is turned on or off.
 +
 +
=== simulation.historyForward===
 +
boolean simulation.historyForward()
 +
Tries restoring a redo snapshot (ctrl+y). Returns true on success, or false if there is no redo history to restore.
 +
 +
=== simulation.historyRestore ===
 +
boolean simulation.historyRestore()
 +
Tries restoring a history snapshot (ctrl+z). Returns true on success, or false if there is no history to restore.
 +
 +
=== simulation.lastUpdatedID ===
 +
type sim.lastUpdatedID()
 +
Returns the last updated particle ID, if the simulation is currently being stepped through particle-by-particle (either using sim.updateUpTo or user input with tpt.setdebug(0x8)). If subframe particle debugging isn't active, returns nil.
 +
 +
=== simulation.listCustomGol ===
 +
table sim.listCustomGol()
 +
Returns a table of all custom game of life types. Each index has a name (string), rulestr (string), rule (number), color1 (number), and color2 (number) property. See [[#simulation.addCustomGol|sim.addCustomGol]] for details about properties.
 +
 +
=== simulation.listStamps ===
 +
table sim.listStamps()
 +
Returns a table of stamps, in order. Stamp names are 10 characters, with no .stm extention or stamps/ prefix.
  
 
=== simulation.loadSave ===
 
=== simulation.loadSave ===
Line 188: Line 353:
  
 
=== simulation.loadStamp ===
 
=== simulation.loadStamp ===
  type sim.loadStamp(string name, number x, number y)
+
  sim.loadStamp(string filename, number x, number y)
  type sim.loadStamp(number id, number x, number y)
+
  sim.loadStamp(number id, number x, number y)
Loads a stamp identified by filename or ID, and places it at position x,y.
+
Loads a stamp identified by filename or ID, and places it at position x,y. Filenames should be given without stamps/ or the .stm suffix. On success, returns 1. On failure, returns nil and the failure reason as a string.
 +
 
 +
'''Changes staged for 98.0'''
 +
 
 +
The signature changes to:
 +
 
 +
sim.loadStamp(string filename, number x, number y, [boolean hflip, [number rotation, [boolean includePressure]]])
 +
sim.loadStamp(number id, number x, number y, [boolean hflip, [number rotation, [boolean includePressure]]])
 +
 
 +
The following changes are applied to the stamp before pasting, in this order:
 +
* if hflip is true, a horizontal flip is applied to the save (same as pressing Shift+R when pasting)
 +
* if rotation is present, this number of 90-degree counterclockwise rotations are applied to the save (same as pressing R this many times when pasting)
 +
* if the position x,y is not CELL-aligned, the stamp is pasted with its top left corner at the nearest CELL-aligned position toward negative infinity, and the difference between this position and the requested one is achieved via "nudging" (same as pressing the arrow keys a few times when pasting)
  
 
=== simulation.neighbors ===
 
=== simulation.neighbors ===
Line 214: Line 391:
 
=== simulation.neighbours ===
 
=== simulation.neighbours ===
 
Same as sim.neighbors()
 
Same as sim.neighbors()
 +
 +
=== simulation.newtonianGravity ===
 +
enabled = sim.newtonianGravity()
 +
sim.newtonianGravity(enabled)
 +
* <code>newtonianGravity</code>: boolean flag that specifies whether Newtonian Gravity is turned on or off.
  
 
=== simulation.partChangeType ===
 
=== simulation.partChangeType ===
 
  nil sim.partChangeType(number index, number type)
 
  nil sim.partChangeType(number index, number type)
 
Reliably change the type of a particle, this method avoids the side effects created by changing the type directly with the "partProperty" method.
 
Reliably change the type of a particle, this method avoids the side effects created by changing the type directly with the "partProperty" method.
 +
 +
=== simulation.partCount ===
 +
count = sim.partCount()
 +
* <code>count</code>: Total count of all particles in the sim.
  
 
=== simulation.partCreate ===
 
=== simulation.partCreate ===
  number sim.partCreate(number index, number x, number y, number type)
+
  number sim.partCreate(number index, number x, number y, number type, [number v])
 
Create a single particle at location x, y. Returns the index of the new particle, or a negative number on failure.  
 
Create a single particle at location x, y. Returns the index of the new particle, or a negative number on failure.  
  
Line 229: Line 415:
 
* -3 : Create particle without checking for collisions with existing particles. In most cases, this is a bad idea, since a lot of elements don't work properly when there are multiple particles in the same place. Particles may also turn into BHOL if there are too many in the same place. The exception to this is elements that have been specifically designed to cope with this (such as multiple energy particles like PHOT and NEUT in the same place).  
 
* -3 : Create particle without checking for collisions with existing particles. In most cases, this is a bad idea, since a lot of elements don't work properly when there are multiple particles in the same place. Particles may also turn into BHOL if there are too many in the same place. The exception to this is elements that have been specifically designed to cope with this (such as multiple energy particles like PHOT and NEUT in the same place).  
 
* particle index, >= 0 : Overwrite an existing particle with a new particle. At the moment no collision checking is performed, so the same considerations apply as for index=-3. It is usually safe if the new particle is in the same location as the old one. This is roughly equivalent to calling sim.partKill then sim.partCreate(-3, ...).
 
* particle index, >= 0 : Overwrite an existing particle with a new particle. At the moment no collision checking is performed, so the same considerations apply as for index=-3. It is usually safe if the new particle is in the same location as the old one. This is roughly equivalent to calling sim.partKill then sim.partCreate(-3, ...).
 +
 +
=== simulation.partExists ===
 +
boolean sim.partExists(number index)
 +
Returns true if a particle exists at a given index.
  
 
=== simulation.partID ===
 
=== simulation.partID ===
Line 252: Line 442:
  
 
=== simulation.partNeighbors ===
 
=== simulation.partNeighbors ===
  number ... sim.partNeighbours(number x, number y, number radius, [number type])
+
  table sim.partNeighbours(number x, number y, number radius, [number type])
Returns a list of particles indexes that neighbour the given coordinates that matches the given type (if it is specified) The resulting list does not contain the "origin particle"
+
Returns an array of indices of particles that neighbour the given coordinates and match the given type (if it is specified). The resulting array does not contain the particle at the specified position.
  
 
=== simulation.partNeighbours ===
 
=== simulation.partNeighbours ===
Line 274: Line 464:
 
  function sim.parts()
 
  function sim.parts()
 
Returns an iterator over particle indexes that can be used in lua for loops
 
Returns an iterator over particle indexes that can be used in lua for loops
 +
 +
=== simulation.paused ===
 +
flag = sim.paused()
 +
sim.paused(flag)
 +
* <code>flag</code>: Boolean flag that says whether or not the sim is paused.
 +
 +
Checks whether or not the simulation is paused. Processing may also continue if the 'f' framerender shortcut is used, which can last for long periods of time. [[#simulation.framerender|sim.framerender]] should be used to check for that
  
 
=== simulation.pmap ===
 
=== simulation.pmap ===
 
  number sim.pmap(number x, number y)
 
  number sim.pmap(number x, number y)
Get the index of the particle at the specified position. Returns 0 if there is no particle there. This function is very similar to sim.partID, but excludes energy particles (such as PHOT, NEUT, ELEC).
+
Get the index of the particle at the specified position. Returns nil if there is no particle there. This function is very similar to sim.partID, but excludes energy particles (such as PHOT, NEUT, ELEC).
  
 
=== simulation.photons ===
 
=== simulation.photons ===
 
  number sim.photons(number x, number y)
 
  number sim.photons(number x, number y)
Get the index of the energy particle at the specified position. Returns 0 if there is no particle there. This function is very similar to sim.pmap
+
Get the index of the energy particle at the specified position. Returns nil if there is no particle there. This function is very similar to sim.pmap
  
 
=== simulation.pressure ===
 
=== simulation.pressure ===
Line 287: Line 484:
 
Returns a value on the pressure map.
 
Returns a value on the pressure map.
  
  nil sim.pressure(number x, number y, number pressure, [number width, number height])
+
  nil sim.pressure(number x, number y, [number width, number height], number pressure)
 
Sets values on the pressure map.
 
Sets values on the pressure map.
  
Line 294: Line 491:
 
  nil sim.prettyPowders(mode)
 
  nil sim.prettyPowders(mode)
 
Sets whether the "pretty powders mode" (powders, such as SAND or BCOL, will be assigned random deco values) is on or off. When called with no arguments, returns a value determining whether it is on or off.
 
Sets whether the "pretty powders mode" (powders, such as SAND or BCOL, will be assigned random deco values) is on or off. When called with no arguments, returns a value determining whether it is on or off.
 +
 +
=== simulation.randomSeed ===
 +
number seed0Lower, number seed0Upper, number seed1Lower, number seed1Upper sim.randomSeed()
 +
nil sim.randomSeed(number seed0Lower, number seed0Upper, number seed1Lower, number seed1Upper)
 +
 +
'''Upcoming in version 98.0'''
 +
 +
Retrieve or set the seed used for the Simulation RNG. This RNG is used by TPT to generate random numbers during sim contexts. The renderer RNG and interface RNG are unaffected.
 +
 +
Because seeds are 64 bits, they are fetched/set in two sets of 32 bits integers.
  
 
=== simulation.reloadSave ===
 
=== simulation.reloadSave ===
 
  nil sim.reloadSave()
 
  nil sim.reloadSave()
 
Reloading save.
 
Reloading save.
 +
 +
=== simulation.removeCustomGol ===
 +
boolean sim.removeCustomGol(string name)
 +
Removes all custom game of life types with the specified name. Returns true if any were removed.
 +
 +
=== simulation.resetGravityField ===
 +
sim.resetGravityField()
 +
Resets the gravity field to 0. While this will temporarily stop all Newtonian Gravity output, any changes will regenerate the gravity map based on the gravity sources in the sim.
  
 
=== simulation.resetPressure ===
 
=== simulation.resetPressure ===
  nil sim.resetPressure()
+
  sim.resetPressure()
 
Resets the pressure map to no pressure.
 
Resets the pressure map to no pressure.
 +
 +
=== simulation.resetSpark ===
 +
sim.resetSpark()
 +
Same effect as the ctrl+= shortcut. Removes all sparks from the simulation and resets them to .life = 0. SPRK with invalid ctypes are deleted. Also resets all wifi cooldowns.
  
 
=== simulation.resetTemp ===
 
=== simulation.resetTemp ===
  nil sim.resetTemp()
+
  sim.resetTemp()
 
Resets the temperature of all particles to their spawn temperature.
 
Resets the temperature of all particles to their spawn temperature.
 +
 +
=== simulation.resetVelocity ===
 +
sim.resetVelocity()
 +
Resets the air velocity map to 0. This map controls the flow of air. Resetting this will have some effect on particles, but won't stop them in their tracks.
 +
 +
=== simulation.replaceModeFlags ===
 +
number sim.replaceModeFlags()
 +
Returns the current replace mode flags.
 +
nil sim.replaceModeFlags(number flags)
 +
Sets the replace mode flags.
 +
 +
If the first bit of that number is set (flags = 1), replace mode is enabled.
 +
 +
If the second bit is set (flags = 2), specific delete is enabled.
  
 
=== simulation.saveStamp ===
 
=== simulation.saveStamp ===
  string sim.saveStamp([number x, number y, number width, number height])
+
  string sim.saveStamp([number x, number y, number width, number height, [boolean includePressure]])
 
Creates a stamp of the specified coordinates. Coordinates default to entire simulation.
 
Creates a stamp of the specified coordinates. Coordinates default to entire simulation.
 
Returns the stamp id created.
 
Returns the stamp id created.
Line 315: Line 548:
 
  table simulation.signs
 
  table simulation.signs
 
A table of signs. simulation.signs[1] through simulation.signs[16] are always defined.
 
A table of signs. simulation.signs[1] through simulation.signs[16] are always defined.
 +
 +
==== Constants ====
 +
* <code>sim.signs.MAX_SIGNS</code>: The maximum number of signs that can exist at once
 +
* <code>sim.signs.JUSTMODE_LEFT</code>: Left justification
 +
* <code>sim.signs.JUSTMODE_MIDDLE</code>: Middle (default) justification
 +
* <code>sim.signs.JUSTMODE_RIGHT</code>: Right justification
 +
* <code>sim.signs.JUSTMODE_NONE</code>: No justification, sign won't have any "tail"
 +
* <code>sim.signs.NUM_JUSTMODES</code>: The number of justification modes
  
 
==== simulation.signs[n] ====
 
==== simulation.signs[n] ====
Line 321: Line 562:
 
A justification of 0 means left, 1 means right, 2 means middle and 3 means none.
 
A justification of 0 means left, 1 means right, 2 means middle and 3 means none.
 
The text property cannot be larger than 45 in length.
 
The text property cannot be larger than 45 in length.
 +
 +
==== simulation.signs.delete ====
 +
nil simulation.signs.delete(number signID)
 +
Deletes the sign at the specified sign id.
  
 
==== simulation.signs.new ====
 
==== simulation.signs.new ====
Line 329: Line 574:
 
  nil sim.takeSnapshot()
 
  nil sim.takeSnapshot()
 
Takes a undo snapshot, for use with ctrl + z
 
Takes a undo snapshot, for use with ctrl + z
 +
 +
=== simulation.temperatureScale ===
 +
number sim.temperatureScale()
 +
Returns the current temperature scale. 0 = Kelvin, 1 = Celsuis, 2 = Fahrenheit
 +
 +
nil sim.temperatureScale(number newTemperatureScale)
 +
Sets the current temperature scale. 0 = Kelvin, 1 = Celsuis, 2 = Fahrenheit. Other options are invalid and will throw an error.
  
 
=== simulation.toolBox ===
 
=== simulation.toolBox ===
 
  type sim.toolBox(number x1, number y1, number x2, number y2, [number tool], [number strength])
 
  type sim.toolBox(number x1, number y1, number x2, number y2, [number tool], [number strength])
Does something
+
Performs the given tool (HEAT, COOL, AIR, etc) in a rectangular area.
  
 
=== simulation.toolBrush ===
 
=== simulation.toolBrush ===
Line 340: Line 592:
 
=== simulation.toolLine ===
 
=== simulation.toolLine ===
 
  type sim.toolLine(number x1, number y1, number x2, number y2, [number rx], [number ry], [number tool], [number brush], [number strength])
 
  type sim.toolLine(number x1, number y1, number x2, number y2, [number rx], [number ry], [number tool], [number brush], [number strength])
Does something
+
Performs the given tool (HEAT, COOL, AIR, etc) as if a line was drawn across the given coordinates with the given brush size. The brush types are 0 (circle), 1 (square) and 2 (triangle).
 +
 
 +
=== simulation.updateUpTo ===
 +
nil sim.updateUpTo([number upTo])
 +
Updates the simulation, but only up to the specified particle ID. Works as if shift+f is pressed while in particle debug mode (tpt.setdebug(0x8)). If no arguments are passed in, updates to the end of the frame.
  
 
=== simulation.velocityX ===
 
=== simulation.velocityX ===
Line 346: Line 602:
 
Returns an X value on the velocity map.
 
Returns an X value on the velocity map.
  
  nil sim.velocityX(number x, number y, [number value], [number width, number height])
+
  nil sim.velocityX(number x, number y, [number width, number height], number value)
 
Sets X values on the velocity map.
 
Sets X values on the velocity map.
  
Line 353: Line 609:
 
Returns an Y value on the velocity map.
 
Returns an Y value on the velocity map.
  
  nil sim.velocityY(number x, number y, [number value], [number width, number height])
+
  nil sim.velocityY(number x, number y, [number width, number height], number value)
 
Sets Y values on the velocity map.
 
Sets Y values on the velocity map.
 +
 +
=== simulation.wallMap ===
 +
Interface with the wall map, which is a [[Lua_API:Simulation#Constants_2|CELL-sized]] map that specifies which walls are at what position.
 +
 +
wallType sim.wallMap(x, y)
 +
sim.wallMap(x, y, wallType)
 +
sim.wallMap(x, y, w, h, wallType)
 +
* <code>wallType</code>: Wall type to set, wall type will be one of the constants in [[Lua_API:Simulation#Walls|sim.walls]]
 +
* <code>x</code>: x position of the cell
 +
* <code>y</code>: y position of the cell
 +
* <code>w</code>: width (cell count) of the area to set
 +
* <code>h</code>: height (cell count) of the area to set
  
 
=== simulation.waterEqualisation ===
 
=== simulation.waterEqualisation ===
Line 368: Line 636:
 
== Constants ==
 
== Constants ==
 
Any of these constants can be accessed with simulation.<constant name here>
 
Any of these constants can be accessed with simulation.<constant name here>
 +
 +
; XRES
 +
X Resolution of the sim
 +
; YRES
 +
Y Resolution of the sim
 +
; CELL
 +
Size of a wall / air simulation block
 +
; XCELLS
 +
The number of cells in the X direction
 +
; YCELLS
 +
The number of cells in the Y direction
 +
; NCELL
 +
The total number of cells in the simulation
 +
; NT
 +
No transition, used in *Transition [https://powdertoy.co.uk/Wiki/W/Element_Properties.html properties]
 +
; ST
 +
Special transition, used in *Transition properties, but there is no way to set a special transition handler from Lua
 +
; ITH
 +
Impossible temperature high, used along with NT to disable transitions
 +
; ITL
 +
Impossible temperature low, used along with NT to disable transitions
 +
; IPH
 +
Impossible pressure high, used along with NT to disable transitions
 +
; IPL
 +
Impossible pressure low, used along with NT to disable transitions
 +
; PT_NUM
 +
Maximum number of element IDs. Does not reflect the current number of elements, only the maximum that can be enabled at one time.
 +
; NUM_PARTS
 +
Not actually a constant, this is updated every frame to reflect the current number of particles in the sim. Deprecated by sim.partCount (TODO document that and remove this)
 +
; MAX_PARTS
 +
Maximum number of particles that can exist at once
 +
; R_TEMP
 +
Room temperature (22C), the default temperature for many elements
 +
; MAX_TEMP
 +
Maximum allowable temperature of the sim, in Kelvin
 +
; MIN_TEMP
 +
Minimum allowable temperature of the sim, in Kelvin
 +
; MAX_PRESSURE
 +
Maximum allowable pressure of the sim
 +
; MIN_PRESSURE
 +
Minimum allowable pressure of the sim
 +
; MAX_VELOCITY
 +
Particle velocity cap
 +
; ISTP
 +
Movement code step value. Particles scan their trajectory and only check for blockers each step.
 +
; CFDS
 +
Air sim related
 +
; PMAPBITS
 +
Number of bits used in pmap to store element type. This controls the element cap, which is 2^PMAPBITS
 +
; PMAPMASK
 +
Mask used to assign type to pmap. ((1<<PMAPBITS)-1)
  
 
=== DECO ===
 
=== DECO ===
; DECO_DIVIDE
+
Used in deco drawing functions
; DECO_SMUDGE
+
; DECO_DRAW
 +
; DECO_CLEAR
 
; DECO_ADD
 
; DECO_ADD
 
; DECO_SUBTRACT
 
; DECO_SUBTRACT
; DECO_CLEAR
 
; DECO_DRAW
 
 
; DECO_MULTIPLY
 
; DECO_MULTIPLY
 +
; DECO_DIVIDE
 +
; DECO_SMUDGE
 +
 +
=== TOOL ===
 +
Used in tool drawing functions
 +
; TOOL_HEAT
 +
; TOOL_COOL
 +
; TOOL_VAC
 +
; TOOL_AIR
 +
; TOOL_PGRV
 +
; TOOL_NGRV
 +
; TOOL_MIX
 +
; TOOL_CYCL
 +
; TOOL_WIND
  
 
=== FIELD ===
 
=== FIELD ===
; FIELD_DCOLOUR
+
Used in sim.partProperty
 +
; FIELD_TYPE
 +
; FIELD_LIFE
 +
; FIELD_CTYPE
 +
; FIELD_X
 
; FIELD_Y
 
; FIELD_Y
 +
; FIELD_VX
 +
; FIELD_VY
 
; FIELD_TEMP
 
; FIELD_TEMP
; FIELD_TYPE
+
; FIELD_FLAGS
; FIELD_VY
+
; FIELD_TMP
; FIELD_X
 
 
; FIELD_TMP2
 
; FIELD_TMP2
; FIELD_TMP
+
; FIELD_TMP3
; FIELD_FLAGS
+
; FIELD_TMP4
; FIELD_VX
+
; FIELD_DCOLOUR
; FIELD_CTYPE
 
; FIELD_LIFE
 
 
 
=== MAX ===
 
; MAX_TEMP
 
  
=== MIN ===
+
=== BRUSH ===
; MIN_TEMP
+
Used in certain brush drawing functions
 +
; BRUSH_CIRCLE
 +
; BRUSH_SQUARE
 +
; BRUSH_TRIANGLE
 +
; NUM_DEFAULTBRUSHES
 +
Number of default brushes
 +
; BRUSH_NUM
 +
Number of total brushes, including any custom brushes
  
=== NUM ===
+
=== EDGE ===
; NUM_PARTS
+
Used in sim.edgeMode
 +
; EDGE_VOID
 +
; EDGE_SOLID
 +
; EDGE_LOOP
 +
; NUM_EDGEMODES
  
=== PT ===
+
=== AIR ===
; PT_NUM
+
Used in sim.airMode
 +
; AIR_ON
 +
; AIR_PRESSUREOFF
 +
; AIR_VELOCITYOFF
 +
; AIR_OFF
 +
; AIR_NOUPDATE
 +
; NUM_AIRMODES
  
=== R ===
+
=== GRAV ===
; R_TEMP
+
Used in sim.gravityMode
 +
; GRAV_VERTICAL
 +
; GRAV_OFF
 +
; GRAV_RADIAL
 +
; GRAV_CUSTOM
 +
; NUM_GRAVMODES
  
=== TOOL ===
+
=== Walls ===
; TOOL_VAC
+
; NUM_WALLS
; TOOL_AIR
+
; walls
; TOOL_NGRV
+
sim.walls is a table containing a mapping of wall IDs to wall identifiers, and wall identifiers to wall IDs. This may come in handy for working with ui.activeTool, which uses identifiers.
; TOOL_PGRV
 
; TOOL_HEAT
 
; TOOL_WIND
 
; TOOL_COOL
 
  
=== Uncategorized ===
+
=== FLAG ===
; YRES
+
Used in .flags property
; XRES
+
; FLAG_MOVABLE
 +
; FLAG_PHOTDECO
 +
; FLAG_SKIPMOVE
 +
; FLAG_STAGNANT
  
 
[[Category:Lua]]
 
[[Category:Lua]]

Latest revision as of 21:41, 27 March 2024

The Simulation API allows for modifying the state and properties of particles, air and gravity

Contents

Methods

simulation.addCustomGol

nil sim.addCustomGol(string rule, string name, number color1, number color2)

Adds a custom game of life type with the specified rule, name, and colors. Rule strings use B#/S#/# notation (more detail). Colors are used when fading between multiple states. Names and rules cannot be duplicates.

nil sim.addCustomGol(number rule, string name, number color1, number color2)

Same as above, but takes a binary representation of the rule instead of a string. Bits 0-8 list stay values (starting at 0), bits 9-16 list begin values (starting at 1), and bits 17-20 are the number of states (decimal value added to 2). This is also how GOL rules are stored as ctypes.

simulation.adjustCoords

number, number sim.adjustCoords(number x, number y)

Actually this is more of a UI method than a simulation method. Given a mouse position x, y in the window, this function returns the corresponding coordinates in the simulation (taking into account the visibility and position of the zoom window, if applicable).

simulation.airMode

number sim.airMode()

Returns the current Air Simulation Mode.

nil sim.airMode(number mode)

Sets the Air Simulation Mode to mode.

Mode numbers are as follows (not currently available as named constants):

0 Normal
1 Pressure off
2 Velocity off
3 Velocity and pressure off
4 No update

simulation.ambientAirTemp

number sim.ambientAirTemp()

Returns the current ambient temperature. When ambient heat mode is turned on, the air at the edges of the screen will remain at this temperature.

nil sim.ambientAirTemp(number temp)

Sets the ambient temperature. The temperature is measured in Kelvin.

simulation.ambientHeat

number sim.ambientHeat(number x, number y)

Returns a value on the ambient heat map (the temperature of the air at that point).

nil sim.ambientHeat(number x, number y, [number width, number height], number temp)

Sets values on the ambient heat map.

simulation.ambientHeatSim

sim.ambientHeatSim(enabled)
enabled = sim.ambientHeat()
  • enabled: Flag that specifies whether ambient heat is enabled or not.

simulation.brush

function sim.brush(number x, number y, [number brushWidth, number brushHeight], [number brushID])

Returns an iterator over positions inside the specified brush.

If width, height or ID is not provided, will use values of the current brush selected by user.

Example:

for x, y in sim.brush(300, 200, 100, 50, 0) do
 sim.partCreate(-1, x, y, elem.DEFAULT_PT_DUST)
end

simulation.can_move

simulation.can_move(number movingElementID, number obstacleElementID, number method)

Decides what a particle does when it hits another particle while moving. Method is one of the following:

  • 0: bounce off the obstacle
  • 1: swap places with the obstacle
  • 2: move over the obstacle
number simulation.can_move(number movingElementID, number obstacleElementID)

Returns what a particle does when it hits another particle while moving, a method like above.

simulation.clearRect

nil sim.clearRect(number x, number y, number width, number height)

Clears all particles in a rectangle starting at x, y down and to the right width and height pixels respectively.

simulation.clearSim

nil sim.clearSim()

Clears everything in the simulation.

simulation.createBox

nil sim.createBox(number x1, number y1, number x2, number y2, [number type], [number flag])

Creates a filled box of either the user's currently selected type or the type specified at the specified coordinates. flag refers to particle replacement flags.

simulation.createLine

nil sim.createLine(number x1, number y1, number x2, number y2, [number rx], [number ry], [number type], [number brush], [number, flag])

Creates a line of of either the user's currently selected type or the type specified at the specified coordinates. rx and ry describe the radius of the brush used. Default radius is 5, 5. flag refers to particle replacement flags.

simulation.createParts

number sim.createParts(number x, number y, [number rx], [number ry], [number type], [number brush], [number flag])

Does something.

simulation.createWallBox

nil sim.createWallBox(number x1, number y1, number x2, number y2, [number walltype])

Creates a filled box of either the specified walltype or the type of the basic wall at the specified particle coordinates. Note: the coordinates might change from particle coordinates to map coordinates in the future.

simulation.createWallLine

nil sim.createWallLine(number x1, number y1, number x2, number y2, [number rx], [number ry], [number walltype])

Creates a line of either the specified walltype or the type of the basic wall at the specified particle coordinates. Note: the coordinates might change from particle coordinates to map coordinates in the future.

simulation.createWalls

number sim.createWalls(number x, number y, [number rx], [number ry], [number walltype])

Does something. Probably with walls :/

simulation.customGravity

number, number sim.customGravity()

Returns the current custom gravity settings as x and y values. Left and up are negative x and negative y respectively.

nil sim.customGravity(number x, number y)

Sets the custom gravity x and y values. Gravity mode must be set to "custom" to have any effect (see sim.gravityMode).

nil sim.customGravity(number y)

Sets the custom gravity y value and sets the x value to 0.

simulation.decoBox

nil sim.decoBox(number x1, number y1, number x2, number y2, [number r, number g, number b, [number a]], [number tool])

Changes the decoration color of all particles in the specified coordinates. tool refers to decoration tools.

simulation.decoBrush

nil sim.decoBrush(number x, number y, [number rx], [number ry], [number r, number g, number b, [number a]], [number tool], [number brush])

Does something tool refers to decoration tools.

simulation.decoColor

number sim.decoColor()

Returns the currently selected decoration color.

nil sim.decoColor(number color)

Sets the selected decoration color to color. color is in the format 0xAARRGGBB

nil sim.decoColor(number r, number g, number b, [number a])

Sets the selected decoration color to r,g,b,a

simulation.decoColour

Same as sim.decoColor()

simulation.decoLine

nil sim.decoLine(number x1, number y1, number x2, number y2, [number rx], [number ry], [number r, number g, number b, [number a]], [number tool], [number brush])

Changes the decoration color of all particles in the line specified. rx and ry describe the radius of the brush used. Default radius is 5, 5. tool refers to decoration tools.

simulation.decoSpace

Controls the color space used by smudge tool.

sim.decoLine(colorSpace)
colorSpace sim.decoLine()
  • space: The color space, can be one of these constants:
    • DECOSPACE_SRGB: Standard SRGB color space
    • DECOSPACE_LINEAR: Linear color space
    • DECOSPACE_GAMMA22: Gamma 2.2
    • DECOSPACE_GAMMA18: Gamma 1.8
    • NUM_DECOSPACES: The total number of color spaces

simulation.deleteStamp

type sim.deleteStamp(string name)

Deleting a stamp identified by filename or ID.

simulation.edgeMode

number sim.edgeMode()

Returns the current Edge Mode

nil sim.edgeMode(number mode)

Sets the current Edge Mode to mode. 0 means normal, 1 creates a wall all the way round the edge of the simulation.

simulation.elecMap

Interface with the elec map, which is a CELL-sized map used to control powered walls like E-Wall and Detector.

value sim.elecMap(x, y)
sim.elecMap(x, y, value)
sim.elecMap(x, y, w, h, value)
  • value: Elec map value. This is an integer that controls for how many frames wall electricity is active in this cell, 0 if there is no power.
  • x: x position of the cell
  • y: y position of the cell
  • w: width (cell count) of the area to set
  • h: height (cell count) of the area to set

simulation.elementCount

number sim.elementCount(number type)

Returns the number of particles of the specified type in the simulation.

simulation.ensureDeterminism

boolean sim.ensureDeterminism()
nil sim.ensureDeterminism(boolean flag)

Upcoming in version 98.0

Fetch or set ensureDeterminism flag. When this flag is set, extra data is included in saves to ensure simulation RNG state is saved, along with other items needed to guarantee proper determinism upon loading the save. This is only useful for debugging, as different builds of the game may do things slightly differently on different machines. Further, Newtonian gravity is not deterministic with this flag enabled even in debugging scenarios.

simulation.fanVelocityX

Interface with the fan velocity map, which is a CELL-sized map used to control fan velocity.

value sim.fanVelocityX(x, y)
sim.fanVelocityX(x, y, value)
sim.fanVelocityX(x, y, w, h, value)
  • value: Fan X velocity, a floating point value
  • x: x position of the cell
  • y: y position of the cell
  • w: width (cell count) of the area to set
  • h: height (cell count) of the area to set

simulation.fanVelocityY

Interface with the fan velocity map, which is a CELL-sized map used to control fan velocity.

value sim.fanVelocityY(x, y)
sim.fanVelocityY(x, y, value)
sim.fanVelocityY(x, y, w, h, value)
  • value: Fan Y velocity, a floating point value
  • x: x position of the cell
  • y: y position of the cell
  • w: width (cell count) of the area to set
  • h: height (cell count) of the area to set

simulation.floodDeco

nil sim.floodDeco(number x, number y, number r, number g, number b, number a)

Flood fills the color at position x, y with another color. Note: Color at position includes console overlay.

simulation.floodParts

number sim.floodParts(number x, number y, [number type], [number cm?], [number flag])

Flood fills either the user's currently selected type or the type specified at the coordinates given. flag refers to particle replacement flags.

simulation.floodWalls

number sim.floodWalls(number x, number y, [number walltype], [number bm?])

Flood fills either the specified walltype or the type of the basic wall at the specified particle coordinates. Note: the coordinates might change from particle coordinates to map coordinates in the future.

simulation.framerender

number sim.framerender()
sim.framerender(number frames)

Advances the simulation the given number of frames, even when paused. If called with no arguments, returns the number of frames currently to be rendered. Usually is 0.

simulation.getSaveID

number, number sim.getSaveID()

Returns the save ID and the history offset of the currently loaded save or nil if the simulation is not a downloaded save. The history offset can be used with loadSave.

simulation.gravityField

Check the gravity output map, which is a CELL-sized map that controls the output of Newtonian Gravity calculation.

x-strength y-strength sim.gravityField(x, y)
  • x-strength: X strength of the gravity field at this location
  • y-strength: Y strength of the gravity field at this location
  • x: x position of the cell
  • y: y position of the cell

simulation.gravityMass

Interface with the gravity input map, which is a CELL-sized map that controls the input to the Newtonian Gravity calculation. The larger the value, the greater the mass / attraction to this location.

strength sim.gravityMass(x, y)
sim.gravityMass(x, y, strength)
sim.gravityMass(x, y, w, h, strength)
  • strength: Strength of the input gravity at this location
  • x: x position of the cell
  • y: y position of the cell
  • w: width (cell count) of the area to set
  • h: height (cell count) of the area to set

simulation.gravMap

DEPRECATED IN 98.0, replaced by sim.gravityMass and sim.gravityField

number sim.gravMap(number x, number y)
nil sim.gravMap(number x, number y, [number width, number height,] number value)

Returns the newtonian gravity at the given coordinates in the simulation. If given a value, will set the newtonian gravity at those coordinates. Width and height refer to the rectangle of affected cells, starting with the coords. If not given, they will default to 1,1.

simulation.gravityGrid

number sim.gravityGrid()

Returns the current setting for drawing the gravity grid. More of a renderer setting than a simulation setting.

nil sim.gravityGrid(number mode)

Sets the setting for drawing the gravity grid to mode.

simulation.gravityMode

number sim.gravityMode()

Returns the current gravity simulation mode.

nil sim.gravityMode(number mode)

Sets the gravity simulation mode to mode.

0 Normal, vertical gravity
1 No gravity
2 Radial gravity
3 Custom gravity (see sim.customGravity)

simulation.gspeed

number sim.gspeed()

Returns the current GoL speed

nil sim.gspeed(number newSpeed)

Sets the current GoL speed. This is the number of frames between GoL updates. Default is one, larger numbers make it slower.

simulation.hash

number simulation.hash()

Upcoming in version 98.0

Returns a 32-bit int represending the hash of the simulation's current state. Nearly all state is included, including particles, air, gravity, frame count, and rng state. Frame count's inclusion means that the hash changes every frame, even while paused).

simulation.heatSim

enabled = sim.heatSim()
sim.heatSim(enabled)
  • heatSim: boolean flag that specifies whether heat simulation is turned on or off.

simulation.historyForward

boolean simulation.historyForward()

Tries restoring a redo snapshot (ctrl+y). Returns true on success, or false if there is no redo history to restore.

simulation.historyRestore

boolean simulation.historyRestore()

Tries restoring a history snapshot (ctrl+z). Returns true on success, or false if there is no history to restore.

simulation.lastUpdatedID

type sim.lastUpdatedID()

Returns the last updated particle ID, if the simulation is currently being stepped through particle-by-particle (either using sim.updateUpTo or user input with tpt.setdebug(0x8)). If subframe particle debugging isn't active, returns nil.

simulation.listCustomGol

table sim.listCustomGol()

Returns a table of all custom game of life types. Each index has a name (string), rulestr (string), rule (number), color1 (number), and color2 (number) property. See sim.addCustomGol for details about properties.

simulation.listStamps

table sim.listStamps()

Returns a table of stamps, in order. Stamp names are 10 characters, with no .stm extention or stamps/ prefix.

simulation.loadSave

nil sim.loadSave(number SaveID, [number hideDescription], [number history?])

Loads the save associated with the specified SaveID. If hideDescription is non zero, the information for the save is not shown.

simulation.loadStamp

sim.loadStamp(string filename, number x, number y)
sim.loadStamp(number id, number x, number y)

Loads a stamp identified by filename or ID, and places it at position x,y. Filenames should be given without stamps/ or the .stm suffix. On success, returns 1. On failure, returns nil and the failure reason as a string.

Changes staged for 98.0

The signature changes to:

sim.loadStamp(string filename, number x, number y, [boolean hflip, [number rotation, [boolean includePressure]]])
sim.loadStamp(number id, number x, number y, [boolean hflip, [number rotation, [boolean includePressure]]])

The following changes are applied to the stamp before pasting, in this order:

  • if hflip is true, a horizontal flip is applied to the save (same as pressing Shift+R when pasting)
  • if rotation is present, this number of 90-degree counterclockwise rotations are applied to the save (same as pressing R this many times when pasting)
  • if the position x,y is not CELL-aligned, the stamp is pasted with its top left corner at the nearest CELL-aligned position toward negative infinity, and the difference between this position and the requested one is achieved via "nudging" (same as pressing the arrow keys a few times when pasting)

simulation.neighbors

type sim.neighbors(number x, number y, [number rx], [number ry], [number type])

Used for iterating through particles in an area centred on the given coordinates (x, y). Radius in the x and y directions is set by rx and ry. Default radius is 2, 2. If type is provided, only particles of the corresponding type will be returned.

The size of the rectangular area is one plus twice the radius, so a radius of 2, 2 gives a 5x5 pixel area centred on x, y. Particles in the centre position x, y are excluded. Only one particle in each position is included, and energy particles (such as photons, neutrons, electrons) are ignored.

Example (i is the index of the neighbouring particle and nx, ny are its coordinates):

for i,nx,ny in sim.neighbors(100,200,1,1) do
 sim.partProperty(i, sim.FIELD_TEMP, 9999)
end

Or if coordinates of the neighbouring particles are not required:

for i in sim.neighbors(100,200,1,1) do
 sim.partProperty(i, sim.FIELD_TEMP, 9999)
end

simulation.neighbours

Same as sim.neighbors()

simulation.newtonianGravity

enabled = sim.newtonianGravity()
sim.newtonianGravity(enabled)
  • newtonianGravity: boolean flag that specifies whether Newtonian Gravity is turned on or off.

simulation.partChangeType

nil sim.partChangeType(number index, number type)

Reliably change the type of a particle, this method avoids the side effects created by changing the type directly with the "partProperty" method.

simulation.partCount

count = sim.partCount()
  • count: Total count of all particles in the sim.

simulation.partCreate

number sim.partCreate(number index, number x, number y, number type, [number v])

Create a single particle at location x, y. Returns the index of the new particle, or a negative number on failure.

Possible values for index are:

  • -1 : Normal particle creation. This is the most useful value. No particle is created if position x, y is occupied and the requested new particle type cannot pass through the particle that is already there.
  • -2 : Create particle as though it was drawn by the user with the brush. Usually not useful.
  • -3 : Create particle without checking for collisions with existing particles. In most cases, this is a bad idea, since a lot of elements don't work properly when there are multiple particles in the same place. Particles may also turn into BHOL if there are too many in the same place. The exception to this is elements that have been specifically designed to cope with this (such as multiple energy particles like PHOT and NEUT in the same place).
  • particle index, >= 0 : Overwrite an existing particle with a new particle. At the moment no collision checking is performed, so the same considerations apply as for index=-3. It is usually safe if the new particle is in the same location as the old one. This is roughly equivalent to calling sim.partKill then sim.partCreate(-3, ...).

simulation.partExists

boolean sim.partExists(number index)

Returns true if a particle exists at a given index.

simulation.partID

number sim.partID(number x, number y)

Get the index of a particle at the specified position. As of v89.3, this will return nil if there is no particle there.

Example (though this is probably best done with sim.neighbours):

for fx = -1, 1, 1 do
 for fy = -1, 1, 1 do
  local i = sim.partID(x + fx, y + fy)
  if i~=nil and sim.partProperty(i, 'type') == elements.DEFAULT_PT_DMND then
   sim.partProperty(index, sim.FIELD_TEMP, 9999)
  end
 end
end

simulation.partKill

nil sim.partKill(number index)
nil sim.partKill(number x, number y)

Reliably delete a particle at a specified index or location, this method avoids the side effects created by changing the type to 0/DEFAULT_PT_NONE with the "partProperty" method

simulation.partNeighbors

table sim.partNeighbours(number x, number y, number radius, [number type])

Returns an array of indices of particles that neighbour the given coordinates and match the given type (if it is specified). The resulting array does not contain the particle at the specified position.

simulation.partNeighbours

Same as sim.partNeighbors()

simulation.partPosition

number x, number y sim.partPosition(number index)

Get the location of the particle at the specified index

simulation.partProperty

nil sim.partProperty(number index, object field, object value)

Set the property value on a particle specified by index

object sim.partProperty(number index, object field)

Get the property value on a particle specified by the index

The "field" may be a field name or field ID, see FIELD constants below for valid fields.

simulation.parts

function sim.parts()

Returns an iterator over particle indexes that can be used in lua for loops

simulation.paused

flag = sim.paused()
sim.paused(flag)
  • flag: Boolean flag that says whether or not the sim is paused.

Checks whether or not the simulation is paused. Processing may also continue if the 'f' framerender shortcut is used, which can last for long periods of time. sim.framerender should be used to check for that

simulation.pmap

number sim.pmap(number x, number y)

Get the index of the particle at the specified position. Returns nil if there is no particle there. This function is very similar to sim.partID, but excludes energy particles (such as PHOT, NEUT, ELEC).

simulation.photons

number sim.photons(number x, number y)

Get the index of the energy particle at the specified position. Returns nil if there is no particle there. This function is very similar to sim.pmap

simulation.pressure

number sim.pressure(number x, number y)

Returns a value on the pressure map.

nil sim.pressure(number x, number y, [number width, number height], number pressure)

Sets values on the pressure map.

simulation.prettyPowders

number sim.prettyPowders()
nil sim.prettyPowders(mode)

Sets whether the "pretty powders mode" (powders, such as SAND or BCOL, will be assigned random deco values) is on or off. When called with no arguments, returns a value determining whether it is on or off.

simulation.randomSeed

number seed0Lower, number seed0Upper, number seed1Lower, number seed1Upper sim.randomSeed()
nil sim.randomSeed(number seed0Lower, number seed0Upper, number seed1Lower, number seed1Upper)

Upcoming in version 98.0

Retrieve or set the seed used for the Simulation RNG. This RNG is used by TPT to generate random numbers during sim contexts. The renderer RNG and interface RNG are unaffected.

Because seeds are 64 bits, they are fetched/set in two sets of 32 bits integers.

simulation.reloadSave

nil sim.reloadSave()

Reloading save.

simulation.removeCustomGol

boolean sim.removeCustomGol(string name)

Removes all custom game of life types with the specified name. Returns true if any were removed.

simulation.resetGravityField

sim.resetGravityField()

Resets the gravity field to 0. While this will temporarily stop all Newtonian Gravity output, any changes will regenerate the gravity map based on the gravity sources in the sim.

simulation.resetPressure

sim.resetPressure()

Resets the pressure map to no pressure.

simulation.resetSpark

sim.resetSpark()

Same effect as the ctrl+= shortcut. Removes all sparks from the simulation and resets them to .life = 0. SPRK with invalid ctypes are deleted. Also resets all wifi cooldowns.

simulation.resetTemp

sim.resetTemp()

Resets the temperature of all particles to their spawn temperature.

simulation.resetVelocity

sim.resetVelocity()

Resets the air velocity map to 0. This map controls the flow of air. Resetting this will have some effect on particles, but won't stop them in their tracks.

simulation.replaceModeFlags

number sim.replaceModeFlags()

Returns the current replace mode flags.

nil sim.replaceModeFlags(number flags)

Sets the replace mode flags.

If the first bit of that number is set (flags = 1), replace mode is enabled.

If the second bit is set (flags = 2), specific delete is enabled.

simulation.saveStamp

string sim.saveStamp([number x, number y, number width, number height, [boolean includePressure]])

Creates a stamp of the specified coordinates. Coordinates default to entire simulation. Returns the stamp id created.

simulation.signs

table simulation.signs

A table of signs. simulation.signs[1] through simulation.signs[16] are always defined.

Constants

  • sim.signs.MAX_SIGNS: The maximum number of signs that can exist at once
  • sim.signs.JUSTMODE_LEFT: Left justification
  • sim.signs.JUSTMODE_MIDDLE: Middle (default) justification
  • sim.signs.JUSTMODE_RIGHT: Right justification
  • sim.signs.JUSTMODE_NONE: No justification, sign won't have any "tail"
  • sim.signs.NUM_JUSTMODES: The number of justification modes

simulation.signs[n]

table simulation.signs[n]

A table which always contains the id property. May also contain text, x, y and justification. These properties can be directly modified to change a sign. A justification of 0 means left, 1 means right, 2 means middle and 3 means none. The text property cannot be larger than 45 in length.

simulation.signs.delete

nil simulation.signs.delete(number signID)

Deletes the sign at the specified sign id.

simulation.signs.new

number simulation.signs.new([string text, number x, number y, number justification])

Creates a new sign with the specified properties. Returns the sign ID, or nil if there are too many signs (the limit is 16).

simulation.takeSnapshot

nil sim.takeSnapshot()

Takes a undo snapshot, for use with ctrl + z

simulation.temperatureScale

number sim.temperatureScale()

Returns the current temperature scale. 0 = Kelvin, 1 = Celsuis, 2 = Fahrenheit

nil sim.temperatureScale(number newTemperatureScale)

Sets the current temperature scale. 0 = Kelvin, 1 = Celsuis, 2 = Fahrenheit. Other options are invalid and will throw an error.

simulation.toolBox

type sim.toolBox(number x1, number y1, number x2, number y2, [number tool], [number strength])

Performs the given tool (HEAT, COOL, AIR, etc) in a rectangular area.

simulation.toolBrush

number sim.toolBrush(number x, number y, [number rx], [number ry], [number tool], [number brush], [number strength])

Performs the given tool (HEAT, COOL, AIR, etc) on the given coordinates with the given brush size. The brush types are 0 (circle), 1 (square) and 2 (triangle).

simulation.toolLine

type sim.toolLine(number x1, number y1, number x2, number y2, [number rx], [number ry], [number tool], [number brush], [number strength])

Performs the given tool (HEAT, COOL, AIR, etc) as if a line was drawn across the given coordinates with the given brush size. The brush types are 0 (circle), 1 (square) and 2 (triangle).

simulation.updateUpTo

nil sim.updateUpTo([number upTo])

Updates the simulation, but only up to the specified particle ID. Works as if shift+f is pressed while in particle debug mode (tpt.setdebug(0x8)). If no arguments are passed in, updates to the end of the frame.

simulation.velocityX

number sim.velocityX(number x, number y)

Returns an X value on the velocity map.

nil sim.velocityX(number x, number y, [number width, number height], number value)

Sets X values on the velocity map.

simulation.velocityY

number sim.velocityY(number x, number y)

Returns an Y value on the velocity map.

nil sim.velocityY(number x, number y, [number width, number height], number value)

Sets Y values on the velocity map.

simulation.wallMap

Interface with the wall map, which is a CELL-sized map that specifies which walls are at what position.

wallType sim.wallMap(x, y)
sim.wallMap(x, y, wallType)
sim.wallMap(x, y, w, h, wallType)
  • wallType: Wall type to set, wall type will be one of the constants in sim.walls
  • x: x position of the cell
  • y: y position of the cell
  • w: width (cell count) of the area to set
  • h: height (cell count) of the area to set

simulation.waterEqualisation

number sim.waterEqualisation()

Returns the current Water equalisation setting.

nil sim.waterEqualisation(number setting)

Set the Water equalisation setting to setting.

simulation.waterEqualization

Same as sim.waterEqualisation()

Constants

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

XRES

X Resolution of the sim

YRES

Y Resolution of the sim

CELL

Size of a wall / air simulation block

XCELLS

The number of cells in the X direction

YCELLS

The number of cells in the Y direction

NCELL

The total number of cells in the simulation

NT

No transition, used in *Transition properties

ST

Special transition, used in *Transition properties, but there is no way to set a special transition handler from Lua

ITH

Impossible temperature high, used along with NT to disable transitions

ITL

Impossible temperature low, used along with NT to disable transitions

IPH

Impossible pressure high, used along with NT to disable transitions

IPL

Impossible pressure low, used along with NT to disable transitions

PT_NUM

Maximum number of element IDs. Does not reflect the current number of elements, only the maximum that can be enabled at one time.

NUM_PARTS

Not actually a constant, this is updated every frame to reflect the current number of particles in the sim. Deprecated by sim.partCount (TODO document that and remove this)

MAX_PARTS

Maximum number of particles that can exist at once

R_TEMP

Room temperature (22C), the default temperature for many elements

MAX_TEMP

Maximum allowable temperature of the sim, in Kelvin

MIN_TEMP

Minimum allowable temperature of the sim, in Kelvin

MAX_PRESSURE

Maximum allowable pressure of the sim

MIN_PRESSURE

Minimum allowable pressure of the sim

MAX_VELOCITY

Particle velocity cap

ISTP

Movement code step value. Particles scan their trajectory and only check for blockers each step.

CFDS

Air sim related

PMAPBITS

Number of bits used in pmap to store element type. This controls the element cap, which is 2^PMAPBITS

PMAPMASK

Mask used to assign type to pmap. ((1<<PMAPBITS)-1)

DECO

Used in deco drawing functions

DECO_DRAW
DECO_CLEAR
DECO_ADD
DECO_SUBTRACT
DECO_MULTIPLY
DECO_DIVIDE
DECO_SMUDGE

TOOL

Used in tool drawing functions

TOOL_HEAT
TOOL_COOL
TOOL_VAC
TOOL_AIR
TOOL_PGRV
TOOL_NGRV
TOOL_MIX
TOOL_CYCL
TOOL_WIND

FIELD

Used in sim.partProperty

FIELD_TYPE
FIELD_LIFE
FIELD_CTYPE
FIELD_X
FIELD_Y
FIELD_VX
FIELD_VY
FIELD_TEMP
FIELD_FLAGS
FIELD_TMP
FIELD_TMP2
FIELD_TMP3
FIELD_TMP4
FIELD_DCOLOUR

BRUSH

Used in certain brush drawing functions

BRUSH_CIRCLE
BRUSH_SQUARE
BRUSH_TRIANGLE
NUM_DEFAULTBRUSHES

Number of default brushes

BRUSH_NUM

Number of total brushes, including any custom brushes

EDGE

Used in sim.edgeMode

EDGE_VOID
EDGE_SOLID
EDGE_LOOP
NUM_EDGEMODES

AIR

Used in sim.airMode

AIR_ON
AIR_PRESSUREOFF
AIR_VELOCITYOFF
AIR_OFF
AIR_NOUPDATE
NUM_AIRMODES

GRAV

Used in sim.gravityMode

GRAV_VERTICAL
GRAV_OFF
GRAV_RADIAL
GRAV_CUSTOM
NUM_GRAVMODES

Walls

NUM_WALLS
walls

sim.walls is a table containing a mapping of wall IDs to wall identifiers, and wall identifiers to wall IDs. This may come in handy for working with ui.activeTool, which uses identifiers.

FLAG

Used in .flags property

FLAG_MOVABLE
FLAG_PHOTDECO
FLAG_SKIPMOVE
FLAG_STAGNANT