**====== SandDef ======**

===== Description =====

`SandDef` is a byte value (ranging from 1 to 255) that defines the type of sand to be created. Each value corresponds to a specific type of sand with unique properties (e.g., color, density, behavior). A value of 255 indicates "empty" or no sand, but it is not considered null.

===== Usage =====

`SandDef` is used as an input parameter in various sand creation commands, such as:

*   [[IRPL:commands:CreateSand]]
*   [[IRPL:commands:CreateSandInRoundArea]]
*   [[IRPL:commands:CreateSandInAreaRand]]
*   [[IRPL:commands:CreateSandInArea]]

===== Examples =====

<code IRPL>
1 ->sandDef  // Creates sand of type 1
5 ->sandDef  // Creates sand of type 5
255 ->sandDef // Creates "empty" sand (no sand)
</code>



**====== CreateSand ======**
CreateSand(<-x <-y <-sandDef)

===== Description =====
Creates sand at the specified coordinates (x, y) using the provided [[IRPL:commands:SandDef|sand definition (`sandDef`)]].

===== Examples =====
<code IRPL>
10 20 1 ->sandDef ->y ->x 
CreateSand(<-x <-y <-sandDef)
</code>

=== See Also ===
[[IRPL:commands:CreateSandInRoundArea]]

[[IRPL:commands:CreateSandInAreaRand]]

[[IRPL:commands:CreateSandInArea]]


**====== CreateSandInRoundArea ======**
CreateSandInRoundArea(<-rect <-probability <-sandDef)

===== Description =====
Creates sand within a rectangular area defined by a vector (`rect`) containing the bottom-left (x,y) and top-right (x,y) corner coordinates. The `probability` value (between 0 and 1) determines the chance of sand being created at each cell within the area. Sand is created using the specified [[IRPL:commands:SandDef|sand definition (`sandDef`)]].

===== Examples =====
<code IRPL>
{0 0 10 10} ->rect 
0.5 ->probability 
1 ->sandDef
CreateSandInRoundArea(<-rect <-probability <-sandDef)
</code>

=== See Also ===
[[IRPL:commands:CreateSand]]

[[IRPL:commands:CreateSandInAreaRand]]

[[IRPL:commands:CreateSandInArea]]


**====== CreateSandInAreaRand ======**
CreateSandInAreaRand(<-rect <-probability <-sandDef)

===== Description =====
Creates sand within a rectangular area defined by a vector (`rect`) containing the bottom-left (x,y) and top-right (x,y) corner coordinates. The `probability` value (between 0 and 1) determines the chance of sand being created at each cell within the area. The distribution of sand is randomized. Sand is created using the specified [[IRPL:commands:SandDef|sand definition (`sandDef`)]].

===== Examples =====
<code IRPL>
{0 0 10 10} ->rect
0.5 ->probability
1 ->sandDef
CreateSandInAreaRand(<-rect <-probability <-sandDef)
</code>

=== See Also ===
[[IRPL:commands:CreateSand]]

[[IRPL:commands:CreateSandInRoundArea]]

[[IRPL:commands:CreateSandInArea]]


**====== CreateSandInArea ======**
CreateSandInArea(<-rect <-sandDef)

===== Description =====
Creates sand within a rectangular area defined by a vector (`rect`) containing the bottom-left (x,y) and top-right (x,y) corner coordinates. Sand is created at every cell within the area using the specified [[IRPL:commands:SandDef|sand definition (`sandDef`)]].

===== Examples =====
<code IRPL>
{0 0 10 10} ->rect
1 ->sandDef
CreateSandInArea(<-rect <-sandDef)
</code>

=== See Also ===
[[IRPL:commands:CreateSand]]

[[IRPL:commands:CreateSandInRoundArea]]

[[IRPL:commands:CreateSandInAreaRand]]

**====== SetSandColor ======**
SetSandColor(<-x <-y <-colors)

===== Description =====
Sets the color and glow of the sand at the specified coordinates (x, y) using a vector (`colors`) containing two colors. The first color in the vector sets the base color of the sand, and the second color sets the glow color.

===== Examples =====
<code IRPL>
10 20 ->y ->x
{ {1 0 0 1} {0 1 0 1} } ->colors // Set sand color to red and glow to green
SetSandColor(<-x <-y <-colors)
</code>

=== See Also ===
[[IRPL:commands:GetSandDef]]

[[IRPL:commands:GetMapSandCount]]

[[IRPL:commands:CountSandInArea]]


**====== GetSandDef ======**
GetSandDef(<-sandName) ->sandDef

===== Description =====
Retrieves the [[IRPL:commands:SandDef|sand definition (`sandDef`)]] associated with the given `sandName`.

===== Examples =====
<code IRPL>
"SandType1" ->sandName
GetSandDef(<-sandName) ->sandDef
</code>

=== See Also ===
[[IRPL:commands:SetSandColor]]

[[IRPL:commands:GetMapSandCount]]

[[IRPL:commands:CountSandInArea]]


**====== GetMapSandCount ======**
GetMapSandCount(<-sandDef) ->count

===== Description =====
Returns the total number of sand particles of the specified [[IRPL:commands:SandDef|type (`sandDef`)]] present on the map. The input `sandDef` value is clamped between 0 and 255.

===== Examples =====
<code IRPL>
1 ->sandDef // Get the count of sand particles with SandDef 1
GetMapSandCount(<-sandDef) ->count
</code>

=== See Also ===
[[IRPL:commands:SetSandColor]]

[[IRPL:commands:GetSandDef]]

[[IRPL:commands:CountSandInArea]]


**====== CountSandInArea ======**
CountSandInArea(<-rect <-sandDef) ->count

===== Description =====
Counts the number of sand particles of the specified [[IRPL:commands:SandDef|type (`sandDef`)]] within a rectangular area defined by a vector (`rect`) containing the bottom-left (x,y) and top-right (x,y) corner coordinates.

===== Examples =====
<code IRPL>
{0 0 10 10} ->rect
1 ->sandDef // Count sand particles with SandDef 1 within the area
CountSandInArea(<-rect <-sandDef) ->count
</code>

=== See Also ===
[[IRPL:commands:SetSandColor]]

[[IRPL:commands:GetSandDef]]

[[IRPL:commands:GetMapSandCount]]


**====== GetSandInArea ======**
GetSandInArea(<-rect <-isRound <-sandDefs <-inclusive) ->sandList

===== Description =====
Retrieves a list (`sandList`) of sand particles within a specified area. The area is defined by a vector (`rect`) containing the bottom-left (x,y) and top-right (x,y) corner coordinates. `isRound` (boolean) determines if the area is treated as a rounded rectangle. `sandDefs` is a list of [[IRPL:commands:SandDef|sand definitions]] to include in the search. `inclusive` (boolean) determines if only the specified `sandDefs` should be included or if all other types should be included.

===== Examples =====
<code IRPL>
{0 0 10 10} ->rect
false ->isRound
{1 2 3} ->sandDefs // List of SandDefs
true ->inclusive // Include only sand particles with SandDef 1, 2, or 3
GetSandInArea(<-rect <-isRound <-sandDefs <-inclusive) ->sandList
</code>


**====== DestroySandInArea ======**
DestroySandInArea(<-rect <-isRound <-sandDefs <-inclusive)

===== Description =====
Destroys sand particles within a specified area. The area is defined by a vector (`rect`) containing the bottom-left (x,y) and top-right (x,y) corner coordinates. `isRound` (boolean) determines if the area is treated as a rounded rectangle. `sandDefs` is a list of [[IRPL:commands:SandDef|sand definitions]] to target for destruction. `inclusive` (boolean) determines if only the specified `sandDefs` should be destroyed or if all other types should be destroyed.

===== Examples =====
<code IRPL>
{0 0 10 10} ->rect
false ->isRound
{1 2 3} ->sandDefs // List of SandDefs
true ->inclusive // Destroy only sand particles with SandDef 1, 2, or 3
DestroySandInArea(<-rect <-isRound <-sandDefs <-inclusive)
</code>


**====== DestroySandFromList ======**
DestroySandFromList(<-sandList)

===== Description =====
Destroys sand particles from a given list (`sandList`). This list could be obtained from commands like `GetSandInArea`.

===== Examples =====
<code IRPL>
// Assuming 'sandList' was obtained from a previous command
DestroySandFromList(<-sandList) 
</code>


**====== GetSandDefData ======**
GetSandDefData(<-sandDef) ->sandDefData

===== Description =====
Retrieves data associated with a specific [[IRPL:commands:SandDef|sand definition (`sandDef`)]]. The returned `sandDefData` may contain various properties of the sand type, such as color, density, and behavior.

===== Examples =====
<code IRPL>
1 ->sandDef // Get data for sand with SandDef 1
GetSandDefData(<-sandDef) ->sandDefData
</code>