Add new features and update examples throughout docs

Signed-off-by: TheRealPear <20259871+TheRealPear@users.noreply.github.com>
PGMDev · Jan 2, 2024 · 673e3db · 673e3db
1 parent d0d382f
commit 673e3db
Show file tree

Hide file tree

Showing 20 changed files with 191 additions and 144 deletions.
diff --git a/docs/examples/airship-battle.mdx b/docs/examples/airship-battle.mdx
@@ -62,7 +62,7 @@ Define the kit that players will receive.
 ```xml
 <kits>
     <kit id="spawn-protection">
-        <potion amplifier="10" duration="oo">damage resistance</potion>
+        <effect amplifier="10">damage resistance</effect>
         <knockback-reduction>1</knockback-reduction>
     </kit>
     <kit id="spawn">
@@ -133,57 +133,36 @@ These regions reference the filters defined above and states where they will wor
 <regions>
     <cuboid id="red-spawn-protect" min="-42,87,3" max="-35,90,-36"/>
     <cuboid id="blue-spawn-protect" min="12,87,3" max="19,90,-36"/>
+    <complement id="deny-obsidian-area">
+        <region id="map"/> <!-- Include the entire map (defined below) -->
+        <cuboid id="blue-core" min="13,85,23" max="18,92,30"/> <!-- Location of Blue's core -->
+        <cuboid id="red-core" min="-41,85,23" max="-36,92,30"/> <!-- Location of Red's core -->
+    </complement>
+    <negative id="not-map">
+        <union id="map">
+            <rectangle min="-100,-2" max="100,123"/> <!-- Main area -->
+            <rectangle min="-36,-14" max="13,-2"/> <!-- Area between spawn tunnels -->
+        </union>
+    </negative>
     <!-- applicators -->
     <apply region="blue-spawn-protect" lend-kit="spawn-protection" filter="only-blue"/>
     <apply region="red-spawn-protect" lend-kit="spawn-protection" filter="only-red"/>
-    <apply leave="never" message="Don't exit the playing field!">
-        <region>
-            <union>
-                <rectangle min="-102,-4" max="102,125"/> <!-- Main area -->
-                <rectangle min="-36,-16" max="13,-2"/> <!-- Area between spawn tunnels -->
-            </union>
-        </region>
-    </apply>
-    <apply block="never" message="Don't edit blocks outside the playing field!">
-        <region>
-            <negative>
-                <union id="map">
-                    <rectangle min="-100,-2" max="100,123"/> <!-- Main area -->
-                    <rectangle min="-36,-14" max="13,-2"/> <!-- Area between spawn tunnels -->
-                </union>
-            </negative>
-        </region>
-    </apply>
+    <apply region="map" leave="never" message="Don't exit the playing field!"/>
+    <apply region="not-map" block="never" message="Don't edit blocks outside the playing field!"/>
     <!-- Do not let players place or destroy dispenser blocks anywhere on the map -->
     <apply block="deny-dispenser" message="Dispensers are disabled on this map!"/>
     <!-- Only the obsidian that makes up the core can be broken -->
-    <apply block-break="deny-obsidian" message="You may not break obsidian outside the core area!">
-        <region>
-            <complement>
-                <region id="map"/>
-                <cuboid min="13,85,23" max="18,92,30"/>
-                <cuboid min="-41,85,23" max="-36,92,30"/>
-            </complement>
-        </region>
-    </apply>
+    <apply region="deny-obsidian-area" block-break="deny-obsidian" message="You may not break obsidian outside the core area!"/>
 </regions>
 ```
 
 [<i className="icon-right">➡️</i>](/docs/modules/objectives/dtc)
-This specifies what material the core is made of, who each core belongs to, and how far the lava needs to leak.
+This specifies what material the core is made of, who each core belongs to, where each cores are located, and how far the lava must leak to count as a completed objective.
 
 ```xml
 <cores material="obsidian" leak="10">
-    <core team="blue-team">
-        <region>
-            <cuboid min="13,85,23" max="18,92,30"/>
-        </region>
-    </core>
-    <core team="red-team">
-        <region>
-            <cuboid min="-41,85,23" max="-36,92,30"/>
-        </region>
-    </core>
+    <core team="blue-team" region="blue-core"/>
+    <core team="red-team" region="red-core"/>
 </cores>
 ```
 
@@ -212,7 +191,7 @@ We do not want an excessive amount of items dropped on the map, so this allows u
     <item>gold block</item>
     <item>bucket</item>
     <item>water bucket</item>
-	<item>golden apple</item>
+    <item>golden apple</item>
 </itemremove>
 ```
 

diff --git a/docs/examples/harb.mdx b/docs/examples/harb.mdx
@@ -23,8 +23,10 @@ Every map XML file starts with the XML header and then the base `<map>` module.
 <map proto="1.4.2">
 <!-- Specifies what the map is called -->
 <name>Harb</name>
+<!-- Shows the map creation date when a user runs /map in game -->
+<created>2012-03-02</created>
 <!-- States what version the map is -->
-<version>1.3.13</version>
+<version>1.3.14</version>
 <!-- Tells the teams what the objective is in order to win the game -->
 <objective>Be the team with the least amount of deaths after 10 minutes.</objective>
 <!-- States who made the map -->
@@ -67,9 +69,9 @@ Define the kit that players will receive.
             <enchantment level="3">protection projectile</enchantment>
         </leggings>
         <boots unbreakable="true" material="iron boots"/>
-        <potion duration="6s">heal</potion>
-        <potion duration="6s">damage resistance</potion>
-        <potion>speed</potion>
+        <effect duration="6s">heal</effect>
+        <effect duration="6s">damage resistance</effect>
+        <effect>speed</effect>
     </kit>
 </kits>
 ```

diff --git a/docs/examples/race-for-victory.mdx b/docs/examples/race-for-victory.mdx
@@ -151,8 +151,8 @@ Define regions that can be later used to apply spawns, filters, etc.
     </union>
     <!-- This is the inverse of the rectangle region (everything outside of the rectangle) -->
     <union id="map-protection">
-        <negative>
-            <rectangle min="-57,-123" max="57,123"/>
+        <negative id="not-map">
+            <rectangle id="map" min="-57,-123" max="57,123"/>
         </negative>
         <cylinder base="0,67,-110" height="4" radius="3"/>
         <cylinder base="0,67,110" height="4" radius="3"/>

diff --git a/docs/examples/the-fenland.mdx b/docs/examples/the-fenland.mdx
@@ -24,6 +24,8 @@ Every map XML file starts with the XML header and then the base `<map>` module.
 <map proto="1.4.2">
 <!-- Specifies what the map is called -->
 <name>The Fenland</name>
+<!-- Shows the map creation date when a user runs /map in game -->
+<created>2013-08-01</created>
 <!-- States what version the map is -->
 <version>1.2.11</version>
 <!-- Tells the teams what the objective is in order to win the game -->

diff --git a/docs/examples/warlock.mdx b/docs/examples/warlock.mdx
@@ -22,8 +22,10 @@ Every map XML file starts with the XML header and then the base `<map>` module.
 <map proto="1.4.2">
 <!-- Specifies what the map is called -->
 <name>Warlock</name>
+<!-- Shows the map creation date when a user runs /map in game -->
+<created>2012-08-29</created>
 <!-- States what version the map is -->
-<version>1.3.11</version>
+<version>1.3.12</version>
 <!-- Tells the teams what the objective is in order to win the game -->
 <objective>Break the obsidian from the enemy team's monument.</objective>
 <!-- States who made the map -->
@@ -225,7 +227,7 @@ We can make special kill rewards for players that fit certain criteria.
         <item material="gold nugget"/>
         <item material="golden apple"/>
     </kill-reward>
-    <!-- Players that kill two enemies in a row will get four ink sacks -->
+    <!-- Players that kill two enemies in a row will get a Lapis Lazuli (represented as ink sack with damage value of 4) -->
     <kill-reward>
         <filter>
             <kill-streak count="2" repeat="true"/>

diff --git a/docs/modules/blocks/structures.mdx b/docs/modules/blocks/structures.mdx
@@ -47,7 +47,7 @@ Structures are a very powerful feature that can be used to implement an endless
   | `id` | Unique identifier used to reference this dynamic from other places in the XML. | <span className="badge badge--primary">String</span> |
   | `structure` | The `id` of the structure to place. | [Structure ID](#structure-attributes) |
   | `filter` | <span className="badge badge--secondary" title="Can be either this attribute or a sub-element.">Property</span>Filter used to determine when a structure is *placed* when `trigger` allows. | [Filter](/docs/modules/mechanics/filters) | `always` *(structure is permanently placed)* |
-  | `trigger` | <span className="badge badge--secondary" title="Can be either this attribute or a sub-element.">Property</span>Dynamic filter which triggers placement and clearing of structures. | [Dynamic Filter](/docs/modules/mechanics/filters#dynamic-filters) |
+  | `trigger` | <span className="badge badge--secondary" title="Can be either this attribute or a sub-element.">Property</span><span className="badge badge--danger">Required</span>Dynamic filter which triggers placement and clearing of structures. | [Dynamic Filter](/docs/modules/mechanics/filters#dynamic-filters) |
   | `location` | The location to place the structure at. The structure's `origin` will be at this point.<br />*Mutually exclusive with `offset`.* | <span className="badge badge--primary">X,Y,Z</span> |
   | `offset` | Relative position to place the structure at. The structure will be translated by this amount from its original location.<br />*Mutually exclusive with `location`.* | <span className="badge badge--primary">X,Y,Z</span> | `0,0,0` *(structure placed at its original location)* |
 </div>
@@ -76,7 +76,7 @@ Structures are a very powerful feature that can be used to implement an endless
     <!-- The bridge will appear 128 blocks directly below it's original location -->
     <dynamic structure="blue-bridge" offset="0,-128,0">
         <filter>
-            <objective team="blue-team">hill</objective>
+            <captured team="blue-team">hill</captured>
         </filter>
     </dynamic>
 

diff --git a/docs/modules/gear/classes.mdx b/docs/modules/gear/classes.mdx
@@ -44,13 +44,22 @@ Players can then change their class in game with the `/class` command.
 
 ```xml
 <classes family="ghost" sticky="true">
+    <!-- This is the default, so players will join with this unless they change class. -->
     <class name="Demon" default="true" description="Smoke and Fire!" icon="fireball">
         <kit>
-            <effect duration="oo" amplifier="2" ambient="true">damage resistance</effect>
-            <effect duration="oo" amplifier="1" ambient="true">speed</effect>
+            <effect amplifier="2" ambient="true">damage resistance</effect>
+            <effect ambient="true">speed</effect>
             <item slot="8" amount="16" material="cooked beef"/>
             <item slot="1" amount="5" name="`3Grenade" grenade="true" material="ender pearl"/>
         </kit>
     </class>
+    <!-- The second class is Pyro, players can select this before joining or changing in game with /class. -->
+    <class name="Pyro" description="Light players on fire!" icon="flint and steel">
+        <kit>
+            <item slot="0" enchantment="fire aspect" name="`6Fire Stick" material="blaze rod"/>
+            <item slot="1" enchantment="arrow fire" name="`6Fire Bow" unbreakable="true" material="bow"/>
+            <item slot="7" amount="10" material="arrow"/>
+        </kit>
+    </class>
 </classes>
 ```
diff --git a/docs/modules/gear/items.mdx b/docs/modules/gear/items.mdx
@@ -147,8 +147,10 @@ This helps simplfy kits so a seperate team kit for colored armor and items is no
 
 ```xml
 <kits>
-    <kit id="spawn" force="true">
-        <!-- automatically applies blue colored armor to blue team, red armor to red team, etc -->
+    <kit id="spawn-kit">
+        <!-- automatically applies blue stained clay to blue team, red stained clay to red team, etc -->
+        <item slot="0" amount="64" team-color="true" material="stained clay"/>
+        <!-- automatically applies blue armor to blue team, red armor to red team, etc -->
         <helmet team-color="true" unbreakable="true" material="leather helmet"/>
         <chestplate team-color="true" unbreakable="true" material="leather chestplate"/>
     </kit>

diff --git a/docs/modules/gear/kill-rewards.mdx b/docs/modules/gear/kill-rewards.mdx
@@ -1,16 +1,17 @@
 ---
 id: kill-rewards
 title: Kill Rewards
+toc_max_heading_level: 4
 ---
 
 The Kill Rewards module allows players to get items or a kit when they kill a player.
 A kill reward can contain either individual items, kits or references to kits.
 The reward can optionally filter which players are eligible to receive the reward, or when/where the reward is active.
 
 This module can, for example, be used to give upgrades to players by giving them gold ingots.
-Then, once they have collected enough ingots, they can craft armor, purchase items from a shop, etc.
+Then, once they have collected enough ingots, they can craft armor, purchase items from a [shop](/docs/modules/gear/shops), or use the ingots as [redeemables](/docs/modules/objectives/scoring#redeemables) for a scorebox, etc.
 
-#### Kill Rewards Element
+##### Kill Rewards Element
 
 <div className="table-container">
   | Element | Description | Value/Children |
@@ -22,27 +23,32 @@ Then, once they have collected enough ingots, they can craft armor, purchase ite
   | `<kill-reward> </kill-reward>` | A single kill reward. | <span className="badge badge--secondary">Kill Reward Sub-elements</span> |
 </div>
 
-#### Kill Reward Attributes
+##### Kill Reward Attributes
 
 <div className="table-container">
   | Attribute | Description | Value/Children |
   |---|---|---|
   | `filter` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>Filter who can claim this reward and when. | [Filter](/docs/modules/mechanics/filters) |
   | `kit` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>The kit to give players as the kill reward. | [Kit ID](/docs/modules/gear/kits) |
+  | `action` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>Run the specified action as the kill reward. | [Action ID](/docs/modules/mechanics/actions-triggers) |
+  | `victim-action` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>Run the specified action on the victim instead of the attacker. | [Action ID](/docs/modules/mechanics/actions-triggers) |
 </div>
 
-#### Kill Reward Sub-elements
+##### Kill Reward Sub-elements
 
 <div className="table-container">
   | Element | Description | Value/Children |
   |---|---|---|
   | `<item>` | Individual items given as a kill reward. | [Item](/docs/modules/gear/items) |
   | `<filter>` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>Filter who can claim this reward and when. | [Filter](/docs/modules/mechanics/filters) |
-  | `<kit>` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>The kit to give players as the kill reward. | [Kit ID](/docs/modules/gear/kits) |
+  | `<kit>` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>The kit to give players as the kill reward. | [Kit](/docs/modules/gear/kits) |
+  | `<action>` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>The action to run as the kill reward. | [Action](/docs/modules/mechanics/actions-triggers) |
+  | `<victim-action>` | <span className="badge badge--secondary" title="Can be either this sub-element or an attribute.">Property</span>The action to run on the victim. | [Action](/docs/modules/mechanics/actions-triggers) |
 </div>
 
-### Examples
+## Examples
 
+#### Kill rewards with filters
 ```xml
 <kill-rewards>
     <!-- Give two emeralds for all kills -->
@@ -63,12 +69,12 @@ Then, once they have collected enough ingots, they can craft armor, purchase ite
 </kill-rewards>
 ```
 
-Kill rewards with kits
-
+#### Kill rewards with kits
 ```xml
 <kill-rewards>
+    <!-- Give the player an iron helmet, iron helmet, and Speed II effect -->
     <kill-reward>
-        <kit>
+        <kit force="true">
             <item slot="0" material="iron sword"/>
             <helmet material="iron helmet"/>
             <effect amplifier="2">speed</effect>
@@ -84,3 +90,22 @@ Kill rewards with kits
     </kill-reward>
 </kill-rewards>
 ```
+
+#### Kill rewards with actions
+```xml
+<kill-rewards>
+    <!-- Runs "some-action" on the victim whenever they are killed by a member of red team -->
+    <kill-reward filter="red-team" victim-action="some-action"/>
+
+    <!-- Kits and actions defined as references -->
+    <kill-reward action="some-kit" /> <!-- Kits are a type of action, so they can be used as an action -->
+    <kill-reward action="some-action"/>
+
+    <!-- Inline defined actions -->
+    <kill-reward>
+        <action>
+            <set var="some_variable" value="1"/>
+        </action>
+    </kill-reward>
+</kill-rewards>
+```
diff --git a/docs/modules/gear/kits.mdx b/docs/modules/gear/kits.mdx
@@ -31,7 +31,7 @@ Removable kits will be noted in the documentation where applicable.
   | `id` | Unique identifier used to reference this kit from other places in the XML. | <span className="badge badge--primary">String</span> |
   | `filter` | <span className="badge badge--secondary" title="Can be either this attribute or a sub-element.">Property</span>Filter when this kit is used. | [Filter](/docs/modules/mechanics/filters) |
   | `parents` | The kit's parent or a comma separated list of parent kits. | <span className="badge badge--primary">String</span> |
-  | `force` | Force apply the kit. | <span className="badge badge--primary">true/false</span> |
+  | `force` | Force apply the kit, which will override existing items in certain slots. | <span className="badge badge--primary">true/false</span> |
   | `overflow-warning` | Warn the player when the kit cannot give the player all of it's items.<br />*Defaults to standard translatable message* | <span className="badge badge--primary">String</span> |
   | `repair-tools` | Repairs tools in the player's inventory with those given in the kit. | <span className="badge badge--primary">true/false</span> | true |
   | `deduct-tools` | Deducts the toolrepair given in the kit by the toolrepair in the player's inventory. | <span className="badge badge--primary">true/false</span> | true |
@@ -95,7 +95,7 @@ You can also clear the player's entire inventory before applying the kit by usin
 
 ```xml
 <kit id="ender" reset-ender-pearls="true">
-    <item slot="0" amount="1" material="ender pearl"/>
+    <item slot="0" amount="4" material="ender pearl"/>
     <!-- clears items and armor slots by default -->
     <clear/>
 </kit>
@@ -373,9 +373,9 @@ If no attributes are specified, `can-fly` defaults to true.
 
 ```xml
 <kit id="fly">
-    <fly/>                 <!-- Allow player to fly -->
-    <fly can-fly="false"/> <!-- Don't allow player to fly -->
-    <fly flying="true"/>   <!-- Make the player fly right away -->
-    <fly flying="false"/>  <!-- Make the player stop flying right away -->
+    <fly/> <!-- Allow player to fly -->
+    <fly can-fly="false"/> <!-- Do not allow player to fly -->
+    <fly flying="true"/> <!-- Make the player fly right away -->
+    <fly flying="false"/> <!-- Make the player stop flying right away -->
 </kit>
 ```
diff --git a/docs/modules/gear/projectiles.mdx b/docs/modules/gear/projectiles.mdx
@@ -47,7 +47,7 @@ or the item form of the custom projectile itself.
 </div>
 
 ```xml
-<!-- Create the projectile "template" -->
+<!-- Create the projectile "lazer" -->
 <projectiles>
     <projectile
         id="lazer"
@@ -60,7 +60,7 @@ or the item form of the custom projectile itself.
 </projectiles>
 <!-- Apply the projectile to an item -->
 <kits>
-    <kit name="lazer-kit">
+    <kit id="lazer-kit">
         <item projectile="lazer" name="`alazer gun" material="stick"/>
     </kit>
 </kits>