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

Jump to bottom

Document server version, variant, & constant changes #149

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Document server version, variant, & constant changes #149

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
36 changes: 32 additions & 4 deletions docs/modules/general/main.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,16 @@ 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` |
| `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 Down Expand Up @@ -141,6 +143,7 @@ Additionally, a variant can also contain constants, which allows you to define t
| 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 |

Expand All @@ -155,10 +158,34 @@ Additionally, a variant can also contain constants, which allows you to define t

| Attribute | Description | Value |
|---|---|---|
| `variant` | The name of the variant to target. | <span className="badge badge--primary">Variant ID</span> |
| `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> |

**Note:** Multiple variants can be targeted as long as it is separated with a comma (`,`).
| `min-server-version` | The minimum server version this variant can run on. |
| `max-server-version` | The maximum server version this variant can run on. |
| `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.
Expand All @@ -178,6 +205,7 @@ PGM will search and replace any corresponding placeholders (`${constant_id}`) wi
|---|---|---|---|
| `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 |

The following example utilizes both map variants and constant.
```xml
Expand Down