diff --git a/docs/modules/general/main.mdx b/docs/modules/general/main.mdx index 0114eff6..e782d5ad 100644 --- a/docs/modules/general/main.mdx +++ b/docs/modules/general/main.mdx @@ -5,13 +5,13 @@ description: Every map XML file must contain the base map module. It contains mo --- Every map XML file must contain the base `` module. -It contains modules that specify the map name, version, objective, authors, contributors, and all other map settings. -The objective is the text that players see when they join the match, and so it is important for this to be very clear, concise, and informative. +It contains modules that specify the map name, version, objective, authors, contributors, and all other map settings. +The objective is the text that players see when they join the match, and so this needs to be very clear, concise, and informative. The `proto=""` attribute specifies what PGM version the XML file was created for. Mapmakers should always use the latest supported proto version, which is documented in depth at [Protocol Versions](/docs/modules/general/proto). -The maps version should follow the versioning schema `major.minor.patch`. +The map's version should follow the versioning schema `major.minor.patch`. | Map Element | Description | Value/Children | |---|---|---| @@ -21,7 +21,9 @@ The maps version should follow the versioning schema `major.minor.patch`. | Map Attributes | Description | Value | Default | |---|---|---|---| -| `proto` | RequiredThe map's XML protocol version. | `1.4.2` | +| `proto` | RequiredThe map's XML protocol version. | Proto Version | +| `min-server-version` | The minimum server version this map can run on. | +| `max-server-version` | The maximum server version this map can run on. | | `internal` | Prevent compass teleports above Y=255. | true/false | false | ##### Map Sub-elements @@ -29,7 +31,7 @@ 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 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 | +| `` | 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 its information, 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. | `` | @@ -53,14 +55,14 @@ The maps version should follow the versioning schema `major.minor.patch`. ``` -### Authors & Contributors +## Authors & Contributors -The authors and contributers elements provide information about who created and helped create the map. +The authors and contributors elements provide information about who created and helped create the map. 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 universally unique 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 names. 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. @@ -94,123 +96,7 @@ If an author or contributor is defined without a UUID, that player will not get ``` -### Include Statements - -Include statements allow for global XML files to be loaded and re-used across different maps. -This can be used to standardize values across maps. -Below is a sample includes file that can be used on Blitz maps: - -```xml title="/server/includes/blitz.xml" - - - - 5 - - -``` - -The file is automatically given an ID based on the file name, which in this case is `blitz`. -Then it can be added into the main `map.xml`. Multiple include statements can be used per map. - -```xml title="/server/maps/map_name/map.xml" - - ... - - - ... - -``` - -### Map Variants - -Mapmakers may choose to build different versions of their maps that are tailored for events, such as tournaments. -This tool allows them to avoid the need to duplicate existing maps and, instead, unify various versions into one location. - -By defining a variant ID, PGM will treat an individual map with one or more variants as separate maps. -Each variant can contain conditionals, which determine whether a section of the XML file from the base (internally, the `default` variant) map should be loaded for a variant map. -Additionally, a variant can also contain constants, which allows you to define text constants that can be used to replace placeholders in the base map XML with the specified values. - -#### Variant Sub-elements - -| Element | Description | Value/Children | -|---|---|---| -| ` ` | A map variant. | String | - -##### Variant Attributes - -| Attribute | Description | Value | Default | -|---|---|---|---| -| `id` | RequiredUnique identifier used to reference this map variant from other places in the XML. | 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 | - -#### Conditionals Sub-elements - -| Element | Description | Value/Children | -|---|---|---| -| ` ` | Apply an XML section if the specified variant is loaded. | XML Modules | -| ` ` | Apply an XML section for all variants except for a specific variant when loaded. | XML Modules | - -##### If/Unless Conditional Attributes - -| Attribute | Description | Value | -|---|---|---| -| `variant` | The name of the variant to target. | Variant ID | -| `has-variant` | Target all maps with a specified variant.
**Note:** This can be useful in a server's global XML file. | Variant ID | - -**Note:** Multiple variants can be targeted as long as it is separated with a comma (`,`). - -### Constants -Constants are values that remain the same, regardless of conditions. -PGM will search and replace any corresponding placeholders (`${constant_id}`) with the constant value. - -| Element | Description | Children | -|---|---|---| -| ` ` | A node containing the constants for this map. | Constant Elements | - -| Sub-elements ||| -|---|---|---| -| ` ` | An individual constant. | String | - -##### Constant Attributes - -| Attribute | Description | Value | Default | -|---|---|---|---| -| `id` | RequiredUnique identifier used to reference this constant from other places in the XML. | String | -| `delete` | When true, PGM will completely delete the attribute or element the constant was used in, rather than leaving it blank. | true/false | false | - -The following example utilizes both map variants and constant. -```xml - -Map Name -5v5 -TE -Spooky Map Name - - -25 - -6 - - 5 - 5 - 3 - - - 6 - 6 - - - - - - - ${max} - - -``` - -### Map Gamemode +## Map Gamemode The gamemode element is used to specify the gamemode(s) of the map. This mainly affects how the map is displayed. diff --git a/docs/modules/general/preprocessing.mdx b/docs/modules/general/preprocessing.mdx new file mode 100644 index 00000000..9874fd40 --- /dev/null +++ b/docs/modules/general/preprocessing.mdx @@ -0,0 +1,181 @@ +--- +id: preprocessing +title: Includes & Preprocessing +--- + +## Includes + +Include statements allow global XML files to be loaded and reused across different maps, thereby standardizing elements across maps. + +Using the include element, an XML file can be split into multiple files and then included in the main one. +This allows you to keep the main file more organized by including sections such as kits, actions, and more. + +```xml + + ... + + ... + +``` + +### Example + +Below is a sample include file that can be used for Blitz maps: + +```xml title="/server/includes/blitz.xml" + + + + 5 + + +``` + +The include file is automatically given an ID based on its file name, which in this case is `blitz`. +Then, it can be added to the main `map.xml`. Multiple include statements can be used per map. + +```xml title="/server/maps/map_name/map.xml" + +... + + +... + +``` + +## Map Variants + +Mapmakers may choose to build different versions of their maps tailored to events, such as seasonal maps (Christmas, Halloween, etc.). +Variants allow them to avoid the need to duplicate existing maps and, instead, unify various versions into one location. + +By defining a variant ID, PGM will treat an individual map with one or more variants as separate maps. +Each variant can contain conditionals, which determine whether a section of the XML file from the base (internally, the `default` variant) map should be loaded for a variant map. +Additionally, a variant can also contain constants, which allows you to define text constants that can be used to replace placeholders in the base map XML with the specified values. + +#### Variant Sub-elements + +| Element | Description | Value/Children | +|---|---|---| +| ` ` | A map variant. | String | + +##### Variant Attributes + +| Attribute | Description | Value | Default | +|---|---|---|---| +| `id` | RequiredUnique identifier used to reference this map variant from other places in the XML. | String | +| `slug` | The variant's internal identifier, usually auto generated from the variant's name. This should only be used when a variant is renamed to retain its information, etc.
*Valid slugs are lowercase and only contain the characters:* `a-z 0-9 _` | String | Auto Generated | +| `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 | + +### Example + +```xml + +Map Name +5v5 +TE +Spooky Map Name +Christmas +... + +``` + + +## Conditionals + +XML files can contain simple `` and `` conditional statements. +These conditionals can be used to reduce duplicated map files and simplify managing multiple map variations. + +For example, instead of having multiple map variants in different folders, they can be condensed into one location. +This also allows map variants to be automatically loaded on specific servers or during special occasions. + +#### Conditionals Sub-elements + +| Element | Description | Value/Children | +|---|---|---| +| ` ` | Apply an XML section if the specified variant is loaded. | XML Modules | +| ` ` | Apply an XML section for all variants except for a specific variant when loaded. | XML Modules | + +##### If/Unless Conditional Attributes + +| Attribute | Description | Value | +|---|---|---| +| `variant` | The map variant to target.
*Multiple variants can be targeted as long as it is separated with a comma (`,`).* | Variant ID | +| `has-variant` | Target all maps with a specified variant.
**Note:** This can be useful in a server's global XML file. | Variant ID | +| `constant` | The name of the constant to check against.
*Constants must be defined before this conditional.* | Constant ID | +| `constant-value` | The constant value to check for. | Constant Value +| `constant-comparison` | The type of comparison performed.
**Note:** If there is no value, it will default to `defined value`. With a value, it will default to `equals`. | `undefined`, `defined`,
`defined delete`,
`defined value`,
`contains`, `regex`, `range`. | + +#### Constant Comparison + +* UNDEFINED: checks that the constant has not been defined to anything. +* DEFINED: checks the constant has been defined, to anything (either to delete or to a value). +* DEFINED_DELETE: the constant has been defined as a delete. +* DEFINED_VALUE: the constant has defined as an actual value (not a delete). +* EQUALS: the constant equals to the attribute constant-value. +* CONTAINS: the constant is one of the the comma-separated list of values in `constant-value`. + ```xml + + ``` +* REGEX: checks if the constant matches the regex. + ```xml + + ``` +* RANGE: check if the constant, interpreted as a number, is in the range. + * In this example, we check if the value is between 0 and 12. + ```xml + + ``` + +## Constants + +Constants are values that remain the same, regardless of conditions. +PGM will search and replace any corresponding placeholders (`${constant_id}`) with the constant value. + +| Element | Description | Children | +|---|---|---| +| ` ` | A node containing the constants for this map. | Constant Elements | + +| Sub-elements ||| +|---|---|---| +| ` ` | An individual constant. | String | + +##### Constant Attributes + +| Attribute | Description | Value | Default | +|---|---|---|---| +| `id` | RequiredUnique identifier used to reference this constant from other places in the XML. | String | +| `delete` | When true, PGM will completely delete the attribute or element the constant was used in, rather than leaving it blank. | true/false | false | +| `fallback` | When true, this constant will not override any previous declaration.
**Note:** This is useful for includes, since you may not want to override individual maps' constant value. | true/false | false | + +### Example + +The following example utilizes both map variants and constants. +```xml + +Map Name +5v5 +TE + + +25 + +6 + + 5 + 5 + 3 + + + 6 + 6 + + + + + + + ${max} + + +``` \ No newline at end of file diff --git a/docs/modules/general/proto.mdx b/docs/modules/general/proto.mdx index c0def2ef..f5788360 100644 --- a/docs/modules/general/proto.mdx +++ b/docs/modules/general/proto.mdx @@ -95,7 +95,7 @@ If you would like to learn more or report issues, please visit the [PGM issue tr - Portals, kits, score boxes & structures can now be dynamically applied using dynamic filters. All region types are dynamic, however, only some filter types are dynamic. - Kits now have [`give`, `take` & `lend` properties](/docs/modules/gear/kits#dynamic-kits). - - Portals have [`forward`, `reverse` & `transit` properties](/docs/modules/mechanics/portals#portal-sub-elements). + - Portals have [`forward`, `reverse` & `transit` properties](/docs/modules/mechanics/portals#portal-attributes). - [Structures](/docs/modules/blocks/structures) & [score boxes](/docs/modules/objectives/scoring#score-boxes) have a `trigger` property. - Added a player count filter. - Added a `` filter to check if the player is standing on the ground. diff --git a/package-lock.json b/package-lock.json index 9fd201ba..a0c0eb7f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,12 +9,12 @@ "version": "0.0.0", "license": "Apache-2.0", "dependencies": { - "@docusaurus/core": "^3.6.1", + "@docusaurus/core": "^3.6.3", "@docusaurus/plugin-client-redirects": "^3.6.3", "@docusaurus/preset-classic": "^3.6.3", "@docusaurus/theme-classic": "^3.6.3", "@fortawesome/fontawesome-svg-core": "^6.7.1", - "@fortawesome/free-solid-svg-icons": "^6.6.0", + "@fortawesome/free-solid-svg-icons": "^6.7.1", "@fortawesome/react-fontawesome": "^0.2.2", "@mdx-js/react": "^3.1.0", "classnames": "^2.5.1", @@ -4033,9 +4033,9 @@ } }, "node_modules/@fortawesome/fontawesome-common-types": { - "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==", + "version": "6.7.1", + "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-6.7.1.tgz", + "integrity": "sha512-gbDz3TwRrIPT3i0cDfujhshnXO9z03IT1UKRIVi/VEjpNHtSBIP2o5XSm+e816FzzCFEzAxPw09Z13n20PaQJQ==", "license": "MIT", "engines": { "node": ">=6" @@ -4052,21 +4052,13 @@ "node": ">=6" } }, - "node_modules/@fortawesome/fontawesome-svg-core/node_modules/@fortawesome/fontawesome-common-types": { - "version": "6.7.1", - "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-6.7.1.tgz", - "integrity": "sha512-gbDz3TwRrIPT3i0cDfujhshnXO9z03IT1UKRIVi/VEjpNHtSBIP2o5XSm+e816FzzCFEzAxPw09Z13n20PaQJQ==", - "engines": { - "node": ">=6" - } - }, "node_modules/@fortawesome/free-solid-svg-icons": { - "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==", + "version": "6.7.1", + "resolved": "https://registry.npmjs.org/@fortawesome/free-solid-svg-icons/-/free-solid-svg-icons-6.7.1.tgz", + "integrity": "sha512-BTKc0b0mgjWZ2UDKVgmwaE0qt0cZs6ITcDgjrti5f/ki7aF5zs+N91V6hitGo3TItCFtnKg6cUVGdTmBFICFRg==", "license": "(CC-BY-4.0 AND MIT)", "dependencies": { - "@fortawesome/fontawesome-common-types": "6.6.0" + "@fortawesome/fontawesome-common-types": "6.7.1" }, "engines": { "node": ">=6" diff --git a/package.json b/package.json index 8423ef8d..dd8a7fcf 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,7 @@ "@docusaurus/preset-classic": "^3.6.3", "@docusaurus/theme-classic": "^3.6.3", "@fortawesome/fontawesome-svg-core": "^6.7.1", - "@fortawesome/free-solid-svg-icons": "^6.6.0", + "@fortawesome/free-solid-svg-icons": "^6.7.1", "@fortawesome/react-fontawesome": "^0.2.2", "@mdx-js/react": "^3.1.0", "classnames": "^2.5.1", diff --git a/sidebars.js b/sidebars.js index 2579bf12..c1a45210 100644 --- a/sidebars.js +++ b/sidebars.js @@ -5,7 +5,8 @@ const sidebars = { type: 'category', label: 'General', items: ["modules/general/introduction", - "modules/general/main", + "modules/general/main", + "modules/general/preprocessing", "modules/general/proto"], }, {