Skip to content

Chat Box

Picture

Image of the Chat Box block

The Chat Box is able to read and write messages to the in-game chat. You can send messages to just one player or to everyone.

Hint

If you prefix your message with a $ the message will not be sent to the global chat but it will still fire the chat event.
Example:
$this message is hidden!

Peripheral Name Interfaces with Has events Introduced in
chatBox Game Chat Yes 0.1b

Events

chat

Fires when a player sends a message into the chat.
Values:
1. username: string The username of the player who sent the message
2. message: string The message sent by the player
3. uuid: string The player's uuid
4. isHidden: boolean Whether the message is hidden or not

1
2
local event, username, message, uuid, isHidden = os.pullEvent("chat")
print("The 'chat' event was fired with the username " .. username .. " and the message " .. message)

Info

The chat event will fire when a chatbox has been connected to a computer. You don't have to .wrap() or .find() the peripheral (unless you intend to send messages).

Functions

sendMessage

sendMessage(message: string[, prefix: string, brackets: string, bracketColor: string, range: number]) -> true | nil, string
Broadcasts a message to the global chat or if range is specified it is sent to all players in the range.
The prefix will change the text that appears inside the brackets at the start of a message. Defaults to "AP".
To change the brackets used around the prefix you must specify a string like so:
"[]", "()", "<>", ...
bracketColor specifies the color to use for the brackets, this must be in the MOTD code format.

Returns true if the message is successfully sent, or nil and an error message if it fails.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
local chatBox = peripheral.find("chatBox")

chatBox.sendMessage("Hello world!") -- Sends "[AP] Hello world!" in chat
os.sleep(1) -- We must account for the cooldown between messages, this is to prevent spam
chatBox.sendMessage("I am dave", "Dave") -- Sends "[Dave] I am dave"
os.sleep(1)

-- Sends a red "Welcome!" message with cyan <> brackets around "<Box>"
-- to players within 30 blocks of the chat box
chatBox.sendMessage("\u00A7cWelcome!", "Box", "<>", "\u00A7b", 30)

Tip

Just like the bracketColor argument you can add colors to the message and prefix arguments using the same MOTD color code format.

sendMessageToPlayer

sendMessageToPlayer(message: string, username: string[, prefix: string, brackets: string, bracketColor: string]) -> true | nil, string
Similar to sendMessage() this sends a message to one specific player. Specify the player to send the message to with the username parameter.

1
2
3
local chatBox = peripheral.find("chatBox")

chatBox.sendMessageToPlayer("Hello there.", "Player123") -- Sends "[AP] Hello there." to Player123 in chat

sendFormattedMessage

sendFormattedMessage(json: string[, prefix: string, brackets: string, bracketColor: string, range: number]) -> true | nil, string
This function is fundamentally the same as sendMessage() except it takes a json text component as the first parameter.
Find out more information on how the text component format works on the minecraft fandom wiki. You can generate the json at minecraft.tools.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
local chatBox = peripheral.find("chatBox")

local message = {
    {text = "Click "}, 
    {
        text = "here",
        underlined = true,
        color = "aqua",
        clickEvent = {
            action = "open_url",
            value = "https://advancedperipherals.madefor.cc/"
        }
    },
    {text = " for the AP "},
    {text = "documentation", color = "red"},
    {text = "!"}
}

local json = textutils.serialiseJSON(message)

chatBox.sendFormattedMessage(message)

sendFormattedMessageToPlayer

sendFormattedMessageToPlayer(json: string, username: string[, prefix: string, brackets: string, bracketColor: string]) -> true | nil, string
Similar to sendFormattedMessage() this sends a formatted message to one specific player. Specify the player to send the message to with the username parameter.

Changelog/Trivia

0.7r
Added the uuid and isHidden parameter to the chat event. Also added the sendFormattedMessage function.

4.0b
Fixed the chat box so that is should now work in LAN worlds

0.1b
Added the chat box. This was the first feature of the mod.