Categories & channels

A category is a chat tab. /me, /global, /ooc, /staffchat, gang chat, job chat - each is one row in the awoken_chat_categories DB table. Categories are live-editable in-game via the Category Manager (wrench icon in the Settings panel, requires awoken_chat.admin).

Default channel set

The 9 channels shipped out of the box:

ID	Command	Proximity	Notes
`all`	(none)	(none)	Read-only merged view. Default-selected tab.
`local`	`/local`	20 m	Local chat (range-limited).
`global`	`/global`	(none)	Server-wide.
`ooc`	`/ooc`	(none)	Out of character.
`me`	`/me`	20 m	Action description, 3D text above the sender.
`ads`	`/ad`	(none)	Disabled by default - flip Enabled on if you use it.
`staff`	`/staffchat`	(none)	ACE-gated to `awoken_chat.staff`.
`gang`	`/gang`	(none)	Filters to `ballas,families,vagos,marabunta,lostmc` (edit the filter).
`job`	`/job`	(none)	Filters to `police,sheriff,ambulance,fire,mechanic` (edit the filter).

Category Manager UI

Open the Settings panel, click the wrench icon. Categories list on the left, edit form on the right. Form is grouped into six sections:

Section	Fields
Identity	`id`, `label`, slash command
Appearance	colour, icon
Access	visibility mode, proximity, ACE permission, job filter, min job grade, gang filter
3D Text	enable 3D, 3D-only (dependent), duration (dependent)
Anonymity	anonymous, anonymous-in-webhook (dependent)
Behaviour	active, show in tabs, bypass antispam, allow reply / react actions

Saving an existing category keeps the form on that row (so you can iterate). Saving a brand-new category promotes the draft to editingId - the second save updates the row you just created instead of trying to create a duplicate.

Per-channel flag reference

Every checkbox / number field in the Category Manager maps to a key in the category’s JSON blob. The defaults match what most servers want.

Identity & appearance

Key	Type	Notes
`id`	`string`	Unique, lowercase, `[a-z0-9_-]`. Used as the DB primary key. Cannot be changed once saved (delete + recreate).
`label`	`string`	Tab strip display name.
`color`	`string`	Hex `#RRGGBB`. Drives the tab tint and the message-name accent.
`icon`	`string`	Font Awesome 6 Solid name, no `fa-` prefix. Picked from a curated dropdown in the UI.
`command`	`string?`	Slash command (omit for view-only tabs like `all`).
`default`	`boolean?`	Mark one category as the default-selected tab.

Access

Key	Type	Notes
`visibility`	`'all' \| 'sender' \| 'staff' \| 'job'`	`sender` shows the message to the sender only (useful for `/try` previews). `staff` shows only to staff + the sender. `job` requires the `job` filter.
`proximity`	`number?`	Metres. `nil` = unlimited range.
`permission`	`string?`	ACE permission required to read/send.
`job`	`string?`	Comma-separated jobs (QB/QBOX/ESX).
`grade`	`number?`	Minimum job grade. Only checked when `job` is set.
`gang`	`string?`	Comma-separated gangs (QBCore/QBOX only - ESX has no native gang system).

3D text

Key	Type	Notes
`threeD`	`boolean?`	Render the message body as floating text above the sender’s head.
`threeDOnly`	`boolean?`	With `threeD = true`, suppress the chat row - the 3D text is the only surface. Server still persists + webhooks the message (audit trail intact).
`threeDDurationSec`	`number?`	Seconds the 3D text stays on screen. Clamped to `[0.25, 60]` client-side. `nil` = global default from `cfg.threeD.durationMs`.

See 3D text for the full picture (render distance, anchoring, etc.).

Anonymity

Key	Type	Notes
`anonymous`	`boolean?`	Hide the sender’s name in-game. The chat row reads `"Anonymous"` with a neutral silhouette avatar; senderId is stripped from the payload.
`anonymousInWebhook`	`boolean?`	Paired with `anonymous`. When both are true, the Discord webhook archive also reads `"Anonymous"` instead of the real character name. Default `false` = staff audit trail keeps real names.

Behaviour

Key	Type	Notes
`enabled`	`boolean?`	`false` = category is fully inert. No slash command, hidden from tabs, no broadcasts. Admin can still see + re-enable in the Category Manager.
`showInTabs`	`boolean?`	`false` hides from the tab strip; the slash command still works.
`bypassAntispam`	`boolean?`	Skip rate-limit + duplicate detection for this channel. RP-style channels like `/me` legitimately repeat (“`nods`”, “`sighs`”) - flip this on for those. Blocked-word filter still applies.
`allowReplies`	`boolean?`	`false` hides the Reply action on messages. Default `true`.
`allowReactions`	`boolean?`	`false` hides the React action. Default `true`.

Creating a custom channel

Example: a /confess confessional channel that posts anonymously in-game AND in Discord, with 3D text disabled (it’s a chat-only channel), and the same proximity as /local.

Wrench icon → New category
Fill in:
- ID: confess
- Label: Confessions
- Slash command: confess
- Color: #A78BFA
- Icon: comment
Access: Proximity 20
Anonymity: tick Anonymous + tick Anonymous in webhook
Save

The /confess command is bound at save time (no restart needed). If webhooks.channels.confess is set in config.lua, every message also posts to that Discord channel, with the author block reading Anonymous.

Live edits & runtime updates

What changed	Effect	Restart needed?
Created a new category	Tab + slash command + suggestion picker entry appear for every connected client	No
Renamed a category’s command (`/me` → `/action`)	New command is bound immediately. Old command keeps working as a free alias until next restart.	No
Toggled Enabled off	`byId` lookup returns nil → handler responds `unknown_channel` → tab disappears	No
Toggled Enabled on	Tab + command re-bind	No
Changed perms / job / gang filter	Next `visibleFor()` call (admin save broadcasts one immediately) re-runs the check	No
Deleted a category	Tab disappears. Old slash command stays registered but the handler returns `unknown_channel`.	Until next restart for the dead command to go away entirely

Job & gang filtering

Filters are simple comma-separated case-insensitive matches against the framework’s job/gang name fields.

Job filter:   police,sheriff,ambulance,fire
Gang filter:  ballas,families,vagos

The bridge resolves the player’s current job/gang and runs a lower-case match. There’s no role abstraction - if your server uses non-standard ids like metro-police, add them explicitly.

After granting a player a new job via your framework, the relevant tab appears automatically within ~1s - the bridge listens to qbx_core:server:onJobUpdate / QBCore:Server:OnJobUpdate / esx:setJob and pushes a refreshed channels list.

Resetting to defaults

TRUNCATE awoken_chat_categories;

Then restart awoken_chat. The seed pass re-inserts the 9 default channels.

This nukes any custom categories. Export anything bespoke first.

Get Started

Awoken Scripts

Categories & channels

Default channel set

Category Manager UI

Per-channel flag reference

Identity & appearance

Access

3D text

Anonymity

Behaviour

Creating a custom channel

Live edits & runtime updates

Job & gang filtering

Resetting to defaults

​Default channel set

​Category Manager UI

​Per-channel flag reference

​Identity & appearance

​Access

​3D text

​Anonymity

​Behaviour

​Creating a custom channel

​Live edits & runtime updates

​Job & gang filtering

​Resetting to defaults

Default channel set

Category Manager UI

Per-channel flag reference

Identity & appearance

Access

3D text

Anonymity

Behaviour

Creating a custom channel

Live edits & runtime updates

Job & gang filtering

Resetting to defaults