> For the complete documentation index, see [llms.txt](https://dtrx-studio.gitbook.io/dtrx-studio-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dtrx-studio.gitbook.io/dtrx-studio-docs/fivem-products/dtrx-chat/configurations.md). # Configurations ### Two-layer configuration model DTRX Chat splits settings into **static** (open files) and **runtime** (database + in-game admin): | Layer | Where | Who edits | Restart needed | | ----------- | --------------------------------------------------------------- | ------------------- | ----------------------------------------------------------- | | **Static** | `public/shared/config.lua` | Server owner (file) | `restart dtrx_chat` (some convars need full server restart) | | **Runtime** | MySQL table `dtrx_chat_settings` + Admin → **Runtime Settings** | Admins in-game | **No restart** changes broadcast via StateBag instantly | {% hint style="warning" %} **For every change in `config.lua`, restart the resource.** Runtime settings edited in the Admin Panel apply live to all players without touching files. {% endhint %} *** ### Static config file #### File location | Item | Value | | ---------- | ------------------------------------------------------------------------ | | Path | `public/shared/config.lua` | | Scope | Shared (`files` entry in `fxmanifest.lua` — loaded on client and server) | | Table name | `ChatConfig` | *** #### Before you edit (read this) {% hint style="info" %} **First boot vs existing server** * On the **first** server start, default channels and runtime values are created automatically in the database when tables are empty. * After that, change channels in Admin → **Categories** and limits in Admin → **Runtime Settings**. Server logic under `client/` and `server/` stays protected by escrow. {% endhint %} *** #### Related files (not in `config.lua`) | File | Purpose | | ---------------------------------------------------------- | ------------------------------------------------------------- | | `public/shared/locales/en.json` (and `pt.json`, `es.json`) | UI strings — default language from `ChatConfig.Locale` | | `public/shared/themes.json` | Built-in theme tokens — default theme from `ChatConfig.Theme` | *** #### Quick reference — `ChatConfig` | Section | Keys | | -------------------- | --------------------------------------------------------------------------------------------------------- | | General | `Debug`, `Locale`, `Theme`, `Ui.ShowBootstrapLoading` | | Bridge | `Bridge.Framework`, `Bridge.Notify` | | Admin | `Admin.AcePermission`, `Admin.FrameworkGroups`, `Admin.PlayerListMax`, `Admin.LogsPageSize` | | Player settings load | `PlayerSettings.TimeoutSec`, `PlayerSettings.MaxAttempts` | | Keybinds | `Keybinds.OpenChat` | | Commands | `Commands.AdminPanel`, `Commands.OpenChat`, `Commands.CloseChat` | | Sticky (assets) | `Sticky.Command`, `Sticky.PropModel`, `Sticky.Proximity.*`, `Sticky.Placement.*` | | Dice (assets) | `Dice.AnimDict`, `Dice.AnimName`, `Dice.AnimFlag`, `Dice.AnimDurationMs`, `Dice.BadgeColor` | | Audio caps | `Audio.MaxDurationSec`, `Audio.MaxSizeKb` | | Location | `Location.CooldownSec` | | Performance | `Performance.AutoMsgTickIntervalMs`, `Performance.Max3DRenderDistanceM`, `Performance.Max3DCullDistanceM` | *** #### General | Option | Type | Default | Description | | ------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Debug` | `boolean` | `false` | `true` = extra F8/client and server console logs (support). `false` = production. | | `Locale` | `string` | `"en"` | Default UI language for **new** players. File must exist: `public/shared/locales/.json`. Bundled: `en`, `pt`, `es`. Players can override in Chat Settings. | | `Theme` | `string` | `"dtrx"` | Default theme id in `themes.json`. Bundled: `dtrx`, `classic`, `terminal`. | | `Ui.ShowBootstrapLoading` | `boolean` | `true` | Small top-right indicator while channels/themes sync on join. `false` hides it (sync still runs). | *** #### Bridge (`Bridge`) | Option | Type | Default | Description | | ----------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Framework` | `string` | `"auto"` | `auto` detects `es_extended`, `qbx_core`, or `qb-core`. Force: `"qb-core"` \| `"qbx_core"` \| `"es_extended"`. Custom: implement `public/bridge/framework/`. | | `Notify` | `string` | `"auto"` | `auto` \| `ox_lib` \| `okokNotify` \| `esx` \| `qbcore` \| `native` \| `custom`. Custom: edit `public/bridge/notify/`. | *** #### Admin access (`Admin`) | Option | Type | Default | Description | | ----------------- | -------- | ---------------------------- | ----------------------------------------------------------------------------- | | `AcePermission` | `string` | `dtrx_chat.admin` | ACE name — must match `server.cfg`. | | `FrameworkGroups` | `table` | `admin`, `god`, `superadmin` | Framework group names that also grant admin (OR with ACE). | | `PlayerListMax` | `number` | `10` | Max rows per admin player-list request (search filters online players first). | | `LogsPageSize` | `number` | `10` | Admin audit log pagination size. | *** #### Player settings bootstrap (`PlayerSettings`) Controls loading per-character settings from the server the first time a player opens chat. | Option | Type | Default | Description | | ------------- | -------- | ------- | --------------------------------------------------------------- | | `TimeoutSec` | `number` | `20` | Seconds to wait per load attempt (raise on high-latency hosts). | | `MaxAttempts` | `number` | `2` | Retries on first open only (`1` = no retry). | {% hint style="info" %} Custom multichar: call `exports.dtrx_chat:NotifySessionReady()` when the character is ready (see Client exports). {% endhint %} *** #### Keybinds (`Keybinds`) | Option | Type | Default | Description | | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `OpenChat` | `string` | `"T"` | Default key for `RegisterKeyMapping`. Players can rebind in FiveM Settings → Key Bindings → FiveM. | *** #### Commands (`Commands`) | Option | Type | Default | Description | | ------------ | -------- | ----------------- | ---------------------------------------------------------- | | `AdminPanel` | `string` | `chatadmin` | Opens admin panel (still requires ACE or framework group). | | `OpenChat` | `string` | `dtrx_chat_open` | Programmatic open via `ExecuteCommand`. | | `CloseChat` | `string` | `dtrx_chat_close` | Programmatic close. | {% hint style="info" %} Renaming commands here does **not** change permissions — only the typed word. {% endhint %} *** #### Sticky notes — static assets (`Sticky`) {% hint style="info" %} Runtime limits (`maxPerPlayer`, `renderDistance`, `maxLength`, etc.) are in **Runtime Settings** (admin panel). {% endhint %} | Option | Type | Default | Description | | ---------------------------- | --------- | --------------------------- | ------------------------------------------------------- | | `Command` | `string` | `stickynote` | Command to open the create modal. | | `PropModel` | `string` | `hei_prop_hei_post_note_01` | World prop model (must stream on your build). | | `Proximity.interactDistance` | `number` | `2.5` | Meters to read or tear a note (E / G by default). | | `Proximity.showFloatingText` | `boolean` | `false` | Draw 3D floating preview text at distance. | | `Placement.*` | `table` | see file | Raycast placement keys, rotation steps, surface offset. | {% hint style="warning" %} Sticky notes use **proximity keys**, not eye-target systems. {% endhint %} *** #### Dice — animation assets (`Dice`) {% hint style="info" %} Cooldown, min/max value, overhead badge, and broadcast radius are **Runtime Settings**. {% endhint %} | Option | Type | Default | Description | | ---------------- | -------- | ------------------------------------------------------ | ------------------------------------------ | | `AnimDict` | `string` | `anim@mp_player_intcelebrationmale@coin_roll_and_toss` | Animation dictionary. | | `AnimName` | `string` | `coin_roll_and_toss` | Animation clip. | | `AnimFlag` | `number` | `48` | Upper-body only (works while NUI is open). | | `AnimDurationMs` | `number` | `2800` | Client animation length hint. | | `BadgeColor` | `string` | `#f5c542` | Overhead dice badge color. | *** #### Voice messages (`Audio`) {% hint style="info" %} Per-channel `allow_audio` is set in the channel editor. These are **hard server caps** (anti-abuse). {% endhint %} | Option | Type | Default | Description | | ---------------- | -------- | ------- | -------------------------- | | `MaxDurationSec` | `number` | `8` | Maximum recorded seconds. | | `MaxSizeKb` | `number` | `96` | Maximum upload size in KB. | *** #### Location sharing (`Location`) | Option | Type | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------------------- | | `CooldownSec` | `number` | `10` | Per-player cooldown before sharing GPS again. `0` = disabled. | *** #### Performance hard caps (`Performance`) {% hint style="info" %} The admin panel can tune 3D defaults, but **never above** these ceilings: {% endhint %} | Option | Type | Default | Description | | ----------------------- | -------- | ------- | ------------------------------------------------------------------------------------- | | `AutoMsgTickIntervalMs` | `number` | `15000` | Auto-message scheduler resolution (lower = more accurate, slightly higher idle cost). | | `Max3DRenderDistanceM` | `number` | `60.0` | Maximum 3D text render distance admins can set. | | `Max3DCullDistanceM` | `number` | `80.0` | Maximum cull distance admins can set. | *** ### Runtime settings (Admin Panel) {% hint style="info" %} Open chat → **Settings** (gear) → **Admin Panel** → **Runtime Settings**. Stored under JSON key `runtime` in `dtrx_chat_settings` and replicated as `GlobalState.dtrx_chat_settings`. {% endhint %} #### Default seed values (first boot only) | Section | Keys | Purpose | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `chat` | `autoHideSeconds`, `maxMessageLength`, `maxHistoryClient`, `maxHistoryServer`, `paginationPageSize`, `closeOnSend` | Chat UX and history limits | | `antiSpam` | `enabled`, `minIntervalMs`, `duplicateThreshold`, `duplicateWindowSec`, `autoMuteSeconds`, `rateLimitWindowSec`, `rateLimitMaxMessages` | Flood protection | | `draw3d` | `enabled`, `maxRenderDistance`, `cullDistance`, `defaultDuration`, scales, opacity, fade timings | 3D ME/DO renderer | | `sticky` | `enabled`, `maxPerPlayer`, `renderDistance`, `maxLength`, `persistent` | Sticky note rules | | `dice` | `enabled`, `minValue`, `maxValue`, `cooldownMs`, `showAboveHead`, `displayDuration`, `broadcastRadius` | Dice game | | `autoMessages` | `enabled` | Scheduled broadcast messages | | `blockedWords` | `enabled` | Word filter master toggle | | `themes` | `defaultTheme` | Server default theme id for new players | {% hint style="info" %} `autoHideSeconds = 0` means the chat stays visible until the player closes it manually. {% endhint %} *** ### Themes (`themes.json`) Built-in theme ids: | Id | Label | Notes | | ---------- | -------- | -------------------------------------- | | `dtrx` | DTRX | Brand default — gold accent on dark UI | | `classic` | Classic | Semi-transparent GTA-style look | | `terminal` | Terminal | Monospace green-on-black | {% hint style="warning" %} Admins can customize built-in colors in the **Themes** tab (saved to DB and merged over `themes.json`). Players pick themes in **Chat Settings → Select Theme**. {% endhint %} *** ### Channels (Admin → Categories) Default seeded channels: | Key | Command | Scope | Highlights | | ----- | ------- | ----------- | --------------------- | | `all` | `all` | global | Global chat | | `me` | `me` | local (15m) | 3D text, FIFO 3 | | `do` | `do` | local (15m) | 3D text, no dice | | `ooc` | `ooc` | global | OOC | | `job` | `job` | job filter | Default job: `police` | {% hint style="info" %} Each channel supports: icon (Lucide id), colors, radius, cost, job/gang lists, emoji/audio/location/dice flags, 3D text color/limit, enable/disable, sort order. {% endhint %} *** ### Troubleshooting (config) | Issue | Check | | ------------------------ | --------------------------------------------------------------------- | | Admin panel “no access” | `add_ace group.admin dtrx_chat.admin allow` and `Admin.AcePermission` | | UI still in English | `Locale` + matching `locales/.json` + restart | | Theme not applied | Theme id exists in `themes.json` or admin Themes tab | | Runtime change ignored | Save in Admin Panel; check `dtrx_chat_settings` row `runtime` | | 3D text distance too far | Admin cannot exceed `Performance.Max3D*` caps | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://dtrx-studio.gitbook.io/dtrx-studio-docs/fivem-products/dtrx-chat/configurations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.