Identity & tags

The identity block decides what appears as the sender label on every chat message - and, by extension, what tokens the @-mention picker accepts.

config.lua

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.

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

-- 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:

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

config.lua

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.

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

Get Started

Awoken Scripts

`nameSource`

Effect on `@`-mentions

`format` & `fallback`

Available tokens

Example formats

`prefixWithId`

Tags / badges

Tag fields

Priority resolution

​nameSource

​Effect on @-mentions

​format & fallback

​Available tokens

​Example formats

​prefixWithId

​Tags / badges

​Tag fields

​Priority resolution

`nameSource`

Effect on `@`-mentions

`format` & `fallback`

Available tokens

Example formats

`prefixWithId`

Tags / badges

Tag fields

Priority resolution