> ## 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.

# Overview

> Where every Awoken Chat setting lives and what it controls.

Awoken Chat splits its configuration across two places by design, so the file can't lie about what the runtime is actually using:

| Where                                   | What                                                                                                                                             | When changes apply                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| **`config.lua`**                        | Boot-only values: framework selection, antispam tuning, blocked-words list, webhooks URLs, permissions, profanity escalation.                    | On `restart awoken_chat`.                                                               |
| **`awoken_chat_categories`** (DB table) | Channels themselves and their per-channel flags (color, command, proximity, perms, job/gang filters, 3D, anonymity, etc.).                       | **Live**, via the in-game Category Manager (wrench icon, requires `awoken_chat.admin`). |
| **`awoken_chat_settings`** (DB table)   | Per-license player preferences (position, scale, font, primary colour, avatar, etc.) and the server-wide global tier (`license = '__global__'`). | Live, via the in-game Settings panel.                                                   |

<Tip>
  The Category Manager is the single source of truth for channels. `config.lua` intentionally has **no** `categories` block - the in-code defaults (`server/channels.lua`'s `AwokenChat.DEFAULT_CATEGORIES`) are seeded into the DB on first start, then the DB takes over. To restore the defaults: `TRUNCATE awoken_chat_categories;` and restart.
</Tip>

## `config.lua` at a glance

The file is sectioned top-to-bottom in the order a server owner usually touches things:

1. **Setup** - branding, framework, permissions
2. **Player display** - identity, tags, avatars
3. **Channels & 3D** - categories pointer, 3D text, fun commands
4. **Moderation** - antispam + blocked words, profanity escalation
5. **Logging** - Discord webhooks (channels, violations, fun commands)
6. **Feature toggles** - optional features, misc, boot-only defaults

```lua config.lua theme={"dark"}
AwokenChatConfig = {
    -- 1. SETUP
    primaryColor   = GetConvar('awoken:primaryColor', '#00E5FF'),
    locale         = 'en',
    debug          = false,
    framework      = 'auto',                -- 'auto' | 'qbox' | 'qbcore' | 'esx' | 'standalone'
    frameworkResources = { ... },
    permissions    = { admin = 'awoken_chat.admin', ... },

    -- 2. PLAYER DISPLAY
    identity = { nameSource = 'character', format = '{fullName}', ... },
    tags     = { ... },
    avatars  = { sources = { initials = true, url = true }, url = { ... } },

    -- 3. CHANNELS & 3D
    threeD       = { renderDistance = 25.0, durationMs = 5000, ... },
    funCommands  = { roll = true, coinflip = true, eightball = true, random = true, ... },

    -- 4. MODERATION
    antispam            = { enabled = true, maxMessages = 6, blockedWords = { ... }, ... },
    profanityEscalation = { enabled = true, rungs = { ... } },

    -- 5. LOGGING
    webhooks = { enabled = false, channels = {}, violations = '', funCommands = '' },

    -- 6. FEATURE TOGGLES
    features           = { privateMessages = true, mentions = true, ... },
    clickToReply       = true,
    emojiShortcodes    = true,
    allChannelFallback = false,
    defaults           = { historyLimit = 250, openKey = 'T', commandKey = 'F6', ... },
}
```

<Info>
  Every value below the section headers is documented inline in the file with one-line comments. The pages here are the longer-form explanation of *why* something is shaped the way it is.
</Info>

## Deep-dive pages

Each of the larger config areas has its own page so you can skim what you need without scrolling through the whole file:

* [**Categories & channels**](/resources/awoken-chat/configuration/categories) - the Category Manager UI, per-channel flags (anonymous, 3D-only, bypass antispam, etc.), job/gang filters, the first-start seed.
* [**Identity**](/resources/awoken-chat/configuration/identity) - `nameSource` (character vs account), format tokens, tags/badges.
* [**Avatars**](/resources/awoken-chat/configuration/avatars) - the initials/URL picker, allowlisted hosts, per-character storage.
* [**Antispam & moderation**](/resources/awoken-chat/configuration/antispam) - rate limiting, duplicate detection, blocked-words filter, profanity escalation ladder.
* [**Webhooks**](/resources/awoken-chat/configuration/webhooks) - per-channel Discord archives, violation log, fun-command audit log.
* [**Fun commands**](/resources/awoken-chat/configuration/fun-commands) - `/roll`, `/coinflip`, `/8ball`, `/random` - 3D-only, proximity-filtered, webhook-audited.
* [**3D text**](/resources/awoken-chat/configuration/3d-text) - `/me`-style overhead rendering, per-channel duration / distance overrides, the `3D only` flag.

## Convars

| Convar                    | Default   | Purpose                                                                                                                                                                    |
| ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `awoken:primaryColor`     | `#00E5FF` | Shared accent colour for every Awoken-branded resource. Players can override it for themselves in the in-game Settings panel; this value is the default for fresh players. |
| `resources_useSystemChat` | *(unset)* | FiveM engine setting. Set to `"false"` in `server.cfg` to hide the engine `[ALL]` MP chat widget.                                                                          |

## Permissions

| ACE                  | Purpose                                                                                                              | Granted via                                    |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `awoken_chat.admin`  | Open the Category Manager, save/delete categories, admin-delete messages, push server-wide visual settings.          | `add_ace group.admin awoken_chat.admin allow`  |
| `awoken_chat.staff`  | Send in the default `/staffchat` category, view staff-visibility channels, see admin-only suggestions in the picker. | `add_ace group.admin awoken_chat.staff allow`  |
| `awoken_chat.clear`  | Use `/clear` and `/clearall` on other players.                                                                       | `add_ace group.admin awoken_chat.clear allow`  |
| `awoken_chat.bypass` | Skip antispam, blocked-word filter, profanity escalation. **Don't grant lightly.**                                   | `add_ace group.admin awoken_chat.bypass allow` |

<Info>
  `awoken_chat.admin` automatically implies `awoken_chat.staff` + `awoken_chat.clear`. You only need to grant the highest-level permission per role. `awoken_chat.bypass` is intentionally NOT implied - it has to be granted explicitly.
</Info>

## Resetting to defaults

| What to reset                                                          | How                                                               |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Channels** (back to the 9 shipped defaults)                          | `TRUNCATE awoken_chat_categories;` and `restart awoken_chat`      |
| **All player settings**                                                | `TRUNCATE awoken_chat_settings;`                                  |
| **Just one player's settings**                                         | `DELETE FROM awoken_chat_settings WHERE license = 'license:...';` |
| **Message history**                                                    | `TRUNCATE awoken_chat_messages;`                                  |
| **Server-wide global tier** (admin's shell/layout/showAvatars choices) | `DELETE FROM awoken_chat_settings WHERE license = '__global__';`  |

<Warning>
  `TRUNCATE awoken_chat_categories` nukes any **custom** channels you've created via the Category Manager. Export anything bespoke first.
</Warning>