# Configuration

`Waypoints` uses a configuration file located in:

* `data/config.lua`

This file controls localization, default waypoint settings, and rendering behavior.

### Localization

```lua
Locale = 'pl' -- 'en' or 'pl'
```

Defines which language should be used.

Supported values:

* `en`
* `pl`

To add a new language, copy `locales/en.json` and create your own language file.

***

### Default Waypoint Settings

These settings are applied to newly created waypoints by default.

```lua
Defaults = {
    drawDistance = 500.0,
    fadeDistance = 400.0,
    size = 1.0,
    icon = 'fa-solid fa-map-pin',
    color = '#4F46E5',
    displayDistance = true,
}
```

#### `drawDistance`

Defines the maximum distance at which the waypoint is rendered.

```lua
drawDistance = 500.0
```

This value is measured in meters.

#### `fadeDistance`

Defines the distance at which the marker begins to fade out.

```lua
fadeDistance = 400.0
```

This value should be less than or equal to `drawDistance`.

#### `size`

Defines the base size multiplier of the marker.

```lua
size = 1.0
```

#### `icon`

Defines the default Font Awesome icon used by the waypoint.

```lua
icon = 'fa-solid fa-map-pin'
```

#### `color`

Defines the default marker accent color in HEX format.

```lua
color = '#4F46E5'
```

#### `displayDistance`

Defines whether the waypoint shows live distance text.

```lua
displayDistance = true
```

Supported values:

* `true`
* `false`

***

### Rendering Configuration

These settings control technical rendering behavior and performance.

```lua
Rendering = {
    distanceUpdateInterval = 100,
    perspectiveDivisor = 5.0,
    checkpointBaseMultiplier = 2.0,
    smallMinScale = 100.0,
    smallAspectRatio = 2.0,
}
```

#### `distanceUpdateInterval`

Defines how often the displayed distance value updates.

```lua
distanceUpdateInterval = 100
```

This value is measured in milliseconds.

#### `perspectiveDivisor`

Defines how quickly the marker shrinks with distance.

```lua
perspectiveDivisor = 5.0
```

Higher values make the marker scale down faster.

#### `checkpointBaseMultiplier`

Defines the base size multiplier used for the rendered sprite.

```lua
checkpointBaseMultiplier = 2.0
```

#### `smallMinScale`

Defines the minimum distance at which simplified rendering mode is used.

```lua
smallMinScale = 100.0
```

This value is measured in meters.

#### `smallAspectRatio`

Defines the width-to-height ratio used in simplified rendering mode.

```lua
smallAspectRatio = 2.0
```

***

### Client Exports

All exports are client-side.

#### `Create(data)`

Creates a new waypoint and returns its numeric ID.

```lua
local id = exports['msk_waypoints']:Create({
    coords = vector3(x, y, z),
    icon = 'fa-solid fa-star',
    color = '#22C55E',
    size = 1.0,
    drawDistance = 500.0,
    displayDistance = true,
})
```

**Supported fields**

* `coords` — world position, required
* `icon` — optional custom icon
* `color` — optional custom color
* `size` — optional custom size
* `drawDistance` — optional custom render distance
* `displayDistance` — optional custom distance label setting

***

#### `Update(id, data)`

Updates an existing waypoint.

```lua
exports['msk_waypoints']:Update(id, {
    coords = vector3(x, y, z),
    color = '#EF4444',
    icon = 'fa-solid fa-flag',
    size = 1.5,
    drawDistance = 300.0,
})
```

***

#### `Remove(id)`

Removes a single waypoint by ID.

```lua
exports['msk_waypoints']:Remove(id)
```

***

#### `RemoveAll()`

Removes all active waypoints.

```lua
exports['msk_waypoints']:RemoveAll()
```

***

#### `Get(id)`

Returns the internal waypoint object for the given ID.

```lua
local waypoint = exports['msk_waypoints']:Get(id)
```

If the waypoint does not exist, this returns `nil`.

***

### DUI Rendering

Waypoints are rendered using pooled DUI instances.

This means:

* visible waypoints acquire a DUI instance when needed
* off-screen or distant waypoints release their DUI back into the pool
* unused DUI instances are recycled for performance

The marker UI supports:

* icon display
* diamond marker styling
* glow effects
* spinning ring effects
* optional live distance label

***

### Render Behavior

The resource uses separate internal loops for control and drawing.

#### Control loop

The control loop checks:

* whether waypoints are on screen
* whether they are inside draw distance
* when DUI instances should be acquired or released

#### Draw loop

The draw loop renders visible waypoint sprites every frame using:

* distance-based scaling
* perspective scaling
* alpha fade-out
* live distance updates

The built-in GPS waypoint is also created and removed automatically depending on whether the player has a map waypoint set.

***

### Notes

* GPS marker toggle state is saved through KVP
* Custom waypoints are removed automatically on resource stop
* `fadeDistance` should always be less than or equal to `drawDistance`
* Marker appearance is controlled through DUI messages
* No texture replacement is required


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mskscripts.gitbook.io/mskscripts/scripts/waypoints/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.