> ## 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.
# Identity & tags
> Name source toggle, format tokens, and the per-player tag badges.
The **identity** block decides what appears as the sender label on every chat message - and, by extension, what tokens the `@`-mention picker accepts.
```lua config.lua theme={"dark"}
identity = {
nameSource = 'character', -- 'character' | 'account'
format = '{fullName}',
fallback = '{name}',
prefixWithId = true,
},
```
## `nameSource`
The single most consequential identity setting. Two modes:
| Value | What it does | Best for |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `'character'` | Uses the player's character name from your framework (`firstName + lastName`). Falls through to the FiveM account name when no character is loaded (character-selection screen, pre-spawn). | Pure RP servers. |
| `'account'` | Uses the player's FiveM display name (`GetPlayerName`). Character data is completely ignored. | Casual / PvP servers where players prefer being known by their handle. |
Changing `nameSource` requires a `restart awoken_chat` - it's read at boot and threaded through the whole identity pipeline.
### Effect on `@`-mentions
The mention picker matches against **only the tokens that match the active name source**:
* `'character'` mode: `@firstName`, `@lastName`, `@First-Last`, `@FirstLast` (squashed), and `@AccountName` as a fallback when no character is loaded.
* `'account'` mode: `@AccountName` only. Typing a character first name surfaces nobody.
This mirrors what the chat actually labels people as, so the mention grammar matches the chat grammar.
## `format` & `fallback`
Only used in **`character`** mode. The string is a Lua template with `{token}` slots that get substituted at send time.
```lua theme={"dark"}
identity = {
nameSource = 'character',
format = '{fullName}', -- when char data is loaded
fallback = '{name}', -- when char data isn't loaded yet
prefixWithId = true,
},
```
### Available tokens
| Token | Substitution |
| ------------- | ---------------------------------------------------------------------------- |
| `{id}` | Player server id (e.g. `12`) |
| `{name}` | FiveM account display name |
| `{firstName}` | Character first name |
| `{lastName}` | Character last name |
| `{fullName}` | `{firstName} {lastName}`, with the space squeezed out if only one is present |
| `{job}` | Framework job label (QBOX: `pd.job.label`, ESX: similar) |
| `{jobGrade}` | Job grade name or number |
| `{gang}` | Framework gang label (QB/QBOX only) |
### Example formats
```lua theme={"dark"}
-- Minimal: just the full name
format = '{fullName}',
-- → "John Doe"
-- Job in brackets (good for emergency services RP servers)
format = '{fullName} [{job}]',
-- → "John Doe [Police]"
-- Full identity card
format = '{fullName} - {job} ({jobGrade})',
-- → "John Doe - Police (Sergeant)"
-- Just first name (low-formality servers)
format = '{firstName}',
fallback = '{name}',
-- → "John" (or "Steam:DiscordGamer42" if char isn't loaded yet)
```
### `prefixWithId`
When `true`, every chat row prefixes the resolved name with `[N]` where N is the server id:
```text theme={"dark"}
[12] John Doe: hello world
```
Useful for staff and PvP servers where moderation needs to identify the source quickly. Set `false` for pure-RP servers where IDs break immersion.
This applies to **both** name source modes - account-mode also gets the `[N]` prefix when this is true.
## Tags / badges
Small chips rendered **before** the sender's name on every chat row. Match a player to a tag by ONE of: license, steam id, discord id, ACE permission. Highest-priority match wins.
```lua config.lua theme={"dark"}
tags = {
-- Staff tag (auto-applied to anyone with awoken_chat.staff ACE)
{
id = 'staff',
label = 'STAFF',
color = '#FFFFFF',
backgroundColor = '#22D3EE',
icon = 'shield-halved',
priority = 90,
ace = 'awoken_chat.staff',
},
-- VIP tag (specific license)
{
id = 'vip',
label = 'VIP',
color = '#0B0B0B',
backgroundColor = '#A78BFA',
icon = 'star',
priority = 50,
license = { 'license:abc123', 'license:def456' },
},
-- Developer tag (multiple Discord ids)
{
id = 'dev',
label = 'DEV',
color = '#FFFFFF',
backgroundColor = '#10B981',
icon = 'code',
priority = 100,
discord = { 'discord:99887766554433', 'discord:11223344556677' },
},
},
```
### Tag fields
| Key | Type | Required | Notes |
| ----------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | yes | Internal identifier. Must be unique. |
| `label` | `string` | yes | Display text on the chip (usually 1-4 chars uppercase). |
| `color` | `string` | yes | Hex `#RRGGBB`. Text colour on the chip. |
| `backgroundColor` | `string` | yes | Hex `#RRGGBB`. Background colour of the chip. |
| `icon` | `string?` | no | Font Awesome 6 Solid name without `fa-` prefix. **OR** a single emoji character. |
| `priority` | `number?` | no | Higher = wins when a player has multiple tags. Default `0`. The HIGHEST-priority tag is the one that renders. |
| `license` | `string \| string[]` | no | Match by full license identifier (`license:abc123...`). |
| `steam` | `string \| string[]` | no | Match by full steam identifier (`steam:1100001abc...`). |
| `discord` | `string \| string[]` | no | Match by full discord identifier (`discord:99887766...`). |
| `ace` | `string?` | no | Match by ACE permission. Auto-applies to anyone allowed for that permission. |
### Priority resolution
Only **one** tag is shown per player - the highest-priority one whose match condition is met. Use `priority` to express a hierarchy: `dev > staff > vip > donor > member`.
```lua theme={"dark"}
{ id = 'dev', label = 'DEV', priority = 100, ace = 'awoken_chat.dev' },
{ id = 'staff', label = 'STAFF', priority = 90, ace = 'awoken_chat.staff' },
{ id = 'vip', label = 'VIP', priority = 50, license = { ... } },
{ id = 'member', label = 'MEMBER', priority = 10, license = { ... } },
```
A player who matches both `staff` and `member` shows `STAFF` (priority 90 > 10).
Tags are sent to the client at message-send time, not at connect. So adding a tag in `config.lua` requires `restart awoken_chat` - the tag list is read on resource start. The CHIP renders live based on the current tag list for whoever's online.