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's 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 Element	Description	Value/Children
<map> </map>	The main map node containing all the modules used in this match.	XML Modules

Map Attributes

Attribute	Description	Value	Default
proto	RequiredThe map's XML protocol version.	1.4.2
internal	Prevent compass teleports above Y 255	true/false	false

Map Sub-elements

Element	Description	Value/Children	Default
<name>	RequiredThe name of the map.	String
<slug>	The map's slug, usually auto generated from the maps 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 _	String	Auto 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>	Phase of this map. Only maps with production andstandard show up on the website.	developmentproduction	production
<edition>	Edition of this map, describes which servers it is run on.	standardrankedtournament	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>
<version>1.0.0</version>
<objective>Short description about the maps objective.</objective>

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

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

</map>

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 mcuuid.net. 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

Element	Description	Value/Children
<author>	A major author of the map, used in<authors>	String
<contributor>	A contributor to the map, used in<contributors>	String

Author & Contributor Attributes

Attribute	Description	Value
contribution	The contribution this author or contributor made to the map.	String
uuid	UUID used to identify a player.	String

<!-- Major map authors. -->
<authors>
    <author>aPerson</author>
    <author uuid="ef4ea031-998f-4ec9-b7b6-1bdd428bcef8" contribution="Clarification of element usage, etc."/> <!-- Plastix -->
    <author uuid="260004f0-996b-4539-ba21-df4ee6336b63"/> <!-- Elliott_ -->
</authors>

<!-- People that contributed in some way to the map. -->
<contributors>
    <!-- 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 -->
</contributors>

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 an example includes file that can be used on Blitz maps:

/server/includes/blitz.xml

<!-- the location for include files is defined in config.yml -->
<map>
    <blitz>
        <lives>5</lives>
    </blitz>
</map>

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.

/server/maps/map_name/map.xml

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

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.

Element	Description	Value/Children
<gamemode> </gamemode>	The gamemode(s) of this map.	Gamemode ID

Gamemode IDs

ID	Description
ad	Attack/Defend
arcade	Arcade
blitz	Blitz
br	Blitz: Rage
cp	Control the Point
ctf	Capture the Flag
ctw	Capture the Wool
dtc	Destroy the Core
dtm	Destroy the Monument
ffa	Free for All
ffb	Flag Football
kotf	King of the Flag
koth	King of the Hill
mixed	Mixed
pd	Payload
rage	Rage
rfw	Race for Wool
scorebox	Scorebox
skywars	Skywars
tdm	Deathmatch

Example

<!-- A FFA map with scoreboxes -->
<gamemode>ffa</gamemode>
<gamemode>scorebox</gamemode>