XML File Includes

A XML file can be split into multiple files and then included into the main one by using the include element. This allows you to keep the main file more organized by including sections such as kits or classes.

<include src="classes.xml"/>

The PGM plugin will look through it’s plugin-wide include path for includes, and it will also look for them relative to from where they are imported. You can set up a chain of includes that respects those same semantics.

Included XML files should have the XML header and the main map container.


<?xml version="1.0"?>
<map proto="1.4.2">

<!-- Add kits, classes etc., here -->


The master map repository contains the following pre-made XML files for you to use

File Description
tutorial.xml Contains the starting and ending stages of a tutorial
continuity-tnt.xml Contains a pre-designed TNT inventory, used on maps such as BoomBox
blasternauts.xml Contains the base XML for an arcade gamemode called 'blasternauts'
blitz-global.xml Contains the autorespawn mechanism for blitz maps
gs.xml Contains pre-made classes for the Ghost Squadron gamemode
gs-ffa.xml Contains pre-made teams for the Ghost Squadron FFA gamemode
stamina.xml Contains the default settings for the stamina module
skywars.xml Contains the base XML for Skywars
block-runner.xml Contains the base XML for an arcade gamemode called 'block runner'
disable-boat-crafting.xml Contains XML that disables boat crafting of any kind


XML files can contain simple <if> and <unless> conditional statements, these conditionals can be used to reduce duplicated map files and simplify managing multiple variations of a map. For example, instead of having multiple map variants in different folders they can condensed into one neat location. This also allows map variants to be automatically loaded on a specific servers or during holiday events.

Conditionals can be used anywhere in the XML and can contain anything. When PGM parses the XML, it will skip over any conditional blocks which are false.

There are two limitations to conditionals right now: attributes can only equate to true/false and conditions are defined in the PGM server configuration.

Element Description
<if a="true"> </if> If a is true, use the contents of this element.
<if a="true" b="true"> </if> If a AND b are both true, use the contents of this element.
<unless a="true"> </unless> If a is NOT true, use the contents of this element.
<unless a="false" b="false"> </unless> If (a OR b) is NOT false, use the contents of this element.
Name Description
ranked="" The map is running on a ranked server.
halloween="" Halloween -- Oct 1st 00:00 to Nov 1st 00:00
christmas="" Christmas -- Dec 1st 00:00 to Dec 26th 00:00
april-fools="" April Fools Day -- Apr 1st 00:00 to Apr 2nd 00:00


<!-- this section is only parsed when on a ranked server. -->
<if ranked="true">
        <tip after="1m">You guys are pros, keep up the good teamwork!</tip>

<!-- Conditional kit inventory -->
    <kit id="red-inventory">
        <if ranked="false">
            <item slot="0" material="iron sword"/>
        <if ranked="true">
            <item slot="0" material="diamond sword"/>

Conditional Terrain

If the individual map variants have a different physical world file they can still be neatly organized in the same folder. The terrain tag can be used to specify a sub-folder that contains the map’s terrain data. This will require any regions, etc. that are different between the worlds to be defined in separate conditionals.

<if ranked="true">
    <terrain world="ranked"/>
    <time result="objectives">30m</time>
<unless ranked="true">
    <terrain world="normal"/>
    <time result="objectives">45m</time>
    <respawn delay="5s" auto="true"/>

Things Not to Do

There are some pitfalls you should avoid when using conditionals. Defining elements outside and inside a conditional is discouraged, instead those elements should be defined inside their own conditionals. For example, elements with ID’s will throw an error if they are defined in both places at the same time. However, some elements will not, and instead the first or last defined instance of that element will be used.

<!-- Don't do this! PGM will throw an error because the id 'zombies' is used twice. -->
    <team id="zombies" color="red" max="30"/>
    <if ranked="true">
        <team id="zombies" color="dark red" max="10"/>

<!-- This is the correct way to do the above. -->
    <if ranked="false">
        <team id="zombies" color="red" max="30"/>
    <if ranked="true">
        <team id="zombies" color="dark red" max="10"/>