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.

Example

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

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

</map>

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

Conditionals

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.

Conditionals

Examples

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

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

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>
</if>
<unless ranked="true">
    <terrain world="normal"/>
    <time result="objectives">45m</time>
    <respawn delay="5s" auto="true"/>
</unless>

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. -->
<teams>
    <team id="zombies" color="red" max="30"/>
    <if ranked="true">
        <team id="zombies" color="dark red" max="10"/>
    </if>
</teams>

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