Avatars

Two avatar sources ship out of the box. Each player picks which one they want from the in-game Settings panel; the choice persists per-character (not just per-license, so two characters on the same license can have distinct avatars).

Source	What it renders	Server-side cost
`initials`	A coloured letter tile (first letter of the character’s first name, hashed colour background).	None - rendered entirely client-side.
`url`	An `<img>` tag pointing at the player’s chosen URL. Hostname + extension allowlisted.	One URL validation on save; image fetch happens in the player’s CEF.

config.lua

avatars = {
    sources = {
        initials = true,    -- ON: shows in the picker
        url      = true,    -- ON: shows in the picker
    },
    url = {
        allowedHosts = {
            'i.imgur.com',
            'imgur.com',
            'cdn.discordapp.com',
            'media.discordapp.net',
        },
        allowedExtensions = { 'png', 'jpg', 'jpeg', 'webp' },
    },
},

Sources toggle

sources = {
    initials = true,
    url      = true,
},

Setting either to false hides that source from the player’s picker. Players currently using a disabled source fall back to initials on their next connect.

Combination	Result
`initials = true, url = true`	Player sees both options in the picker. Default.
`initials = true, url = false`	No URL avatars - only the letter tile. Privacy-focused servers.
`initials = false, url = true`	Forces players to pick a URL. Not recommended - new players without a URL fall back to initials anyway.
Both `false`	Falls back to `initials`. The picker just shows that option as the only choice.

New players default to initials (hardcoded server-side). They keep using the letter tile until they actively pick a URL in the Settings panel.

URL allowlist

The biggest reason this isn’t a free-form text field: a player can otherwise paste any URL into the chat and force every other player’s CEF to fetch it. That’s a vector for tracking pixels, DDOS reflection, and IP-grabbing. The allowlist caps that.

url = {
    allowedHosts = {
        'i.imgur.com',
        'imgur.com',
        'cdn.discordapp.com',
        'media.discordapp.net',
    },
    allowedExtensions = { 'png', 'jpg', 'jpeg', 'webp' },
},

Validation rules

A URL is accepted iff all are true:

Starts with http:// or https://.
Hostname (just the host, no path) appears verbatim in allowedHosts (case-insensitive).
File extension appears verbatim in allowedExtensions (case-insensitive).
Total length ≤ 512 chars.

Failed validation surfaces an inline red error in the player’s Settings panel under the URL field, plus a chat system warning. The avatar doesn’t change.

Error key	Trigger
`avatar_url_empty`	Empty input.
`avatar_url_too_long`	Over 512 chars.
`avatar_url_malformed`	Not parseable as `http(s)://host/path.ext`.
`avatar_url_bad_host`	Hostname not in `allowedHosts`.
`avatar_url_bad_extension`	File extension not in `allowedExtensions`.

Per-character storage

Avatars are saved keyed by the framework’s character id (e.g. QBOX citizenid), not just the license. Two characters on the same license each have their own avatar.

// awoken_chat_settings.data (JSON blob for one player's license)
{
    "characterAvatars": {
        "QBX12345": { "source": "url", "url": "https://i.imgur.com/aaa.png" },
        "QBX67890": { "source": "initials" }
    },
    // ... other settings
}

When the player switches character mid-session:

Bridge fires qbx_core:server:onPlayerLoaded (or equivalent).
Server pushes the new character’s avatar fields to the NUI via settingsSaved.
Settings panel + every chat row updates live.

Standalone fallback

On a standalone server (no framework, no character id), the per-character layer doesn’t apply. Avatars save as flat avatarSource + avatarUrl keys on the settings row, applying license-wide. That’s the legacy behaviour pre-multichar.

Avatar in anonymous channels

For channels with anonymous = true:

The server strips avatarUrl from the payload before broadcasting.
The chat row renders a neutral grey silhouette tile (fa-user-secret icon) instead of the player’s real avatar.
Every recipient sees the same silhouette - the avatar tile is keyed to the channel, not the player.

The moment the player sends in a non-anonymous channel, their real avatar is back in the same chat session - no relog needed. See Categories for the full anonymous flag behaviour.

Avatar in Discord webhooks

When archiving messages to Discord:

The author block’s avatar uses the player’s URL avatar (if set).
Players using initials mode have no URL - the Discord embed shows a default Discord icon.

For anonymous channels with anonymousInWebhook = true, the avatar is omitted from the Discord embed too (matching the “Anonymous” label).

Get Started

Awoken Scripts

Sources toggle

URL allowlist

Validation rules

Per-character storage

Standalone fallback

Avatar in anonymous channels

Avatar in Discord webhooks

​Sources toggle

​URL allowlist

​Validation rules

​Per-character storage

​Standalone fallback

​Avatar in anonymous channels

​Avatar in Discord webhooks

Sources toggle

URL allowlist

Validation rules

Per-character storage

Standalone fallback

Avatar in anonymous channels

Avatar in Discord webhooks