Features Overview

Complete feature reference for oxide-chat.

Modern UI Design

Oxide Chat features a professional, modern interface with glassmorphism styling.

Visual Elements

• Frosted-glass look: Layered translucency (noise, sheen, and inset glow) gives a frosted appearance without relying on backdrop blur, which the FiveM UI does not render correctly
• Smooth Animations: Fade-in/out for messages
• Custom Scrollbar: Styled scrollbar for message history
• Typography: Clean, readable font with proper spacing
• Color-Coded Messages: Different colors for each chat type

Adjustable Layout

• Adjustable chat width (320-640px) and height (160-600px)
• Configurable position (8 preset positions or custom coordinates by dragging)
• Proper text wrapping for long messages

Proximity Chat System

Roleplay-focused chat with distance-based message delivery.

How It Works

1. Player sends a proximity message (e.g., /me waves)
2. Server calculates nearby players within configured range
3. Only players in range receive the message
4. Optional Line of Sight check for immersion

Proximity Commands

Configuration

-- config/main.lua
Config.ProximityDistance = {
    me = 15.0,
    ['do'] = 15.0,
    whisper = 3.0,
    shout = 50.0,
    local_ooc = 20.0,
}

Line of Sight

Immersive LOS checking for proximity messages.

How It Works

• Uses StartShapeTestLosProbe() to raycast between players
• Checks for obstacles at eye level (0.7m offset)
• Players in the same vehicle are exempt from LOS checks
• LOS check is client-side for performance; security relies on server distance checks

Configuration

Config.RequireLOS = {
    me = true,      -- /me requires line of sight
    ['do'] = true,  -- /do requires line of sight
    whisper = false, -- Whisper works through walls
    shout = false,   -- Shout works through walls
    local_ooc = false,
}

Design Notes

LOS validation is intentionally client-side:

• Server-side raycasts are unreliable in FiveM
• Security is enforced by server-side distance checks
• Client-side LOS is for immersion only

Job Radio Channels

Dedicated chat channels for job-specific communication. These are the ready-made examples of the wider Custom Chat Channels system — they are ordinary channel rows an admin can restyle, retarget to other jobs, or remove entirely.

Built-in Channels

How It Works

1. Player sends a job message (e.g., /lspd Responding to call)
2. Server validates the player's job (server-authoritative)
3. Message is sent only to players with the same job
4. Message includes the sender's name and job grade

Message Format

[LSPD] John Smith (Sergeant): Responding to the scene

Managing Job Radios

Job radios are managed in-game like any other channel — an admin opens /chat settings → Messaging → Chat Types to edit their styling, change which jobs they belong to, add new radios, or delete them, with no restart. See Custom Chat Channels below and the Admin Guide.

Custom Chat Channels

Admins can create their own slash-command channels — job radios, staff chat, business radios, event channels, and more — entirely in-game, with no file editing and no restart. Each channel is a custom row in the chat types list (/chat settings → Messaging → Chat Types), sitting alongside the built-in message styling.

What a channel can do

• Its own command and aliases — e.g. /staff, or /lspd with /pd and /leo as aliases.
• Its own styling — prefix, color, and italics, shown right on its message.
• A scope that decides who sends and who sees:
  • Members only (radio) — only qualifying players send and see the traffic.
  • Everyone — anyone sends, everyone sees.
  • Members send, everyone sees — only qualifying players send, but everyone reads it.
  • Nearby players — only players within range see it (with an optional line-of-sight check).
• A restriction that decides who may use it — no restriction, specific jobs (with optional minimum grade and on-duty requirement), or admins only.
• A per-channel cooldown to limit how often each player can send.

How It Works

1. An admin adds a channel row in /chat settings and saves.
2. The command works immediately for every allowed player who is online — no restart.
3. The restriction is enforced on the server, so it can't be bypassed.
4. Deleting a channel stops it working right away (its command lingers until the next restart, then politely refuses).

Automatic integration

• Player colors: every channel's chat type automatically appears in each player's personal color settings (/chat customize → Colors tab) for recoloring and visibility toggles.
• Command suggestions: new channels show up in the autocomplete list for the players allowed to use them.
• Category tabs: a channel can be grouped into a tab by adding its chat type ID to a category (see Chat Categories).

See the Admin Guide for the full walkthrough and Configuration for the factory defaults.

Private Messaging

Direct player-to-player messaging.

Commands

Features

• Reply Tracking: Last PM sender is tracked for quick replies
• Confirmation: Sender sees confirmation of sent message
• Validation: Server validates target exists and is online
• Cleanup: Reply tracking is cleaned when players disconnect

Message Format

[PM from John Smith (5)]: Hey, can we meet?
[PM to Jane Doe (12)]: Sure, on my way!

Friends & Block List

A character-based social graph built into chat. Friends and blocks are tied to a player's character, so they persist between sessions.

Features

• Consent-based requests: Adding someone sends a friend request; they have to accept it. If they've already requested you, adding them accepts it automatically.
• Presence: Friends show as online or offline, and you get a notification when a friend comes online.
• Block list: Blocking someone drops any existing friendship and stops private messages between the two of you (in both directions).
• Persistence: Data is stored in the chat_friends and chat_blocks database tables, which are created automatically on first start (the schema also ships in sql/install.sql).
• Friends panel: The chat UI includes a friends panel for viewing your friends, responding to requests, and managing blocks.

Commands

See Commands — Friends for details. Other resources can also read and manage the social graph through server exports — see Exports — Friends & Blocks.

Chat Categories (Tabs)

Chat types can be grouped into switchable tabs shown above the message list — for example an "All" tab, a "Local" tab for roleplay chat, and a "PMs" tab. Tabs are purely visual: they filter which messages are displayed and never change who receives a message.

Default Tabs

Tabs are fully configurable — you can add, remove, or reorder them. See Configuration — Chat Categories. Players can also hide the tab bar in their appearance settings.

Automatic Announcements

Broadcast a rotating list of messages to everyone on the server on a timer — ideal for server rules, Discord links, and event reminders.

Features

• Rotating list: Cycle through your messages in order or pick one at random.
• Configurable interval: Set how many seconds pass between messages (minimum 30).
• Empty-server aware: Broadcasts are skipped when no one is online.
• Runtime toggle: Admins can turn announcements on or off with /chat autobroadcast on|off without restarting, and the choice is saved across restarts.

See Configuration — Automatic Announcements for setup and Commands for the command.

Mentions

Players can mention each other with @ in chat.

Features

• Autocomplete: Typing @ and part of a name suggests matching online players.
• Highlighting: Explicit @mentions are highlighted in the message (matching the style of apps like Discord and Slack), and a player's own name is highlighted when they're mentioned.
• Live player list: The list of online players used for autocomplete is kept up to date as players join and leave.

Inline Images & GIFs

Players can share pictures and GIFs directly in chat.

Features

• Pasted image links: A direct image link (.png, .jpg, .jpeg, .gif, .webp) pasted into a message shows as the picture itself. Works in every message type — normal chat, PMs, OOC, the RP commands and custom channels.
• GIF picker: A GIF button next to the emoji picker opens a Giphy search. Clicking a GIF posts it to chat, Discord-style. Requires a free Giphy API key in server.cfg — the button stays hidden until one is set.
• Allowed-hosts whitelist: Only links from sites you approve will embed (Giphy and the Discord CDN by default). Everything else stays plain text. Note: imgur blocks the FiveM game client, so imgur links can't display in-game.
• Sender restriction: Optionally limit image sending to specific jobs (with a minimum grade) or admins only.
• Own cooldown: Images have their own per-player rate limit, separate from the normal chat cooldown.
• Server-side checks: Link validation, host checks, permissions and cooldowns are all enforced on the server, and Giphy searches go through the server so the API key never reaches players.

See Configuration — Images & GIFs for setup, including how to get the Giphy key.

Chat Types & Styling

Color-coded message types for visual distinction.

Built-in Types

Every chat type — the built-in ones and any custom channels — lives in a single list, Config.ChatChannels. The first nine rows above (default through pm) are the built-in message styling; the police, ambulance, and mechanic types come from the three job-radio channels that ship in the same list. All of them are restyled the same way, in /chat settings → Messaging → Chat Types. See Custom Chat Channels and Configuration — Chat Types.

Custom Chat Types

To add a new chat type with its own color and prefix, add a custom row to the chat types list — in /chat settings → Messaging → Chat Types, or as a factory default in Config.ChatChannels:

{
    command = 'taxi', label = 'Taxi Radio',
    prefix = 'TAXI', color = '#00FF00', italic = false,
    scope = 'global', restrict = 'none',
}

A custom row's chat type ID can't be one of the built-in ones (me, do, ooc, pm, and so on).

Settings Panel

Player-customizable chat experience.

Opening Settings

• Type /chat customize in chat
• Click the gear icon in chat header (if visible)

General Settings

Appearance Settings

Per-Type Settings

• Toggle visibility for each chat type
• Custom color overrides per chat type

Data Management

• Export settings as base64 JSON
• Import settings from another client
• Automatic migration between setting versions

Command Autocomplete

Smart command suggestions while typing.

Features

• Suggestions appear as you type /
• Filter by typing the command name
• Shows command description and parameters
• Move the highlight with Tab or the arrow keys
• Accept the highlighted command with Enter (this completes it in the box; it does not send)

Keyboard Navigation

Blacklisting Commands

Hide internal/debug commands from suggestions:

-- config/blacklist.lua
Config.BlacklistedPrefixes = {
    ['_'] = true,     -- Hide _internal commands
    ['dev'] = true,   -- Hide dev* commands
}

Config.BlacklistedCommands = {
    'secretCommand',  -- Hide specific command
}

Message History

Navigate through previous messages.

Features

• Recall messages you have already sent with Arrow Up/Down when the input is focused
• History persists during your session
• Separate from the message display history

Configuration

Config.MaxMessages = 100      -- Messages visible in chat

Rate Limiting

Prevent spam with configurable cooldowns.

Default Cooldowns

Configuration

Config.Cooldowns = {
    chat = 1000,          -- 1 second
    proximity = 1500,     -- 1.5 seconds
    ooc = 5000,           -- 5 seconds
    pm = 1000,            -- 1 second
    announcement = 30000, -- 30 seconds
}

Behavior

• Players receive notification when rate limited
• Shows remaining cooldown time
• Console/rcon commands bypass cooldowns

Security Features

Protection against common exploits.

Server-Side Validation

• Message Sanitization: Control characters stripped
• Length Limits: Max 256 characters per message
• Job Validation: Server verifies job for job chat
• Target Validation: PM targets verified online
• Cooldown Enforcement: Rate limits server-side

Name Spoofing Prevention

• Character names are fetched server-side through the o-link bridge (works with any supported framework)
• Client cannot override display names in messages

Memory Leak Prevention

• Cooldown tables cleaned on player disconnect
• PM reply tracking cleaned on disconnect

Compatibility Layer

Full support for standard FiveM chat API.

Client Events

Server Events

Exports

Both exports['oxide-chat'] and exports['chat'] work:

exports['chat']:addMessage(source, { args = { 'Test' } })
exports['oxide-chat']:addMessage({ args = { 'Test' } })

See Exports & API for complete API documentation.

Admin Settings Panel

Admins can edit almost every server-wide setting live, in-game — no file editing and no restart. Type /chat settings to open it.

Features

• Database-backed: settings live in a shared oxide_settings database table. On the first server start the values from config/main.lua are imported; after that the panel is the place to change them, and the changes stick across restarts.
• Organized and searchable: settings are grouped into sidebar categories (Core, Messaging, Broadcasts, Players) with Basic and Advanced views and a search box.
• Applies live to everyone: saving updates every connected player right away — new colors, category tabs, cooldowns, and so on take effect without anyone reconnecting.
• Reset to default: each field has a reset button that restores the config/main.lua factory value.

See the Admin Guide for the full walkthrough of the panel and every admin command.

Admin Commands

All admin tools are subcommands of a single /chat command. They require admin permission (the server console can always run them). See the Admin Guide for details.

/chat announce

Send a server-wide announcement. Supports a Title | Body format to add a bold heading.

/chat announce Server restart in 10 minutes
/chat announce Event Tonight | Race meet at the docks, 8 PM

• Has a 30-second cooldown (the console has none)

/chat clear

Clear the chat window for everyone, or for one player.

/chat clear        -- Clear for all players
/chat clear [id]   -- Clear for a specific player

/chat test

Send sample messages of every chat type — handy for checking colors.

/chat test         -- Send to yourself

From the server console, add a player ID: chat test [id].

/chat autobroadcast

Turn automatic announcements on or off at runtime. The choice is saved and survives restarts.

/chat autobroadcast on     -- Enable
/chat autobroadcast off    -- Disable
/chat autobroadcast        -- Toggle

See Automatic Announcements for setup.

/chat settings

Open the Admin Settings Panel described above (in-game only).

Next Steps