Configuration Reference

Table of Contents

• Configuration Files
• General Settings
• Keybinds
• UI Settings
• Proximity Settings
• Line of Sight Settings
• Chat Type Styling
• Cooldowns
• Default Player Settings
• Command Blacklist
• Debug Mode
• Complete Default Configuration

---

Configuration Files

Configuration is split across multiple files in the config/ folder:

File	Purpose
main.lua	Core settings, UI, proximity, chat types
commands.lua	Command definitions with formatting
blacklist.lua	Commands to hide from suggestions

---

General Settings

Config.MaxMessages

Maximum messages kept in chat history.

Config.MaxMessages = 100

Config.MaxMessageLength

Maximum characters per message.

Config.MaxMessageLength = 256

Config.MessageFadeTime

Time in milliseconds before messages fade. Set to 0 to disable fading.

Config.MessageFadeTime = 10000  -- 10 seconds

Config.InputHistorySize

Number of previous inputs to remember for arrow-key navigation.

Config.InputHistorySize = 50

---

Keybinds

Config.OpenKey

Key to open chat input.

Config.OpenKey = 'T'

Config.CloseKey

Key to close chat input.

Config.CloseKey = 'Escape'

Note: Keybinds can be changed by players in FiveM settings under "Key Bindings".

---

UI Settings

Config.UI

Basic UI configuration.

Config.UI = {
    position = 'left',   -- 'left' or 'right' (legacy, use DefaultSettings)
    width = 550,         -- Chat width in pixels
    height = 320,        -- Chat height in pixels
}

Note: These are default values. Players can customize via the settings panel.

---

Proximity Settings

Config.ProximityDistance

Distance in meters for each proximity chat type.

Config.ProximityDistance = {
    me = 15.0,           -- /me action range
    ['do'] = 15.0,       -- /do description range
    whisper = 3.0,       -- /whisper range (very close)
    shout = 50.0,        -- /shout range (long distance)
    local_ooc = 20.0,    -- /looc range
}

Choosing Ranges

Range	Use Case
3-5m	Intimate/whisper
10-20m	Normal conversation
30-50m	Shouting/yelling
50m+	Very loud events

---

Line of Sight Settings

Config.RequireLOS

Whether each chat type requires line of sight.

Config.RequireLOS = {
    me = true,           -- /me requires seeing the player
    ['do'] = true,       -- /do requires seeing the player
    whisper = false,     -- Whisper works through walls
    shout = false,       -- Shout works through walls
    local_ooc = false,   -- LOOC works through walls
}

How LOS Works

• Uses raycasting from eye level to eye level
• Players in the same vehicle are always visible
• Client-side check for immersion (server handles security via distance)

---

Chat Type Styling

Config.ChatTypes

Styling for each message type.

Config.ChatTypes = {
    default = {
        color = '#F4F5F7',
    },
    system = {
        prefix = 'SYSTEM',
        color = '#5F6670',
    },
    announcement = {
        prefix = 'ANNOUNCEMENT',
        color = '#9B2C2C',
    },
    ooc = {
        prefix = 'OOC',
        color = '#C47A2C',
    },
    me = {
        color = '#F4F5F7',
        italic = true,
    },
    ['do'] = {
        color = '#5F6670',
        italic = true,
    },
    whisper = {
        prefix = 'WHISPER',
        color = '#C47A2C',
    },
    shout = {
        prefix = 'SHOUT',
        color = '#9B2C2C',
    },
    -- Job channels
    police = {
        prefix = 'LSPD',
        color = '#3b82f6',
    },
    ambulance = {
        prefix = 'EMS',
        color = '#ef4444',
    },
    mechanic = {
        prefix = 'MECHANIC',
        color = '#f97316',
    },
}

Chat Type Properties

Property	Type	Description
color	string	Hex color code
prefix	string	Prefix shown before message
italic	boolean	Whether to italicize message

Adding Custom Types

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

---

Cooldowns

Config.Cooldowns

Rate limiting in milliseconds.

Config.Cooldowns = {
    ooc = 5000,          -- 5 seconds between OOC messages
    announcement = 30000, -- 30 seconds between announcements
    chat = 1000,         -- 1 second between regular messages
    pm = 1000,           -- 1 second between private messages
    proximity = 1500,    -- 1.5 seconds between /me, /do, etc.
}

Cooldown Behavior

• Cooldowns are enforced server-side
• Players receive notification with remaining time
• Console commands bypass cooldowns

---

Default Player Settings

Config.DefaultSettings

Default values for player-customizable settings. These are used when no saved settings exist.

Config.DefaultSettings = {
    -- Position
    position = 'top-left',        -- 3x3 grid or 'custom'
    gradientDirection = '90deg',  -- Gradient angle for custom position
    customX = 24,                 -- Custom X position (px)
    customY = 24,                 -- Custom Y position (px)

    -- General
    fontSize = 14,                -- Font size (12-20)
    fadeTime = 10,                -- Fade time in seconds (0 = never)
    timestampMode = 'hover',      -- 'always', 'hover', 'never'
    suggestionsPosition = 'top',  -- 'top' or 'bottom'

    -- Per-type visibility and colors
    chatTypes = {
        ooc = { visible = true, color = '#C47A2C' },
        me = { visible = true, color = '#F4F5F7' },
        ['do'] = { visible = true, color = '#5F6670' },
        system = { visible = true, color = '#5F6670' },
        whisper = { visible = true, color = '#C47A2C' },
        shout = { visible = true, color = '#9B2C2C' },
        announcement = { visible = true, color = '#9B2C2C' },
        police = { visible = true, color = '#3b82f6' },
        ambulance = { visible = true, color = '#ef4444' },
        mechanic = { visible = true, color = '#f97316' },
    },

    -- Appearance
    appearance = {
        backgroundOpacity = 75,        -- 0-100%
        blurIntensity = 8,             -- 0-20px
        chatWidth = 480,               -- 320-640px
        animationsEnabled = true,      -- Message animations
        messageDensity = 'comfortable', -- 'compact', 'comfortable', 'spacious'
    },

    _version = 2,  -- Settings schema version
}

Position Options

Value	Location
top-left	Top left corner
top-middle	Top center
top-right	Top right corner
left	Middle left
center	Screen center
right	Middle right
bottom-left	Bottom left corner
bottom-middle	Bottom center
bottom-right	Bottom right corner
custom	Uses customX/customY values

Timestamp Modes

Value	Description
always	Always show timestamps
hover	Show on message hover
never	Never show timestamps

Message Density

Value	Vertical Padding
compact	Minimal spacing
comfortable	Default spacing
spacious	Extra spacing

---

Command Blacklist

Config.BlacklistedPrefixes

Hide commands starting with these prefixes from suggestions.

Config.BlacklistedPrefixes = {
    ['_'] = true,      -- Internal commands
    ['dev'] = true,    -- Developer commands
    ['debug'] = true,  -- Debug commands
    ['test'] = true,   -- Test commands
}

Config.BlacklistedCommands

Hide specific commands from suggestions.

Config.BlacklistedCommands = {
    'toggleChat',   -- Internal toggle
    'chatResult',   -- NUI callback
}

Config.IsBlacklisted()

Helper function to check if a command is blacklisted.

if Config.IsBlacklisted('devCommand') then
    -- Command won't appear in suggestions
end

---

Debug Mode

Config.Debug

Enable debug logging and features.

Config.Debug = false

When Enabled

• Server print messages appear in chat
• Additional console logging
• Debug commands available

Production

Always set to false in production:

Config.Debug = false

---

Complete Default Configuration

config/main.lua

Config = Config or {}

-- General Settings
Config.MaxMessages = 100
Config.MaxMessageLength = 256
Config.MessageFadeTime = 10000
Config.InputHistorySize = 50

-- Keybinds
Config.OpenKey = 'T'
Config.CloseKey = 'Escape'

-- UI Settings
Config.UI = {
    position = 'left',
    width = 550,
    height = 320,
}

-- Proximity Settings
Config.ProximityDistance = {
    me = 15.0,
    ['do'] = 15.0,
    whisper = 3.0,
    shout = 50.0,
    local_ooc = 20.0,
}

-- Line of Sight
Config.RequireLOS = {
    me = true,
    ['do'] = true,
    whisper = false,
    shout = false,
    local_ooc = false,
}

-- Chat Type Styling
Config.ChatTypes = {
    default = { color = '#F4F5F7' },
    system = { prefix = 'SYSTEM', color = '#5F6670' },
    announcement = { prefix = 'ANNOUNCEMENT', color = '#9B2C2C' },
    ooc = { prefix = 'OOC', color = '#C47A2C' },
    me = { color = '#F4F5F7', italic = true },
    ['do'] = { color = '#5F6670', italic = true },
    whisper = { prefix = 'WHISPER', color = '#C47A2C' },
    shout = { prefix = 'SHOUT', color = '#9B2C2C' },
    police = { prefix = 'LSPD', color = '#3b82f6' },
    ambulance = { prefix = 'EMS', color = '#ef4444' },
    mechanic = { prefix = 'MECHANIC', color = '#f97316' },
}

-- Cooldowns (milliseconds)
Config.Cooldowns = {
    ooc = 5000,
    announcement = 30000,
    chat = 1000,
    pm = 1000,
    proximity = 1500,
}

-- Debug Mode
Config.Debug = false