Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document server version, variant, & constant changes #149

Merged
merged 3 commits into from
Dec 10, 2024
+205 −145
Merged

Document server version, variant, & constant changes #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5707f13
Document server version, variant, & constant changes
TheRealPear Sep 23, 2024
aac23ed
Move includes, variants, conditionals, etc to a new page
TheRealPear Dec 4, 2024
657c542
Change example per Pablo's suggestion
TheRealPear Dec 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 11 additions & 125 deletions docs/modules/general/main.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<map>` 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 |
|---|---|---|
Expand All @@ -21,15 +21,17 @@ The maps version should follow the versioning schema `major.minor.patch`.

| Map Attributes | Description | Value | Default |
|---|---|---|---|
| `proto` | <span className="badge badge--danger">Required</span>The map's XML protocol version. | `1.4.2` |
| `proto` | <span className="badge badge--danger">Required</span>The map's XML protocol version. | <span className="badge badge--secondary">Proto Version</span> |
| `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. | <span className="badge badge--primary">true/false</span> | false |

##### Map Sub-elements

| 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 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> |
| `<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 its information, 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>` |
Expand All @@ -53,14 +55,14 @@ The maps version should follow the versioning schema `major.minor.patch`.
</map>
```

### 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.

Expand Down Expand Up @@ -94,123 +96,7 @@ If an author or contributor is defined without a UUID, that player will not get
</contributors>
```

### 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"
<!-- the location for include files is defined in config.yml -->
<map>
<blitz>
<lives>5</lives>
</blitz>
</map>
```

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>
...
<!-- All maps with this include statement will give the player 5 lives -->
<include id="blitz"/>
...
</map>
```

### 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 |
|---|---|---|
| `<variant> </variant>` | A map variant. | <span className="badge badge--primary">String</span> |

##### Variant Attributes

| 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` | 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 |

#### Conditionals Sub-elements

| Element | Description | Value/Children |
|---|---|---|
| `<if> </if>` | Apply an XML section if the specified variant is loaded. | <span className="badge badge--secondary">XML Modules</span> |
| `<unless> </unless>` | Apply an XML section for all variants except for a specific variant when loaded. | <span className="badge badge--secondary">XML Modules</span> |

##### If/Unless Conditional Attributes

| Attribute | Description | Value |
|---|---|---|
| `variant` | The name of the variant to target. | <span className="badge badge--primary">Variant ID</span> |
| `has-variant` | Target all maps with a specified variant.<br />**Note:** This can be useful in a server's global XML file. | <span className="badge badge--primary">Variant ID</span> |

**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 |
|---|---|---|
| `<constants> </constants>` | A node containing the constants for this map. | <span className="badge badge--secondary">Constant Elements</span> |

| Sub-elements |||
|---|---|---|
| `<constant> </constant>` | An individual constant. | <span className="badge badge--primary">String</span> |

##### Constant Attributes

| Attribute | Description | Value | Default |
|---|---|---|---|
| `id` | <span className="badge badge--danger">Required</span>Unique identifier used to reference this constant from other places in the XML. | <span className="badge badge--primary">String</span> |
| `delete` | When true, PGM will completely delete the attribute or element the constant was used in, rather than leaving it blank. | <span className="badge badge--primary">true/false</span> | false |

The following example utilizes both map variants and constant.
```xml
<map proto="1.4.2">
<name>Map Name</name>
<variant id="5v5">5v5</variant> <!-- Loaded as "Map Name: 5v5" -->
<variant id="tournament">TE</variant> <!-- Loaded as "Map Name: TE" -->
<variant id="halloween" override="true">Spooky Map Name</variant> <!-- Loaded as "Spooky Map Name" -->

<!-- PGM will replace "${team_size}" and "${max}" placeholder with the new value -->
<constant id="team_size">25</constant>
<constant id="overfill" delete="true"/> <!-- "max-overfill" will not exist when "Map Name" is loaded -->
<constant id="max">6</constant>
<if variant="5v5">
<constant id="team_size">5</constant>
<constant id="overfill">5</constant>
<constant id="max">3</constant>
</if>
<if variant="tournament">
<constant id="team_size">6</constant>
<constant id="overfill">6</constant>
<constant id="max" delete="true"/>
</if>

<team id="red" max="${team_size}" max-overfill="${overfill}"/>
<team id="blue" max="${team_size}" max-overfill="${overfill}"/>
<score>
<limit>${max}</limit> <!-- 6 in "Map Name", 3 in "Map Name: 5v5", non-existent in "Map Name: TE" -->
</score>
</map>
```

### 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.
Expand Down
181 changes: 181 additions & 0 deletions docs/modules/general/preprocessing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<map>
...
<include id="include-name-goes-here"/>
...
</map>
```

### Example

Below is a sample include file that can be used for Blitz maps:

```xml title="/server/includes/blitz.xml"
<!-- The location for include files is defined in /plugins/PGM/config.yml -->
<map>
<blitz>
<lives>5</lives>
</blitz>
</map>
```

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>
...
<!-- All maps with this include statement will give the player 5 lives -->
<include id="blitz"/>
...
</map>
```

## 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 |
|---|---|---|
| `<variant> </variant>` | A map variant. | <span className="badge badge--primary">String</span> |

##### Variant Attributes

| 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> |
| `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.<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> |
| `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 |

### Example

```xml
<map proto="1.5.0">
<name>Map Name</name>
<variant id="5v5">5v5</variant> <!-- Loaded as "Map Name: 5v5" -->
<variant id="tournament">TE</variant> <!-- Loaded as "Map Name: TE" -->
<variant id="halloween" override="true">Spooky Map Name</variant> <!-- Loaded as "Spooky Map Name" -->
<variant id="christmas" world="christmas"/>Christmas</variant> <!-- Loaded as "Map Name: Christmas" with a different world -->
...
</map>
```


## Conditionals

XML files can contain simple `<if>` and `<unless>` 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 |
|---|---|---|
| `<if> </if>` | Apply an XML section if the specified variant is loaded. | <span className="badge badge--secondary">XML Modules</span> |
| `<unless> </unless>` | Apply an XML section for all variants except for a specific variant when loaded. | <span className="badge badge--secondary">XML Modules</span> |

##### If/Unless Conditional Attributes

| Attribute | Description | Value |
|---|---|---|
| `variant` | The map variant to target.<br />*Multiple variants can be targeted as long as it is separated with a comma (`,`).* | <span className="badge badge--primary">Variant ID</span> |
| `has-variant` | Target all maps with a specified variant.<br />**Note:** This can be useful in a server's global XML file. | <span className="badge badge--primary">Variant ID</span> |
| `constant` | The name of the constant to check against.<br />*Constants must be defined before this conditional.* | <span className="badge badge--primary">Constant ID</span> |
| `constant-value` | The constant value to check for. | <span className="badge badge--secondary">Constant Value</span>
| `constant-comparison` | The type of comparison performed.<br />**Note:** If there is no value, it will default to `defined value`. With a value, it will default to `equals`. | `undefined`, `defined`,<br />`defined delete`,<br />`defined value`,<br />`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
<if constant="const" constant-value="a,b,c" constant-comparison="contains"/>
```
* REGEX: checks if the constant matches the regex.
```xml
<if constant="const" constant-value="[0-9]+" constant-comparison="regex"/>
```
* 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
<if constant="const" constant-value="0..12" constant-comparison="range"/>
```

## 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 |
|---|---|---|
| `<constants> </constants>` | A node containing the constants for this map. | <span className="badge badge--secondary">Constant Elements</span> |

| Sub-elements |||
|---|---|---|
| `<constant> </constant>` | An individual constant. | <span className="badge badge--primary">String</span> |

##### Constant Attributes

| Attribute | Description | Value | Default |
|---|---|---|---|
| `id` | <span className="badge badge--danger">Required</span>Unique identifier used to reference this constant from other places in the XML. | <span className="badge badge--primary">String</span> |
| `delete` | When true, PGM will completely delete the attribute or element the constant was used in, rather than leaving it blank. | <span className="badge badge--primary">true/false</span> | false |
| `fallback` | When true, this constant will not override any previous declaration.<br />**Note:** This is useful for includes, since you may not want to override individual maps' constant value. | <span className="badge badge--primary">true/false</span> | false |

### Example

The following example utilizes both map variants and constants.
```xml
<map proto="1.5.0">
<name>Map Name</name>
<variant id="5v5">5v5</variant> <!-- Loaded as "Map Name: 5v5" -->
<variant id="tournament">TE</variant> <!-- Loaded as "Map Name: TE" -->

<!-- PGM will replace "${team_size}" and "${max}" placeholder with the new value -->
<constant id="team_size">25</constant>
<constant id="overfill" delete="true"/> <!-- "max-overfill" will not exist when "Map Name" is loaded -->
<constant id="max">6</constant>
<if variant="5v5">
<constant id="team_size">5</constant>
<constant id="overfill">5</constant>
<constant id="max">3</constant>
</if>
<if variant="tournament">
<constant id="team_size">6</constant>
<constant id="overfill">6</constant>
<constant id="max" delete="true"/>
</if>

<team id="red" max="${team_size}" max-overfill="${overfill}"/>
<team id="blue" max="${team_size}" max-overfill="${overfill}"/>
<score>
<limit>${max}</limit> <!-- 6 in "Map Name", 3 in "Map Name: 5v5", non-existent in "Map Name: TE" -->
</score>
</map>
```
2 changes: 1 addition & 1 deletion docs/modules/general/proto.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<grounded/>` filter to check if the player is standing on the ground.
Expand Down
Loading