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.
<rectangle id="xyzzy-region" min="-50,-50" max="50,50"/>
<!-- Region reference -->
The area a region applies to is specified with one or more of the following elements.
-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.
Block Bounded Regions
|Block Bounded Regions|
A rectangular solid from to .
Using the attribute offsets the original min/max value by . ie. (min + size = max) & (max - size = min)
Only block bounded when using finite coordinates.
A cylinder located at with a radius of and a height of .
Only block bounded when using a finite radius.
A single block located at .
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.
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.
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:
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
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
Apply Element Attributes
|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/false||false|
|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 a blue team usage filter and referenced the region in an attribute. -->
<apply region="region1" use="blue-team-filter"/>
<!-- Multiple regions or region references in a regions sub-element. -->
<rectangle min="-5,-5" max="5,5"/>
<!-- Inline effect filter -->
<!-- Give a kit to players entering the region. -->
<!-- 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">
<rectangle min="-6,-58" max="7,-47"/>
<rectangle min="-6,48" max="7,59"/>
<!-- Example regions from Harb using region modifiers. -->
<rectangle id="main-area" min="-50,-32" max="51,33"/>
<rectangle id="blue-base" min="-20,-62" max="21,-32"/>
<rectangle id="red-base" min="-20,33" max="21,63"/>
<rectangle min="-56,-2" max="57,3"/>
<!-- Protect portal areas -->
<apply block="never" region="portals-area"/>
<apply block="no-tnt" region="bases" message="You may not place TNT in the bases."/>
Applying Velocities to Regions
An applies velocity attribute changes the players velocity when they enter the specified region.
This velocity is specified as a
Example using velocity for jump pads
<!-- Yellow Pads -->
<cuboid min="-1081,1,-2116" max="-1078,2,-2113"/>
<cuboid min="-1062,1,-2123" max="-1059,2,-2120"/>
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 Diagram
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 Mirrors Diagram
<!-- Region Union-->
<!-- Blue Team Base -->
<apply enter="only-blue" message="You may not enter the enemy team's base!">
<cuboid min="-20,8,-75" max="11,41,-79"/>
<cuboid min="8,8,-80" max="13,41,-75"/>
<!-- Region Mirror -->
<apply block="never" message="You may not under-bridge!">
<cuboid id="red-underside" min="-oo,-oo,-oo" max="oo,41,40"/>
<mirror origin="116,44,93" normal="0,0,1">
<cuboid min="-oo,-oo,-oo" max="oo,37,oo"/>
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
<point yaw="90" pitch="50">X,Y,Z</point>
|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.
|PropertyThe region or regions the point provider modifies.||Randomize-able Regions|
NOTE: The pitch and yaw arguments can also accept a
TIP: Copy the yaw and pitch from the F3 screen in Minecraft (the
Facing: Direction (Axis) (Yaw/Pitch) line).