From 8ee08748ac1367e3231fa9d521bc8cb572211af4 Mon Sep 17 00:00:00 2001 From: Pear <20259871+TheRealPear@users.noreply.github.com> Date: Tue, 23 Jul 2024 16:25:15 -0400 Subject: [PATCH] Document tracking compass modules & more (#123) Signed-off-by: Pear <20259871+TheRealPear@users.noreply.github.com> --- docs/commands/community.mdx | 1 + docs/commands/events.mdx | 1 + docs/commands/main.mdx | 15 ++-- docs/modules/environment/world.mdx | 30 +++---- docs/modules/gear/consumables.mdx | 47 +++++++++-- docs/modules/gear/items.mdx | 2 +- docs/modules/gear/repair-remove-keep.mdx | 6 +- docs/modules/general/main.mdx | 39 ++++----- docs/modules/information/broadcasts.mdx | 2 +- docs/modules/mechanics/actions-triggers.mdx | 94 +++++++++++++++++++-- docs/modules/mechanics/damage.mdx | 21 ++++- docs/modules/mechanics/spawns.mdx | 2 +- docs/modules/mechanics/tracking-compass.mdx | 65 ++++++++++++++ docs/modules/mechanics/variables.mdx | 20 +++++ docs/modules/objectives/scoring.mdx | 2 +- docusaurus.config.js | 2 +- package-lock.json | 32 +++---- package.json | 4 +- sidebars.js | 3 +- 19 files changed, 307 insertions(+), 81 deletions(-) create mode 100644 docs/modules/mechanics/tracking-compass.mdx diff --git a/docs/commands/community.mdx b/docs/commands/community.mdx index 75bf18fc..6509dafe 100644 --- a/docs/commands/community.mdx +++ b/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. diff --git a/docs/commands/events.mdx b/docs/commands/events.mdx index eaf617ec..c286710a 100644 --- a/docs/commands/events.mdx +++ b/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. diff --git a/docs/commands/main.mdx b/docs/commands/main.mdx index 552f4399..56f15167 100644 --- a/docs/commands/main.mdx +++ b/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
actions page | Inspect variables for a player. | -q query
-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
-f force || `JOIN_FORCE` | | `/leave` | obs | Leave the match. ||| `LEAVE` | | `/loadnewmaps` | findnewmaps
new
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.
**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 | min-players] | `RESIZE` | | `/ffa size` || Set the maximum players. || [reset | max-players] (max-overfill) | `RESIZE` | | `/team min` || Set the minimum players on a team. || [team] (reset | min-players) | `RESIZE` | @@ -46,9 +51,9 @@ Permissions are prefixed with `Permissions` (i.e. `Permissions.ADMINCHAT`). | `/class` | selectclass
c
cl | Selects your class. | | `/classlist` | classes
listclasses
cls | List all available classes. | | `/g` | all
! (*do not use forward slash*) | Send a message to everyone. || [message] | - | `/inventory` | inv
vi | View a player’s inventory. | + | `/inventory` | inv
vi | View a player's inventory. | | `/list` | who
online
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
ml | List all loaded maps. | -a author
-t tag1,tag2
-n name | | `/match` | matchinfo | Show the match info. | | `/mode list` | page | List all objective modes. || [page] | diff --git a/docs/modules/environment/world.mdx b/docs/modules/environment/world.mdx index 9bf53ec6..49d8a15d 100644 --- a/docs/modules/environment/world.mdx +++ b/docs/modules/environment/world.mdx @@ -6,7 +6,8 @@ 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 64 @@ -14,14 +15,15 @@ A world's maximum build height can be set using the `maxbuildheight` element. On ### 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.
| Element | Description | @@ -34,22 +36,18 @@ The `world=""` attribute is used to specify the sub-folder that contains the map
| Attribute | Description | Value | Default | |---|---|---|---| - | `world` | The level data sub-folder to be used with this map. | Sub-folder Name | | `vanilla` | Specify if this world is uses the vanilla or null chunk generator. | true/false | false | - | `seed` | This world's generation seed. | String | - | `pre-match-physics` | Allow physics events, such as water flowing, before the match starts. | true/false | false | + | `seed` | The world's seed that determines how the world is generated. | String | + | `environment` | The world's dimension type.
**Note:** Worlds with `the end` environment are not supported. | `normal`
`nether` | `normal` | + | `pre-match-physics` | N/AAllow physics events, such as water flowing, before the match starts. | true/false | false |
```xml + - - - - - - - + + ``` ### Internal Maps diff --git a/docs/modules/gear/consumables.mdx b/docs/modules/gear/consumables.mdx index c686f79d..e69d388a 100644 --- a/docs/modules/gear/consumables.mdx +++ b/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` | RequiredUnique identifier used to reference this consumable from other places in the XML. | String | - | `action`|`kit` | RequiredRun the specified action upon consumption. | [Action ID](/docs/modules/mechanics/actions-triggers) | - | `on` | RequiredSpecify how the consumable should be used.
**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.
*This is useful when using potion bottles and golden apples as the consumable item.* | true/false | true | + | `action` | RequiredRun the specified action upon consumption. | [Action ID](/docs/modules/mechanics/actions-triggers) | + | `on` | RequiredSpecify how the consumable should be used. | `eat`
`right click`
`left click`
`click` (both) | + | `override` | The consumable is affected by vanilla behaviors, such as giving the player potion effects.
*This is useful when using potion bottles and golden apples as the consumable item.* | true/false | true | + | `consume` | PGM will consume the item once per use for the user.
**Note:** This attribute is ignored if the value of `on` attribute is `eat`. | true/false | [*](#override--consume-behavior) | +
+ +### 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. + +
+ | Override | Consume | Vanilla Behavior | Result | + |---|---|---|---| + | `false` | `false` | No consume (e.g.: stick) | Optimal0 used | + | `false` | `false` | Consumes (e.g.: snowball) | Sub-optimal1 used | + | `false` | `true` | No consume (e.g.: stick) | Optimal1 used | + | `false` | `true` | Consumes (e.g.: snowball) | Invalid2 used | + | `true` | `false` | Any case | Optimal0 used | + | `true` | `true` | Any case | Optimal1 used |
### Examples ```xml - + @@ -50,9 +66,9 @@ When consumed, these items can trigger [actions](/docs/modules/mechanics/actions ``` ```xml - + - + @@ -65,3 +81,22 @@ When consumed, these items can trigger [actions](/docs/modules/mechanics/actions ``` + +```xml + + + + + + + + + + + + + 20 + + +``` diff --git a/docs/modules/gear/items.mdx b/docs/modules/gear/items.mdx index 2d849cc6..f7371994 100644 --- a/docs/modules/gear/items.mdx +++ b/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. | Formatted Text | | `lore` | Custom text that appears when a player hovers over the item in their inventory. | Formatted Text | | `color` | Leather armor color as a hexadecimal color. `RRGGBB`
*Only applies to leather armor items.* | Hex Color | - | `team-color` | Automatically applies the team's [Dye Color](/docs/modules/format/teams#team-attributes) to colored blocks *(wool, stained glass, etc)*. | true/false | false | + | `team-color` | Automatically applies the team's [Dye Color](/docs/modules/format/teams#team-attributes) to colored blocks *(wool, stained glass, banner, etc)*. | true/false | false | | `grenade` | Projectile explodes on impact.
*Works with ender pearls, snowballs, eggs, and arrows.* | true/false | false | | `grenade-power` | The power of the grenade explosion on impact. | Decimal | 1.0 | | `grenade-fire` | Toggle if grenade explosion creates fire. | true/false | false | diff --git a/docs/modules/gear/repair-remove-keep.mdx b/docs/modules/gear/repair-remove-keep.mdx index 9d9f0250..28c018df 100644 --- a/docs/modules/gear/repair-remove-keep.mdx +++ b/docs/modules/gear/repair-remove-keep.mdx @@ -20,7 +20,7 @@ Repairing arrows instead of removing them has the advantage of the player being |---|---| | ` ` | A node containing all the tools that will be repaired when picked up. | - | Sub-elements | | Value/Children | + | Sub-elements | | Value | |---|---|---| | ` ` | A single tool that will be repaired, can be anything with durability. | [Material Name](/docs/reference/items/inventory#material-matchers) | @@ -43,7 +43,7 @@ Defines items that will be deleted when dropped on the map. Also works when item |---|---| | ` ` | A node containing all the items that will be removed when dropped. | - | Sub-elements | | Value/Children | + | Sub-elements | | Value | |---|---|---| | ` ` | The item that will be removed when dropped. | [Material Name](/docs/reference/items/inventory#material-matchers) | @@ -69,7 +69,7 @@ If there is a spawn kit, kept items will be given back *after* the kit is applie |---|---| | ` ` | A node containing all the items kept when respawning. | - | Sub-elements | | Value/Children | + | Sub-elements | | Value | |---|---|---| | ` ` | The item that will remain in a player's inventory when they die and respawn. | [Material Name](/docs/reference/items/inventory#material-matchers) | diff --git a/docs/modules/general/main.mdx b/docs/modules/general/main.mdx index c0b7207f..c9f7e32e 100644 --- a/docs/modules/general/main.mdx +++ b/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 | |---|---|---|---| | `` | RequiredThe name of the map. | String | - | `` | 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.
*Valid slugs are lowercase and only contain the characters:* `a-z 0-9 _` | String | Auto Generated | - | `` | RequiredThe map's [semantic version](https://semver.org/) string. | `1.0.0` | + | `` | 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.
*Valid slugs are lowercase and only contain the characters:* `a-z 0-9 _` | String | Auto Generated | + | `` | RequiredThe map's [semantic version](https://semver.org/). | `1.0.0` | | `` | RequiredThe map's objective, shown at the start of the match. | String | - | `` | RequiredThe authors of the map, at least one author is required. | `` | + | `` | RequiredThe authors of the map. At least one author is required. | `` | | `` | Contributors to the map. | `` | | `` | The date on which this map was initially released. | `YYYY-MM-DD` | - | `` | The phase of this map.
**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`
`production` | `production` | - | `` | The edition of this map, describing which servers it should run on. | `standard`
`ranked`
`tournament` | `standard` | - | `` | A custom title for this match's gamemode. | String | - | `` | The gamemode(s) of this map, if this is not specified the map will set the gamemode(s) to whatever modules are used. | Gamemode ID | + | `` | The stage of development the map is in.
**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`
`staging`
`production` | `production` | + | `` | The type of gameplay environment this map is intended for.
**Note:** In legacy PGM, only standard edition maps show up on a website configured with an API. | `standard`
`ranked`
`tournament` | `standard` | + | `` | A custom title for this match's gamemode.
**Note:** A map can have multiple gamemode titles. PGM will select the last as the map's primary title. | String | + | `` | The gamemode(s) of this map. If this is not specified the map will set the gamemode(s) to whatever modules are used. | Gamemode ID | ```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. | String | - | `contribution` | The contribution this author or contributor made to the map. | String | + | `contribution` | A description of the contribution this author or contributor made to the map. | String | ```xml @@ -148,13 +148,13 @@ Additionally, a variant can also contain constants, which allows you to define t | ` ` | A map variant. | String | -#### Variant Attributes +##### Variant Attributes
| Attribute | Description | Value | Default | |---|---|---|---| | `id` | RequiredUnique identifier used to reference this map variant from other places in the XML. | String | - | `world` | Specify the world the variant should use during a match. | String | + | `world` | The world the variant should use during a match. | String | | `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. | true/false | false |
@@ -167,7 +167,7 @@ Additionally, a variant can also contain constants, which allows you to define t | ` ` | Apply an XML section for all variants except for a specific variant when loaded. | XML Modules | -#### If/Unless Conditional Attributes +##### If/Unless Conditional Attributes
| Attribute | Description | Value | @@ -192,7 +192,7 @@ PGM will search and replace any corresponding placeholders (`${constant_id}`) wi | ` ` | An individual constant. | String |
-#### Constant Attributes +##### Constant Attributes
| Attribute | Description | Value | Default | @@ -250,33 +250,34 @@ This means that a map that uses destroyables and flags would be displayed as "DT
| ID | Description | |---|---| - | `ad` | Attack/Defend | | `arcade` | Arcade | + | `ad` | Attack/Defend | | `bedwars` | Bed Wars | | `blitz` | Blitz | | `br` | Blitz: Rage | | `bridge` | Bridge | - | `cp` | Control the Point | | `ctf` | Capture the Flag | | `ctw` | Capture the Wool | + | `cp` | Control the Point | + | `tdm` | Deathmatch | | `dtc` | Destroy the Core | | `dtm` | Destroy the Monument | - | `ffa` | Free for All | + | `5cp` | 5 Control Points | | `ffb` | Flag Football | + | `ffa` | Free for All | | `infection` | Infection | | `kotf` | King of the Flag | | `koth` | King of the Hill | | `mixed` | Mixed | | `payload` | Payload | - | `rage` | Rage | | `rfw` | Race for Wool | + | `rage` | Rage | | `scorebox` | Scorebox | | `skywars` | Skywars | | `sg` | Survival Games | - | `tdm` | Deathmatch |
-Example +##### Example ```xml diff --git a/docs/modules/information/broadcasts.mdx b/docs/modules/information/broadcasts.mdx index 7a83cbe8..0490c9ca 100644 --- a/docs/modules/information/broadcasts.mdx +++ b/docs/modules/information/broadcasts.mdx @@ -42,7 +42,7 @@ It should not be used for generic server-related messages.
| Element | Description | Value | |---|---|---| - | `` | PropertyDuration to wait after the match starts to show the message. | [Filters](/docs/modules/mechanics/filters) | + | `` | PropertyFilter if the broadcast message should be sent after the duration has passed, or if it is skipped. | [Filters](/docs/modules/mechanics/filters) |
### Examples diff --git a/docs/modules/mechanics/actions-triggers.mdx b/docs/modules/mechanics/actions-triggers.mdx index 51d7415e..374d05c2 100644 --- a/docs/modules/mechanics/actions-triggers.mdx +++ b/docs/modules/mechanics/actions-triggers.mdx @@ -1,6 +1,7 @@ --- id: actions-triggers title: Actions & Triggers +toc_max_heading_level: 4 --- Actions are a set of features that are applied to players, teams, or matches, similiar to [Kits](/docs/modules/gear/kits). @@ -23,7 +24,11 @@ In the future, some features that are currently used in Kits may be transferred | `` | Removes entities based on a filter. | | `` | Applies a [Kit](/docs/modules/gear/kits). | | `` | Places blocks in a block-bounded region. | + | `` | Places a structure at a specified location when triggered. | | ` ` | Finds and replaces certain items. | + | ` ` | Allow players to pay with items in their inventory to trigger an action. | + | `` | A player-scoped kit that applies velocity to the player. | + | `` | Teleport a player to a specific location. |
### Action Attributes @@ -61,6 +66,28 @@ In the future, some features that are currently used in Kits may be transferred | `fade-out` | How long the title and subtitle text will fade out. | [Time Period](/docs/reference/misc/time-periods) | 1s | +#### Replacements + +
+ | Element | Description | Value | + |---|---|---| + | `` | A list of replacements.
**Note:** In the future, more replacements such as player names will be supported. | Replacements Sub-elements | + + | Sub-element | Description | + |---|---| + | `` | A numerical placeholder. | +
+ +##### Decimal Attributes + +
+ | Attribute | Description | Value | + |---|---|---| + | `id` | Unique identifier used to reference this decimal from other places in the XML. | String | + | `value` | RequiredThe variable this decimal should evaluate. It can be used with formulas. | Expression | + | `format` | Customize how the decimal should be displayed, e.g. `#.00`. | [Java DecimalFormat pattern](https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html) | +
+ ### Sound Attributes
@@ -78,7 +105,8 @@ In the future, some features that are currently used in Kits may be transferred | Attribute | Description | Value | |---|---|---| | `var` | RequiredThe variable to update. | [Variable](/docs/modules/mechanics/variables) | - | `value` | RequiredSets a new value for the variable. | String | + | `index` | If setting an array-type variable, the expression to be evaluated.
*Required when using array-type variables.* | Expression | + | `value` | RequiredSets a new value for the variable. | Expression |
### Kill-Entities Attributes @@ -96,23 +124,77 @@ In the future, some features that are currently used in Kits may be transferred |---|---|---|---| | `region` | PropertyRequiredThe region to fill in. Multiple regions will be treated as an union. | [Region](/docs/modules/mechanics/regions) | | `material` | RequiredThe filling material. | [Single Material Pattern](/docs/reference/items/inventory#material-matchers) | - | `filter` | Filters which blocks get affected. *May impact preformace for large fills.* | [Filter](/docs/modules/mechanics/filters) | - | `events` | Calls events for block placements and removals, which will make it affected by other filters and PGM features. *May impact preformace for large fills.* | true/false | false | + | `filter` | Filters which blocks get affected. *May impact performance for large fills.* | [Filter](/docs/modules/mechanics/filters) | + | `events` | Calls events for block placements and removals, which will make it affected by other filters and PGM features. *May impact performance for large fills.* | true/false | false | -### Replace Item Attributes/Elements +### Paste-Structure Attributes
| Attribute | Description | Value | |---|---|---| - | `` | The item to find. | [Item Attributes](/docs/modules/gear/items#item-attributes) | + | `x` | The X coordinate of the location to paste the structure, measured in east-west. | Expression | + | `y` | The Y coordinate of the location to paste the structure, measured in altitude. | Expression | + | `z` | The Z coordinate of the location to paste the structure, measured in north-south. | Expression | + | `structure` | The structure to paste. | [Structure ID](/docs/modules/blocks/structures) | +
+ +### Replace Item + +#### Sub-elements + +
+ | Sub-elements | Description | Value | + |---|---|---| + | `` | The item to find in a player's inventory. | [Item Attributes](/docs/modules/gear/items#item-attributes) | | `` | The new item to replace with. | [Item Attributes](/docs/modules/gear/items#item-attributes) | +
+ +#### Attributes + +
+ | Attribute | Description | Value | + |---|---|---| | `keep-amount` | Player recives the same amount of the new item as they had of the old item. | true/false | | `keep-enchants` | Enchantments on the old item will be applied to the new item. | true/false | | `ignore-metadata` | Filters which entities to remove. | true/false | | `amount` | Match for item stacks that have a certain amount of items in a range. | Range |
+### Take-Payment + +#### Sub-elements + +
+ | Sub-elements | Description | Value | + |---|---|---| + | `` | PropertyRequiredAn individual payment. | [Item Attributes](/docs/modules/gear/items#item-attributes) | + | `` | PropertyThe action to trigger upon a successful payment. | Action | + | `` | PropertyThe action to trigger upon a failed payment. | Action | +
+ +#### Attributes + +
+ | Attribute | Description | Value | + |---|---|---| + | `material` | RequiredThe item to display as an icon. | [Material Name](/docs/reference/items/inventory#material-matchers) | + | `price` | The amount of a currency needed to purchase. | Number | + | `currency` | The currency needed to purchase. | [Filter](/docs/modules/mechanics/filters) | +
+ +### Velocity & Teleport Attributes + +
+ | Attribute | Description | Value | + |---|---|---| + | `x` | The X coordinate, measured in east-west. | Expression | + | `y` | The Y coordinate, measured in altitude. | Expression | + | `z` | The Z coordinate, measured in north-south. | Expression | + | `yaw` | The horizontal angle a user looks to. | Expression | + | `pitch` | The vertical angle a user looks to. | Expression | +
+ ## Trigger Element The trigger element waits for a dynamic filter to activate it, and afterwards it will trigger an action. @@ -168,7 +250,7 @@ This example uses the `expose` attribute in Action to allow moderators to enable a "Blitz Mode" using the `/action` command. Moderators must have the `GAMEPLAY` permissions in order to use `/action`. See [Commands](/docs/commands/main) for more details. -``` +```xml diff --git a/docs/modules/mechanics/damage.mdx b/docs/modules/mechanics/damage.mdx index b55df417..a25af5c6 100644 --- a/docs/modules/mechanics/damage.mdx +++ b/docs/modules/mechanics/damage.mdx @@ -27,8 +27,8 @@ The difficulty level can be set to `peaceful`, `easy`, `normal`, or `hard`. The ### Hunger -Specify if a player can starve to death, usually used with the difficulty setting.
-This can also be accomplished with the `naturalRegeneration` [gamerule](/docs/modules/mechanics/gamerules). +Specify if a player can starve to death, usually used with the difficulty setting. +This can also be accomplished with the [`naturalRegeneration` gamerule](/docs/modules/mechanics/gamerules). ```xml @@ -94,6 +94,14 @@ While almost every form of damage can be disabled safely, it is recommended that | ` ` | The damage type that is disabled. | [Damage Cause](#damage-causes) | +#### Damage Attributes +
+ | Attribute | Description | Value | + |---|---|---| + | `attacker-action` | The action to trigger for the attacker. | [Action ID](/docs/modules/mechanics/actions-triggers) | + | `victim-action` | The action to trigger for the victim. | [Action ID](/docs/modules/mechanics/actions-triggers) | +
+ _Example_ ```xml @@ -103,6 +111,15 @@ _Example_ ``` +```xml + + + + explosion + + +``` + #### Block Explosion Attributes The `BLOCK_EXPLOSION` damage cause has several extended attributes to customize who/what gets damaged. Only attributes with `false` as the value need to be explicitly defined since all attributes default to `true`. diff --git a/docs/modules/mechanics/spawns.mdx b/docs/modules/mechanics/spawns.mdx index 432f3a01..1cc15afd 100644 --- a/docs/modules/mechanics/spawns.mdx +++ b/docs/modules/mechanics/spawns.mdx @@ -140,7 +140,7 @@ If a player has a bed spawn location set, it overrides all other spawn regions f | `auto` | Automatically respawn the player after the delay time has elapsed. | true/false | false | | `blackout` | Dead players get a blindness effect applied. | true/false | false | | `spectate` | Allow dead players to fly around. | true/false | false | - | `bed` | N/AAllow players to respawn from beds. | true/false | false | + | `bed` | N/AAllow players to respawn from beds. | true/false | false | | `message` | PropertyMessage to display on the respawn screen to respawning players. | Formatted Text | diff --git a/docs/modules/mechanics/tracking-compass.mdx b/docs/modules/mechanics/tracking-compass.mdx new file mode 100644 index 00000000..625b2190 --- /dev/null +++ b/docs/modules/mechanics/tracking-compass.mdx @@ -0,0 +1,65 @@ +--- +id: tracking-compass +title: Tracking Compass +--- + +The Tracking Compass module allows you to override the vanilla compass behavior by pointing +it to a player of interest. In addition, you can control how the compass selects the target to track. + +#### Compass Element + +
+ | Element | Description | + |---|---| + | ` ` | Node containing all compass properties used in this map. | + + | Sub-element || + |---|---| + | `` | An individual compass property pointing to the nearest player passing a filter. | + | `` | An individual compass property pointing to a specific flag. | +
+ +##### Compass Attributes + +
+ | Attribute | Description | Value | Default | + |---|---|---|---| + | `order` | When using `DEFINITION_ORDER`, the compass targets first matching target. When using `CLOSEST`, the compass goes through all matching targets and chooses the one closest to the player. | `DEFINITION_ORDER`
`CLOSEST` | + | `show-distance` | Show the distance between the compass holder and tracked player in meters. | true/false | false | +
+ +##### Player/Flag Attribute + +
+ | Attribute | Description | Value | Default | + |---|---|---|---| + | `filter` | Filters who should be tracked by the compass. | [Filter](/docs/modules/mechanics/filters) | + | `holder-filter` | Filters out what compass targets can be eligible for what players, e.g. a team targets a different flag than the other team. | [Filter](/docs/modules/mechanics/filters) | + | `name` | The title name that describes the tracked flag or player's role, e.g. "Wool Carrier." | Formatted Text | + | `show-player` | Show the tracked player's username to the compass holder.
**Note:** This is only applicable to `` sub-element. | true/false | false | +
+ +## Examples + +```xml + + + + + + + + + + + + + + + + blue-flag + + + red-flag + +``` \ No newline at end of file diff --git a/docs/modules/mechanics/variables.mdx b/docs/modules/mechanics/variables.mdx index d5c3ab49..838f48da 100644 --- a/docs/modules/mechanics/variables.mdx +++ b/docs/modules/mechanics/variables.mdx @@ -21,7 +21,9 @@ You can define as many variables as you want and all variables must have a scope | `` | A score variable, allowing direct access to competitor's score. This is automatically scoped to teams. | | `` | A time limit variable which starts/stops the time limit of the match. | | `` | A variable that sets the build height of the map. | + | `` | A variable that represents a collection of values. | | `` | A team-rescoping variable that allows using a specific team's value from a different team-scoped variable as a match-scoped variable. | + | `` | A variable that reads a player's location components. | ### Variable Attributes @@ -35,6 +37,15 @@ You can define as many variables as you want and all variables must have a scope | `default` | Sets the initial value of the variable. | Number | +### Array Attributes + +
+ | Attribute | Description | Value | + |---|---|---| + | `id` | Unique identifier used to reference this array-type variable from other places in the XML. | String | + | `size` | RequiredThe size of this array. | 1 - 1024 | +
+ ### With-Team Attributes
@@ -45,6 +56,15 @@ You can define as many variables as you want and all variables must have a scope | `team` | The team to target. | [Team ID](/docs/modules/format/teams#team-attributes) |
+### Player-Location Attributes + +
+ | Attribute | Description | Value | + |---|---|---| + | `id` | Unique identifier used to reference this player-location variable from other places in the XML. | String | + | `component` | The player's location component to target. `XYZ`, `YAW`, and `PITCH` represents the player's position/angle, `DIR_XYZ` represents the player's direction, and `VEL_XYZ` represents the player's velocity. | `X`, `Y`, `Z`, `PITCH`, `YAW`,
`DIR_X`, `DIR_Y`, `DIR_Z`,
`VEL_X`, `VEL_Y`, and `VEL_Z` | +
+ ## Examples ### Setting Variables diff --git a/docs/modules/objectives/scoring.mdx b/docs/modules/objectives/scoring.mdx index cf305d24..6ddebafe 100644 --- a/docs/modules/objectives/scoring.mdx +++ b/docs/modules/objectives/scoring.mdx @@ -61,7 +61,7 @@ A score box will give points to a players team when they enter or bring a redeem | `silent` | Do not notify players when points are scored in this box. | true/false | false | | `region` | PropertyRequiredThe location and size of the score box. | [Region](/docs/modules/mechanics/regions) | | `filter` | PropertyFilter who can score in this box. | [Filter](/docs/modules/mechanics/filters) | No Filter | - | `trigger` | PropertyDynamic conditions under which this score box is applied. | [Dynamic Filter](/docs/modules/mechanics/filters#dynamic-filters) | + | `trigger` | N/APropertyDynamic conditions under which this score box is applied. | [Dynamic Filter](/docs/modules/mechanics/filters#dynamic-filters) | #### Box Sub-elements diff --git a/docusaurus.config.js b/docusaurus.config.js index c5f5d7f4..b4009ac0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -86,7 +86,7 @@ const config = { announcementBar: { id: 'new_features', content: - 'New Features: Consumables, Map Variants, Constants, and Structures', + 'New Features: Tracking Compass, Consumables, Map Variants, and Constants', backgroundColor: '#fafbfc', textColor: '#091E42', isCloseable: true, diff --git a/package-lock.json b/package-lock.json index 1de1ff24..e3073592 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,8 +11,8 @@ "dependencies": { "@docusaurus/core": "^3.4.0", "@docusaurus/preset-classic": "^3.4.0", - "@fortawesome/fontawesome-svg-core": "^6.5.2", - "@fortawesome/free-solid-svg-icons": "^6.5.2", + "@fortawesome/fontawesome-svg-core": "^6.6.0", + "@fortawesome/free-solid-svg-icons": "^6.6.0", "@fortawesome/react-fontawesome": "^0.2.2", "@mdx-js/react": "^3.0.1", "classnames": "^2.5.1", @@ -2797,33 +2797,33 @@ } }, "node_modules/@fortawesome/fontawesome-common-types": { - "version": "6.5.2", - "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-6.5.2.tgz", - "integrity": "sha512-gBxPg3aVO6J0kpfHNILc+NMhXnqHumFxOmjYCFfOiLZfwhnnfhtsdA2hfJlDnj+8PjAs6kKQPenOTKj3Rf7zHw==", - "hasInstallScript": true, + "version": "6.6.0", + "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-6.6.0.tgz", + "integrity": "sha512-xyX0X9mc0kyz9plIyryrRbl7ngsA9jz77mCZJsUkLl+ZKs0KWObgaEBoSgQiYWAsSmjz/yjl0F++Got0Mdp4Rw==", + "license": "MIT", "engines": { "node": ">=6" } }, "node_modules/@fortawesome/fontawesome-svg-core": { - "version": "6.5.2", - "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-svg-core/-/fontawesome-svg-core-6.5.2.tgz", - "integrity": "sha512-5CdaCBGl8Rh9ohNdxeeTMxIj8oc3KNBgIeLMvJosBMdslK/UnEB8rzyDRrbKdL1kDweqBPo4GT9wvnakHWucZw==", - "hasInstallScript": true, + "version": "6.6.0", + "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-svg-core/-/fontawesome-svg-core-6.6.0.tgz", + "integrity": "sha512-KHwPkCk6oRT4HADE7smhfsKudt9N/9lm6EJ5BVg0tD1yPA5hht837fB87F8pn15D8JfTqQOjhKTktwmLMiD7Kg==", + "license": "MIT", "dependencies": { - "@fortawesome/fontawesome-common-types": "6.5.2" + "@fortawesome/fontawesome-common-types": "6.6.0" }, "engines": { "node": ">=6" } }, "node_modules/@fortawesome/free-solid-svg-icons": { - "version": "6.5.2", - "resolved": "https://registry.npmjs.org/@fortawesome/free-solid-svg-icons/-/free-solid-svg-icons-6.5.2.tgz", - "integrity": "sha512-QWFZYXFE7O1Gr1dTIp+D6UcFUF0qElOnZptpi7PBUMylJh+vFmIedVe1Ir6RM1t2tEQLLSV1k7bR4o92M+uqlw==", - "hasInstallScript": true, + "version": "6.6.0", + "resolved": "https://registry.npmjs.org/@fortawesome/free-solid-svg-icons/-/free-solid-svg-icons-6.6.0.tgz", + "integrity": "sha512-IYv/2skhEDFc2WGUcqvFJkeK39Q+HyPf5GHUrT/l2pKbtgEIv1al1TKd6qStR5OIwQdN1GZP54ci3y4mroJWjA==", + "license": "(CC-BY-4.0 AND MIT)", "dependencies": { - "@fortawesome/fontawesome-common-types": "6.5.2" + "@fortawesome/fontawesome-common-types": "6.6.0" }, "engines": { "node": ">=6" diff --git a/package.json b/package.json index 08194cf0..06438e3a 100644 --- a/package.json +++ b/package.json @@ -22,8 +22,8 @@ "dependencies": { "@docusaurus/core": "^3.4.0", "@docusaurus/preset-classic": "^3.4.0", - "@fortawesome/fontawesome-svg-core": "^6.5.2", - "@fortawesome/free-solid-svg-icons": "^6.5.2", + "@fortawesome/fontawesome-svg-core": "^6.6.0", + "@fortawesome/free-solid-svg-icons": "^6.6.0", "@fortawesome/react-fontawesome": "^0.2.2", "@mdx-js/react": "^3.0.1", "classnames": "^2.5.1", diff --git a/sidebars.js b/sidebars.js index 9f9917a5..12175f6e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -53,7 +53,8 @@ const sidebars = { "modules/mechanics/lanes", "modules/mechanics/damage", "modules/mechanics/gamerules", - "modules/mechanics/spawners",], + "modules/mechanics/spawners", + "modules/mechanics/tracking-compass"], }, { type: 'category',