> For the complete documentation index, see [llms.txt](https://tg-dev.gitbook.io/tg-dev-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tg-dev.gitbook.io/tg-dev-docs/tg-waypoint/config.md).

# Config

### Basic Configuration

Main configuration file:

```
config/config.lua
```

Most users only need these settings:

```lua
Config.General = {
    Locale = 'en',
    OpenSettingsCommand = 'wpmenu',
    DistanceUnit = 'mi',
    ShowStreetName = true,
    KvpKey = 'tg-waypoint:ui-settings'
}
```

#### General Options

| Option                | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| `Locale`              | UI language. Included: `en`, `tr`, `de`, `fr`, `es`.                                            |
| `OpenSettingsCommand` | Command used to open the settings menu. Default: `/wpmenu`.                                     |
| `DistanceUnit`        | Distance format. Use `mi` or `km`.                                                              |
| `ShowStreetName`      | Shows or hides the waypoint street name.                                                        |
| `KvpKey`              | Per-player saved settings key. Change this only if you want to reset all saved player settings. |

### Default UI Settings

Default waypoint UI values are configured in `Config.UiSettings`. These values are used when a player joins for the first time or when they reset their settings to defaults.

Players can change most of these options from the in-game settings menu. Saved player settings override these defaults.

```lua
Config.UiSettings = {
    performanceMode = 'optimized',

    turnMarkerSettings = {
        enabled = false,
        type = 2,
        scale = 1.15,
        count = 5,
        spacing = 1.5,
        opacity = 255,
        upDownEffect = false,
        breathingEffect = false
    },

    profiles = {
        onfoot = {
            opacity = 1.0,
            scale = 1.3,
            background = 1.0,
            arrowColor = '#ffbe5c',
            backdropColor = '#0c1018',
            textColor = '#ffffff',
            arrowPreset = 'native',
            fontPreset = 'aldrich'
        },

        vehicle = {
            opacity = 1.0,
            scale = 1.3,
            background = 1.0,
            arrowColor = '#ffbe5c',
            backdropColor = '#0c1018',
            textColor = '#ffffff',
            arrowPreset = 'native',
            fontPreset = 'aldrich'
        }
    },

    displayMode = 'always'
}
```

#### Main UI Options

| Option               | Description                                     |
| -------------------- | ----------------------------------------------- |
| `performanceMode`    | Default update mode. Use `optimized` or `high`. |
| `displayMode`        | Controls when the waypoint UI is visible.       |
| `profiles`           | Separate UI settings for walking and driving.   |
| `turnMarkerSettings` | Default road turn marker settings.              |

#### Display Modes

| Value     | Description                                      |
| --------- | ------------------------------------------------ |
| `always`  | Show the waypoint UI whenever a waypoint exists. |
| `never`   | Never show the waypoint UI.                      |
| `vehicle` | Show only while driving.                         |
| `onfoot`  | Show only while walking.                         |

#### Profiles

`Config.UiSettings.profiles` contains two profiles:

| Profile   | Used When                   |
| --------- | --------------------------- |
| `vehicle` | Player is inside a vehicle. |
| `onfoot`  | Player is walking.          |

Each profile has its own opacity, scale, background strength, colors, arrow style, and font.

| Option          | Range / Values | Description                          |
| --------------- | -------------- | ------------------------------------ |
| `opacity`       | `0.2` - `1.0`  | Overall waypoint UI opacity.         |
| `scale`         | `0.1` - `1.5`  | Waypoint UI size.                    |
| `background`    | `0.2` - `1.0`  | Backdrop/background strength.        |
| `arrowColor`    | Hex color      | Arrow color. Example: `#ffbe5c`.     |
| `backdropColor` | Hex color      | Background/backdrop color.           |
| `textColor`     | Hex color      | Street name and distance text color. |
| `arrowPreset`   | See below      | Waypoint arrow style.                |
| `fontPreset`    | See below      | Waypoint text font.                  |

Available `arrowPreset` values:

```
minimal, cyber, tactical, native, rpg, speed, compact, pin
```

Available `fontPreset` values:

```
aldrich, oxanium, daysone, archivoblack, specialgothic, zendots
```

#### Turn Marker Settings

Turn markers are the road markers shown before turns.

| Option            | Range / Values             | Description                                  |
| ----------------- | -------------------------- | -------------------------------------------- |
| `enabled`         | `true` / `false`           | Enables or disables turn markers by default. |
| `type`            | `2`, `3`, `20`, `21`, `22` | GTA/FiveM marker type.                       |
| `scale`           | `0.2` - `3.0`              | Turn marker size.                            |
| `count`           | `1` - `8`                  | Number of markers drawn in a row.            |
| `spacing`         | `0.2` - `5.0`              | Space between markers.                       |
| `opacity`         | `0` - `255`                | Marker alpha/visibility.                     |
| `upDownEffect`    | `true` / `false`           | Enables vertical marker movement.            |
| `breathingEffect` | `true` / `false`           | Enables sequential marker fade animation.    |

Turn marker color follows the active profile `arrowColor` until the player changes marker color from the settings menu.

For example, while driving it follows `profiles.vehicle.arrowColor`. While walking it follows `profiles.onfoot.arrowColor`.

Colors must use hex format:

```
#RRGGBB
```

### Player Usage

Players can open the settings menu with:

```
/wpmenu
```

The command can be changed in:

```lua
Config.General.OpenSettingsCommand
```

Settings are saved per player automatically.

### Sharing Settings

The settings menu includes a Share panel.

* `Copy` creates a `TGWP1:` settings code.
* `Apply` loads a pasted `TGWP1:` code into the preview.
* `Save Configuration` must be pressed after applying a code to keep it permanently.

### Resetting Player Settings

Player settings are saved with FiveM KVP. To reset a single player, they can use the Reset Defaults button in the settings menu.

To force fresh settings for everyone, change:

```lua
Config.General.KvpKey = 'tg-waypoint:ui-settings-v2'
```

Use a new key name only when you intentionally want to ignore old saved settings.

### Localization

Language strings are in:

```
config/lang.lua
```

To change the language:

```lua
Config.General.Locale = 'en'
```

To add a new language, copy an existing locale block in `config/lang.lua`, translate the values, and set `Config.General.Locale` to the new key.