Overview

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.

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.

`config.lua` at a glance

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

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

config.lua

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', ... },
}

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.

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 - the Category Manager UI, per-channel flags (anonymous, 3D-only, bypass antispam, etc.), job/gang filters, the first-start seed.
Identity - nameSource (character vs account), format tokens, tags/badges.
Avatars - the initials/URL picker, allowlisted hosts, per-character storage.
Antispam & moderation - rate limiting, duplicate detection, blocked-words filter, profanity escalation ladder.
Webhooks - per-channel Discord archives, violation log, fun-command audit log.
Fun commands - /roll, /coinflip, /8ball, /random - 3D-only, proximity-filtered, webhook-audited.
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`

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.

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__';`

TRUNCATE awoken_chat_categories nukes any custom channels you’ve created via the Category Manager. Export anything bespoke first.

Get Started

Awoken Scripts

`config.lua` at a glance

Deep-dive pages

Convars

Permissions

Resetting to defaults

​config.lua at a glance

​Deep-dive pages

​Convars

​Permissions

​Resetting to defaults

`config.lua` at a glance

Deep-dive pages

Convars

Permissions

Resetting to defaults