Regions

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
Block Bounded Regions

A rectangular solid from to .
Only block bounded when using finite coordinates.
Randomize-able

A cylinder located at with a radius of and a height of .
Only block bounded when using a finite radius.
Randomize-able

A single block located at .
Randomize-able

A sphere located at with a radius of .
Only block bounded when using a finite radius.

A single point region located at .
This region will always return the same location even when used in a randomized context, e.g., spawns.
Randomize-able
Unbounded Regions

A rectangle from to .

A circle located at with a radius of .
The region goes from 0 to map height, i.e. PGM doesn't check the players Y position.

Half of the world split by a plane pointing towards a normal.
|
Half of the world split at the specified axis.
If multiple axises are defined the specified parts of each axis are intersected and returned.
Static Regions

A zero size/position region, contains nothing.

A reference-able zero size/position region, contains nothing. Can be referenced with the region ID:

A reference-able infinite size region, contains everything. Can be referenced with the region ID:

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 <region> sub-element.

Apply Element Attributes
AttributeDescriptionValueDefault
PropertyThe region this apply affects.Region
PropertyFilter player enter events.Filter
PropertyFilter player leave events.Filter
PropertyFilter block place and break events.Filter
PropertyFilter block place events.Filter
PropertyFilter block place against events.Filter
PropertyFilter block break events.Filter
PropertyFilter world block updates; water flowing, portals disappearing, etc.Filter
PropertyFilter right-click events.Filter
Send a message to the player if the filter denies the event.String
Warn the player before they actually break a denied block.true/falsefalse
Apply Effects
PropertyGive a kit to players entering the region.Kit
PropertyGive a kit to players entering the region, and remove it when they leave the region. This can be used only with removable kits. Any non-removable kit will generate an error. The kits page explains which kit types are removable.Kit
Change a players velocity when they enter the region.X,Y,Z
PropertyFilter when/if kits and velocities are applied.Filter

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.

Inverse of a region, the region or regions will no longer be considered block bounded.
Combination of multiple regions.
Subtracts successive regions from the first defined region.
Returns the area that multiple regions intersect with.

Region Combinations

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.

Copy and translate a region by blocks.
Copy and mirror a region towards a normal around a point.

Region Mirror

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
AttributeDescriptionValue
PropertyThe region the point provider modifies.Randomize-able Region
Specifies what direction the player is looking horizontally from -180° to 180°.
South 0°, East -90°, North 180° and West 90°.
-180 to 180
Specifies what direction the player is looking vertically from -90° to 90°.
-90° is straight up 90° is straight down.
-90 to 90
Specify the exact block coordinates that the player should look at.
This attribute will negate any angles set by the and attributes.
X,Y,Z
Point Sub-elements
ElementDescriptionValue/Children
PropertyThe region or regions the point provider modifies.Randomize-able Regions

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).