Regions are a type of filter that filters the coordinates of a query. They are used to define, among other things, the area a filter applies to or where a portal links from. There are two distinct types of regions; block bounded regions, which contain a finite amount of blocks and unbounded regions that contain a infinite amount. All regions and region modifiers can have a id attribute to reference them from kits, portals, etc.

<regions>
    <rectangle id="xyzzy-region" min="-50,-50" max="50,50"/>
</regions>

<!-- Region reference -->
<region id="xyzzy-region"/>

The area a region applies to is specified with one or more of the following elements. Use oo and -oo to specify positive/negative infinity in coordinates. See the Properly Defining Regions guide for information on how to properly get the coordinates of a region.

Region Types

Half-space Regions

A half-space region contains everything on one side of an arbitrary plane. The plane is defined by an origin point and a normal vector, and the region contains everything on the side of the plane that the normal is pointing towards. The example below defines a region with a diagonal boundary:

<half origin="5,0,0" normal="1,1,0"/>

The above and below regions can be used to conveniently define axis-aligned half-spaces:

<above y="50"/>         <!-- Everything above Y=50 -->
<below x="0" z="0"/>    <!-- Everything in the -X, -Z quadrant -->

Applying Things to Regions

Filters, kits, and velocity changes can be applied to regions by using an <apply> element. The apply element can contain more than one region. If the apply element contains more than one region the same settings are applied to all of them. Applies with no region default to <everywhere/>. Applies can also be defined in the filters element.

The order in which apply elements are specified determines which takes precedence when regions overlap. Applies specified first override those specified further down in the XML. See filter apply order for a more detailed example. The region an apply affects can be specified as an attribute or in a sub-element.

Apply Element Attributes

Apply Examples

<!-- Apply a blue team usage filter and referenced the region in an attribute. -->
<apply region="region1" use="blue-team-filter"/>

<apply kit="dark-tower-kit">
    <region>
        <!-- Multiple regions or region references in a regions sub-element. -->
        <region id="region1"/>
        <rectangle min="-5,-5" max="5,5"/>
    </region>
    <!-- Inline effect filter -->
    <filter>
        <team>blue</team>
    </filter>
</apply>

Examples

<!-- Give a kit to players entering the region. -->
<apply kit="knight">
    <region>
        <region id="r-knight"/>
        <region id="b-knight"/>
    </region>
</apply>
  
<!-- Only allow breaking of sandstone stairs and deny placing of all blocks. -->
<apply block-break="only-sandstone-stairs" block-place="never" message="You may not modify this area">
    <region>
        <rectangle min="-6,-58" max="7,-47"/>
        <rectangle min="-6,48" max="7,59"/>
    </region>
</apply>
  
<!-- Example regions from Harb using region modifiers. -->
<regions>
    <rectangle id="main-area" min="-50,-32" max="51,33"/>
    <union id="bases">
        <rectangle id="blue-base" min="-20,-62" max="21,-32"/>
        <rectangle id="red-base" min="-20,33" max="21,63"/>
    </union>
    <complement id="portals-area">
        <rectangle min="-56,-2" max="57,3"/>
        <region id="main-area"/>
    </complement>
  
    <!-- Protect portal areas -->
    <apply block="never" region="portals-area"/>
    <apply block="no-tnt" region="bases" message="You may not place TNT in the bases."/>
</regions>

An applies velocity attribute changes the players velocity when they enter the specified region. This velocity is specified as a X,Y,Z vector. On the mapdev servers velocity can be tested with the /vel x y z command.

Example using velocity for jump pads

<regions>
    <!--  Yellow Pads  -->
    <apply velocity="-0.4,1.1,0.0">
        <region>
            <cuboid min="-1081,1,-2116" max="-1078,2,-2113"/>
        </region>
    </apply>
    <apply velocity="0.0,1.4,-0.4">
        <region>
            <cuboid min="-1062,1,-2123" max="-1059,2,-2120"/>
        </region>
    </apply>
</regions>

Region Modifiers

Regions can be inverted, combined, subtracted, or intersected by putting them inside of the following elements.

Regions can be translated or mirrored with the following elements. When translating or mirroring a region the original is not modified instead a copy is created.

When mirroring a region the origin is the central point around which the region is mirrored. This point can be inside or outside the region being mirrored. The normal specifies which direction the region is being mirrored, e.g., 1,0,0 would mirror along the +X axis.

Examples

<!-- Region Union-->
<regions>
    <!-- Blue Team Base -->
    <apply enter="only-blue" message="You may not enter the enemy team's base!">
        <region>
            <union>
                <cuboid min="-20,8,-75" max="11,41,-79"/>
                <cuboid min="8,8,-80" max="13,41,-75"/>
            </union>
        </region>
    </apply>
</regions>

<!-- Region Mirror -->
<regions>
    <apply block="never" message="You may not under-bridge!">
        <region>
            <cuboid id="red-underside" min="-oo,-oo,-oo" max="oo,41,40"/>
            <mirror origin="116,44,93" normal="0,0,1">
                <region id="red-underside"/>
            </mirror>
            <cuboid min="-oo,-oo,-oo" max="oo,37,oo"/>
        </region>
    </apply>
</regions>

Point Providers

A point provider is used to return individual points inside a region. It can also be used to modify the position returned by a region to include the direction a player ends up facing when spawned, etc. Input can be a region, a region modifier or simply an exact X,Y,Z coordinate.

<point yaw="90" pitch="50">X,Y,Z</point>

Point Attributes

Point Sub-elements

NOTE: The pitch and yaw arguments can also accept a X,Y,Z coordinate.
TIP: Copy the yaw and pitch from the F3 screen in minecraft (the Facing: Direction (Axis) (Yaw/Pitch) line).