Skip to main content

Main Map Element

Every map XML file must contain the base <map> module. It contains modules that specify the map name, version, objective, authors, contributors, and all other map settings. The objective is the text that players see when they join the match, and so it is important for this to be very clear, concise, and informative.

The proto="" attribute specifies what PGM version the XML file was created for. Mapmakers should always use the latest supported proto version, which is documented in depth at Protocol Versions.

The maps version should follow the versioning schema major.minor.patch.

Map ElementDescriptionValue/Children
<map> </map>The main map node containing all the modules used in this match.XML Modules
Map Attributes
Map AttributesDescriptionValueDefault
protoRequiredThe map's XML protocol version.1.4.2
internalPrevent compass teleports above Y=255.true/falsefalse
Map Sub-elements
<name>RequiredThe name of the map.String
<slug>The map's slug, usually auto generated from the map's name. This should only be used when a map is renamed to retain the map's ratings, etc.
Valid slugs are lowercase and only contain the characters: a-z 0-9 _
StringAuto Generated
<version>RequiredThe map's semantic version string.1.0.0
<objective>RequiredThe map's objective, shown at the start of the match.String
<authors>RequiredThe authors of the map, at least one author is required.<author>
<contributors>Contributors to the map.<contributor>
<created>The date on which this map was initially released.YYYY-MM-DD
<phase>The phase of this map.
Note: By default, it will not appear in the list when a user runs /maps. In legacy PGM, only maps with production and standard show up on a website configured with an API.
<edition>The edition of this map, describing which servers it should run on.standard
<game>A custom title for this match's gamemode.String
<gamemode>The gamemode(s) of this map, if this is not specified the map will set the gamemode(s) to whatever modules are used.Gamemode ID
<map proto="1.4.2">
<name>Map Name</name>
<objective>Short description about the map's objective.</objective>

<!-- Map authors & contributors. -->

<!-- Map modules, i.e. objectives, regions, spawns. -->


Authors & Contributors

The authors and contributers elements provide information about who created and helped create the map. There can be multiple authors and contributors to a map. The contribution attribute should be used to specify what their contribution to the map was.

A player's name should not be used to credit them, instead their UUID should be used. A UUID is a unique user identifier that is used to keep track of players even if they change their name. You can check player UUIDs at If an author or contributor is defined without a UUID, that player will not get any mapmaker perks on the map.

Author or Contributor Sub-elements

<author>A major author of the map, used in <authors>.String
<contributor>A contributor to the map, used in <contributors>.String
Author & Contributor Attributes
uuidThe UUID used to identify a Minecraft player.String
contributionThe contribution this author or contributor made to the map.String
<!-- Major map authors -->
<author>aPerson</author> <!-- Credit a person that doesn't have a Minecraft account -->
<author uuid="ef4ea031-998f-4ec9-b7b6-1bdd428bcef8" contribution="Clarification of element usage, etc."/> <!-- Plastix -->
<author uuid="260004f0-996b-4539-ba21-df4ee6336b63"/> <!-- Elliott_ -->

<!-- People that contributed in some way to the map -->
<!-- Credit a person that doesn't have a Minecraft account -->
<contributor contribution="A contribution">aHelper</contributor>
<contributor uuid="3fbec7dd-0a5f-40bf-9d11-885a54507112" contribution="Some help"/> <!-- Cubist -->

Include Statements

Include statements allow for global XML files to be loaded and re-used across different maps. This can be used to standardize values across maps. Below is a sample includes file that can be used on Blitz maps:

<!-- the location for include files is defined in config.yml -->

The file is automatically given an ID based on the file name, which in this case is blitz. Then it can be added into the main map.xml. Multiple include statements can be used per map.

<!-- All maps with this include statement will give the player 5 lives -->
<include id="blitz"/>

Map Variants

Mapmakers may choose to build different versions of their maps that are tailored for events, such as tournaments. This tool allows them to avoid the need to duplicate existing maps and, instead, unify various versions into one location.

By defining a variant ID, PGM will treat an individual map with one or more variants as separate maps. Each variant can contain conditionals, which determine whether a section of the XML file from the base (internally, the default variant) map should be loaded for a variant map. Additionally, a variant can also contain constants, which allows you to define text constants that can be used to replace placeholders in the base map XML with the specified values.

Variant Sub-elements

<variant> </variant>A map variant.String

Variant Attributes

idRequiredUnique identifier used to reference this map variant from other places in the XML.String
worldSpecify the world the variant should use during a match.String
overrideToggle if the variant name should override the base map name. If set to false, PGM will append : [variant] to the base map name.true/falsefalse

Conditionals Sub-elements

<if> </if>Apply an XML section if the specified variant is loaded.XML Modules
<unless> </unless>Apply an XML section for all variants except for a specific variant when loaded.XML Modules

If/Unless Conditional Attributes

variantThe name of the variant to target.Variant ID
has-variantTarget all maps with a specified variant.
Note: This can be useful in a server's global XML file.
Variant ID

Note: Multiple variants can be targeted as long as it is separated with a comma (,).


Constants are values that remain the same, regardless of conditions. PGM will search and replace any corresponding placeholders (${constant_id}) with the constant value.

<constants> </constants>A node containing the constants for this map.Constant Elements
<constant> </constant>An individual constant.String

Constant Attributes

idRequiredUnique identifier used to reference this constant from other places in the XML.String
deleteWhen true, PGM will completely delete the attribute or element the constant was used in, rather than leaving it blank.true/falsefalse

The following example utilizes both map variants and constant.

<map proto="1.4.2">
<name>Map Name</name>
<variant id="5v5">5v5</variant> <!-- Loaded as "Map Name: 5v5" -->
<variant id="tournament">TE</variant> <!-- Loaded as "Map Name: TE" -->
<variant id="halloween" override="true">Spooky Map Name</variant> <!-- Loaded as "Spooky Map Name" -->

<!-- PGM will replace "${team_size}" and "${max}" placeholder with the new value -->
<constant id="team_size">25</constant>
<constant id="overfill" delete="true"/> <!-- "max-overfill" will not exist when "Map Name" is loaded -->
<constant id="max">6</constant>
<if variant="5v5">
<constant id="team_size">5</constant>
<constant id="overfill">5</constant>
<constant id="max">3</constant>
<if variant="tournament">
<constant id="team_size">6</constant>
<constant id="overfill">6</constant>
<constant id="max" delete="true"/>

<team id="red" max="${team_size}" max-overfill="${overfill}"/>
<team id="blue" max="${team_size}" max-overfill="${overfill}"/>
<limit>${max}</limit> <!-- 6 in "Map Name", 3 in "Map Name: 5v5", non-existent in "Map Name: TE" -->

Map Gamemode

The gamemode element is used to specify the gamemode(s) of the map. This mainly affects how the map is displayed. If no <gamemode> tags are specified, the map will set the gamemode(s) to whatever modules are used. This means that a map that uses destroyables and flags would be displayed as "DTM and CTF" unless specified otherwise.

<gamemode> </gamemode>The gamemode(s) of this map.Gamemode ID

Gamemode IDs

bedwarsBed Wars
brBlitz: Rage
cpControl the Point
ctfCapture the Flag
ctwCapture the Wool
dtcDestroy the Core
dtmDestroy the Monument
ffaFree for All
ffbFlag Football
kotfKing of the Flag
kothKing of the Hill
rfwRace for Wool
sgSurvival Games


<!-- A FFA map with scoreboxes -->