minetest_modding_book/_en/players/chat.md

title	layout	root	idx	description	redirect_from	cmd_online	cb_cmdsprivs
Chat and Commands	default	../..	4.2	Registering a chatcommand and handling chat messages with register_on_chat_message	/en/chapters/chat.html	level title message warning Offline players can run commands <p>A player name is passed instead of a player object because mods can run commands on behalf of offline players. For example, the IRC bridge allows players to run commands without joining the game.</p> <p>So make sure that you don't assume that the player is online. You can check by seeing if <pre>minetest.get_player_by_name</pre> returns a player.</p>	level title message warning Privileges and Chat Commands The shout privilege isn't needed for a player to trigger this callback. This is because chat commands are implemented in Lua, and are just chat messages that begin with a /.

Introduction

Mods can interact with player chat, including sending messages, intercepting messages, and registering chat commands.

• Sending Messages to All Players
• Sending Messages to Specific Players
• Chat Commands
• Complex Subcommands
• Intercepting Messages

Sending Messages to All Players

To send a message to every player in the game, call the chat_send_all function.

minetest.chat_send_all("This is a chat message to all players")

Here is an example of how this appears in-game:

<player1> Look at this entrance
This is a chat message to all players
<player2> What about it?

The message appears on a separate line to distinguish it from in-game player chat.

Sending Messages to Specific Players

To send a message to a specific player, call the chat_send_player function:

minetest.chat_send_player("player1", "This is a chat message for player1")

This message displays in the same manner as messages to all players, but is only visible to the named player, in this case player1.

Chat Commands

To register a chat command, for example /foo, use register_chatcommand:

minetest.register_chatcommand("foo", {
    privs = {
        interact = true,
    },
    func = function(name, param)
        return true, "You said " .. param .. "!"
    end,
})

In the above snippet, interact is listed as a required privilege meaning that only players with the interact privilege can run the command.

Chat commands can return up to two values, the first being a Boolean indicating success, and the second being a message to send to the user.

{% include notice.html notice=page.cmd_online %}

Complex Subcommands

It is often required to make complex chat commands, such as:

• /msg <to> <message>
• /team join <teamname>
• /team leave <teamname>
• /team list

This is usually done using Lua patterns. Patterns are a way of extracting stuff from text using rules.

local to, msg = string.match(param, "^([%a%d_-]+) (*+)$")

The above code implements /msg <to> <message>. Let's go through left to right:

• ^ means match the start of the string.
• () is a matching group - anything that matches stuff in here will be returned from string.match.
• [] means accept characters in this list.
• %a means accept any letter and %d means accept any digit.
• [%d%a_-] means accept any letter or digit or _ or -.
• + means match the thing before one or more times.
• * means match any character in this context.
• $ means match the end of the string.

Put simply, the pattern matches the name (a word with only letters/numbers/-/_), then a space, then the message (one or more of any character). The name and message are returned, because they're surrounded by parentheses.

That's how most mods implement complex chat commands. A better guide to Lua Patterns would probably be the lua-users.org tutorial or the PIL documentation.

There is also a library written by the author of this book which can be used to make complex chat commands without patterns called Chat Command Builder.

Intercepting Messages

To intercept a message, use register_on_chat_message:

minetest.register_on_chat_message(function(name, message)
    print(name .. " said " .. message)
    return false
end)

By returning false, you allow the chat message to be sent by the default handler. You can actually remove the line return false and it would still work the same, because nil is returned implicitly and is treated like false.

{% include notice.html notice=page.cb_cmdsprivs %}

You should make sure you take into account that it may be a chat command, or the user may not have shout.

minetest.register_on_chat_message(function(name, message)
    if message:sub(1, 1) == "/" then
        print(name .. " ran chat command")
    elseif minetest.check_player_privs(name, { shout = true }) then
        print(name .. " said " .. message)
    else
        print(name .. " tried to say " .. message ..
                " but doesn't have shout")
    end

    return false
end)