Protocol Versions

The proto attribute specifies what iteration of PGM a certain XML document was created for. It instructs PGM on whether to allow the usage of deprecated or newly introduced features within a map. If the value is lower than the currently recommended proto version, the map will load but the XML may be interpreted in an outdated and unexpected ways.

Mapmakers should always use the latest supported proto version, and this may be required of new maps that are to be added to any map compilation projects, such as ResourcePile.

Map Element

Map Element	Description	Value/Children
<map> </map>	The main map node containing the protocol version to be used.	XML Modules

Map Attributes

Attribute	Description	Value
proto	RequiredThe map XML's protocol version.	Recommended1.5.0

Map Protocol Values

Version	Description
1.5.0	Refer to Changes in 1.5.0.
1.4.2	Refer to Changes in 1.4.2.
1.4.1	No change in features on PGM. Use 1.4.0 or 1.4.2 instead.
1.4.0	Filters, regions, and teams are always referenced by its ID (replaces name). Disallows <time> inside <score> or <blitz> & disallows <title> inside <blitz>.
1.3.6	Moved all defining elements out of module XML root. Everything scores zero points by default.
1.3.5	Filters are aware of who owns TNT.
1.3.4	Wools must have a location property.
1.3.3	Define how overlapping regions should behave.
1.3.2	Added monument modes.
1.3.1	Fixed a bug in which cuboids' max value were off by one. Note: When upgrading a map from proto 1.3.0 or below, all cuboid max values should be manually increased by positive 1. No other region types are affected.

Map Protocol Changelog

Changes in 1.5.0

note

1.5.0 is now available. As the latest protocol version, it is not fully polished, so bugs are expected. If you would like to learn more or report issues, please visit the PGM issue tracker.

Breaking

• Some variables and some additional filters are now their own IDs that will be reserved by PGM. Those IDs can be referenced anywhere in the XML.

  • This applies to the following filters: observing, participating, alive, dead, match-idle, match-starting, match-running, match-finished, match-started, crouching, walking, sprinting, grounded, flying, can-fly, and void.

    <!-- Sample proto 1.4.2 XML -->
    <filters>
        <alive id="alive"/> 
    </filters>
    <some-other-feature filter="alive"/>
    
    <!-- Sample proto 1.5.0 XML -->
    <filters>
      <!-- Defining the alive id is not necessary, as it's a built-in now -->
    </filters>
    <some-other-feature filter="alive"/>    

  • This applies to the following variables: lives, score, timelimit, maxbuildheight, player.x, player.y, player.z, player.pitch, player.yaw, player.dir_x, player.dir_y, player.dir_z, player.vel_x, player.vel_y, player.vel_z, player.has_target, player.target_x, player.target_y, player.target_z, player.place_x, player.place_y, and player.place_z.

• Triggers and switch-scope actions now exclude observers when the scope is team or player.

  • For maps below proto 1.4.2, observers defaults to true for backward compatibility. In proto 1.5.0, it defaults to false.

    <!-- Sample proto 1.4.2 XML -->
    <trigger scope="player" observers="true" filter="your-filter">
    <switch-scope inner="player" observers="true">
• Actions now untrigger by default.

  • This is not a common behavior, as the only action to untrigger is removable kits. This is expected to change in the future.

  • For maps below proto 1.4.2, untrigger-filter defaults to never for backward compatibility. In proto 1.5.0, an action with no filter will default to always while a filtered action will default to never.

    <!-- Sample proto 1.5.0 XML -->
    <action untrigger-filter="always">

Changes in 1.4.2

Breaking

• The objectives filter will now always automatically derive team ownership for the objective from context. To match an objective without any specific team, the any="true" attribute needs to be specified.

New

Partially implemented

• Portals, kits, score boxes & structures can now be dynamically applied using dynamic filters. All region types are dynamic, however, only some filter types are dynamic.
  • Kits now have give, take & lend properties.
  • Portals have forward, reverse & transit properties.
  • Structures & score boxes have a trigger property.
• Added a player count filter.
• Added a <grounded/> filter to check if the player is standing on the ground.
• Added <match-started/>, <match-running/> & <match-finished/> filters that are used to check the state of the current match.
• New pre-match-physics attribute for the terrain module to enable physics events before the match starts.
• Added <observing> and <participant> filters. Also added an observers filter property to portals to restrict observer access.
• Added player rank and score filters. Filters return if the player's rank or score is within the specified range.
• Control points have new recovery and decay attributes that replace the incremental attribute and allow more control of the progress.

Changes in 1.4.0

Breaking

• Filters, regions, and kits now use id instead of name.

  • Keep in mind that IDs are all in the same namespace, so you can not use the same ID for two different types of thing.

• Teams have an id attribute and are always referenced by it everywhere in the XML, never by name.

• Standalone filter definitions are no longer wrapped in a <filter> tag, they start with an actual filter, just like regions, e.g.

  <filters>
      <team id="only-red">red-team</team>
  </filters>

• The region for an <apply> must be either a region attribute or a <region> sub-element. It cannot appear directly inside the <apply> tag.

• Inline filters must always be a single tag, multiple tags are not accepted anywhere. To combine multiple filters, always use a compound filter like <all> or <any>. This change is retroactive, and affects all proto versions.

• There is no longer a filter type called <block>, use <material> instead. <block> is always interpreted as a region.

• The old built-in filters are gone, and there are only two new ones: always which is equivalent to allow-all, and never which is equivalent to deny-all.

  • All of the new built-ins have equivalent tags of the same name i.e. <always/> & <never/>.

• <allow> and <deny> can now be used anywhere a filter is expected, and actually function how they were supposed to i.e. they cause the filter to be ignored (skipped over) if it does not match.

• Blitz titles are no longer a part of the Blitz module, instead they are set using the map sub-element <game> and can be used with any gamemode.

• Match time limit is no longer part of the <score> or <blitz> module, instead it is defined directly in the root element.

  <map proto="1.4.0">
  <time result="objectives">5m</time>
  <!-- Other modules -->
  </map>

Changes

• The top-level tags <filters> and <regions> are now the same thing. You can define filters, regions, and <apply>s in either one (remember that regions are a type of filter, have been for a while now).

• Any filter tag anywhere can have an id attribute.

• The <apply> tag accepts both references and inline definitions for its region, kit, and all of its filter properties, e.g. the two tags below are equivalent:

  <apply region="effect-pad" kit="effect-kit" filter="only-red" block="only-leaves"/>
  <apply>
      <region>
          <cuboid min="1,2,3" max="4,5,6"/> <!-- effect-pad -->
      </region>
      <kit>
          <potion>...</potion> <!-- effect-kit -->
      </kit>
      <filter>
          <team>red-team</team>
      </filter>
      <block>
          <material>leaves</material>
      </block>
  </apply>

• The safe and spread attributes of spawns can now be combined.

• A items slot attribute is no longer required in kits. This attribute now also accepts Mojang slot names e.g. slot.hotbar.8 or armor.head.

New

• There are two built-in regions called everywhere and nowhere that contain all points and no points, respectively.
  • All of the new built-ins have equivalent tags of the same name i.e. <everywhere/> & <nowhere/>.
• A team can have a minimum required size with the min="" attribute.
• Objectives have a required attribute that specifies if they are required to complete the match.

Removed

• The <multitrade/> tag has been removed, it is now always enabled.

Changes in 1.3.6

Breaking

• Regions for cores, destroyables, wools, portals, and score boxes must be defined in a <region> sub-element or referenced in a region attribute.

  <core>
      <region>
          <cuboid min="..." max="..."/>
      </region>
  </core>
  <core region="my-region"/>

  • Similarly, spawn regions must be defined in a <regions> sub-element or referenced in a regions attribute.

    <spawns>
        <spawn team="red">
            <regions yaw="90">
                <cuboid min="1,0,2" max="3,0,4"/>
                <cylinder base="7,8,9" radius="5" height="0"/>
            </regions>
        </spawn>
    </spawns>

• Everything scores 0 points by default, this means you have to explicitly define <kills> and <deaths> in the score module if you want players to get points for killing players.