Skip to content

Commit

Permalink
Document server version, variant, & constant changes
Browse files Browse the repository at this point in the history
Signed-off-by: Pear <20259871+TheRealPear@users.noreply.github.com>
  • Loading branch information
TheRealPear committed Oct 28, 2024
1 parent 6af56ce commit acf8047
Showing 1 changed file with 32 additions and 4 deletions.
36 changes: 32 additions & 4 deletions docs/modules/general/main.mdx
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

0 comments on commit acf8047

Please sign in to comment.