Features Overview

Table of Contents

• Modern UI Design
• Proximity Chat System
• Line of Sight
• Job Radio Channels
• Private Messaging
• Chat Types & Styling
• Settings Panel
• Command Autocomplete
• Message History
• Rate Limiting
• Security Features
• Compatibility Layer
• Admin Commands

---

Modern UI Design

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

Visual Elements

• Glassmorphic Background: Semi-transparent with backdrop blur
• 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

Responsive Design

• Adjustable chat width (320-640px)
• Configurable position (9 preset positions or custom coordinates)
• Proper text wrapping for long messages
• Mobile-friendly touch interactions

---

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

Command	Range	Description
/me	15m	Roleplay actions
/do	15m	Environment descriptions
/whisper	3m	Quiet speech
/shout	50m	Loud speech
/looc	20m	Local out-of-character

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.

Built-in Channels

Command	Job	Prefix
/lspd, /pd, /police	police	[LSPD]
/ems, /ambulance, /medic	ambulance	[EMS]
/mechanic, /mech	mechanic	[MECHANIC]

How It Works

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

Message Format

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

Adding Custom Job Channels

Add to config/commands.lua:

{
    name = 'taxi',
    aliases = { 'cab' },
    description = 'Taxi company radio',
    type = 'job',
    jobs = { 'taxi' },
    chatType = 'taxi',
}

Then add chat type styling in config/main.lua:

Config.ChatTypes.taxi = {
    prefix = 'TAXI',
    color = '#FFFF00',
}

---

Private Messaging

Direct player-to-player messaging.

Commands

Command	Usage	Description
/msg, /pm, /dm	/msg [id] [message]	Send private message
/reply, /r	/reply [message]	Reply to last PM

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!

---

Chat Types & Styling

Color-coded message types for visual distinction.

Built-in Types

Type	Color	Prefix	Style
default	#F4F5F7	-	Normal
system	#5F6670	SYSTEM	Normal
announcement	#9B2C2C	ANNOUNCEMENT	Normal
ooc	#C47A2C	OOC	Normal
me	#F4F5F7	-	Italic
do	#5F6670	-	Italic
whisper	#C47A2C	WHISPER	Normal
shout	#9B2C2C	SHOUT	Normal
police	#3b82f6	LSPD	Normal
ambulance	#ef4444	EMS	Normal
mechanic	#f97316	MECHANIC	Normal

Custom Chat Types

Add to config/main.lua:

Config.ChatTypes.custom = {
    color = '#00FF00',
    prefix = 'CUSTOM',
    italic = false,
}

---

Settings Panel

Player-customizable chat experience.

Opening Settings

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

General Settings

Setting	Options	Description
Position	9 presets + custom	Where chat appears on screen
Font Size	12-20px	Text size for messages
Fade Time	0-60 seconds	When messages fade (0 = never)
Timestamp Mode	always/hover/never	When to show timestamps
Suggestions Position	top/bottom	Where autocomplete appears

Appearance Settings

Setting	Range	Description
Background Opacity	0-100%	Chat background transparency
Blur Intensity	0-20px	Backdrop blur amount
Chat Width	320-640px	Width of chat window
Message Density	compact/comfortable/spacious	Vertical spacing
Animations	on/off	Message fade animations

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 command name
• Shows command description and parameters
• Navigate with Arrow Up/Down
• Accept with Tab

Keyboard Navigation

Key	Action
Tab	Accept highlighted suggestion
Arrow Up	Previous suggestion
Arrow Down	Next suggestion
Escape	Close suggestions

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

• Configurable history size (default: 50 messages)
• Navigate with Arrow Up/Down when input is focused
• History persists during session
• Separate from message display history

Configuration

Config.InputHistorySize = 50  -- Previous inputs to remember
Config.MaxMessages = 100      -- Messages visible in chat

---

Rate Limiting

Prevent spam with configurable cooldowns.

Default Cooldowns

Type	Cooldown	Description
chat	1 second	Regular messages
proximity	1.5 seconds	/me, /do, /whisper, /shout, /looc
ooc	5 seconds	Global OOC messages
pm	1 second	Private messages and replies
announcement	30 seconds	Admin announcements

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 fetched server-side from QBCore
• 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

Event	Support
chat:addMessage	Full
chat:addSuggestion	Full
chat:addSuggestions	Full
chat:removeSuggestion	Full
chat:clear	Full
chatMessage	Full

Server Events

Event	Support
chat:addMessage	Full
chat:addSuggestion	Full
chat:removeSuggestion	Full
chat:clear	Full
chat:addTemplate	Full

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 Commands

Server administration commands.

/announce

Send server-wide announcement.

/announce Server restart in 10 minutes

• Requires admin ACE permission
• Has 30-second cooldown
• Can be used from console without cooldown

/clearchat

Clear chat history.

/clearchat        -- Clear for all players
/clearchat [id]   -- Clear for specific player

• Requires admin ACE permission
• Can target specific player or all

/testchat

Send test messages for all chat types (admin only).

/testchat         -- Send to self
/testchat [id]    -- Send to specific player (console)