Build a mod
Commands and keys
Add your own chat commands and keybinds, read the keyboard and mouse, send chat and play sounds.
Players need a way to use your mod. The two simplest ones are a command they type in chat and a key they press.
Add a command
commands.register takes the command name, a function and a short description.
commands.register("hello", function(args, raw)
chat.print("Hello, " .. (args[1] or "stranger"))
end, "Say hello")
Now typing /hello Steve in chat prints "Hello, Steve".
argsis a list of the words after the command, split on spaces.args[1]is the first one.rawis everything after the command as one piece of text, which is handy when you want spaces kept.
Command names are not case sensitive, and you can leave the slash off when you register one. Two mods cannot use the same command name: the second one gets an error.
Mod commands run in your game and are never sent to the server. They also win over the game's own commands, so a mod that registers /time replaces the real one while it runs.
commands.unregister("hello") removes one of your commands, and commands.list() lists every mod command with its name, description and mod.
Talk in chat
chat.print("Only you can see this")
chat.send("Everyone in the world can see this")
chat.command("time set day")
chat.printonly shows a message to you. It joins everything you pass with spaces, and§color codes work.chat.sendsends a real chat message, andchat.commandruns a game command (the slash is optional).
chat.send and chat.command need a world. They also skip mod commands, so chat.command("hello") runs the game's /hello, not your mod's.
Filter or change chat
The chat_receive event fires for every line that shows up in chat. Cancel it to hide the line, or assign e.message to change it.
on("chat_receive", function(e)
if e.message:find("joined the game") then
e:cancel()
end
end)
chat_send fires when the player sends a message from the chat box. e.command is true when it starts with a slash. Cancel it to stop the message, or assign e.message to change what gets sent.
There is more about both in Events and timers.
Add a keybind
keys.bind adds a key for your mod.
keys.bind({
id = "greet",
label = "Say hello",
default = "g",
onPress = function()
chat.print("Hello, " .. player.name() .. "!")
end,
})
| Option | What it does |
|---|---|
id | a name for the keybind, unique in your mod |
label | the name players see |
default | the key it starts on. Leave it out for no key |
description | a tooltip for players |
onPress | runs once each time the key goes down |
onRelease | runs when the key comes back up |
inScreens | set to true to make the key work while a menu is open |
Players change the key in your mod's Settings, under Mods. Every keybind shows up there on its own, and settings.get("greet") tells you which key it is set to.
Key names
Keys are named the way the game names them, in lower case:
- letters and numbers:
atoz,0to9 - function keys:
f1tof24 space,enter,escape,tab,backspace,insert,delete,home,end,page.up,page.down- arrows:
up,down,left,right - modifiers:
left.shift,right.shift,left.control,right.control,left.alt,right.alt - symbols:
grave.accent,minus,equal,left.bracket,right.bracket,semicolon,apostrophe,comma,period,slash,backslash - the number pad:
keypad.0tokeypad.9,keypad.enter
keys.code(name) turns a name into the key's number, and keys.name(code) goes the other way.
Read the keyboard and mouse
if keys.isDown("left.shift") then
chat.print("Shift is held")
end
if mouse.isDown("right") then
chat.print("The right mouse button is held")
end
local mx, my = mouse.x(), mouse.y()
keys.isDown only knows about the keyboard. Use mouse.isDown with "left", "right" or "middle" for mouse buttons. mouse.x() and mouse.y() are in GUI pixels, the same as your drawings.
To hear every key press, listen for the key event. It tells you the key, whether it was pressed, released or held down (e.action), and whether Shift, Ctrl or Alt were held. Cancel it to keep the key away from the game.
on("key", function(e)
if e.key == "f6" and e.action == "press" then
chat.print("You pressed F6")
end
end)
mouse_click and mouse_scroll work the same way for the mouse.
Play a sound
sound.play(id, volume, pitch) plays one of the game's sounds. Volume and pitch are 1 if you leave them out.
sound.play("entity.experience_orb.pickup")
sound.play("block.note_block.pling", 1, 2)
The minecraft: part is optional. A sound that does not exist just plays nothing.
Example: a zoom key
This one ties it together. Hold C to zoom in, let go to zoom out.
-- name: Zoom
-- version: 1.0.0
local normalFov
keys.bind({
id = "zoom",
label = "Zoom",
default = "c",
onPress = function()
normalFov = game.option("fov")
game.setOption("fov", 30)
end,
onRelease = function()
if normalFov then
game.setOption("fov", normalFov)
normalFov = nil
end
end,
})
on("unload", function()
if normalFov then game.setOption("fov", normalFov) end
end)
It saves the player's field of view before changing it, so letting go puts back exactly what they had. The unload listener puts it back too, in case the mod is turned off while you are zoomed in.
The field of view goes from 30 to 110. A value outside that range does not get clamped: the game resets the option to its default instead, so stay inside it.



