Skip to content

ComputerCraft API

License registration

  • If you want to send messages to players from your chatbox, you'll need to register a license key. You can do this with the in-game command: /chatbox license register.
  • Add the license key to the computer by running chatbox register <key> - you can click to copy in-game.
  • Otherwise, to set the computer as a chatbox computer as a guest (can receive but not send messages and events), run chatbox register guest.
  • You can now use the global chatbox API and receive events from the server!

Basic chat logger program

This is an example program that will log public messages, and print them to the terminal:

lua
while true do
	local event, user, message, data = os.pullEvent("chat_ingame")

	print(string.format("<%s> %s", user, message))
end

Basic command-based chatbot

This is an example chatbot that uses backslash commands (\commands), and responds to the user privately with chatbox.tell. The bot responds to the command \echo, with whatever text the user sent it.

This will require the license to be registered with /chatbox license register and added to the computer with chatbox register.

lua
if not chatbox.hasCapability("command") or not chatbox.hasCapability("tell") then
	error("Chatbox does not have the required permissions. Did you register the license?")
end

local BOT_NAME = "&cMy Bot" -- You can colour bot names!

while true do
	local event, user, command, args = os.pullEvent("command")

	if command == "echo" then
		if #args > 0 then
			chatbox.tell(user, "Received: " .. table.concat(args, " "), BOT_NAME)
		else
			chatbox.tell(user, "Send some text to be echoed!", BOT_NAME)
		end
	end
end

Events

In-game chat event

The event received when a player posts a message in public chat.

NameArgument Description
event"chat_ingame"
userThe username of the user that sent this message (or their UUID if they don't have a name)
messageThe full raw text of their message (including markdown characters)
dataTable containing the full Event packet

Discord chat event

The event received when a player posts a message in Discord.

NameArgument Description
event"chat_discord"
userThe username and discriminator (e.g. Lemmmy#8924) of the user that sent this message (or their Snowflake ID if they don't have a name)
messageThe full raw text of their message (including markdown characters)
dataTable containing the full Event packet

Chatbox chat event

The event received when another chatbox sends a message.

NameArgument Description
event"chat_chatbox"
nameThe name of the chatbox
userThe username of the user that owns this chatbox (or their UUID if they don't have a name)
messageThe full raw text of their message (including markdown or formatting characters)
dataTable containing the full Event packet

Command event

The event received when a player runs a backslash command (\command) in-game.

NameArgument Description
event"command"
userThe username of the user that owns this chatbox (or their UUID if they don't have a name)
commandThe command the user ran
argsA table containing the space-separated arguments of the command (excluding the command itself)
dataTable containing the full Event packet

Join event

The event received when a player joins the game.

NameArgument Description
event"join"
userThe username of the user that joined (or their UUID if they don't have a name)
dataTable containing the full Event packet

Leave event

The event received when a player leaves the game.

NameArgument Description
event"leave"
userThe username of the user that left (or their UUID if they don't have a name)
dataTable containing the full Event packet

Death event

The event received when a player dies in-game.

NameArgument Description
event"death"
userThe username of the user that died (or their UUID if they don't have a name)
sourceThe name (or UUID) of the thing that killed the player, or nil
textThe text of the death message
dataTable containing the full Event packet

World change event

The event received when a player changes worlds.

NameArgument Description
event"world_change"
userThe username of the user that changed worlds.
originThe identifier string of the world the user has moved from.
destinationThe identifier string of the world the user is now in.
dataTable containing the full Event packet

AFK event

The event received when a player goes AFK in-game.

NameArgument Description
event"afk"
userThe username of the user that went AFK (or their UUID if they don't have a name)
dataTable containing the full Event packet

AFK return event

The event received when a player returns from being AFK in-game.

NameArgument Description
event"afk_return"
userThe username of the user that went AFK (or their UUID if they don't have a name)
dataTable containing the full Event packet

Server restart scheduled event

The event received when a server restart has been scheduled.

If a server restart was scheduled before the websocket connected, then the server_restart_scheduled event will be sent after the chatbox API has connected. In this case, restartSeconds will not be the time until the restart, but instead the time that was initially specified for the restart. If the precise restart time is required, it can be accessed via the restartAt field (ISO-8601) of the data table, which contains the full Event packet.

NameArgument Description
event"server_restart_scheduled"
typeThe type of restart. Will be "automatic" or "manual".
secondsThe number of seconds specified until the restart.
dataTable containing the full Event packet

Server restart cancelled event

The event received when a previously scheduled server restart has now been cancelled.

NameArgument Description
event"server_restart_cancelled"
typeThe type of restart. Will be "automatic" or "manual".
dataTable containing the full Event packet

Functions

chatbox.say(text, name, prefix, mode)

Sends a message to public chat. You'll need explicit permission from a member of staff to get this capability.

NOTE

This requires your license to have the say capability, which most do not.

You can use these formatting modes:

  • markdown - Discord-like markdown formatting. Supports URLs, but not colours.
  • format - Minecraft-like formatting strings (e.g. &e for yellow). Supports colours, but not URLs.
NameArgument Description
textThe message to send to chat
name(optional) The name of this chatbox (shows in the name tag)
prefix(optional) Unused (legacy compatibility). Set this to nil
mode(optional) The text formatting mode to use. Must be markdown or format. Defaults to markdown

chatbox.tell(user, text, name, prefix, mode)

Sends a private message to a user. Note: this requires you to register a chatbox license with /chatbox license register.

You can use these formatting modes:

  • markdown - Discord-like markdown formatting. Supports URLs, but not colours.
  • format - Minecraft-like formatting strings (e.g. &e for yellow). Supports colours, but not URLs.
NameArgument Description
userThe username of the user to send a message to
textThe message to send to chat
name(optional) The name of this chatbox (shows in the name tag)
prefix(optional) Unused (legacy compatibility). Set this to nil
mode(optional) The text formatting mode to use. Must be markdown or format. Defaults to markdown

chatbox.getPlayers()

Returns a table of user objects that are currently online in-game.

chatbox.getPlayerList()

Returns a list of player usernames that are currently online in-game. You should probably use chatbox.getPlayers() instead.

chatbox.hasCapability(capability)

Checks if the chatbox license has the specified capability. Valid capabilities:

CapabilityDefaultsDescription
readGuest, registeredRead messages from in-game chat and Discord, and receive events such as joining and leaving.
commandRegisteredReceive in-game backslash commands.
tellRegisteredSend private messages to individual players.
sayNoneSend public messages to the whole in-game chat.

chatbox.getLicenseOwner()

Returns the username and user object of the player that owns this chatbox license.

chatbox.isConnected()

Returns whether the chatbox is connected to the API.