Document proto 1.5.0 (#151)

* Document proto 1.5.0 Signed-off-by: Pear <[email protected]> * Implement CoWink's suggested change Co-authored-by: Patrick <[email protected]> Signed-off-by: Pear <[email protected]> * Delete extra word Signed-off-by: Pear <[email protected]> * Implement Pablo's suggested change (part 1) Co-authored-by: Pablo Herrera <[email protected]> Signed-off-by: Pear <[email protected]> * Implement Pablo's suggested change (part 2) Signed-off-by: Pear <[email protected]> * Adjust untrigger notes Based on updates in PGMDev/PGM#1411 Signed-off-by: Pear <[email protected]> * Fix XML issue in Race for Victory example Signed-off-by: Pear <[email protected]> --------- Signed-off-by: Pear <[email protected]> Co-authored-by: Patrick <[email protected]> Co-authored-by: Pablo Herrera <[email protected]>
PGMDev · Oct 15, 2024 · a168281 · a168281
1 parent 145b404
commit a168281
Show file tree

Hide file tree

Showing 12 changed files with 65 additions and 27 deletions.
diff --git a/docs/examples/airship-battle.mdx b/docs/examples/airship-battle.mdx
@@ -26,7 +26,7 @@ Make the lava leak by destroying the obsidian blocks containing it and other obs
 Every map XML file starts with the XML header and then the base `<map>` module.
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <!-- Specifies what the map is called -->
 <name>Airship Battle</name>
 <!-- Shows the map creation date when a user runs /map in game -->

diff --git a/docs/examples/harb.mdx b/docs/examples/harb.mdx
@@ -20,7 +20,7 @@ _The large spawn island for harb, where players initially spawn at when the map
 Every map XML file starts with the XML header and then the base `<map>` module.
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <!-- Specifies what the map is called -->
 <name>Harb</name>
 <!-- Shows the map creation date when a user runs /map in game -->

diff --git a/docs/examples/ozone.mdx b/docs/examples/ozone.mdx
@@ -21,7 +21,7 @@ _This map was copied in 1/4th sections._
 Every map XML file starts with the XML header and then the base `<map>` module.
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <!-- Specifies what the map is called -->
 <name>Ozone FFA</name>
 <!-- States what version the map is -->

diff --git a/docs/examples/race-for-victory.mdx b/docs/examples/race-for-victory.mdx
@@ -31,11 +31,11 @@ to help their way back to base!_
 Every map XML file starts with the XML header and then the base `<map>` module.
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <!-- Specifies what the map is called -->
 <name>Race for Victory</name>
 <!-- States what version the map is -->
-<version>1.2.4</version>
+<version>1.2.5</version>
 <!-- Tells the teams what the objective is in order to win the game -->
 <objective>Take the enemy's wool located to either side of the enemy's base and place it in your victory monument.</objective>
 <!-- States who made the map -->
@@ -175,7 +175,7 @@ Define regions that can be later used to apply spawns, filters, etc.
     <!-- applicators -->
     <apply region="blue-wool-rooms" block="only-red" use="only-red"/>
     <apply region="blue-wool-rooms" enter="only-red" message="You may not enter your own wool room!"/>
-    <apply region="red-wool-rooms" block="only-blue" use="only-red"/>
+    <apply region="red-wool-rooms" block="only-blue" use="only-blue"/>
     <apply region="red-wool-rooms" enter="only-blue" message="You may not enter your own wool room!"/>
     <apply region="red-base" enter="only-red" message="You may not enter the enemy spawn!"/>
     <apply region="red-base" block="only-red"/>

diff --git a/docs/examples/the-fenland.mdx b/docs/examples/the-fenland.mdx
@@ -21,7 +21,7 @@ All players spawn with diamond pickaxes necessary to break them._
 Every map XML file starts with the XML header and then the base `<map>` module.
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <!-- Specifies what the map is called -->
 <name>The Fenland</name>
 <!-- Shows the map creation date when a user runs /map in game -->

diff --git a/docs/examples/warlock.mdx b/docs/examples/warlock.mdx
@@ -19,7 +19,7 @@ _The monument is obsidian protected by stone bricks and a wooden pressure plate
 Every map XML file starts with the XML header and then the base `<map>` module.
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <!-- Specifies what the map is called -->
 <name>Warlock</name>
 <!-- Shows the map creation date when a user runs /map in game -->

diff --git a/docs/guides/preparing/local-server-setup.mdx b/docs/guides/preparing/local-server-setup.mdx
@@ -285,7 +285,7 @@ map:
     # List of git repositories to load maps.
     # When using multiple GitHub repositories hosted by PGM networks, beware of duplicate maps.
      - uri: "https://github.com/PGMDev/Maps"
-      path: "sample-github-maps"
+       path: "sample-github-maps"
 
 # Experimental features that are not yet stable.
 experiments:

diff --git a/docs/guides/xml-pointers/conventions.mdx b/docs/guides/xml-pointers/conventions.mdx
@@ -11,7 +11,7 @@ Modules must all start on column one.
 This means that all children tags under the `<map>` tag must be aligned with said `<map>` tag.
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <name>Blocks DTC</name>
 <version>1.3.4</version>
 <objective>Leak lava from the enemy's obsidian core.</objective>
@@ -23,7 +23,7 @@ This means that all children tags under the `<map>` tag must be aligned with sai
 Modules that have sub elements such as the `author` tag must be indented with 4 spaces below the parent element.
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 ...
 <authors>
     <author uuid="060baa18-2852-40d8-afcb-e61607c04be3"/> <!-- PepsiDog -->
@@ -38,7 +38,7 @@ That means the end of one module should have the start of another on the immedia
 
 ```xml
 <!-- Correct -->
-<map proto="1.4.2">
+<map proto="1.5.0">
 <name>Blocks DTC</name>
 <version>1.3.4</version>
 <objective>Leak lava from the enemy's obsidian core.</objective>
@@ -47,7 +47,7 @@ That means the end of one module should have the start of another on the immedia
 
 ```xml
 <!-- Incorrect! -->
-<map proto="1.4.2">
+<map proto="1.5.0">
 
 <name>Blocks DTC</name>
 
@@ -90,7 +90,7 @@ Contributors are optional but are still to remain near the top of a XML file.
 :::
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <name>Blocks DTC</name>
 <version>1.3.4</version>
 <objective>Leak lava from the enemy's obsidian core.</objective>
@@ -105,10 +105,11 @@ Contributors are optional but are still to remain near the top of a XML file.
 
 ### The Protocol
 
-All maps should use the latest [protocol version](/docs/modules/general/proto). The proto version can be defined with this line:
+All maps should use the latest [protocol version](/docs/modules/general/proto).
+The proto version can be defined with this line:
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 ```
 
 ### Authors and Contributors

diff --git a/docs/modules/general/main.mdx b/docs/modules/general/main.mdx
@@ -41,7 +41,7 @@ The maps version should follow the versioning schema `major.minor.patch`.
 | `<gamemode>` | The gamemode(s) of this map. If this is not specified the map will set the gamemode(s) to whatever modules are used. | <span className="badge badge--primary">Gamemode ID</span> |
 
 ```xml
-<map proto="1.4.2">
+<map proto="1.5.0">
 <name>Map Name</name>
 <version>1.0.0</version>
 <objective>Short description about the map's objective.</objective>

diff --git a/docs/modules/general/proto.mdx b/docs/modules/general/proto.mdx
@@ -1,12 +1,11 @@
 ---
 id: proto
 title: Protocol Versions
-description: 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.
 toc_max_heading_level: 4
 ---
 
-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. 
+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](https://mcresourcepile.github.io).
@@ -21,12 +20,13 @@ Mapmakers should always use the latest supported proto version, and this may be
 
 | Attribute | Description | Value |
 |---|---|---|
-| `proto` | <span className="badge badge--danger">Required</span>The map XML's protocol version. | <span className="badge badge--success">Recommended</span>`1.4.2` |
+| `proto` | <span className="badge badge--danger">Required</span>The map XML's protocol version. | <span className="badge badge--success">Recommended</span>`1.5.0` |
 
 ##### Map Protocol Values
 
 | Version | Description |
 |---|---|
+| `1.5.0` | Refer to [Changes in 1.5.0](#changes-in-150). |
 | `1.4.2` | Refer to [Changes in 1.4.2](#changes-in-142). |
 | `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`).<br />Disallows `<time>` inside `<score>` or `<blitz>` &amp; disallows `<title>` inside `<blitz>`. |
@@ -42,10 +42,47 @@ Mapmakers should always use the latest supported proto version, and this may be
 ### Changes in 1.5.0
 
 :::note
-`1.5.0` is a upcoming protocol version that is currently in its planning stage and therefore, **not implemented**.
-If you would like to learn more or propose changes, please visit [PGM#1267 on the issue tracker](https://github.com/PGMDev/PGM/issues/1267).
+`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](https://github.com/PGMDev/PGM/issues).
 :::
 
+#### 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`.
+
+    ```xml
+    <!-- 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`.
+
+    ```xml
+    <!-- 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](/docs/modules/gear/kits#dynamic-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`.
+
+    ```xml
+    <!-- Sample proto 1.5.0 XML -->
+    <action untrigger-filter="always">
+    ```
+
 ### Changes in 1.4.2
 
 #### Breaking

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -125,7 +125,7 @@ const config = {
       announcementBar: {
         id: 'new_features',
         content:
-          'New Features: <a href="/docs/modules/mechanics/tracking-compass">Tracking Compass</a>, <a href="/docs/modules/gear/consumables">Consumables</a>, <a href="/docs/modules/general/main#map-variants">Map Variants</a>, and <a href="/docs/modules/general/main#constants">Constants</a>',
+          'New Features: <a href="/docs/modules/general/proto">Proto 1.5.0</a>, <a href="/docs/modules/mechanics/tracking-compass">Tracking Compass</a>, <a href="/docs/modules/gear/consumables">Consumables</a>, and <a href="/docs/modules/general/main#map-variants">Map Variants</a>',
         backgroundColor: '#fafbfc',
         textColor: '#091E42',
         isCloseable: true,

diff --git a/package-lock.json b/package-lock.json