PowderSimulation
Inherits: Node2D < CanvasItem < Node < Object
This node is what you will use to handle individual simulations. It could be called an "orchestrator" class for the simulation, as it does not define the base chunk or cell classes, but simply contains them and tells them what to do. It also contains useful methods for maniplulating the world, such as placing elements or clearing all cells.
NOTE: This node defines _Ready() and _Draw(), so if you are attaching a script to this node and using those functions, make sure to include super() in it so it still calls the parent class functions as well as whatever you put.
Public Methods
| Return Type | Method |
|---|---|
| void | FillWorld() |
| void | ClearWorld() |
| bool | PlaceElement() |
| void | PlaceGroupElements() |
| Vector2I | WorldToLocal() |
| Vector2 | LocalToWorld() |
| void | SetWorldStreamer() |
| WorldStreamer | GetWorldStreamer() |
| SandInfo.Chunk | GetChunk() |
| bool | SimContainsCell() |
| bool | SimContainsChunk() |
| void | SetFollowMode() |
| void | SetFollowNode() |
| void | SetConstraints() |
| Vector2 | ChunkLocalToWorld() |
| Vector2I | LocalToChunk() |
| Vector2I | WorldToChunk() |
| void | QueueSwap() |
| void | CommitSwapQueue() |
| bool | AddChunk() |
| bool | RemoveChunk() |
| void | InitGrid() |
| void | UpdateChunks(int tick) |
| void | DecideSleepingChunks() |
| void | RenderChunkUpdates() |
| void | UpdateSimulationSize() |
| void | UpdateSimulation() |
| SandInfo.Cell | GetCell() |
| void | SetCell(Vector2I pos, AllElements element) |
Properties
| Type | Property |
|---|---|
| Exported Properties | |
| float | SimulationSpeed |
| bool | UseDirtyRects |
| int | IndividualChunkSize |
| Vector2I | ChunkGridSize |
| int | ChunkInsomnia |
| bool | Centered |
| int | PixelScale |
| bool | FollowEnabled |
| Node2D | FollowNode |
| Rect2 | FollowAreaConstraint |
| bool | FollowCenterConstraintsOnFollowedNode |
| bool | DebugMode |
| Color | DebugChunkBorderColor |
| bool | ShowSimBorder |
| int | SimBorderWidth |
| Non-Exported Properties | |
| Dictionary |
Chunks |
| Vector2I | SimulationSize |
| Vector2I | SimulationMaxExtents |
| Vector2I | SimulationMinExtents |
| float | UpdateTime |
| float | DrawTime |
| List |
ActiveChunkRenderers |
| Node2D | ChunkRendererParent |
| Dictionary |
NeighborIndexOffsets |
Method Descriptions
void FillWorld(AllElements with)
Replaces every cell in the current world with the element specified in with.
void ClearWorld()
Replaces every cell in the current world with AllElements.AIR. Functionally equivalent to calling FillWorld(AllElements.AIR).
Vector2I WorldToLocal(Vector2 from_world)
Vector2 from_world- the world-space coordinates to find the closest element from. world-space is the same as global_position for Nodes.
Returns the given cell world position (Godot's regular global_position for nodes) translated into local simulation position.
Vector2 LocalToWorld(Vector2I fromLocal, bool includeParentOffset = true)
Vector2I fromLocal- the local-space coordinates to translate to world-space.bool includeParentOffset- Whether or not to include the offset of thePowderSimulationparent Node in the calculation.
Returns the given chunk local simulation position translated into world position.
bool PlaceElement(Vector2I pos, AllElements element, bool overRide = false)
Vector2I pos- the local-space coordinates to the cell where the specified element will be placed.AllElements element- the element to replace the specified cell's element with.bool overRide- iffalse, only places the specified element if the cell's element isAIR.
Replaces the element of the cell at pos with element. If overRide is set to true, overrides the element of the cell at pos regardless of what it already is.
If overRide is true, only changes the element if the element of the cell is already AIR.
Returns
trueif the placement succeeded, otherwise returnsfalse.
Ex.
PlaceElement(Vector2I(0, 0), AllElements.SAND, true)will replace the cell at pos(0, 0)'s element withelement, regardless of the element it was beforehand becauseoverRidewas set totrue.
void PlaceGroupElements(int brushSize, Vector2I pos, AllElements element, bool overRide = false)
int brushSize- the amount the square placement pattern expands in all four directions.
Calls PlaceElement repeatedly in a square pattern which starts at pos and expands outward brushSize times.
Ex.
brushSize= 0 will place a single element, andbrushsize= 1 will place a group of nine elements, starting fromposand extending 1 cell in all four directions.
void SetWorldStreamer(WorldStreamer NewStreamer)
WorldStreamer NewStreamer- The WorldStreamer instance to assign.
Assigns a WorldStreamer object to the simulation. When assigned, using FollowMode will save/load chunks using the WorldStreamer object. Set to null to disable this behavior.
WorldStreamer GetWorldStreamer()
Returns the current WorldStreamer instance attached to this node.
SandInfo.Chunk GetChunk(Vector2I pos)
Vector2I pos- The position to search for a chunk.
Returns the chunk currently at pos. Throws an error if there is no chunk at pos.
bool SimContainsCell(Vector2I pos)
Vector2I pos- The position to search for a cell.
Returns Whether the given pos corresponds to a cell in the simulation.
bool SimContainsChunk(Vector2I pos)
Vector2I pos- The position to search for a chunk.
Returns Whether the given pos corresponds to a chunk in the simulation.
void SetFollowMode(bool to)
bool to- The boolean to setFollowEnabledto.
Sets FollowEnabled to to.
void SetFollowNode(Node2D what)
Node2D what- The node to setFollowNodeto.
Sets the node for the simulation to follow. If FollowEnabled is set to true, the simulation uses the Node2D's position to determine where the constraints are centered.
void SetConstraints(Vector2 to)
Vector2 to- What to set the constraints to.
Sets the constraints for the simulation. If FollowEnabled is set to true, the simulation auto loads/unloads chunks to fill the range ± to.
Vector2 ChunkLocalToWorld(Vector2I fromLocal, bool includeParentOffset = true)
Vector2I fromLocal- The local chunk position in which to transform.bool includeParentOffset- Whether or not to include the offset of the the parent node in the calculation. For example, if the position of the chunk is (32, 32) and the local position of this node is (10, 10) the final position will be (42, 42).
Returns the given chunk local simulation position translated into world position.
Vector2I LocalToChunk(Vector2I localPos)
Vector2I localPos- The local simulation position (position of a cell) to convert to chunk position.
Returns the local simulation position to chunk coordinates. Truncates decimals toward zero. Used for finding a cell's chunk from just the position.
Vector2I WorldToChunk(Vector2 worldPos)
Vector2I worldPos- The world position (same as global_position for Node2Ds) converted to local chunk position.
Returns the given global (world) position converted to local chunk position.
void QueueSwap(SandInfo.Cell Cell1, SandInfo.Cell Cell2)
SandInfo.Cell Cell1- The first cell to swap.SandInfo.Cell Cell2- The second cell to swap.
Adds two cells to list of cells to be swapped at the end of the frame.
void CommitSwapQueue()
Writes all the buffered swaps onto the simulation.
bool AddChunk(Vector2I at)
Vector2I at- The chunk position at which the new chunk will be created.
Adds an empty chunk at the specified coordinates.
Returns whether or not the chunk was successfully added.
bool RemoveChunk(Vector2I at)
Vector2I at- The chunk position at which the chunk will be removed.
Removes the chunk at the specified coordinates.
Returns whether there was a chunk at the specified position or not.
void InitGrid()
Populates the grid with Chunk and Cell objects set to the correct default state. One of the functions called in this node's _Ready() function.
void UpdateChunks(int tick)
int tick- The elapsed frame, mod by two (constrained to 0 and 1). Changes update direction based on the current tick, making the simulation less one-sided.
Updates the cells in all the chunks of the simulation, sending them to the swap buffer. Automatically called in UpdateSimulation().
void DecideSleepingChunks()
Updates the sleep state of each chunk in the simulation decided by their insomnia count.
There are currently no functions that require this to be called as UpdateChunks() does it itself.
void RenderChunkUpdates()
Loops through each chunk and sends its cell data to its respective ChunkRenderer.
void UpdateSimulationSize()
Updates the simulation_size variable if chunk grid size has been changed. This is automatically done, so no need to call this.
void UpdateSimulation(bool wait = true)
bool wait- Whether or not to check if the correct amount of time has passed specified inSimulationSpeed, and if not, does not call the function.
Updates the simulation while being safe to put in _Process/_PhysicsProcess because if wait is set to true, it will not tick until the right amount of time has passed specified in SimulationSpeed.
If wait is set to false, runs one tick of the simulation regardless.
SandInfo.Cell GetCell(Vector2I pos)
Vector2I pos- The position to get the cell from.
Returns the cell at the specified pos. Throws an error if a cell does not exist at pos.
void SetCell(Vector2I pos, AllElements element)
Vector2I pos- The position to get the cell for editing.AllElements element- The element to change the cell to.
Replaces the element at pos with element.
Property Descriptions
float SimulationSpeed
How fast the simulation runs, with 1.0 corresponding with 60 updates/second.
bool UseDirtyRects
Dirty rects are rectangles calculated at runtime that only contain the cells that were updated in the last frame, lowering the total number of cells needing updates.
Recommended for chunk sizes 32 and above.
int IndividualChunkSize
How many cells squared each cell contains. It is squared because the chunk size is only measured on one axis.
Vector2I ChunkGridSize
How many chunks to be used in the simulation.
int ChunkInsomnia
How many update loops with no change in a specific chunk have to occur before sleeping the chunk.
bool Centered
Whether the simulation appears at the center of this Node's position or offset like Control Nodes are.
int PixelScale
How big the pixels appear on the screen.
bool FollowEnabled
Whether or not to use the Node Follow feature.
Node Follow constrains the simulation to a certain size by unloading/loading chunks dynamically as the FollowNode's position changes. It also works with the filesystem if a WorldStreamer is set with SetWorldStreamer().
Node2D FollowNode
The Node to follow when FollowEnabled is true.
Rect2 FollowAreaConstraint
The size to constrain the simulation in when FollowEnabled is true. DO NOT set the Position property of the Rect2, it will get overridden.
bool FollowCenterConstraintsOnFollowedNode
Whether or not to center the constraints on FollowNode by setting FollowAreaConstraint.Position to -(FollowAreaConstraint.Size / 2.0). Only effective when FollowEnabled is true.
bool DebugMode
Draws a visual of chunk borders and dirty rects.
Color DebugChunkBorderColor
What color to display the chunk borders as when DebugMode is true.
bool ShowSimBorder
Draws a rectangular border around the entire simulation.
int SimBorderWidth
How wide the line at the simulation border will be.
Dictionary<Vector2I, SandInfo.Chunk> Chunks
The current chunks in the simulation mapped to their positions.
Vector2I SimulationSize
The size of all the cells in the simulation, basically the max extents of the simulation if the top-left corner was (0, 0)
Vector2I SimulationMaxExtents
The bottom-rightmost cell position in the simulation.
Vector2I SimulationMinExtents
The top-leftmost cell position in the simulation.
float UpdateTime
The amount of time it took this frame to update the simulation. Used for debug purposes.
float DrawTime
The amount of time it took this frame to draw the simulation. Used for debug purposes.
List<ChunkRendererCS> ActiveChunkRenderers
The active ChunkRendererCSs in the simulation. There is one ChunkRenderer per chunk.
Node2D ChunkRendererParent
The parent node of all the ChunkRenderer nodes.
Dictionary<Vector2I, int> NeighborIndexOffsets
A C# Dictionary that maps the Vector2I constants from SandInfo to the amount to add to a cell index to get that specific neighbor.