Difference between revisions of "Lua API:Simulation"
m (Remove some "upcoming in 98.0" notices) |
(Document can_move constants (99.0)) |
||
(3 intermediate revisions by 3 users not shown) | |||
Line 71: | Line 71: | ||
=== simulation.can_move === | === simulation.can_move === | ||
− | + | Controls action to take when particles collide | |
− | |||
− | |||
− | |||
− | |||
− | + | <pre>action = simulation.can_move(movingElement, obstacleElement) -- query action | |
− | + | simulation.can_move(movingElement, obstacleElement, action) --set action</pre> | |
+ | * <code>movingElement</code>: Element ID of the particle trying to move | ||
+ | * <code>obstacleElement</code>: Element ID of the particle it ran into | ||
+ | * <code>action</code>: Action to take during collision. Can be one of these constants: | ||
+ | ** <code>CANMOVE_BOUNCE</code>: Do not move into. Acts as a wall. | ||
+ | ** <code>CANMOVE_SWAP</code>: Swap positions. | ||
+ | ** <code>CANMOVE_ENTER</code>: Share same space. | ||
+ | ** <code>CANMOVE_BUILTIN</code>: Custom in-game logic will handle this collision. | ||
+ | ** <code>NUM_CANMOVEMODES</code>: The total number of valid collision actions. | ||
+ | |||
+ | The default action is always 1 or 0. Heavier elements move into lighter elements. This function can be used to customize that. Setting it to ENTER is useful for energy particles, but it will cause stacking and BHOL for other elements. Setting it to BUILTIN is not useful for Lua elements, because they can't write custom collision functions. | ||
=== simulation.clearRect === | === simulation.clearRect === | ||
Line 401: | Line 407: | ||
* -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. | * -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. | + | * -2 : Create particle as though it was drawn by the user with the brush(runs the Create function). 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). | * -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, ...). | ||
Line 431: | Line 437: | ||
=== simulation.partNeighbors === | === simulation.partNeighbors === | ||
− | table sim. | + | table sim.partNeighbors(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. | 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. | ||
Line 574: | Line 580: | ||
=== simulation.toolBrush === | === simulation.toolBrush === | ||
− | + | 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). | 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). | ||
Latest revision as of 01:04, 7 December 2024
The Simulation API allows for modifying the state and properties of particles, air and gravity
Contents
- 1 Methods
- 1.1 simulation.addCustomGol
- 1.2 simulation.adjustCoords
- 1.3 simulation.airMode
- 1.4 simulation.ambientAirTemp
- 1.5 simulation.ambientHeat
- 1.6 simulation.ambientHeatSim
- 1.7 simulation.brush
- 1.8 simulation.can_move
- 1.9 simulation.clearRect
- 1.10 simulation.clearSim
- 1.11 simulation.createBox
- 1.12 simulation.createLine
- 1.13 simulation.createParts
- 1.14 simulation.createWallBox
- 1.15 simulation.createWallLine
- 1.16 simulation.createWalls
- 1.17 simulation.customGravity
- 1.18 simulation.decoBox
- 1.19 simulation.decoBrush
- 1.20 simulation.decoColor
- 1.21 simulation.decoColour
- 1.22 simulation.decoLine
- 1.23 simulation.decoSpace
- 1.24 simulation.deleteStamp
- 1.25 simulation.edgeMode
- 1.26 simulation.elecMap
- 1.27 simulation.elementCount
- 1.28 simulation.ensureDeterminism
- 1.29 simulation.fanVelocityX
- 1.30 simulation.fanVelocityY
- 1.31 simulation.floodDeco
- 1.32 simulation.floodParts
- 1.33 simulation.floodWalls
- 1.34 simulation.framerender
- 1.35 simulation.getSaveID
- 1.36 simulation.gravityField
- 1.37 simulation.gravityMass
- 1.38 simulation.gravMap
- 1.39 simulation.gravityGrid
- 1.40 simulation.gravityMode
- 1.41 simulation.gspeed
- 1.42 simulation.hash
- 1.43 simulation.heatSim
- 1.44 simulation.historyForward
- 1.45 simulation.historyRestore
- 1.46 simulation.lastUpdatedID
- 1.47 simulation.listCustomGol
- 1.48 simulation.listStamps
- 1.49 simulation.loadSave
- 1.50 simulation.loadStamp
- 1.51 simulation.neighbors
- 1.52 simulation.neighbours
- 1.53 simulation.newtonianGravity
- 1.54 simulation.partChangeType
- 1.55 simulation.partCount
- 1.56 simulation.partCreate
- 1.57 simulation.partExists
- 1.58 simulation.partID
- 1.59 simulation.partKill
- 1.60 simulation.partNeighbors
- 1.61 simulation.partNeighbours
- 1.62 simulation.partPosition
- 1.63 simulation.partProperty
- 1.64 simulation.parts
- 1.65 simulation.paused
- 1.66 simulation.pmap
- 1.67 simulation.photons
- 1.68 simulation.pressure
- 1.69 simulation.prettyPowders
- 1.70 simulation.randomSeed
- 1.71 simulation.reloadSave
- 1.72 simulation.removeCustomGol
- 1.73 simulation.resetGravityField
- 1.74 simulation.resetPressure
- 1.75 simulation.resetSpark
- 1.76 simulation.resetTemp
- 1.77 simulation.resetVelocity
- 1.78 simulation.replaceModeFlags
- 1.79 simulation.saveStamp
- 1.80 simulation.signs
- 1.81 simulation.takeSnapshot
- 1.82 simulation.temperatureScale
- 1.83 simulation.toolBox
- 1.84 simulation.toolBrush
- 1.85 simulation.toolLine
- 1.86 simulation.updateUpTo
- 1.87 simulation.velocityX
- 1.88 simulation.velocityY
- 1.89 simulation.wallMap
- 1.90 simulation.waterEqualisation
- 1.91 simulation.waterEqualization
- 2 Constants
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
Controls action to take when particles collide
action = simulation.can_move(movingElement, obstacleElement) -- query action simulation.can_move(movingElement, obstacleElement, action) --set action
-
movingElement
: Element ID of the particle trying to move -
obstacleElement
: Element ID of the particle it ran into -
action
: Action to take during collision. Can be one of these constants:-
CANMOVE_BOUNCE
: Do not move into. Acts as a wall. -
CANMOVE_SWAP
: Swap positions. -
CANMOVE_ENTER
: Share same space. -
CANMOVE_BUILTIN
: Custom in-game logic will handle this collision. -
NUM_CANMOVEMODES
: The total number of valid collision actions.
-
The default action is always 1 or 0. Heavier elements move into lighter elements. This function can be used to customize that. Setting it to ENTER is useful for energy particles, but it will cause stacking and BHOL for other elements. Setting it to BUILTIN is not useful for Lua elements, because they can't write custom collision functions.
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)
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()
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, [boolean hflip, [number rotation, [boolean includePressure]]]) sim.loadStamp(number id, number x, number y, [boolean hflip, [number rotation, [boolean includePressure]]])
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.
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(runs the Create function). 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.partNeighbors(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)
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
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