Chatbox Library

Comprehensive chat system management with message routing and formatting for the Lilia framework.

---

Overview

The chatbox library provides comprehensive functionality for managing chat systems in the Lilia framework. It handles registration of different chat types (IC, OOC, whisper, etc.), message parsing and routing, distance-based hearing mechanics, and chat formatting. The library operates on both server and client sides, with the server managing message distribution and validation, while the client handles parsing and display formatting. It includes support for anonymous messaging, custom prefixes, radius-based communication, and integration with the command system for chat-based commands.

---

lia.chat.timestamp

📋 Purpose

Generates a formatted timestamp string for chat messages based on current time

⏰ When Called

Automatically called when displaying chat messages if timestamps are enabled

⚙️ Parameters

Parameter	Type	Description
ooc	boolean	Whether this is an OOC message (affects spacing format)

↩️ Returns

• string - Formatted timestamp string or empty string if timestamps disabled

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    -- Simple: Get timestamp for IC message
    local timestamp = lia.chat.timestamp(false)
    -- Returns: " (14:30) " or "" if timestamps disabled

📊 Medium Complexity

    -- Medium: Use timestamp in custom chat format
    local function customChatFormat(speaker, text)
        local timeStr = lia.chat.timestamp(false)
        chat.AddText(timeStr, Color(255, 255, 255), speaker:Name() .. ": " .. text)
    end

⚙️ High Complexity

    -- High: Dynamic timestamp with custom formatting
    local function getFormattedTimestamp(isOOC, customFormat)
        local baseTime = lia.chat.timestamp(isOOC)
        if customFormat and baseTime ~= "" then
            return baseTime:gsub("%((%d+:%d+)%)", "[" .. customFormat .. "]")
        end
        return baseTime
    end

---

lia.chat.register

📋 Purpose

Registers a new chat type with the chatbox system, defining its behavior and properties

⏰ When Called

During module initialization to register custom chat types (IC, OOC, whisper, etc.)

⚙️ Parameters

Parameter	Type	Description
chatType	string	Unique identifier for the chat type
data	table	Configuration table containing chat type properties

↩️ Returns

• nil

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    -- Simple: Register basic IC chat
    lia.chat.register("ic", {
        prefix = "/",
        color  = Color(255, 255, 255),
        radius = 200
    })

📊 Medium Complexity

    -- Medium: Register whisper chat with custom properties
    lia.chat.register("whisper", {
        prefix = {"/w", "/whisper"},
        color  = Color(150, 150, 255),
        radius = 50,
        format = "whisperFormat",
        desc   = "Whisper to nearby players"
    })

⚙️ High Complexity

    -- High: Register admin chat with complex validation
    lia.chat.register("admin", {
        prefix    = "/a",
        color     = Color(255, 100, 100),
        onCanSay  = function(speaker)
            return speaker:IsAdmin()
        end,
        onCanHear = function(speaker, listener)
            return listener:IsAdmin()
        end,
        format    = "adminFormat",
        arguments = {
            {type = "string", name = "message"}
        },
        desc      = "Admin-only communication channel"
    })

---

lia.chat.parse

📋 Purpose

Parses a chat message to determine its type and extract the actual message content

⏰ When Called

When a player sends a chat message, either from client input or server processing

⚙️ Parameters

Parameter	Type	Description
client	Player	The player who sent the message
message	string	The raw message text to parse
noSend	boolean, optional	If true, prevents sending the message to other players

↩️ Returns

• chatType (string), message (string), anonymous (boolean)

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    -- Simple: Parse a basic IC message
    local chatType, message, anonymous = lia.chat.parse(LocalPlayer(), "Hello everyone!")
    -- Returns: "ic", "Hello everyone!", false

📊 Medium Complexity

    -- Medium: Parse message with prefix detection
    local function processPlayerMessage(player, rawMessage)
        local chatType, cleanMessage, anonymous = lia.chat.parse(player, rawMessage)
        if chatType == "ooc" then
            print(player:Name() .. " said OOC: " .. cleanMessage)
        end
        return chatType, cleanMessage, anonymous
    end

⚙️ High Complexity

    -- High: Advanced message processing with validation
    local function advancedMessageParser(player, message, options)
        local chatType, cleanMessage, anonymous = lia.chat.parse(player, message, options.noSend)
        -- Custom validation based on chat type
        if chatType == "admin" and not player:IsAdmin() then
            player:notifyErrorLocalized("noPerm")
            return nil, nil, nil
        end
        -- Log message for moderation
        if options.logMessages then
            lia.log.add("chat", player:Name() .. " [" .. chatType .. "]: " .. cleanMessage)
        end
        return chatType, cleanMessage, anonymous
    end

---

lia.chat.send

📋 Purpose

Sends a chat message to appropriate recipients based on chat type and hearing rules

⏰ When Called

Server-side when distributing parsed chat messages to players

⚙️ Parameters

Parameter	Type	Description
speaker	Player	The player who sent the message
chatType	string	The type of chat message (ic, ooc, whisper, etc.)
text	string	The message content to send
anonymous	boolean, optional	Whether to hide the speaker's identity
receivers	table, optional	Specific list of players to send to

↩️ Returns

• nil

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    -- Simple: Send IC message to all nearby players
    lia.chat.send(player, "ic", "Hello everyone!")

📊 Medium Complexity

    -- Medium: Send anonymous whisper to specific players
    local function sendAnonymousWhisper(speaker, message, targets)
        lia.chat.send(speaker, "whisper", message, true, targets)
    end

⚙️ High Complexity

    -- High: Advanced message broadcasting with custom logic
    local function broadcastAdminMessage(speaker, message, options)
        local receivers = {}
        -- Collect admin players
        for _, player in player.Iterator() do
            if player:IsAdmin() and (not options.excludeSelf or player ~= speaker) then
                table.insert(receivers, player)
            end
        end
        -- Send with custom formatting
        lia.chat.send(speaker, "admin", "[ADMIN] " .. message, false, receivers)
        -- Log the message
        lia.log.add("admin_chat", speaker:Name() .. ": " .. message)
    end

---