> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Customise Awoken UI's theme, components and behaviour.

All configuration lives in `config.lua` at the root of the `awoken_ui` resource. Every option belongs to the global `AwokenConfig` table.

```lua config.lua theme={"dark"}
--[[
    Awoken UI Configuration
    Edit these values to customize the UI to your liking.
    Changes take effect on resource restart.
]]

AwokenConfig = {
    -- Primary accent color for the entire UI (hex format)
    -- This color drives the theme - panels, borders, glows, and accents all derive from it
    -- Can also be set via convar: setr awoken:primaryColor "#00E5FF" in server.cfg
    -- The convar takes priority if set, allowing shared colour across all awoken resources
    primaryColor = GetConvar('awoken:primaryColor', '#00E5FF'),

    -- Disable specific UI components
    -- If disabled, ox_lib's default component will be used instead
    disabledComponents = {
        textUI = false,
        notify = false,
        progressBar = false,
        progressCircle = false,
        radial = false,
        skillCheck = false,
        inputDialog = false,
        contextMenu = false,
        alertDialog = false,
        listMenu = false,
    },

    -- Locale - language used for the UI's fixed text (buttons, hints, labels).
    -- Included: 'en' (English), 'de' (German), 'fr' (French), 'es' (Spanish),
    -- 'pl' (Polish), 'pt' (Portuguese - Portugal), 'pt-br' (Brazilian Portuguese).
    -- Edit any file in locales/ to change the wording, or copy one to add a new language.
    locale = 'en',

    -- Debug mode (prints debug info to console)
    debug = false,

    -- Default notification duration in ms (overridden if code specifies a custom duration)
    notificationDuration = 3000,

    -- Default notification position (overridden if code specifies a custom position)
    -- Options: 'top-right', 'top-center', 'top-left', 'bottom-right', 'bottom-center', 'bottom-left', 'center-right', 'center-left'
    notificationPosition = 'top-center',

    -- Notification size multiplier. 1.0 = default, 0.9 = 10% smaller, 1.2 = 20% larger.
    notificationScale = 1.0,

    -- Force every notification to the position above, ignoring positions requested by
    -- individual scripts - one setting instead of editing positions across many resources
    forceNotificationPosition = false,

    -- Default TextUI position (overridden if code specifies a custom position)
    -- Options: 'right-center', 'left-center', 'top-center', 'bottom-center'
    textUIPosition = 'right-center',

    -- Force every TextUI to the position above, ignoring positions requested by scripts
    forceTextUIPosition = false,

    -- Glow/outline around the TextUI panel in the primary colour
    -- Set to false for a cleaner finish with a subtle neutral border instead
    textUIGlow = true,

    -- Progress bar variant: 'primary' or 'secondary'
    -- primary = full glass panel bar, secondary = minimal thin bar
    progressBarVariant = 'primary',

    -- Key to cancel progress bar (lowercase)
    progressCancelKey = 'x',

    -- Radial menu open mode: 'press' (toggle) or 'hold' (held open)
    radialOpenMode = 'press',

    -- Radial menu open key
    radialOpenKey = 'z',

    -- Skill check variant: 'circle' or 'bar'
    skillcheckVariant = 'circle',

    -- Context menu position: 'right' or 'left'
    contextMenuPosition = 'right',

    -- Alert dialog variant: 'standard' or 'fullscreen'
    -- standard = light backdrop dim, world still visible
    -- fullscreen = heavy dark backdrop with blur, fully isolates the dialog
    alertDialogVariant = 'standard',

    -- Which side the confirm button sits on: 'right' or 'left'
    -- right (default) = Cancel on the left, Confirm on the right
    -- left = Confirm on the left, Cancel on the right
    alertConfirmPosition = 'right',

}
```

<Tip>
  Colour values are injected as CSS variables at runtime, so changes apply after a simple `ensure awoken_ui` - no rebuild required.
</Tip>

## Language & text

Every fixed string the UI shows - the context menu's **Close** / **Press ESC** / **Available Options** labels, dialog buttons, the **Press X to cancel** hint, skill-check prompts and more - lives in the `locales/` folder. Each file returns a simple table of `key = "text"` pairs, so you can translate the UI or just reword it to match your server.

### Included languages

Set `locale` in `config.lua` to any of the bundled codes:

| Code    | Language              |
| :------ | :-------------------- |
| `en`    | English               |
| `de`    | German                |
| `fr`    | French                |
| `es`    | Spanish               |
| `pl`    | Polish                |
| `pt`    | Portuguese (Portugal) |
| `pt-br` | Brazilian Portuguese  |

```lua config.lua theme={"dark"}
locale = 'fr', -- file name in locales/ without the .lua
```

### Changing the wording

Open `locales/en.lua` (or whichever language you use) and edit the text inside the quotes. Leave the keys on the left untouched.

```lua locales/en.lua theme={"dark"}
return {
    context_close            = 'Close',
    context_closeHint        = 'Press ESC',
    context_availableOptions = 'Available Options',
    -- ...
}
```

### Adding a new language

1. Copy `locales/en.lua` to a new file, e.g. `locales/it.lua`.
2. Translate the text on the right-hand side of each line.
3. Set `locale = 'it'` in `config.lua`.

<Tip>
  English is always loaded as the base, so any key you remove, mistype, or haven't translated yet falls back to English - a partial translation will never break the UI. Locale files are read at runtime, so changes apply after a simple `ensure awoken_ui` with no rebuild.
</Tip>

## Global Awoken colour

Set the primary colour globally for Awoken UI, Awoken Target, and other Awoken resources via your `server.cfg`. This convar overrides the `primaryColor` setting in `config.lua`.

```cfg server.cfg theme={"dark"}
# Awoken primary accent colour (default: #00E5FF)
setr awoken:primaryColor "#00E5FF"
```

This allows you to theme all Awoken resources with a single setting.

## Awoken Target icon

The targeting reticle that appears on screen when ox\_target is active can be changed via the `awoken:targetIcon` convar. Set it once in `server.cfg`, restart ox\_target, and the icon swaps for every player.

```cfg server.cfg theme={"dark"}
# Awoken Target reticle (default: crosshair)
setr awoken:targetIcon "crosshair"
```

### Built-in presets

Five SVG presets ship with the resource. All five inherit your primary colour automatically through `currentColor`, so there's nothing else to configure once you pick one.

| Value       | Description                                                              |
| :---------- | :----------------------------------------------------------------------- |
| `crosshair` | Two concentric rings with a centre dot and four tick marks. The default. |
| `dot`       | Single filled circle. Minimal, no rings.                                 |
| `plus`      | Plain plus sign with no rings or dot.                                    |
| `bullseye`  | Two concentric rings with a fully filled centre.                         |
| `eye`       | Almond eye outline with a small pupil.                                   |

### FontAwesome icons

You can also pass any FontAwesome 6 Solid class name prefixed with `fa-`. The icon inherits your accent colour the same way the presets do.

```cfg server.cfg theme={"dark"}
setr awoken:targetIcon "fa-bullseye"
setr awoken:targetIcon "fa-crosshairs"
setr awoken:targetIcon "fa-hand-pointer"
setr awoken:targetIcon "fa-location-crosshairs"
setr awoken:targetIcon "fa-circle-dot"
```

<Tip>
  Anything that isn't a recognised preset name or a `fa-` class falls back to `crosshair`, so a typo or unset convar won't break the reticle.
</Tip>