Chat

The Chat class is a static service for global communication. Messages are assigned unique IDs when created and are managed using these IDs, not objects.

Error Handling Pattern

This API uses the "Error or Nil" pattern.

• If a function succeeds, it returns nil for the error parameter
• If a function fails, it returns a string error message

Static Service: Chat

Function	Description	Scope
Chat.Send	Sends a message with optional broadcast options	S
Chat.EditMessage	Updates content for a message with targeting options	S
Chat.RemoveMessage	Deletes messages with targeting options	S
Chat.GetMessages	Retrieves messages with filtering options	S
Chat.GetMessageInfo	Gets detailed information about a specific message	S
Chat.Clear	Clears chat history	S
Chat.MutePlayer	Mutes or unmutes a player	S
Chat.IsPlayerMuted	Checks if a player is muted	S

Functions

Chat.Send

S Shared (Client & Server)

local messageId, err = Chat.Send(content, options)

Parameters:

• content (string): The message content to send S
• options (table): Optional configuration
  • broadcast (boolean): If true, sends to all players S
  • target (Player | table): Specific player(s) to send to S
    • Can be a single Player object
    • Can be a table of Player objects or player IDs
  • color (string): Hex color code (e.g., "#FF0000") S
  • showSender (boolean): If false, displays only message content (defaults to true) S
  • channel (string): Chat channel (e.g., "global", "team", "admin") S

Returns:

• messageId (string): Unique identifier for the created message (or nil on failure)
• err: nil on success, or a string error message

Chat.EditMessage

S Shared (Client & Server)

local err = Chat.EditMessage(messageId, newText, options)

Parameters:

• messageId (string): The ID of the message to edit S
• newText (string): The updated message content S
• options (table): Optional configuration
  • broadcast (boolean): If true, edits for all players S
  • target (Player | table): Specific player(s) to edit for S
    • Can be a single Player object
    • Can be a table of Player objects or player IDs

Returns:

• err: nil on success, or a string error message

Chat.RemoveMessage

S Shared (Client & Server)

local err = Chat.RemoveMessage(messageId, options)

Parameters:

• messageId (string): The ID of the message to remove S
• options (table): Optional configuration
  • broadcast (boolean): If true, removes for all players S
  • target (Player | table): Specific player(s) to remove for S
    • Can be a single Player object
    • Can be a table of Player objects or player IDs

Returns:

• err: nil on success, or a string error message

Chat.GetMessages

S Shared (Client & Server)

local messages, err = Chat.GetMessages(options)

Parameters:

• options (table): Optional filtering configuration
  • limit (number): Maximum number of messages to retrieve (defaults to 50) S
  • channel (string): Filter by channel S
  • sender (string): Filter by sender name/ID S
  • after (number | Player | table): Get messages after timestamp, or from specific player(s) S
  • before (number | Player | table): Get messages before timestamp, or from specific player(s) S
  • target (Player | table): Get messages for specific player(s) S

Returns:

• messages (table): Array of message objects (or nil on failure)
• err: nil on success, or a string error message

Chat.GetMessageInfo

S Shared (Client & Server)

local messageInfo, err = Chat.GetMessageInfo(messageId)

Parameters:

• messageId (string): The ID of the message to get information about S

Returns:

• messageInfo (table): Detailed message information (or nil on failure)
  • id (string): Message ID
  • content (string): Message content
  • sender (string): Sender name/ID
  • timestamp (number): Creation timestamp
  • channel (string): Chat channel
  • color (string): Message color
  • edited (boolean): Whether message was edited
  • editTimestamp (number): Last edit timestamp (if edited)
• err: nil on success, or a string error message

Chat.Clear

S Shared (Client & Server)

local err = Chat.Clear(options)

Parameters:

• options (table): Optional configuration
  • broadcast (boolean): If true, clears for all players S

Returns:

• err: nil on success, or a string error message

Chat.MutePlayer

S Server Only

local err = Chat.MutePlayer(playerId, duration, reason)

Parameters:

• playerId (string): The ID of the player to mute S
• duration (number): Mute duration in minutes (0 for permanent) S
• reason (string): Optional reason for the mute S

Returns:

• err: nil on success, or a string error message

Chat.IsPlayerMuted

S Shared (Client & Server)

local isMuted, err = Chat.IsPlayerMuted(playerId)

Parameters:

• playerId (string): The ID of the player to check S

Returns:

• isMuted (boolean): Whether the player is muted (or nil on failure)
• err: nil on success, or a string error message

Constants & Constraints

Constant	Value	Description
Chat.MAX_LENGTH	512	Max characters per message
Chat.RATE_LIMIT	1.5	Cooldown in seconds for Chat.Send
Chat.MAX_HISTORY	1000	Maximum messages stored in history
Chat.MAX_TARGETS	50	Maximum players for targeted messages
Chat.MUTE_MAX_DURATION	1440	Maximum mute duration in minutes (24 hours)
Chat.CHANNELS	["global", "team", "admin", "system", "whisper"]	Available chat channels

Events

Server Events

Event	Description	Parameters
onChatMessage	Triggered when any message is sent	messageId (string), sender (string), content (string), options (table)
onChatMessageEdited	Triggered when a message is edited	messageId (string), oldContent (string), newContent (string), editor (string)
onChatMessageRemoved	Triggered when a message is removed	messageId (string), remover (string)
onPlayerMuted	Triggered when a player is muted	playerId (string), duration (number), reason (string), moderator (string)
onPlayerUnmuted	Triggered when a player is unmuted	playerId (string), moderator (string)

Client Events

Event	Description	Parameters
onChatMessage	Triggered when client receives a message	messageId (string), sender (string), content (string), options (table)
onChatMessageEdited	Triggered when client sees an edited message	messageId (string), newContent (string)
onChatMessageRemoved	Triggered when client sees a removed message	messageId (string)
onChatCleared	Triggered when chat is cleared	clearedBy (string)

Event Handlers

onChatMessage

S Shared (Client & Server)

AddEventHandler('onChatMessage', function(messageId, sender, content, options)
    -- Message was sent (server) or received (client)
end)

Parameters:

• messageId (string): ID of the message
• sender (string): ID/name of the sender
• content (string): Message content
• options (table): Message options (channel, color, etc.)

onChatMessageEdited

S Shared (Client & Server)

AddEventHandler('onChatMessageEdited', function(messageId, oldContent, newContent, editor)
    -- Message was edited (server) or edit received (client)
end)

Parameters:

• messageId (string): ID of the edited message
• oldContent (string): Original message content (server only, nil on client)
• newContent (string): Updated message content
• editor (string): ID/name of who edited the message

onChatMessageRemoved

S Shared (Client & Server)

AddEventHandler('onChatMessageRemoved', function(messageId, remover)
    -- Message was removed (server) or removal received (client)
end)

Parameters:

• messageId (string): ID of the removed message
• remover (string): ID/name of who removed the message (server only, nil on client)

onPlayerMuted

S Server Only

AddEventHandler('onPlayerMuted', function(playerId, duration, reason, moderator)
    -- Player was muted
end)

Parameters:

• playerId (string): ID of the muted player
• duration (number): Mute duration in minutes (0 = permanent)
• reason (string): Reason for the mute
• moderator (string): ID/name of who performed the mute

onPlayerUnmuted

S Server Only

AddEventHandler('onPlayerUnmuted', function(playerId, moderator)
    -- Player was unmuted
end)

Parameters:

• playerId (string): ID of the unmuted player
• moderator (string): ID/name of who performed the unmute

onChatCleared

S Shared (Client & Server)

AddEventHandler('onChatCleared', function(clearedBy)
    -- Chat was cleared
end)

Parameters:

• clearedBy (string): ID/name of who cleared the chat

Error Codes

• ERR_RATE_LIMIT: Throttled by the server
• ERR_NOT_FOUND: Message object no longer exists in memory
• ERR_FILTERED: Content blocked by safety systems
• ERR_MSG_TOO_LONG: Content exceeds MAX_LENGTH
• ERR_INVALID_COLOR: Invalid color format
• ERR_INVALID_CHANNEL: Invalid channel name
• ERR_TOO_MANY_TARGETS: Target list exceeds maximum
• ERR_PLAYER_NOT_FOUND: Target player not found
• ERR_PERMISSION_DENIED: Insufficient permissions for operation
• ERR_ALREADY_MUTED: Player is already muted
• ERR_NOT_MUTED: Player is not muted
• ERR_INVALID_DURATION: Duration exceeds maximum or is negative
• ERR_EMPTY_CONTENT: Message content is empty
• ERR_SYSTEM_CHANNEL: Cannot send to system channel
• ERR_MESSAGE_LOCKED: Message is locked and cannot be edited/removed