Document tracking compass modules & more (PGMDev#123)

Signed-off-by: Pear <20259871+TheRealPear@users.noreply.github.com>

docs/commands/community.mdx

@@ -1,6 +1,7 @@
 ---
 id: community
 title: Community Commands
+hide_table_of_contents: true
 ---
 
 This page describes a list of commands, aliases, and permissions for [Community](https://github.com/PGMDev/Community/), a standalone plugin for managing PGM servers. 

docs/commands/events.mdx

@@ -1,6 +1,7 @@
 ---
 id: events
 title: Events Commands
+hide_table_of_contents: true
 ---
 
 This page describes a list of commands, aliases, and permissions for the [Events](https://github.com/PGMDev/Events) plugin.

docs/commands/main.mdx

@@ -1,6 +1,7 @@
 ---
 id: main
 title: PGM Commands
+hide_table_of_contents: true
 ---
 
 This page describes a list of PGM commands, aliases, and permissions.
@@ -13,16 +14,20 @@ Permissions are prefixed with `Permissions` (i.e. `Permissions.ADMINCHAT`).
   | `/action list` | actions list<br />actions page | Inspect variables for a player. | -q query<br />-a all | [page] | `GAMEPLAY` |
   | `/action trigger` | actions trigger | Trigger a specific action. || [action] | `GAMEPLAY` |
   | `/action untrigger` | actions untrigger | Untrigger a specific action. || [action] | `GAMEPLAY` |
+  | `/filter` || Match a filter against a player. || [filter] [target] | `DEBUG` |
   | `/mode push` || Reschedule all unconditional objective modes. || [time] | `GAMEPLAY` |
   | `/mode start` || Starts an objective mode. || [mode number] [time] | `GAMEPLAY` |
   | `/team alias` || Rename a team. || [old team name] [new team name] | `GAMEPLAY` |
   | `/timelimit` | tl | Start a time limit. | -r result (can be `default`, `objectives`, `tie`, or name of team) | [duration] [result] [overtime] [max-overtime] | `GAMEPLAY` |
-  | `/join` | play | Join the match. | -f force | [team] – defaults to random | `JOIN` |
+  | `/join` | play | Join the match. | -f force | [team] - defaults to random | `JOIN` |
   | `/team force` || Force a player onto a team. ||| `JOIN_FORCE` |
-  | `/team shuffle` || Shuffle players among the teams. || -a all -f force | `JOIN_FORCE` |
+  | `/team shuffle` || Shuffle players among the teams. | -a all<br />-f force || `JOIN_FORCE` |
   | `/leave` | obs | Leave the match. ||| `LEAVE` |
   | `/loadnewmaps` | findnewmaps<br />new<br />maps | Load new maps. | -f force || `RELOAD` |
-  | `/pgm` || Reload the configuration. ||| `RELOAD` |
+  | `/showxml` || Open a file editor with the map's XML on the server side.<br />**Note:** This command is only available for locally hosted servers with a desktop environment. || [map name] |
+  | `/pgm reload` || Reload the configuration. ||| `RELOAD` |
+  | `/pgm help` || View available PGM commands. ||| `RELOAD` |
+  | `/pgm confirm` || Execute any pending commands. ||| `RELOAD` |
   | `/ffa min` || Set the minimum players. || [reset &#124; min-players] | `RESIZE` |
   | `/ffa size` || Set the maximum players. || [reset &#124; max-players] (max-overfill) | `RESIZE` |
   | `/team min` || Set the minimum players on a team. || [team] (reset &#124; min-players) | `RESIZE` |
@@ -46,9 +51,9 @@ Permissions are prefixed with `Permissions` (i.e. `Permissions.ADMINCHAT`).
   | `/class` | selectclass<br />c<br />cl | Selects your class. |
   | `/classlist` | classes<br />listclasses<br />cls | List all available classes. |
   | `/g` | all<br />! (*do not use forward slash*) | Send a message to everyone. || [message] |
-  | `/inventory` | inv<br />vi | View a player’s inventory. |
+  | `/inventory` | inv<br />vi | View a player's inventory. |
   | `/list` | who<br />online<br />ls | View a list of online players. |
-  | `/map` | mapinfo | Show info about a map. || [map name] – defaults to current map |
+  | `/map` | mapinfo | Show info about a map. || [map name] - defaults to current map |
   | `/maps` | maplist<br />ml | List all loaded maps. | -a author<br />-t tag1,tag2<br />-n name |
   | `/match` | matchinfo | Show the match info. |
   | `/mode list` | page | List all objective modes. || [page] |

docs/modules/environment/world.mdx

@@ -6,22 +6,24 @@ description: You can use these world and terrain modules to have a finer control
 
 ### Build Height
 
-A world's maximum build height can be set using the `maxbuildheight` element. Once a player tries to build past the set maximum build height, they will be prompted with a message stating that they can not build past the playing field.
+A world's maximum build height can be set using the `maxbuildheight` element.
+Once a player tries to build past the set maximum build height, they will be prompted with a message stating that they can not build past the playing field.
 
 ```xml
 <maxbuildheight>64</maxbuildheight>
 ```
 
 ### Terrain
 
-A world's terrain generator can be modified to use a specific seed, world and/or whether the vanilla chunk generator is used. By default a new random seed is generated for each match, unless one is specified in the seed attribute.
+A world's terrain generator can be modified to use a specific seed, world and/or whether the vanilla chunk generator is used. 
+By default a new random seed is generated for each match, unless one is specified in the seed attribute.
 
 When using the vanilla generator, the default Minecraft terrain generator will be used instead of generating null chunks.
-The specific world generation rules such as flat worlds, etc., can be changed by editing the world's `level.dat` file with a NBT editor. The `RandomSeed` value in the level data file is not used.
+The specific world generation rules such as flat worlds, etc., can be changed by editing the world's `level.dat` file with a NBT editor.
+The `RandomSeed` value in the level data file is not used.
 
-Any chunks not in the world's `region/` folder will be generated according to the Minecraft chunk generation rules. This means that only the terrain that you have modified needs to be saved with the world.
-
-The `world=""` attribute is used to specify the sub-folder that contains the map's `region/` and `level.dat` files.
+Any chunks not in the world's `region/` folder will be generated according to the Minecraft chunk generation rules.
+This means that only the terrain that you have modified needs to be saved with the world.
 
 <div className="table-container">
   | Element | Description |
@@ -34,22 +36,18 @@ The `world=""` attribute is used to specify the sub-folder that contains the map
 <div className="table-container">
   | Attribute | Description | Value | Default |
   |---|---|---|---|
-  | `world` | The level data sub-folder to be used with this map. | <span className="badge badge--primary">Sub-folder Name</span> |
   | `vanilla` | Specify if this world is uses the vanilla or null chunk generator. | <span className="badge badge--primary">true/false</span> | false |
-  | `seed` | This world's generation seed. | <span className="badge badge--primary">String</span> |
-  | `pre-match-physics` | Allow physics events, such as water flowing, before the match starts. | <span className="badge badge--primary">true/false</span> | false |
+  | `seed` | The world's seed that determines how the world is generated. | <span className="badge badge--primary">String</span> |
+  | `environment` | The world's dimension type.<br />**Note:** Worlds with `the end` environment are not supported. | `normal`<br />`nether` | `normal` |
+  | `pre-match-physics` | <span className="badge badge--danger" title="This feature once existed, but has not been re-implemented in modern versions of PGM.">N/A</span>Allow physics events, such as water flowing, before the match starts. | <span className="badge badge--primary">true/false</span> | false |
 </div>
 
 ```xml
+<!-- Make a vanilla world with the seed 'qwerty' -->
 <terrain vanilla="true" seed="qwerty"/>
 
-<!-- Christmas world conditional -->
-<if christmas="true">
-    <terrain world="christmas"/>
-</if>
-<if christmas="false">
-    <terrain world="normal"/>
-</if>
+<!-- Make the world Nether-like. The 'region' folder must be renamed to 'DIM-1' for this to work. -->
+<terrain environment="nether"/>
 ```
 
 ### Internal Maps

docs/modules/gear/consumables.mdx

@@ -25,15 +25,31 @@ When consumed, these items can trigger [actions](/docs/modules/mechanics/actions
   | Attribute | Description | Value | Default |
   |---|---|---|---|
   | `id` | <span className="badge badge--danger">Required</span>Unique identifier used to reference this consumable from other places in the XML. | <span className="badge badge--primary">String</span> |
-  | `action`&#124;`kit` | <span className="badge badge--danger">Required</span>Run the specified action upon consumption. | [Action ID](/docs/modules/mechanics/actions-triggers) |
-  | `on` | <span className="badge badge--danger">Required</span>Specify how the consumable should be used.<br />**Note:** The only action currently supported is `eat`. In the future, more actions such as clicking will be supported. | `eat` |
-  | `override` | Consumable is affected by vanilla behaviors, such as giving the player potion effects.<br />*This is useful when using potion bottles and golden apples as the consumable item.* | <span className="badge badge--primary">true/false</span> | true |
+  | `action` | <span className="badge badge--danger">Required</span>Run the specified action upon consumption. | [Action ID](/docs/modules/mechanics/actions-triggers) |
+  | `on` | <span className="badge badge--danger">Required</span>Specify how the consumable should be used. | `eat`<br />`right click`<br />`left click`<br />`click` (both) |
+  | `override` | The consumable is affected by vanilla behaviors, such as giving the player potion effects.<br />*This is useful when using potion bottles and golden apples as the consumable item.* | <span className="badge badge--primary">true/false</span> | true |
+  | `consume` | PGM will consume the item once per use for the user.<br />**Note:** This attribute is ignored if the value of `on` attribute is `eat`. | <span className="badge badge--primary">true/false</span> | [*](#override--consume-behavior) |
+</div>
+
+### Override & Consume Behavior
+Some combinations of `override` and `consume` values can lead to unexpected behaviors involving either
+the user's client or PGM itself. This chart outlines the expected vanilla behavior for each configuration.
+
+<div className="table-container">
+  | Override | Consume | Vanilla Behavior | Result |
+  |---|---|---|---|
+  | `false` | `false` | No consume (e.g.: stick) | <span className="badge badge--success">Optimal</span>0 used |
+  | `false` | `false` | Consumes (e.g.: snowball) | <span className="badge badge--warning">Sub-optimal</span>1 used |
+  | `false` | `true` | No consume (e.g.: stick) | <span className="badge badge--success">Optimal</span>1 used |
+  | `false` | `true` | Consumes (e.g.: snowball) | <span className="badge badge--danger">Invalid</span>2 used |
+  | `true` | `false` | Any case | <span className="badge badge--success">Optimal</span>0 used |
+  | `true` | `true` | Any case | <span className="badge badge--success">Optimal</span>1 used |
 </div>
 
 ### Examples
 
 ```xml
-<!-- Create the consumable "template" -->
+<!-- Create the consumable "porkchop-that-says-yum" -->
 <consumables>
     <consumable id="porkchop-that-says-yum" action="say-yum" on="eat" override="false"/>
 </consumables>
@@ -50,9 +66,9 @@ When consumed, these items can trigger [actions](/docs/modules/mechanics/actions
 ```
 
 ```xml
-<!-- Create the consumable "template" -->
+<!-- Create the consumable "fast-apple" -->
 <consumables>
-    <consumable id="fast-apple" kit="speed-kit" on="eat"/>
+    <consumable id="fast-apple" action="speed-kit" on="eat"/>
 </consumables>
 <kits>
     <!-- Apply the consumable to an item -->
@@ -65,3 +81,22 @@ When consumed, these items can trigger [actions](/docs/modules/mechanics/actions
     </kit>
 </kits>
 ```
+
+```xml
+<!-- Create the consumable "heal" -->
+<!-- When the healing stick is right clicked, it is "consumed" and applies the
+heal-click action (kit) that sets the player's health back to 20 -->
+<consumables>
+    <consumable id="heal" action="heal-click" on="click" override="true" consume="true"/>
+</consumables>
+<kits>
+    <!-- Apply the consumable to an item -->
+    <kit id="spawn-kit">
+        <item material="stick" consumable="heal" name="Healing stick!"/>
+    </kit>
+    <!-- Define the kit the consumable gives you -->
+    <kit id="heal-click">
+        <health>20</health>
+    </kit>
+</kits>
+```

docs/modules/gear/items.mdx

@@ -43,7 +43,7 @@ or on the [bukkit docs - Material](https://hub.spigotmc.org/javadocs/bukkit/org/
   | `name` | The item's display name that appears when it is selected. | <span className="badge badge--primary">Formatted Text</span> |
   | `lore` | Custom text that appears when a player hovers over the item in their inventory. | <span className="badge badge--primary">Formatted Text</span> |
   | `color` | Leather armor color as a hexadecimal color. `RRGGBB`<br />*Only applies to leather armor items.* | <span className="badge badge--primary">Hex Color</span> |
-  | `team-color` | Automatically applies the team's [Dye Color](/docs/modules/format/teams#team-attributes) to colored blocks *(wool, stained glass, etc)*. | <span className="badge badge--primary">true/false</span> | false |
+  | `team-color` | Automatically applies the team's [Dye Color](/docs/modules/format/teams#team-attributes) to colored blocks *(wool, stained glass, banner, etc)*. | <span className="badge badge--primary">true/false</span> | false |
   | `grenade` | Projectile explodes on impact.<br />*Works with ender pearls, snowballs, eggs, and arrows.* | <span className="badge badge--primary">true/false</span> | false |
   | `grenade-power` | The power of the grenade explosion on impact. | <span className="badge badge--primary">Decimal</span> | 1.0 |
   | `grenade-fire` | Toggle if grenade explosion creates fire. | <span className="badge badge--primary">true/false</span> | false |

docs/modules/gear/repair-remove-keep.mdx

@@ -20,7 +20,7 @@ Repairing arrows instead of removing them has the advantage of the player being
   |---|---|
   | `<toolrepair> </toolrepair>` | A node containing all the tools that will be repaired when picked up. |
 
-  | Sub-elements | | Value/Children |
+  | Sub-elements | | Value |
   |---|---|---|
   | `<tool> </tool>` | A single tool that will be repaired, can be anything with durability. | [Material Name](/docs/reference/items/inventory#material-matchers) |
 </div>
@@ -43,7 +43,7 @@ Defines items that will be deleted when dropped on the map. Also works when item
   |---|---|
   | `<itemremove> </itemremove>` | A node containing all the items that will be removed when dropped. |
 
-  | Sub-elements | | Value/Children |
+  | Sub-elements | | Value |
   |---|---|---|
   | `<item> </item>` | The item that will be removed when dropped. | [Material Name](/docs/reference/items/inventory#material-matchers) |
 </div>
@@ -69,7 +69,7 @@ If there is a spawn kit, kept items will be given back *after* the kit is applie
   |---|---|
   | `<itemkeep> </itemkeep>` | A node containing all the items kept when respawning. |
 
-  | Sub-elements | | Value/Children |
+  | Sub-elements | | Value |
   |---|---|---|
   | `<item> </item>` | The item that will remain in a player's inventory when they die and respawn. | [Material Name](/docs/reference/items/inventory#material-matchers) |
 </div>