From bfc375aef39c58703814275161f68b749e28a85b Mon Sep 17 00:00:00 2001 From: Ezhh Date: Tue, 29 Aug 2017 11:41:24 +0100 Subject: [PATCH] Chat and Commands: Improve readability and grammar --- en/chapters/chat.md | 76 ++++++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/en/chapters/chat.md b/en/chapters/chat.md index 5d22cef..fccc77a 100644 --- a/en/chapters/chat.md +++ b/en/chapters/chat.md @@ -6,56 +6,59 @@ root: ../../ ## Introduction -In this chapter we will learn how to interact with player chat, including +Mods can interact with player chat, including sending messages, intercepting messages and registering chat commands. -* Send a message to all players. -* Send a message to a certain player. -* Chat commands. -* Complex subcommands. -* Intercepting messages. +* [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) -## Send a message to all players +## Sending messages to all players -It's as simple as calling the chat_send_all function, as so: +To send a message to every player in the game, call the chat_send_all function. {% highlight lua %} minetest.chat_send_all("This is a chat message to all players") {% endhighlight %} -Here is an example of how it would appear ingame (there are other messages -around it). +Here is an example of how this appears in-game: Look at this entrance This is a chat message to all players What about it? -## Send a message to a certain player +The message appears on a separate line to distinguish it from in-game player chat. -It's as simple as calling the chat_send_player function, as so: +## Sending messages to specific players + +To send a message to a specific player, call the chat_send_player function: {% highlight lua %} minetest.chat_send_player("player1", "This is a chat message for player1") {% endhighlight %} -Only player1 can see this message, and it's displayed the same as above. +This message displays in the same manner as messages to all players, but is +only visible to the named player, in this case player1. ### Older mods -Occasionally you'll see mods with code like this: +Occasionally you'll see mods where the chat_send_player function includes a +boolean: {% highlight lua %} minetest.chat_send_player("player1", "This is a server message", true) minetest.chat_send_player("player1", "This is a server message", false) {% endhighlight %} -The boolean at is no longer used, and has no affect +The boolean is no longer used, and has no affect [[commit]](https://github.com/minetest/minetest/commit/9a3b7715e2c2390a3a549d4e105ed8c18defb228). ## Chat commands -In order to register a chat command, such as /foo, use register_chatcommand: +To register a chat command, for example /foo, use register_chatcommand: {% highlight lua %} minetest.register_chatcommand("foo", { @@ -68,9 +71,9 @@ minetest.register_chatcommand("foo", { }) {% endhighlight %} -Calling /foo bar will result in `You said bar!` in the chat console. +Calling /foo bar will display `You said bar!` in the chat console. -Let's do a break down: +You can restrict which players are able to run commands: {% highlight lua %} privs = { @@ -78,23 +81,26 @@ privs = { }, {% endhighlight %} -This makes it so that only players with the `interact` [privilege](privileges.html) can run the -command. Other players will see an error message informing them which -privilege they're missing. +This means only players with the `interact` [privilege](privileges.html) can run the +command. Other players will see an error message informing them of which +privilege they're missing. If the player has the necessary privileges, the command +will run and the message will be sent: {% highlight lua %} return true, "You said " .. param .. "!" {% endhighlight %} -This returns two values, firstly a boolean which says that the command succeeded -and secondly the chat message to send to the player. +This returns two values, a boolean which shows the command succeeded +and the chat message to send to the player. -The reason that a player name rather than a player object is passed is because -**the player might not actually be online, but may be running commands from IRC**. -So don't assume that `minetest.get_player_by_name` will work in a chat command call back, -or any other function that requires an ingame player. `minetest.show_formspec` will also -not work for IRC players, so you should provide a text only version. For example, the -email mod allows both `/inbox` to show the formspec, and `/inbox text` to send to chat. +A player name, instead of a player object, is passed because +**the player might not actually be in-game, but may be running commands from IRC**. +Due to this, you should not assume `minetest.get_player_by_name`, or any other +function that requires an in-game player, will work in a chat command call back. + +`minetest.show_formspec` also won't work when a command is run from IRC, so you +should provide a text only version. For example, the email mod allows both `/inbox` +to show a formspec, and `/inbox text` to send information to chat. ## Complex subcommands @@ -105,14 +111,14 @@ It is often required to make complex chat commands, such as: * /team leave * /team list -Traditionally mods implemented this using Lua patterns. However, a much easier -way is to use a mod library that I wrote to do this for you. -See [Complex Chat Commands](chat_complex.html). +Many mods implement this using Lua patterns; however, a much easier +approach is to use a mod library. See rubenwardy's +[Complex Chat Commands](chat_complex.html). ## Intercepting messages -You can use register_on_chat_message, like so: +To intercept a message, use register_on_chat_message: {% highlight lua %} minetest.register_on_chat_message(function(name, message) @@ -121,8 +127,8 @@ minetest.register_on_chat_message(function(name, message) end) {% endhighlight %} -By returning false, we're allowing the chat message to be sent by the default -handler. You can actually miss out the line `return false`, and it would still +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. **WARNING: CHAT COMMANDS ARE ALSO INTERCEPTED.** If you only want to catch