This manual will provide you with enough information to compose your own map specification file (commonly referred to as the map.xml file or "the xml"). It includes examples and descriptions of each module / feature. You are expected to understand the basics of XML before reading this document.
Understanding the following high level concepts will help you write a better map specification file.
Modules are the fundamental building blocks of the map specification because they isolate different aspects of gameplay to simplify coding. Although they are separate, many modules refer to features provided by other modules (for example, regions). Almost everything with a separate top-level tag is specified in a different module.
Many times modules need to parse a specific type of data to function. The following is a non-exhaustive list of data types understood by PGM:
Regions are absolutely essential to a specification file. Currently a region is defined as any object that can contain a 3D point. Due to that loose restriction, PGM regions can take on an arbitrary complexity. For a list of region types and how to define them, refer to the region module below.
Vectors are simply a list of floating point numbers. PGM supports both 2D and 3D vectors. 2D vectors are assumed to be defined for all values of Y and take specific information for the X and Z components. 3D vectors take the form of x,y,z and are based upon the same coordinate system of Minecraft (y is up-down).
Each component is assumed to be a floating point number (read: any real number), but infinity and negative infinity are also supported (syntax: oo for infinity, -oo for negative infinity).
Examples:
- base="2.5,-3,403"
- min="-oo,3,29"
- max="30,28,oo"
Materials should be very familiar to any Minecraft user, for they are the "building blocks" of Minecraft. However, currently PGM only supports the code names for each material, so you must refer to the Bukkit Material documentation for the correct names. Note that capitalization does not matter and underscores may be replaced with spaces. Some parts of the specification protocol may support materials with an optional data value (syntax: wood:3 for wood with a data value of 3).
Matchers are very simple primitives for matching certain types of objects. There are many types of matchers for different types of data including blocks, entities, teams, and more. Refer to the filter module documentation for more information.
Many modules allow for element inheritance when defining attributes. For element inheritance there are two main types of tags: the "parent" tag and the "child" tag. Parent tags usually take on the plural version of the child tag, which is usually singular.
For example, take the following XML:
<players color="purple">
<players clan="Dominators">
<player color="blue">Player 1</player>
<player color="red">Player 2</player>
<player>Player 3</player>
</players>
<player clan="Weaklings">Player 4</player>
<player clan="PGM" color="pink">Player 5</player>
</players>
From this we determine the following:
<players>is the parent element,<player>is the child element.- Player 1 is a member of the Dominators clan and is blue.
- Player 2 is a member of the Dominators clan and is red.
- Player 3 is a member of the Dominators clan and is purple.
- Player 4 is a member of the Weaklings clan and is purple.
- Player 5 is a member of the PGM clan and is pink.
Note that element inheritance is usually provided as a utility to the specification author so he does not need to duplicate as much information.
The following is an incredibly basic map.xml file:
<?xml version="1.0.0">
<map proto="1.2.0">
<name>Cake Wars</name>
<version>1.4</version>
<objective>Leak lava from the enemy's gold core below the cakeline.</objective>
<authors>
<author>bigbangbrother02</author>
<author>Thungon</author>
</authors>
<contributors>
<contributor contribution="morale support">Someone</contributor>
</contributors>
<rules>
<rule>Rule 1</rule>
<rule>Rule 2</rule>
</rules>
</map>
The map specification file is built upon the idea of modules. Currently PGM supports a very large range of modules, each providing a unique feature. Most modules only apply in the scope of a match duration (they don't take effective before / after a match), but there are a few exceptions to this rule.
The team module is required in every map specification file and takes the following form:
<teams>
<team color="{color}" max="{player cap}">{name}</team>
</teams>
Teams can have the following attributes:
- color: color the team will have in chat (required)
- max: maximum number of players who may join the team (required)
- overhead-color: color of the names above the heads of the members of the team (defaults to the color specified in color)
All teams specified in the team module are assumed to be participating teams.
Specifying spawn points is one of the first things you will want to do when writing a map specification file. The plugin needs to have a valid spawn point for every player who will ever play on the map.
Spawns are specified using element inheritance with <spawns> being the parent element and <spawn> being the child element. Spawns take the following form:
<spawns>
<spawn team="red" yaw="90">3,2,3</spawn>
<default yaw="180">5,20,3</default>
</spawns>
Note that a spawns should be specified for each playing team. The <default> spawn is used for spawning observers who fall out of the world or first time players who just joined. There should only be a single default spawn, and it must be specified in the top level <spawns> section.
Spawn specifications have two mains parts:
Point providers are used to fetch a (possibly random) point. The most important aspect of a point provider is the vector provider. Currently there are two main types of vector providers:
- static vector provider rovides a single, static vector. It is specified simply as a vector or wrapped with the
<point>x,y,z</point>tag. - random vector point provider takes a random vector from a specified region. It is specified simply as a region that supports the random operators (currently only cuboids).
Point providers are composed of a single vector provider and (static) yaw and pitch values.
Multiple point providers may be specified for a single spawn point. In that case, PGM will randomly select which point provider to fetch a point from using equal chance probability.
For example:
<spawn yaw="180">
<point>10,2,10</point>
<cuboid min="1,2,3" max="4,5,6"/>
</spawn>
In this case the half the time a player will spawn at the point 10,2,10 and the other half he will spawn in a random point contained by the cuboid specified above.
Note that in the most explicit form all point providers are wrapped with the <point> tag. An advantage to wrapping with the point tag is that you may specify a custom yaw / pitch value independent of the parent tag.
For example:
<spawn yaw="90">
<point>1,2,3</point>
<point yaw="180">4,5,6</point>
</spawn>
The first point will have a yaw of 90 degrees while the second point will have a yaw of 180. Though point providers can be wrapped with the point tag, most of the time it is not necessary and is dropped for the sake of conciseness.
Tip: When specifying a random region for players to spawn in (and it is not a safe spawn), make sure that the region is "flat" (height is 0) and the y value is at the point a player's feet should be at so they spawn on the ground instead of the air.
Spawns may take a small amount of attributes:
- team: team the spawn point will be active for (only while the match is running)
- kit: name of a kit that should be given to anyone who spawns according to this spawn policy
In addition to those two attributes, there is also an option to enable safe spawning by specifying safe="true" for a spawn. Safe spawns behave much differently from a regular spawn policy. For each point provider specified in the safe spawn, the plugin will generate 100 random points from the point provider to check. A point is determined to be safe if the block underneath it is completely solid and the two blocks above it are air. If it does not find a safe spawn point out of the 100 generated, the plugin will move on to the next point provider, or if none exist then simply drop them at the last generated point regardless of safety. Due to this behavior, it is best to specify a static point provider in a safe portion of the map as a last provider for a safe spawn.
Examples:
<spawn team="red" yaw="90">1,2,3</spawn>
Spawns members of the red team at the point (1,2,3) rotated 90 degrees.
<spawn team="blue" yaw="180" safe="true">
<cuboid min="1,2,3" max="4,5,6"/>
<point yaw="90">10,11,12</point>
</spawn>
First tries to spawn members of the blue team inside a random, safe point in the cuboid above rotated 180 degrees. If no safe spawn could be find, it'll instead drop them at (10,11,12) rotated 90 degrees, regardless of safety since it is the last point provider listed.
<default yaw="180"><cylinder base="1,2,3" radius="3" height="0"/></default>
Spawns observers and first joiners at a random point in the cylinder based at (1,2,3) rotated 180 degrees.
Is this going to be finished?