3.6 KiB
Iterating over larger areas of blocks
These functions help scan larger areas of blocks without using generic loop functions, like nested loop.
scan(center, range, upper_range?, expr)
Evaluates expression over area of blocks defined by its center center = (cx, cy, cz), expanded in all directions
by range = (dx, dy, dz) blocks, or optionally in negative with range coords, and upper_range coords in
positive values. That means that if you want a box starting at the northwest coord with given base, width and height
dimensions, you can do 'scan(center, 0, 0, 0, w, h, d, ...).
center can be defined either as three coordinates, a single tuple of three coords, or a block value.
range and upper_range can have the same representations, just if they are block values, it computes the distance to
the center as range instead of taking the values as is. That way you can iterate from the center to a box whose surface
area constains the range and/or upper_range blocks.
expr receives _x, _y, _z variables as coords of current analyzed block and _, which represents the block itself.
Returns number of successful evaluations of expr (with true boolean result) unless called in void context,
which would cause the expression not be evaluated for their boolean value.
scan also handles continue and break statements, using continue's return value to use in place of expression
return value. break return value has no effect.
volume(from_pos, to_pos, expr)
Evaluates expression for each block in the area, the same as the scan function, but using two opposite corners of
the rectangular cuboid. Any corners can be specified, its like you would do with /fill command.
You can use a position or three coordinates to specify, it doesn't matter.
For return value and handling break and continue statements, see scan function above.
neighbours(pos)
Returns the list of 6 neighbouring blocks to the argument. Commonly used with other loop functions like for.
for(neighbours(x,y,z),air(_)) => 4 // number of air blocks around a block
rect(center, range?, upper_range?)
Returns an iterator, just like range function that iterates over a rectangular area of blocks. If only center
point is specified, it iterates over 27 blocks (range of 1). If range arguments are specified, expands selection by
the respective number of blocks in each direction. If upper_range arguments are specified, it uses range for
negative offset, and upper_range for positive, similar to scan.
Basically the arguments are the same as the first three arguments of scan, except this function returns the list of
blocks that scan would evaluate over. If you are going to iterate over these blocks, like for(rect(args), do_something()),
then scan(args, do_something()) is an equivalent, yet more compute-friendly alternative, especially for very large areas.
center can be defined either as three coordinates, a list of three coords, or a block value.
range and upper_range can have the same representations, just if they are block values, it computes the distance to the center
as range instead of taking the values as is.`
diamond(center_pos, radius?, height?)
Iterates over a diamond like area of blocks. With no radius and height, its 7 blocks centered around the middle (block + neighbours). With a radius specified, it expands shape on x and z coords, and with a custom height, on y. Any of these can be zero as well. radius of 0 makes a stick, height of 0 makes a diamond shape pad.
If radius and height are the same, creats a 3D diamond, of all the blocks which are a manhattan distance of radius away
from the center.