Document tracking compass modules & more

Signed-off-by: Pear <[email protected]>

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/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/general/main.mdx

@@ -34,16 +34,16 @@ The maps version should follow the versioning schema `major.minor.patch`.
   | Element | Description | Value/Children | Default |
   |---|---|---|---|
   | `<name>` | <span className="badge badge--danger">Required</span>The name of the map. | <span className="badge badge--primary">String</span> |
-  | `<slug>` | The map's slug, usually auto generated from the map's name. This should only be used when a map is renamed to retain the map's ratings, etc.<br />*Valid slugs are lowercase and only contain the characters:* `a-z 0-9 _` | <span className="badge badge--primary">String</span> | <span className="badge badge--secondary">Auto Generated</span> |
-  | `<version>` | <span className="badge badge--danger">Required</span>The map's [semantic version](https://semver.org/) string. | `1.0.0` |
+  | `<slug>` | The map's internal identifier, usually auto generated from the map's name. This should only be used when a map is renamed to retain the map's ratings, etc.<br />*Valid slugs are lowercase and only contain the characters:* `a-z 0-9 _` | <span className="badge badge--primary">String</span> | <span className="badge badge--secondary">Auto Generated</span> |
+  | `<version>` | <span className="badge badge--danger">Required</span>The map's [semantic version](https://semver.org/). | `1.0.0` |
   | `<objective>` | <span className="badge badge--danger">Required</span>The map's objective, shown at the start of the match. | <span className="badge badge--primary">String</span> |
-  | `<authors>` | <span className="badge badge--danger">Required</span>The authors of the map, at least one author is required. | `<author>` |
+  | `<authors>` | <span className="badge badge--danger">Required</span>The authors of the map. At least one author is required. | `<author>` |
   | `<contributors>` | Contributors to the map. | `<contributor>` |
   | `<created>` | The date on which this map was initially released. | `YYYY-MM-DD` |
-  | `<phase>` | The phase of this map.<br />**Note:** By default, it will not appear in the list when a user runs /maps. In legacy PGM, only maps with production and standard show up on a website configured with an API. | `development`<br />`production` | `production` |
-  | `<edition>` | The edition of this map, describing which servers it should run on. | `standard`<br />`ranked`<br />`tournament` | `standard` |
-  | `<game>` | A custom title for this match's gamemode. | <span className="badge badge--primary">String</span> |
-  | `<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> |
+  | `<phase>` | The stage of development the map is in.<br />**Note:** By default, it will not appear in the list when a user runs `/maps`. In legacy PGM, only maps in production phase show up on a website configured with an API. | `development`<br />`staging`<br />`production` | `production` |
+  | `<edition>` | The type of gameplay environment this map is intended for.<br />**Note:** In legacy PGM, only standard edition maps show up on a website configured with an API. | `standard`<br />`ranked`<br />`tournament` | `standard` |
+  | `<game>` | A custom title for this match's gamemode.<br />**Note:** A map can have multiple gamemode titles. PGM will select the last as the map's primary title. | <span className="badge badge--primary">String</span> |
+  | `<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> |
 </div>
 
 ```xml
@@ -66,7 +66,7 @@ There can be multiple authors and contributors to a map.
 The contribution attribute should be used to specify what their contribution to the map was.
 
 A player's name should **not** be used to credit them, instead their UUID should be used. 
-A UUID is a unique user identifier that is used to keep track of players even if they change their name. 
+A UUID is a universally unique identifier that is used to keep track of players even if they change their name. 
 You can check player UUIDs at [mcuuid.net](https://mcuuid.net/). 
 If an author or contributor is defined without a UUID, that player will not get any mapmaker perks on the map.
 
@@ -85,7 +85,7 @@ If an author or contributor is defined without a UUID, that player will not get
   | Attribute | Description | Value |
   |---|---|---|
   | `uuid` | The UUID used to identify a Minecraft player. | <span className="badge badge--primary">String</span> |
-  | `contribution` | The contribution this author or contributor made to the map. | <span className="badge badge--primary">String</span> |
+  | `contribution` | A description of the contribution this author or contributor made to the map. | <span className="badge badge--primary">String</span> |
 </div>
 
 ```xml
@@ -148,13 +148,13 @@ Additionally, a variant can also contain constants, which allows you to define t
   | `<variant> </variant>` | A map variant. | <span className="badge badge--primary">String</span> |
 </div>
 
-#### Variant Attributes
+##### Variant Attributes
 
 <div className="table-container">
   | Attribute | Description | Value | Default |
   |---|---|---|---|
   | `id` | <span className="badge badge--danger">Required</span>Unique identifier used to reference this map variant from other places in the XML. | <span className="badge badge--primary">String</span> |
-  | `world` | Specify the world the variant should use during a match. | <span className="badge badge--primary">String</span> |
+  | `world` | The world the variant should use during a match. | <span className="badge badge--primary">String</span> |
   | `override` | Toggle if the variant name should override the base map name. If set to false, PGM will append `: [variant]` to the base map name. | <span className="badge badge--primary">true/false</span> | false |
 </div>
 
@@ -167,7 +167,7 @@ Additionally, a variant can also contain constants, which allows you to define t
   | `<unless> </unless>` | Apply an XML section for all variants except for a specific variant when loaded. | <span className="badge badge--secondary">XML Modules</span> |
 </div>
 
-#### If/Unless Conditional Attributes
+##### If/Unless Conditional Attributes
 
 <div className="table-container">
   | Attribute | Description | Value |
@@ -192,7 +192,7 @@ PGM will search and replace any corresponding placeholders (`${constant_id}`) wi
   | `<constant> </constant>` | An individual constant. | <span className="badge badge--primary">String</span> |
 </div>
 
-#### Constant Attributes
+##### Constant Attributes
 
 <div className="table-container">
   | Attribute | Description | Value | Default |
@@ -276,7 +276,7 @@ This means that a map that uses destroyables and flags would be displayed as "DT
   | `tdm` | Deathmatch |
 </div>
 
-Example
+##### Example
 
 ```xml
 <!-- A FFA map with scoreboxes -->

docs/modules/information/broadcasts.mdx

@@ -42,7 +42,7 @@ It should not be used for generic server-related messages.
 <div className="table-container">
   | Element | Description | Value |
   |---|---|---|
-  | `<filter>` | <span className="badge badge--secondary" title="Can be either this attribute or a sub-element.">Property</span>Duration to wait after the match starts to show the message. | [Filters](/docs/modules/mechanics/filters) |
+  | `<filter>` | <span className="badge badge--secondary" title="Can be either this attribute or a sub-element.">Property</span>Filter if the broadcast message should be sent after the duration has passed, or if it is skipped. | [Filters](/docs/modules/mechanics/filters) |
 </div>
 
 ### Examples