Regions

What are they?

Regions are very useful. They're essentially 3D shapes that most operations use to define where they work. They allow for much more flexibility than Skript's simple blocks expression, with complex shapes for maximum customization.

They can be created by using their respective expression. So far, the implemented regions are cuboid, cylinder, ellipsoid, and convex polyhedral. These seem to be the most useful ones, and both WorldEdit and FAWE support them.

Cuboid

Cuboid regions are pretty self-explanatory, and just takes two locations to create. You can think of this one as a rectangular prism in the world. Here's a few examples of how to get one:

set {cuboid} to a new cuboid region from {location1} to {location2}
set {cuboid} to region from {location1} to {location2}

These regions also have a couple of additional syntax that the other region types don't; there are expressions to get the walls and faces of a cuboid region, which actually return another region.

Walls

The walls of a cuboid region are exactly what you would assume they are. You can get them (as another region) using the expression [region] walls of %worldeditregion%, where the region is any cuboid region. Here's an example of how to get them:

set {walls} to the region walls of {cuboid}

Faces

The faces of a cuboid region are just the walls, but including the ceiling and floor. Similar to the walls, you can get them (as another region) using the expression [region] faces of %worldeditregion%, where the region is, you guessed it, any cuboid region. Here's an example of how to get them:

set {faces} to the region faces of {cuboid}

Cylinder

Cylindrical regions are also pretty easy to understand, but they require a little bit more information. With these, you need to provide a location (where the centre of the region should be), a radius (or radii [x,y]), and a height. Here's another few examples of how to get these:

set {cyl} to a new cylindrical region at {centre} with radius 5 and with height 10
set {cyl} to cyl region at {centre} with radii (10,9) with height 30

Ellipsoid

Ellipsoid regions are simple as well, and are fairly similar to their cylindrical counterparts. They take another radius in place of the height though, so that all three axes (x,y,z) can have their radius modified. Once again, here's a few examples of how to get these:

set {ellipsoid} to a new spherical region at {centre} with radius 5    # x=5 y=x z=x
set {ellipsoid} to ellipsoid region at {centre} with radii (10,9,8)    # x=10 y=9 z=8
set {ellipsoid} to ellipse region at {center} with radii (7,12)        # x=7 y=12 z=x

Convex polyhedral

Convex polyhedral regions are when regions are at their trickiest, though they're still fairly simple to understand. This type of region uses a list of locations to be constructed, where each location represents a vertex. The resulting convex polyhedral region will be an area which contains all of the locations provided. If you're still a bit confused on how these works, I recommend playing around with them in-game. As you might have guessed by now, here's a few examples of how to get these:

set {convex} to a new convex polyhedral region using {locations::*}
set {convex} to convex region at {locations::*}

Warning

There seems to be a bug somewhere with serializing a convex polyhedral region (i.e. storing it in a global variable). While they do sometimes work, I wouldn't rely on SkWE being able to do this reliably.

Properties

So, now that you know how to get a region object, you may as well learn about the properties that each region has. These are just pieces of information that describe a region. None of them are complex enough to warrant having a dedicated section, but there are volume, centre, walls, and faces, which apply to all regions, and vertices, which is only applicable to convex polyhedral regions.

Operations

Now, as stated before, regions by themselves don't do anything, but they do dictate the area in which operations can happen. There are a whole bunch of operations, most of which need more data than just the region to complete. With this in mind, examples will be provided under the description of each, which will all show the most data that can be included. Keep in mind that, for the most part, not all of the data needs to be provided. Check the patterns for a more in-depth look at how the syntax work, and what is optional.

Centre

This, similar in a way to the centre property of a region, skips the middle man and sets the block in the centre of a region.

create a block at the center of {region} with bedrock

Faces

This is another operation which has an expression counterpart. While the expressions simply returns the region that represents the faces of a given cuboid region, this operation just directly sets the blocks to a given pattern. Note that, like the expression, this will only work on cuboid regions.

create the faces of {cuboid} made out of "5%%stone,1%%stone_bricks,1%%cobblestone"

Flora

This operation generates flora (i.e. grass, flowers, etc.) in a given region, where it can be naturally generated. It can be given a density, which defaults to 5.

make flora within {region} with density 10

Hollow

This operation hollows out the objects in a given region. It can be provided with thickness and pattern values; the former is the number of blocks to be left behind in the 'border', and the latter is the pattern of blocks to leave behind where any block gets hollowed out.

hollow out {region} with thickness 2 leaving behind glass block

Move

This is, pretty objectively, the most complex operation that there is, in terms of data that it can be provided. As you may have guessed from the name, it moves the blocks in a given region in a given direction. But it doesn't stop there... it can be provided a mask (so that only certain blocks get moved), an integer (the number of times to move the blocks, a pattern (to set the now-air blocks to), whether or not it should ignore air, whether or not it should copy entities, and finally whether or not it should copy biomes. This turns out to be, at its maximum, a pretty lengthy pattern.

move blocks that match stone in {region} up 50 blocks and fill the area with glass block while ignoring air while copying entities while copying biomes

Naturalize

From a pretty convoluted operation to a shockingly simple one, this operation just sets the first three layers of blocks in a region to grass/dirt, and sets blocks below to stone.

naturalize {region}

Overlay

This is also a fairly simple operation, which places a layer of blocks above the surface blocks in a region.

overlay the top level of blocks in {region} with "5%%diamond_block,5%%emerald_block"

Regenerate

This operation regenerates a given region, as if untouched by players or the server. It can be provided a seed to use (this will just default to the seed of the world, obviously), as well as whether or not it should regenerate biomes while it's going.

regenerate {region} with seed -76346913447246011 while regenerating biomes

Caution

There seems to be some sort of problem with this syntax... it works, but it takes ages and can impact server performance. I wouldn't recommend using it yet, unless you're sure its safe to do so.

Other info

For more information on regions in general, the WorldEdit region docs would be the best resource. Just note that there is some stuff which skript-worldedit doesn't support yet (e.g. WorldEdit CUI stuff, some of the operations, etc.).