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

# Installation

> Drop-in replacement for the stock FiveM chat resource. Framework-specific cleanup steps included.

<Warning>
  Awoken Chat **replaces** the chat surface entirely. It declares `provide 'chat'` so existing scripts calling `exports.chat:addMessage` / `chat:addSuggestion` continue to work, but you must not run another chat resource alongside it. Every supported framework also ships some conflicting commands - the [Framework-specific cleanup](#framework-specific-cleanup) section below tells you exactly what to disable per framework, with file paths and line numbers.
</Warning>

## Asset download

<Info>
  To find the asset, you must have made the purchase using your own keymaster account. Otherwise, you can use the transfer system to move the asset to a different keymaster account.
</Info>

Once the purchase is made on our official website, you will receive your asset directly in your [Cfx.re portal](https://portal.cfx.re/). Download it from your panel.

## Requirements

| Resource                               | Required by   | Notes                                                                              |
| -------------------------------------- | ------------- | ---------------------------------------------------------------------------------- |
| `oxmysql`                              | Awoken Chat   | **Required.** Schema (settings, categories, messages) auto-creates on first start. |
| `qbx_core` / `qb-core` / `es_extended` | Auto-detected | Optional. Used for character names + job/gang tab filtering. Standalone is fine.   |

<Tip>
  Set the `awoken:primaryColor` convar in `server.cfg` to theme the chat alongside Awoken UI, Awoken Target, and any other Awoken-branded resource at once.
</Tip>

## Base install

<Steps>
  <Step title="Stop the server" />

  <Step title="Remove any existing chat resource">
    Your framework's existing chat surface needs to go. Either delete the resource folder, or comment out / remove its `ensure` line in `server.cfg` so it never starts - a stopped resource that's still `ensure`d will come back on the next restart. See [Framework-specific cleanup](#framework-specific-cleanup) for the exact commands per framework - the short version:

    * **QBOX**: remove `chat` and `qbx_chat_theme`
    * **QBCore**: remove the cfx `chat` if you have it.
    * **ESX**: remove `chat`, `esx_chat_theme`, and `esx_rpchat` (if installed)
    * **Standalone**: remove `chat`
    * **Third-party**: remove any `prism-chat`, `okokChat*`, `tg-chat`, `omi-ChatUI`, `nh-chat`, `wasabi_adminchat`, `core_chat`, `overflow_chat` etc.
  </Step>

  <Step title="Disable the engine MP chat widget">
    In `server.cfg`, add this line so the GTA engine `[ALL]` widget stays hidden too:

    ```cfg server.cfg theme={"dark"}
    set resources_useSystemChat false
    ```

    Awoken Chat suppresses the engine widget client-side as belt-and-braces, but flipping the convar removes any flicker on join.
  </Step>

  <Step title="Drop the Awoken Chat folder in place">
    Extract the build into `resources/` (or any subfolder of your resources path).
  </Step>

  <Step title="Confirm load order">
    Both `oxmysql` and your framework (if any) must start **before** `awoken_chat`. This is critical - Awoken Chat's command registrations need to load *after* the framework's so they override the conflicting ones (see the [Framework-specific cleanup](#framework-specific-cleanup) section for why).

    ```cfg server.cfg theme={"dark"}
    ensure oxmysql
    ensure qbx_core           # or qb-core / es_extended / nothing
    # any other framework resources here
    ensure awoken_chat
    ```
  </Step>

  <Step title="(Optional) Set the global accent colour">
    ```cfg server.cfg theme={"dark"}
    setr awoken:primaryColor "#00E5FF"
    ```

    Read by every Awoken-branded resource. Players can still override it for themselves in the in-game Settings panel - this is the brand default for new players.
  </Step>

  <Step title="Start the server">
    `ensure awoken_chat`. On first boot you'll see:

    ```text theme={"dark"}
    [awoken_chat] Framework bridge: qbox          (or esx / qbcore / standalone)
    [awoken_chat][db] seeded 9 default categories  (only on the very first start)
    [awoken_chat] Ready. 9 channel(s) configured.
    ```
  </Step>
</Steps>

***

## Framework-specific cleanup

Each framework ships some commands that overlap with Awoken Chat's defaults. **Comment them out at the source** so they can't fire alongside Awoken's handlers. The blocks to wrap are shown verbatim below per framework - find them in the file and wrap the whole block in a Lua multi-line comment (`--[[ ... ]]`), or prefix each line with `--`.

<Warning>
  These edits are made to **mandatory framework files**, so they'll need re-applying after a framework update. Keep a note of which files you've touched. Awoken Chat does technically override these commands at runtime (last-registered wins in FiveM), but commenting them out at the source is the only way to be 100% sure the framework's old behaviour can't leak through during troubleshooting, load-order changes, or partial restarts.
</Warning>

<Tabs>
  <Tab title="QBOX">
    ### Conflicting commands to comment out in `qbx_core`

    Open `qbx_core/server/commands.lua` and wrap each of these four blocks in `--[[ ... ]]`:

    **`/ooc`** (around line **367**, spans to \~line 416):

    ```lua qbx_core/server/commands.lua theme={"dark"}
    --[[
    lib.addCommand('ooc', {
        help = locale('command.ooc.help')
    }, function(source, args)
        -- ... entire proximity-OOC handler ...
        -- (wrap the whole lib.addCommand('ooc', ...) call, including the closing `end)`)
    end)
    ]]
    ```

    **`/me`** (around line **418**, spans to \~line 433):

    ```lua qbx_core/server/commands.lua theme={"dark"}
    --[[
    lib.addCommand('me', {
        help = locale('command.me.help'),
        params = { { name = locale('command.me.params.message.name'), ... } }
    }, function(source, args)
        -- ... statebag-based 3D /me handler ...
        -- (wrap the whole lib.addCommand('me', ...) call)
    end)
    ]]
    ```

    <Tip>
      qbx\_core's `/me` uses a state-bag handler to render 3D world-text. Awoken Chat's `/me` does both chat + 3D in one. If you'd rather keep qbx\_core's 3D `/me` *and* have Awoken's chat `/me` as a separate command, **leave the qbx\_core `/me` block alone** and rename Awoken's `/me` to `/action` (or similar) in the Category Manager - both can coexist.
    </Tip>
  </Tab>

  <Tab title="QBCore">
    ### Conflicting commands to comment out in `qb-core`

    Open `qb-core/server/commands.lua` and wrap each of these four blocks in `--[[ ... ]]`:

    **`/ooc`** (around line **275**):

    ```lua qb-core/server/commands.lua theme={"dark"}
    --[[
    QBCore.Commands.Add('ooc', Lang:t('command.ooc.help'), {}, false, function(source, args)
        local message = table.concat(args, ' ')
        local Players = QBCore.Functions.GetPlayers()
        -- ... proximity OOC handler using chat:addMessage ...
    end, 'user')
    ]]
    ```

    **`/me`** (around line **300**):

    ```lua qb-core/server/commands.lua theme={"dark"}
    --[[
    QBCore.Commands.Add('me', Lang:t('command.me.help'), { { name = Lang:t('command.me.params.message.name'), help = Lang:t('command.me.params.message.help') } }, false, function(source, args)
        if #args < 1 then
            TriggerClientEvent('QBCore:Notify', source, Lang:t('error.missing_args2'), 'error')
            return
        end
        local ped = GetPlayerPed(source)
        local pCoords = GetEntityCoords(ped)
        local msg = table.concat(args, ' '):gsub('[~<].-[>~]', '')
        local Players = QBCore.Functions.GetPlayers()
        for i = 1, #Players do
            local Player = Players[i]
            local target = GetPlayerPed(Player)
            local tCoords = GetEntityCoords(target)
            if target == ped or #(pCoords - tCoords) < 20 then
                TriggerClientEvent('QBCore:Command:ShowMe3D', Player, source, msg)
            end
        end
    end, 'user')
    ]]
    ```

    ### Conflicting command to comment out in `qb-adminmenu`

    Open `qb-adminmenu/server/server.lua` (around line **342**) and wrap the `staffchat` block:

    ```lua qb-adminmenu/server/server.lua theme={"dark"}
    --[[
    QBCore.Commands.Add('staffchat', 'Staff Chat', {{ name = 'message', help = 'message' }}, false, function(source, args)
        -- ... staff broadcast handler ...
    end, 'admin')
    ]]
    ```
  </Tab>

  <Tab title="ESX">
    ### Conflicting commands to comment out in `es_extended`

    Open `[core]/es_extended/server/modules/commands.lua` and wrap each of these blocks in `--[[ ... ]]`:

    **`/clear` (+ `/cls` alias)** (lines **426-428**):

    ```lua [core]/es_extended/server/modules/commands.lua theme={"dark"}
    --[[
    ESX.RegisterCommand({ "clear", "cls" }, "user", function(xPlayer)
        xPlayer.triggerEvent("chat:clear")
    end, false, { help = TranslateCap("command_clear") })
    ]]
    ```

    **`/clearall` (+ `/clsall` alias)** (lines **430-438**):

    ```lua [core]/es_extended/server/modules/commands.lua theme={"dark"}
    --[[
    ESX.RegisterCommand({ "clearall", "clsall" }, "admin", function(xPlayer)
        TriggerClientEvent("chat:clear", -1)
        if Config.AdminLogging then
            ESX.DiscordLogFields("UserActions", "Clear Chat /clearall Triggered!", "pink", {
                { name = "Player", value = xPlayer and xPlayer.name or "Server Console", inline = true },
                { name = "ID", value = xPlayer and xPlayer.source or "Unknown ID", inline = true },
            })
        end
    end, true, { help = TranslateCap("command_clearall") })
    ]]
    ```

    ### `esx_rpchat` - the big one if it's installed

    [`esx_rpchat`](https://github.com/esx-framework/ESX-Legacy-Addons/tree/main/%5Besx_addons%5D/esx_rpchat) is **optional** and NOT in the default `server.cfg`, but very common on legacy servers. If you have it, **remove it** - it registers:

    | Command    | File              | Line   |
    | ---------- | ----------------- | ------ |
    | `/me`      | `server/main.lua` | **34** |
    | `/do`      | `server/main.lua` | **45** |
    | `/twt`     | `server/main.lua` | **10** |
    | `/anontwt` | `server/main.lua` | **22** |
    | `/msg`     | `server/main.lua` | **56** |

    ```cfg server.cfg theme={"dark"}
    # Comment out if present:
    # ensure esx_rpchat
    ```
  </Tab>

  <Tab title="Standalone">
    If you're not running a framework:

    ```cfg server.cfg theme={"dark"}
    # Comment out the stock chat:
    # ensure chat
    ensure oxmysql
    ensure awoken_chat
    ```

    No further cleanup needed - there's no framework to conflict with. Awoken Chat will detect the absence of a framework, use its standalone bridge, and use FiveM account names for the identity surface.
  </Tab>
</Tabs>

## Updating

Re-download the asset from your Cfx.re portal, replace the folder, and restart with `ensure awoken_chat`. The DB schema is forward-compatible - existing categories, player settings, and message history survive updates.

<Tip>
  Customisations live in **`config.lua`** (boot-only values like the antispam tuning, blocked-words list, framework selection, webhooks) and the **`awoken_chat_categories` DB table** (live, in-game-editable via the Category Manager). Replacing the folder only overwrites the code, not the DB - your tuning persists across updates.
</Tip>

## Reset to defaults

Categories live in the `awoken_chat_categories` table and are managed in-game. To restore the shipped defaults at any time:

```sql theme={"dark"}
TRUNCATE awoken_chat_categories;
```

Then `restart awoken_chat`. The seed pass re-inserts every default channel.

<Warning>
  This also nukes any **custom** categories you created via the Category Manager. Export anything bespoke before truncating.
</Warning>