From 8bbb673c0bd89ddf5ded1d648632e68002479b32 Mon Sep 17 00:00:00 2001 From: kab0u <99147300+kab0u@users.noreply.github.com> Date: Tue, 31 Jan 2023 17:31:48 +0100 Subject: [PATCH] Improve the documentation for chat command definition in lua_api.txt (#13168) --- doc/lua_api.txt | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 61743e5f4..80d7580d8 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -9299,20 +9299,31 @@ Chat command definition Used by `minetest.register_chatcommand`. +Specifies the function to be called and the privileges required when a player +issues the command. A help message that is the concatenation of the params and +description fields is shown when the "/help" chatcommand is issued. + { - params = " ", -- Short parameter description + params = "", + -- Short parameter description. See the below note. - description = "Remove privilege from player", -- Full description + description = "", + -- General description of the command's purpose. - privs = {privs=true}, -- Require the "privs" privilege to run + privs = {}, + -- Required privileges to run. See `minetest.check_player_privs()` for + -- the format and see [Privileges] for an overview of privileges. func = function(name, param), - -- Called when command is run. Returns boolean success and text output. - -- Special case: The help message is shown to the player if `func` - -- returns false without a text output. + -- Called when command is run. + -- * `name` is the name of the player who issued the command. + -- * `param` is a string with the full arguments to the command. + -- Returns a boolean for success and a string value. + -- The string is shown to the issuing player upon exit of `func` or, + -- if `func` returns `false` and no string, the help message is shown. } -Note that in params, use of symbols is as follows: +Note that in params, the conventional use of symbols is as follows: * `<>` signifies a placeholder to be replaced when the command is used. For example, when a player name is needed: `` @@ -9324,6 +9335,18 @@ Note that in params, use of symbols is as follows: * `()` signifies grouping. For example, when param1 and param2 are both required, or only param3 is required: `( ) | ` +Example: + + { + params = " ", + + description = "Remove privilege from player", + + privs = {privs=true}, -- Require the "privs" privilege to run + + func = function(name, param), + } + Privilege definition --------------------