167 lines
5.3 KiB
Markdown
167 lines
5.3 KiB
Markdown
---
|
|
title: Chat and Commands
|
|
layout: default
|
|
root: ../..
|
|
idx: 4.2
|
|
description: Registering a chatcommand and handling chat messages with register_on_chat_message
|
|
redirect_from: /en/chapters/chat.html
|
|
cmd_online:
|
|
level: warning
|
|
title: Offline players can run commands
|
|
message: <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>
|
|
|
|
cb_cmdsprivs:
|
|
level: warning
|
|
title: Privileges and Chat Commands
|
|
message: 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-all-players)
|
|
* [Sending Messages to Specific Players](#sending-messages-to-specific-players)
|
|
* [Chat Commands](#chat-commands)
|
|
* [Complex Subcommands](#complex-subcommands)
|
|
* [Intercepting Messages](#intercepting-messages)
|
|
|
|
## Sending Messages to All Players
|
|
|
|
To send a message to every player in the game, call the chat_send_all function.
|
|
|
|
```lua
|
|
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:
|
|
|
|
```lua
|
|
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`:
|
|
|
|
```lua
|
|
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](privileges.html) 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](https://www.lua.org/pil/20.2.html).
|
|
Patterns are a way of extracting stuff from text using rules.
|
|
|
|
```lua
|
|
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](http://lua-users.org/wiki/PatternsTutorial)
|
|
or the [PIL documentation](https://www.lua.org/pil/20.2.html).
|
|
|
|
<p class="book_hide">
|
|
There is also a library written by the author of this book which can be used
|
|
to make complex chat commands without patterns called
|
|
<a href="chat_complex.html">Chat Command Builder</a>.
|
|
</p>
|
|
|
|
|
|
## Intercepting Messages
|
|
|
|
To intercept a message, use register_on_chat_message:
|
|
|
|
```lua
|
|
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`.
|
|
|
|
```lua
|
|
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)
|
|
```
|