### Get Map and Directory Paths

Source: https://pwitvoet.github.io/mess/template-functions

These functions provide access to file paths and directories relevant to the current map and MESS installation. `map_path()` returns the current map file path, `map_dir()` returns its directory, `templates_dir()` returns the templates directory, `ted_dirs()` returns template entity directories, `ted_path()` resolves a relative path within template directories, and `mess_dir()` returns the MESS executable directory.

```MESS Script
string map_path()
string map_dir()
string templates_dir()
array ted_dirs()
string ted_path(string relative_path)
string mess_dir()
```

--------------------------------

### MESS MScript Function: ted_dir() Example

Source: https://pwitvoet.github.io/mess/rewrite-rules

Provides an example of using the `ted_dir()` MScript function within a .ted file. This function returns the directory or .zip file path containing the current .ted file.

```plaintext
// Example usage of ted_dir() in a .ted file
// The output might be like: 'C:\HL\Tools\MESS\template_entities\my_templates.zip'
// or 'C:\HL\Tools\MESS\template_entities\my_templates'
```

--------------------------------

### MESS Rewrite Rule Syntax Examples

Source: https://pwitvoet.github.io/mess/rewrite-rules

Demonstrates the basic syntax for MESS rewrite rules, including property overwriting and deletion. These rules are ignored by FGD readers as they are commented out.

```plaintext
// @MESS REWRITE:
// "property-name": "new-value"
// delete "property-name"
// @MESS;
```

--------------------------------

### Trim Characters from Start of String

Source: https://pwitvoet.github.io/mess/data-types

Returns a copy of a string with specified characters removed from the beginning. If no characters are specified, whitespace is removed.

```string
string trimstart(string chars = none)
```

--------------------------------

### Array Slicing and Subsetting

Source: https://pwitvoet.github.io/mess/data-types

Illustrates how to extract sub-arrays using the slice, skip, and take functions. Slice allows specifying start, end, and step, while skip and take are for removing initial elements or keeping initial elements, respectively.

```javascript
let arr = ['A', 'B', 'C', 'D'];
console.log(arr.slice(1, 3)); // Output: ['B', 'C']
console.log(arr.skip(2)); // Output: ['C', 'D']
console.log(arr.take(2)); // Output: ['A', 'B']
```

```python
arr = ['A', 'B', 'C', 'D']
print(arr[1:3]) # Slice
print(arr[2:]) # Skip first 2
print(arr[:2]) # Take first 2
```

--------------------------------

### MScript String Length Property

Source: https://pwitvoet.github.io/mess/data-types

Demonstrates how to get the length of a string in MScript using the '.length' property. This property returns the number of characters in the string.

```MScript
'hello'.length
```

--------------------------------

### Get Function Argument Info

Source: https://pwitvoet.github.io/mess/standard-functions

Retrieves information about a specific parameter of a given function. It returns an object containing details like name, type, optional status, and default value. Returns 'none' if the function or parameter is not found.

```pseudocode
object func_arg(function func, string name)
// Returns an object with information about the specified function parameter, or `none` if the given function is `none` or if the parameter does not exist.
// For example, `func_arg(range, 'step')` returns `{name: 'step', type: 'number', optional: 1, default_value: none}`.
```

--------------------------------

### MScript String startswith() Method

Source: https://pwitvoet.github.io/mess/data-types

Illustrates checking if a string begins with a specified prefix in MScript using the 'startswith' method. Case sensitivity can be controlled.

```MScript
'firestorm'.startswith('fire')
```

--------------------------------

### Select Random Item from Array with randitem()

Source: https://pwitvoet.github.io/mess/template-functions

The `randitem` function selects a random item from a given array. An optional array of weights can be provided to influence the probability of selection for each item. Items with weights less than or equal to 0 are not selected. If all weights are 0 or less, `none` is returned.

```MScript
any randitem(array items)
any randitem(array items, array weights)
```

--------------------------------

### Trim Characters from String

Source: https://pwitvoet.github.io/mess/data-types

Returns a copy of a string with specified characters removed from both the start and end. If no characters are specified, whitespace is removed.

```string
string trim(string chars = none)
```

--------------------------------

### Generate Random Integers with randi()

Source: https://pwitvoet.github.io/mess/template-functions

The `randi` function generates pseudo-random integers. It can be called with no arguments (returning 0 or 1), one argument (returning a number between 0 and the argument, exclusive), two arguments (returning a number between the two arguments, exclusive of the upper bound), or three arguments (adding a step to the possible returned values).

```MScript
number randi()
number randi(number max)
number randi(number min, number max)
number randi(number min, number max, number step)
```

--------------------------------

### Array Indexing and Properties

Source: https://pwitvoet.github.io/mess/data-types

Demonstrates accessing array elements by index, including negative indexing, and retrieving the array's length. It also shows how to access specific elements as positional, angular, or color values if they are numbers.

```javascript
let arr = [1, 2, 3];
console.log(arr.length); // Output: 3
console.log(arr[0]); // Output: 1
console.log(arr[-1]); // Output: 3
console.log(arr.x); // Output: 1
console.log(arr.y); // Output: 2
console.log(arr.z); // Output: 3
```

```python
arr = [1, 2, 3]
print(len(arr))
print(arr[0])
print(arr[-1])
# Note: Direct access like arr.x is not standard Python for lists.
# You would typically use indexing or specific libraries for such access.
```

--------------------------------

### Count Substring Occurrences

Source: https://pwitvoet.github.io/mess/data-types

Counts the number of non-overlapping occurrences of a substring within a string. Supports case-insensitive search and an offset to start counting from a specific position.

```string
number count(string str, number offset = none, bool ignore_case = false)
```

--------------------------------

### Manage Global Variables with getglobal(), setglobal(), useglobal(), incglobal()

Source: https://pwitvoet.github.io/mess/template-functions

These functions allow for managing global variables to share information between entities. `getglobal(name)` retrieves a variable's value, `setglobal(name, value)` sets or updates a variable, `useglobal(name)` initializes a variable if it doesn't exist, and `incglobal(name)` increments a global variable (though its specific implementation is not detailed here).

```MESS Script
any getglobal(string name)
any setglobal(string name, any value)
bool useglobal(string name)
void incglobal(string name)
```

--------------------------------

### Find First Index of Value

Source: https://pwitvoet.github.io/mess/data-types

Finds the index of the first occurrence of a given value in an array. An optional offset can be provided to start the search from a specific position. Returns `none` if the value is not found.

```javascript
const arr = ['B', 'A', 'B', 'A'];
console.log(arr.index('A')); // Output: 1
```

--------------------------------

### Find Last Occurrence of Substring

Source: https://pwitvoet.github.io/mess/data-types

Returns the index of the last occurrence of a substring within a string. Supports case-insensitive search and an offset to start searching from a specific position. Returns 'none' if the substring is not found.

```string
number|none lastindex(string str, number offset = none, bool ignore_case = false)
```

--------------------------------

### Find First Occurrence of Substring

Source: https://pwitvoet.github.io/mess/data-types

Returns the index of the first occurrence of a substring within a string. Supports case-insensitive search and an offset to start searching from a specific position. Returns 'none' if the substring is not found.

```string
number|none index(string str, number offset = 0, bool ignore_case = false)
```

--------------------------------

### MScript String equals() Method

Source: https://pwitvoet.github.io/mess/data-types

Shows how to compare two strings for equality in MScript using the 'equals' method. It supports optional case-insensitive comparison.

```MScript
'abc'.equals('ABC', 1)
```

--------------------------------

### Find Last Index of Value

Source: https://pwitvoet.github.io/mess/data-types

Finds the index of the last occurrence of a given value in an array. An optional offset can be provided to start the search from a specific position, searching backwards. Returns `none` if the value is not found.

```javascript
const arr = ['B', 'A', 'B', 'A'];
console.log(arr.lastindex('B')); // Output: 2
```

--------------------------------

### Array Transformation and Aggregation

Source: https://pwitvoet.github.io/mess/data-types

Explains functional programming methods like map for transforming elements, reduce for aggregating values, and sort/reverse for reordering. Also covers numerical aggregations like max, min, and sum.

```javascript
let arr = [1, 2, 3, 4];
console.log(arr.map(x => x * 2)); // Output: [2, 4, 6, 8]
console.log(arr.reduce((sum, x) => sum + x, 0)); // Output: 10
console.log(arr.sort((a, b) => a - b)); // Output: [1, 2, 3, 4]
console.log(arr.reverse()); // Output: [4, 3, 2, 1]
console.log(arr.max()); // Output: 4
console.log(arr.min()); // Output: 1
console.log(arr.sum()); // Output: 10
```

```python
arr = [1, 2, 3, 4]
print(list(map(lambda x: x * 2, arr))) # Map
print(sum(arr)) # Sum (also reduce)
print(sorted(arr)) # Sort
arr.reverse() # Reverse (in-place)
print(max(arr))
print(min(arr))
```

--------------------------------

### Map Format

Source: https://pwitvoet.github.io/mess/convert-options

Specify the format of the output .map file.

```APIDOC
## -mapformat FORMAT

The output .map format. Available options are:
  * `valve220` - The 'standard' valve220 .map format. This is the default value.
  * `trenchbroomvalve220` - The TrenchBroom variant of the standard valve220 format. This file format uses `func_group` entities and TrenchBroom-specific properties to store groups and layers (VIS groups).
```

--------------------------------

### Texture Name Handling

Source: https://pwitvoet.github.io/mess/convert-options

Configure how spaces in texture names are handled during map export. Options include replacing spaces, ignoring them, or failing the conversion.

```APIDOC
## -invalidtexturename INVALID_TEXTURE_HANDLING

The .map file format does not allow texture names to contain spaces. This option determines what should happen if a texture name does contain a space:
  * `replace` - Spaces are replaced by the value of `-texturenamereplacement` (which by default is an underscore: `_`). This is the default behavior.
  * `ignore` - Spaces are ignored. If the output format is .map, the resulting .map file will be invalid.
  * `fail` - File conversion will fail with an error message.

## -texturenamereplacement TEXT

If `-invalidtexturename` is set to `replace` (the default behavior), spaces in texture names are replaced with the value of this setting. The default value is an underscore (`_`). Setting this to an empty string (`-texturenamereplacement ""`) will cause spaces to be removed.
```

--------------------------------

### Text Functions: Unicode Character Conversion

Source: https://pwitvoet.github.io/mess/standard-functions

Includes functions to get the Unicode value of a character (ord) and to create a character from a Unicode value (chr). These functions handle string and number inputs and return string or number outputs.

```mess
number ord(string str)
number ord(string str, number index)
string chr(number value)
```

--------------------------------

### Apply Function with Arguments

Source: https://pwitvoet.github.io/mess/standard-functions

Executes a given function with a provided array of arguments. It returns the result of the function call. If the function is 'none', it returns 'none'.

```pseudocode
object func_apply(function func, array arguments)
// Calls the given function with the given arguments and returns the result. Returns `none` if the given function is `none`.
// For example, `func_apply(min, [3, 4])` returns `3`.
```

--------------------------------

### Instance ID Functions

Source: https://pwitvoet.github.io/mess/template-functions

Functions for retrieving instance-specific identifiers, useful for creating unique entity names within template instances.

```APIDOC
## Instance ID Functions

### Description
Functions to get the `targetname` of the macro entity creating the current instance, or the unique ID of the current instance if the `targetname` is empty. These are useful for ensuring unique entity names within template instances.

### Functions

#### `string id()`

*   **Description**: Returns the `targetname` of the macro entity that is creating the current instance, or the unique ID of the current instance if the `targetname` is empty. The return value is always a string.
*   **Example**: If a `macro_insert` named `fire1` creates a template instance, and that template has an `env_beam` named `{id()}_beam`, the resulting entity will be named `fire1_beam`.

#### `number iid()`

*   **Description**: Returns the unique ID of the current instance, as a number.
*   **Example**: If a template contains a `func_button` named `btn_{iid()}`, and the current instance ID is `15`, the resulting `func_button` will be named `btn_15`.

#### `number parentid()`

*   **Description**: Returns the unique ID of the macro entity that is creating the current instance. This ID is not related to instance IDs.
*   **Example**: If a `macro_insert` creates multiple template instances, and a template entity is named `spr_{parentid()}`, and the macro entity's unique ID is `20`, all resulting sprites will be named `spr_20`.

#### `number nth()`

*   **Description**: Returns the sequence number of the current instance. The first instance created by a macro entity is `0`, the second is `1`, and so on.
*   **Example**: If a `macro_insert` with `instance_count` of `5` creates instances of a template with an `env_sprite` named `spr_{nth()}`, the result will be `env_sprite` entities named `spr_0`, `spr_1`, `spr_2`, `spr_3`, and `spr_4`.
*   **Usage in Macro**: Can be used in the macro entity itself. Setting `instance_offset` to `{nth() * 32} 0 0` positions subsequent instances 32 units to the right of the previous one.
```

--------------------------------

### JMF File Version

Source: https://pwitvoet.github.io/mess/convert-options

Specify the version of the output .jmf file.

```APIDOC
## -jmfversion VERSION

The output .jmf file version. Available options are:
  * `v121` - The most common version, before the J.A.C.K. 1.1.3773 update.
  * `v122` - The latest version as of early 2024, which introduces background images for the 2D views. This is the default version.
```

--------------------------------

### Randomize Instance Angles and Scale (Scripting)

Source: https://pwitvoet.github.io/mess/covering-terrain-with-props

This script randomizes the 'Instance angles' and 'Instance scale' properties for terrain objects. It uses the `rand()` function to generate values within specified ranges, making objects appear more natural. No external dependencies are required.

```scripting
Instance angles (Pitch Yaw Roll) | `0 {rand(0, 360)} 0`
Instance scale | `{rand(0.5, 1.25)}`
```

--------------------------------

### RMF File Version

Source: https://pwitvoet.github.io/mess/convert-options

Specify the version of the output .rmf file.

```APIDOC
## -rmfversion VERSION

The output .rmf file version. Available options are:
  * `v1_6` - Used by Worldcraft 1.5b.
  * `v1_8` - Used by Worldcraft 1.6 to 2.1. This version increases the maximum length of texture names to 260.
  * `v2_2` - Used by Worldcraft 3.3 and Hammer 3.4 and 3.5. This version adds support for texture UV axis. This is the default version.
```

--------------------------------

### Access Parent Entity Properties with attr_count() and get_attr()

Source: https://pwitvoet.github.io/mess/template-functions

These functions provide access to the properties of the parent entity. `attr_count()` returns the number of visible properties, excluding 'special' ones. `get_attr()` can return all properties as an array of key-value objects, a specific property by its index (supporting negative indexes), or a specific property by its name. If a property is not found, `none` is returned.

```MScript
number attr_count()
array get_attr()
object|none get_attr(number index)
object|none get_attr(string name)
```

--------------------------------

### MESS Rewrite Rule Execution Timing: AFTER_MACRO_EXPANSION

Source: https://pwitvoet.github.io/mess/rewrite-rules

Demonstrates how to specify that rewrite rules should be applied after macro expansion using the AFTER_MACRO_EXPANSION keyword. This is useful for cleanup or fixing properties after macros have been processed.

```plaintext
// @MESS REWRITE AFTER_MACRO_EXPANSION WHEN "{_tb_group}":
//   // delete "_tb_group"
// // @MESS;
```

--------------------------------

### Log Values with trace for Debugging

Source: https://pwitvoet.github.io/mess/template-functions

Writes a value and an optional message to the log file, returning the original value. This function aids in debugging by allowing inspection of variable states within scripts or templates without altering execution flow.

```scripting
trace(any value, string message)
```

```scripting
trace(any value)
```

--------------------------------

### WAD File Specification

Source: https://pwitvoet.github.io/mess/convert-options

Specify the WAD files to be loaded by the map.

```APIDOC
## -wad NAMES

When exporting to a .map file, this setting sets the `wad` map property (a special property in the `worldspawn` entity). This property tells the game which .wad files to load. Multiple wad names must be separated by semicolons.
.map files that are meant to be compiled only need to contain .wad filenames: `halflife.wad;liquids.wad`. .map files that are meant to be edited by TrenchBroom should use relative or absolute paths: `valve/halflife.wad;valve/liquids.wad`.
```

--------------------------------

### Manage Entity Spawnflags with hasflag() and setflag()

Source: https://pwitvoet.github.io/mess/template-functions

These functions interact with the special `spawnflags` property of an entity. `hasflag(flag, flags)` checks if a specific flag is set within the provided flags value. `setflag(flag, set, flags)` sets or unsets a specific flag within the provided flags value, returning the updated flags. These are used in conjunction with the `_mess_spawnflagN` properties for scripting flag manipulation.

```MScript
boolean hasflag(number flag, number flags)
number setflag(number flag, boolean set, number flags)
```

--------------------------------

### Convert String to Lowercase

Source: https://pwitvoet.github.io/mess/data-types

Returns a copy of a string with all characters converted to lowercase.

```string
string lower()
```

--------------------------------

### Convert String to Uppercase

Source: https://pwitvoet.github.io/mess/data-types

Returns a copy of a string with all characters converted to uppercase.

```string
string upper()
```

--------------------------------

### Find All Regular Expression Matches

Source: https://pwitvoet.github.io/mess/data-types

Returns an array containing all non-overlapping occurrences of a regular expression pattern found within the string.

```string
array matches(string pattern)
```

--------------------------------

### Convert .rmf or .jmf to TrenchBroom .map

Source: https://pwitvoet.github.io/mess/file-conversion

Converts a .jmf file to a TrenchBroom .map file, with options to specify map format, game name, and WAD files.

```APIDOC
## POST /convert/rmf-jmf-to-trenchbroom

### Description
Converts a .jmf file to a TrenchBroom .map file. This includes options to specify the map format for TrenchBroom, the game name, and WAD files.

### Method
POST

### Endpoint
/convert

### Parameters
#### Query Parameters
- **input_file** (string) - Required - The path to the input .jmf file.
- **output_file** (string) - Required - The path for the output TrenchBroom .map file.
- **mapformat** (string) - Optional - Specifies the map format for TrenchBroom (e.g., "trenchbroomvalve220"). Defaults to a standard format if not provided.
- **tbgame** (string) - Optional - Sets the TrenchBroom game name (e.g., "Half-Life").
- **wad** (string) - Optional - Sets the map's WAD property, can be a semicolon-separated list (e.g., "halflife.wad;liquids.wad").

### Request Example
```bash
MESS.exe -convert -mapformat trenchbroomvalve220 -tbgame "Half-Life" -wad "halflife.wad;liquids.wad" input_file.jmf output_file.map
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of successful conversion.
```

--------------------------------

### Array Properties

Source: https://pwitvoet.github.io/mess/data-types

Explains the properties available for arrays, such as length and context-specific properties like x, y, z, pitch, yaw, roll, r, g, b, and brightness.

```APIDOC
## Array Properties

### `number length`
Returns the number of items in this array.
For example, `['A', 'B', 'C'].length` returns `3`.

### Position, angles and colors
Arrays contain a few properties that don't make sense in all contexts, but they can be convenient when working with positions, angles and colors.

#### `number|none x`
`number|none y`
`number|none z`
These properties return the first, second and third item respectively, but only if they are a number. For example, `[1, 2, 3].x` returns `1`, but `['A', 'B', 'C'].y` returns `none`.

#### `number|none pitch`
`number|none yaw`
`number|none roll`
These properties also return the first, second and third item respectively, if they are a number.

#### `number|none r`
`number|none g`
`number|none b`
`number|none brightness`
Once more, these properties return the first, second, third and fourth items respectively, if they are a number.
```

--------------------------------

### Array Functions: Range and Repetition

Source: https://pwitvoet.github.io/mess/standard-functions

Provides functions for creating arrays. 'range' generates a sequence of numbers, while 'repeat' creates an array by duplicating a given value. These functions accept numeric or any type of input and return arrays.

```mess
array range(number stop)
array range(number start, number stop)
array range(number start, number stop, number step)
array repeat(any value, number count)
```

--------------------------------

### Setting Spawn Flags with MScript in MESS

Source: https://pwitvoet.github.io/mess/entity-properties

Explains how to use special properties like `_mess_spawnflagN` to dynamically enable or disable specific spawn flags for an entity using MScript. These properties are removed after processing.

```MScript
key | value
---
`classname`| `env_beam`
`_mess_spawnflag0`| `{start_on}`
`_mess_spawnflag2`| `{enable_random_strike_time}`
```

```MScript
key | value
---
`classname`| `env_beam`
`spawnflags`| `5`
```

--------------------------------

### Array Member Functions - Cutting and Combining

Source: https://pwitvoet.github.io/mess/data-types

Provides information on functions for manipulating arrays by cutting, combining, or modifying their contents, such as slice, skip, take, first, last, concat, prepend, append, and insert.

```APIDOC
## Array Member Functions - Cutting and Combining

### `array slice(number start, number end = none, number step = 1)`
Returns a new array by taking specific items from this array. By default, the result will contain all items between the start index (inclusive) and the end index (exclusive). If no end is given, then items will be taken until the end of the array is reached. Both start and end index can be negative.
The `step` argument lets you skip elements or invert the result. For example, a `step` value of `2` will skip every second item, and a `step` value of `-1` will pick items in reversed order.
For example, `['A', 'B', 'C', 'D'].slice(1, 3)` returns `['B', 'C']`.

### `array skip(number count)`
Returns a new array that contains all but the first `count` items from this array.
For example, `['A', 'B', 'C'].skip(2)` returns `['C']`.

### `array take(number count)`
Returns a new array that contains only the first `count` items from this array.
For example, `['A', 'B', 'C'].take(2)` returns `['A', 'B']`.

### `any first()`
Returns the first item from the array, or `none` if the array is empty.
For example, `['A', 'B', 'C'].first()` returns `'A'`.

### `any last()`
Returns the last item from the array, or `none` if the array is empty.
For example, `['A', 'B', 'C'].last()` returns `'C'`.

### `array concat(array other)`
Returns a new array with the items from the given array added at the end.
For example, `['A', 'B', 'C'].concat(['X', 'Y', 'Z'])` returns `['A', 'B', 'C', 'X', 'Y', 'Z']`.

### `array prepend(any value)`
Returns a new array with the given value added at the start.
For example, `['A', 'B', 'C'].prepend('Z')` returns `['Z', 'A', 'B', 'C']`.

### `array append(any value)`
Returns a new array with the given value added at the end.
For example, `['A', 'B', 'C'].append('Z')` returns `['A', 'B', 'C', 'Z']`.

### `array insert(number index, any value)`
Returns a new array with the given value inserted at the given index. The index can be negative.
For example, `['A', 'B', 'C'].insert(2, 'Z')` returns `['A', 'B', 'Z', 'C']`.
```