Add new features and update examples throughout docs (#114)

Signed-off-by: TheRealPear <20259871+TheRealPear@users.noreply.github.com>
PGMDev · Feb 23, 2024 · b4a082e · b4a082e
1 parent d0d382f
commit b4a082e
Show file tree

Hide file tree

Showing 23 changed files with 339 additions and 168 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,37 @@ 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"/>
+    <!-- Subtracts successive regions (blue-core and red-core) from the first region (map) -->
+    <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 +192,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/guides/xml-pointers/conventions.mdx b/docs/guides/xml-pointers/conventions.mdx
@@ -24,6 +24,7 @@ Modules that have sub elements such as the `author` tag must be indented with 4
 
 ```xml
 <map proto="1.4.2">
+...
 <authors>
     <author uuid="060baa18-2852-40d8-afcb-e61607c04be3"/> <!-- PepsiDog -->
 </authors>
@@ -85,7 +86,7 @@ There are 6 modules that make up the maps definition.
 They should all be placed at the top of the document; following the order below: `map`, `name`, `version`, `objective`, `authors` and `contributors`.
 
 :::note
-Contributors are optional but are still to remain at the top.
+Contributors are optional but are still to remain near the top of a XML file.
 :::
 
 ```xml
@@ -135,6 +136,7 @@ A Minor is classified by the addition of changes that affect gameplay but not to
 A Patch is classified by a small change to fix a bug or unintentional feature.
 
 ```xml
+<!-- Major.Minor.Patch -->
 <version>1.2.3</version>
 ```
 
@@ -152,18 +154,24 @@ Objectives are short and concise statements that tell the player what they need
 
 ### Identification Naming
 
-Modules that require an `id` to be defined should be named in all lowercase and use a `-` dash to signify a space.
+Modules that require an `id` to be defined should be named in all lowercase and use a dash (`-`) to signify a space.
+
+One exception to this is that [variable](/docs/modules/mechanics/variables) ids cannot use a dash (`-`) and instead must use underscores (`_`) to signify a space.
 
 ```xml
 <team id="only-blue">blue-team</team>
+
+<!-- Variables -->
+<variable id="cant-do-this"/>
+<variable id="do_this_instead"/>
 ```
 ### Team Filters
 
-Team filters should be named by following the Identification naming and start with `only-` followed by the team name.
+Team filters should be named by following the identification naming and start with `only-` followed by the team name.
 
 `only-blue` `only-elves`
 
 ### Enumeration Naming
 
-Bukkit names should be set into lower case with `_` underscores replaced with spaces.
-For example, `PROTECTION_ENVIRONMENTAL` should become `protection environmental`.
+Bukkit names should be set into lower case with underscores (`_`) replaced with spaces.
+For example, `PROTECTION_ENVIRONMENTAL` should be `protection environmental`.
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>
+```