# How to read this documentation

The goal of this documentation is to be a quick reference/manual for regular users, instead of a technical documentation. It should be easily readable by users without too much technical knowledge of the mod. However, there are certain aspects that you as a reader should be aware of when it comes to how the information is presented.

---

## Cvar values

Valid values for cvars are presented in few different ways.

Value                | Explanation
|:-------------------|:----------------------
any integer          | Any whole number. The cvar ignores decimal values and truncates the number, meaning `2.2` and `2.9` both evaluate to `2`.
any value            | Any floating point number (a number with decimals), e.g. `2.5`.
any positive integer | Any whole number equal to or higher than `0`.
any positive value   | Any floating point number equal to or higher than `0.0`.
0 or 1               | Toggle cvar, `0` means disabled, `1` means enabled.
0 - 5                | A whole number within range `0 - 5`.
0.0 - 5.0            | A floating point number within range `0.0 - 5.0`.
bitflag              | A combined value of "flags". Valid values for the flags are listed under the cvar explanation. Adding the desired flag values together represents the final value. For example, a cvar might have flags `1`, `2`, and `4`. If you want to enable flags `1` and `4`, you add them together `1 + 4 = 5`, which is the final value.
any color            | Takes a color string as an input, see [color system](getting_started.md/#color-system) for more information.
size/scale (range)   | Takes a size or scale value as an input, see [size & scale system](getting_started.md/#size--scale-system) for more information.
any string           | Takes in a string literal. This might sometimes be listed with a context-specific name, such as `filename` or `directory`.

```{note}
ET handles cvar values internally as 32-bit values. For simplicitys sake, this documentation doesn't explicitly define the numeric limits of 32-bit values everywhere, but says that you can use "any" value for them. In reality, there are limitations:

* Valid range for integers is `-2147483648 - 2147483647`.
* Valid range for floating point numbers is `-3.40282e+38 - 3.40282e+38`.
* Maximum length for a string value is **256** characters.
  * This includes color codes where applicable.

Unless a cvar explicitly defines the valid values with a range, these are the limitations for a given cvar's value.
```

---

## Commands

ETJump has many commands that are accessible to clients, either as [console commands](client/client_commands.md) or via the [admin system](server/admin_system.md). These commands often take in one ore more arguments. The way these arguments are presented in the documentation uses the following format:

* arguments in `<angle brackets>` or in plain text are **mandatory**.
* arguments in `[square brackets]` are optional.
* values separated with `|` are valid values for a given argument
* values in `(parentheses)` specify a valid range of values for a given argument.
  * values can be specified inside angle or square brackets, e.g. `<value (1-5)>` or `[value <a|b|c>]`.

```{note}
In some examples, the valid values are broken down to separate examples to simplify reading.
```

These can be combined within a single argument. For example, it's possible to have an `[optional argument <with mandatory value (and range of valid values)>]`.

Let's take a look at a few examples from the [admin system](server/admin_system.md).

Command                                                                                   | Explanation
:-----------------------------------------------------------------------------------------|:-----------------------------------------------------------------
`!8ball <question>`                                                                       | Takes a single mandatory argument, `<question>`. 
`!help [command]`                                                                         | Takes a single optional argument, `[command]`.
`!loadcheckpoints <run name> [rank]`                                                      | Takes a single mandatory argument, `<run name>`, and an optional argument `[rank]`.
`!moverscale <value (0.1-5.0)>`                                                           | Takes a single mandatory argument, `<value>`, which has a valid range of `(0.1-5.0)`
`!add-season --name <name> --start-date <YYYY-MM-DD> [--end-date-exclusive <YYYY-MM-DD>]` | Takes two mandatory arguments, `--name <name>` and `--start-date <YYYY-MM-DD>`, and an optional argument `--end-date-exclusive`, which if given, requires a mandatory value `<YYYY-MM-DD>`.
`!tokens delete [easy\|e\|medium\|m\|hard\|h <number (1-32)>]`                            | Takes a single mandatory argument, `delete` and an optional argument with one of the values `easy\|e\|medium\|m\|hard\|h`, which if given, requires a mandatory value `<number>` in the range of `(1-32)`.