Skip to main content

Protocol Versions

The proto="" attribute specifies what iteration of PGM a certain XML document was created for. It also 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 way.

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 ElementDescriptionValue/Children
The main map node containing the protocol version to be used.XML Modules
Map Attributes​
AttributeDescriptionValue
RequiredThe map XML's protocol version.Recommended
Map Protocol Values​
VersionDescription
Refer to Changes in 1.4.2.
NoteNo change in features on PGM. Use or instead.
Filters, regions, and teams are always referenced by its ID (replaces ).
Disallows inside or & disallows inside .
Required objectives to define if they are needed to win the match.
Moved all defining elements out of module XML root.
Everything scores zero points by default.
Filters are aware of who owns TNT.
Wools must have a location property.
Define how overlapping regions should behave.
Added monument modes.
Off-by-one region bug fixed.

Map Protocol Changelog​

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.
  • 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 & 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.