Build a mod

Commands and keys

Add your own chat commands and keybinds, read the keyboard and mouse, send chat and play sounds.

Publicidad

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".

  • args is a list of the words after the command, split on spaces. args[1] is the first one.
  • raw is 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.print only shows a message to you. It joins everything you pass with spaces, and § color codes work.
  • chat.send sends a real chat message, and chat.command runs 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,
})
OptionWhat it does
ida name for the keybind, unique in your mod
labelthe name players see
defaultthe key it starts on. Leave it out for no key
descriptiona tooltip for players
onPressruns once each time the key goes down
onReleaseruns when the key comes back up
inScreensset 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: a to z, 0 to 9
  • function keys: f1 to f24
  • 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.0 to keypad.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.