MultiRegion

As you read in the Region wiki page, a standard Region only represents a cuboid section of a world. There are cases where you need to define an entirely different shape, something amorphous. Instead of trying to cover each potential use case with mathematical models, you have MultiRegion, which allows you to treat multiple Regions as one - and it's better than it sounds.

To start, you simply instantiate the MultiRegion with a list of regions to include. Calling contains(Location) will return whether any of its child regions contain the given Location. You can also add more regions to it by calling add(Region). However, as you're probably thinking, this is inefficient. A human wouldn't create an optimal setup with the minimum number of regions needed to cover a given space with no overlap. And you'd be right, which is why MultiRegion has a method called recalculate().

Calling recalculate() on a MultiRegion makes all other calls to it faster. It scraps all of its child regions and breaks it down into the least number of regions that covers the same area with no overlap. The lack of overlap is important, as overlap can interfere with some operations. This method will also smartly cluster sub-regions to make sure all other operations are as fast as possible.

Just as Region has the stream() method to stream all of its blocks, so does MultiRegion. But calling stream() on a MultiRegion could result in iterating the same block multiple times if any of the child regions overlap. Other operations may also cause the MultiRegion to have a non-optimal layout, or not function properly, so it is recommended to call recalculate() after using any of the following methods:

add - Only after you have finished adding all regions subtract - If you intend to add more regions afterwards, or after you have finished adding and subtracting regions expand - After you have finished all operations, or every time if retracting

MultiRegion and Region also can both be converted to and from strings. If possible, it is recommended to construct the MultiRegion, recalculate it, and convert it to a string for storing rather than recalculating every time.