From c6b81ade29f45a8a53656785d0164fd38686db16 Mon Sep 17 00:00:00 2001 From: ShrBox Date: Thu, 2 Jan 2025 01:16:19 +0800 Subject: [PATCH] docs: fix format --- docs/apis/GameAPI/Command.md | 319 ++++++++++++++++-------------- docs/apis/GameAPI/Command.zh.md | 330 +++++++++++++++++--------------- 2 files changed, 346 insertions(+), 303 deletions(-) diff --git a/docs/apis/GameAPI/Command.md b/docs/apis/GameAPI/Command.md index 597b2acf..73c6ae6e 100644 --- a/docs/apis/GameAPI/Command.md +++ b/docs/apis/GameAPI/Command.md @@ -2,48 +2,53 @@ The following APIs provide interfaces for registering and listening to custom commands in the game: -### Execute a Background Command +### Execute a Background Command `mc.runcmd(cmd)` -- Parameters: - - cmd : `String` - The command to be executed. +- Parameters: + - cmd : `String` + The command to be executed. - Return value: Whether the execution was successful. - Return value type: `Boolean` [JavaScript] + ```js mc.runcmd("say Hello!"); ``` + [Lua] + ```lua mc.runcmd("say Hello!") ``` -### Execute a Background Command (Enhanced Version) +### Execute a Background Command (Enhanced Version) `mc.runcmdEx(cmd)` -- Parameters: +- Parameters: - - cmd : `String` - The command to be executed. -- Return value: Command Execution Result `Object` + - cmd : `String` + The command to be executed. +- Return value: Command Execution Result `Object` - Return value type: `Object` - - For a returned execution result object res, there are the following members: + - For a returned execution result object res, there are the following members: | Members | Meaning | Data Type | - | ----------- | ------------------------------------------------- | --------- | + | ----------- | ------------------------------------------------- | --------- | | res.success | Whether the execution was successful. | `Boolean` | | res.output | The output result after BDS executes the command. | `String` | - !!! note - The implementation of runcmdEx is very different from ordinary runcmd. The Enhanced version has a **hidden execution** mechanism, and the execution result will not be output to the console. Therefore, if necessary, you must manually use the log function to output the result. +The implementation of runcmdEx is very different from ordinary runcmd. The Enhanced version has a **hidden execution** +mechanism, and the execution result will not be output to the console. Therefore, if necessary, you must manually use +the log function to output the result. [JavaScript] + ```js var result = mc.runcmdEx("say Hello!"); log(result.output); @@ -51,82 +56,90 @@ log(result.output); ## Command Registration API -An interface for registering custom commands is provided here. By docking with the built-in command system of BDS, the commands you register can be used by players, consoles, command blocks, NPCs and other objects that can execute commands in games. In addon, you can also use the commands registered here. +An interface for registering custom commands is provided here. By docking with the built-in command system of BDS, the +commands you register can be used by players, consoles, command blocks, NPCs and other objects that can execute commands +in games. In addon, you can also use the commands registered here. !!! warning - Except for variable parameters (String, RawText, Message, etc.), the commands cannot contain non-English lowercase letters! +Except for variable parameters (String, RawText, Message, etc.), the commands cannot contain non-English lowercase +letters! ### Register a Top-Level Command `mc.newCommand(cmd,description[,permission,flag,alias])` -- Parameters: - - - cmd : `String` - The command that will be registered. - - description : `String` - The description text for the command. - - permission : `PermType` - (Optional parameter) - - | Execution Permission | Meaning | - | ---------------------- | --------------------------------------------------- | - | `PermType.Any` | Anyone can execute the command. | - | `PermType.GameMasters` | Only the OP can execute the command.(Default value) | - | `PermType.Console` | Only the console can execute the command. | - - - flag : `Integer` - (Optional parameter) Default value is `0x80` - At present, you can directly press this input, and related modifications will be made in the future. - - alias : `String` - (Optional argument) Add an alias for the command. - Multiple aliases can be set for a command, which is equivalent to triggering the same command when executed. +- Parameters: + + - cmd : `String` + The command that will be registered. + - description : `String` + The description text for the command. + - permission : `PermType` + (Optional parameter) + + | Execution Permission | Meaning | + | ---------------------- | --------------------------------------------------- | + | `PermType.Any` | Anyone can execute the command. | + | `PermType.GameMasters` | Only the OP can execute the command.(Default value) | + | `PermType.Console` | Only the console can execute the command. | + + - flag : `Integer` + (Optional parameter) Default value is `0x80` + At present, you can directly press this input, and related modifications will be made in the future. + - alias : `String` + (Optional argument) Add an alias for the command. + Multiple aliases can be set for a command, which is equivalent to triggering the same command when executed. - Return value: Command Object. - Return value type: `Command` !!! tip - Top-level commands, i.e. something like `list` `gamerule`, the first input after the `/` character. - +Top-level commands, i.e. something like `list` `gamerule`, the first input after the `/` character. + After registering the top-level command, this function returns a command object. Next, the function expansion of this command needs to be carried out in this command object. ### Command Object - Function -Through the command object, you can register various forms and functions for this command. Suppose there is a `Command`. The command object has the following member functions. +Through the command object, you can register various forms and functions for this command. Suppose there is a `Command`. +The command object has the following member functions. #### Set Command Alias `Command.setAlias(alias)` -- Parameters: - - alias : `String` - Command alias. + +- Parameters: + - alias : `String` + Command alias. - Return value: Whether creating the alias succeeded or not. - Return value type: `Boolean` #### Add Command Enumerations `Command.setEnum(name,values)` -- Parameters: - - name : `String` - Enumeration name, used to distinguish the enumeration when setting parameters. - - values : `Array` - Valid values ​​for enumeration. + +- Parameters: + - name : `String` + Enumeration name, used to distinguish the enumeration when setting parameters. + - values : `Array` + Valid values ​​for enumeration. - Return value: New enumeration option identification name. - Return value type: `String` #### Add a Required Parameter `Command.mandatory(name,type[,enumName,identifier,enumOptions])` -- Parameters: - - name : `String` - Parameter name, used to identify the parameter when executing the command. - - type : `ParamType` - Command parameter type. - - enumName : `String` - Enumeration name (only valid when `ParamType` is `Enum`, used to distinguish enumeration options). - - identifier : `String` - Parameter identifier, used to uniquely identify parameters in special cases, generally can be replaced by `enumName` or `name`. - - enumOptions : `Integer` - Parameter options, set to `1` to expand enumeration options in the command prompt. - For example `` will become ``. + +- Parameters: + - name : `String` + Parameter name, used to identify the parameter when executing the command. + - type : `ParamType` + Command parameter type. + - enumName : `String` + Enumeration name (only valid when `ParamType` is `Enum`, used to distinguish enumeration options). + - identifier : `String` + Parameter identifier, used to uniquely identify parameters in special cases, generally can be replaced by + `enumName` or `name`. + - enumOptions : `Integer` + Parameter options, set to `1` to expand enumeration options in the command prompt. + For example `` will become ``. - Return value: Whether setting succeeded or not. - Return value type: `Boolean` @@ -134,25 +147,26 @@ Through the command object, you can register various forms and functions for thi `Command.optional(name,type[,enumName,identifier,enumOptions])` -- Parameters: - - name : `String` - Parameter name, used to identify the parameter when executing the command. - - type : `ParamType` - Command parameter type. - - enumName : `String` - Enumeration name (only valid when `ParamType` is `Enum`, used to distinguish enumeration options). - - identifier : `String` - Parameter identifier, used to uniquely identify parameters in special cases, generally can be replaced by `enumName` or `name`. - - enumOptions : `Integer` - Parameter options, set to `1` to expand enumeration options in the command prompt. - For example `` will become ``. +- Parameters: + - name : `String` + Parameter name, used to identify the parameter when executing the command. + - type : `ParamType` + Command parameter type. + - enumName : `String` + Enumeration name (only valid when `ParamType` is `Enum`, used to distinguish enumeration options). + - identifier : `String` + Parameter identifier, used to uniquely identify parameters in special cases, generally can be replaced by + `enumName` or `name`. + - enumOptions : `Integer` + Parameter options, set to `1` to expand enumeration options in the command prompt. + For example `` will become ``. - Return value: Whether setting succeeded or not. - Return value type: `Boolean` -#### Valid Command Parameter Types and Explanations +#### Valid Command Parameter Types and Explanations | Command Parameter Type | Meaning | -| ---------------------- | --------------------------------------------------------------------------------------------------------------- | +|------------------------|-----------------------------------------------------------------------------------------------------------------| | `ParamType.Bool` | Boolean Parameter | | `ParamType.Int` | Integer Parameter | | `ParamType.Float` | Floating point Parameter | @@ -176,32 +190,38 @@ Through the command object, you can register various forms and functions for thi `Command.overload(params)` -- Parameters: - - params : `Array` - Parameter identifier, parameter list used by overloading, available parameter identifier, enumeration name, parameter name. - Note that you cannot use identifiers that cannot distinguish specific parameters. For example, both parameters are called `action` but the enumeration options are different. In this case, the enumeration name should be used instead of the parameter name. +- Parameters: + - params : `Array` + Parameter identifier, parameter list used by overloading, available parameter identifier, enumeration name, + parameter name. + Note that you cannot use identifiers that cannot distinguish specific parameters. For example, both parameters are + called `action` but the enumeration options are different. In this case, the enumeration name should be used + instead of the parameter name. - Return value: Whether setting succeeded or not. - Return value type: `Boolean` !!! tip - Command overloading is the method used by BDS to distinguish different command forms, and each different command form corresponds to a command overloading. - As you can see, the parameter names provided in the command overload form a new command form. +Command overloading is the method used by BDS to distinguish different command forms, and each different command form +corresponds to a command overloading. +As you can see, the parameter names provided in the command overload form a new command form. #### Set Command Callback `Command.setCallback(callback)` -- Parameters: - - callback : `Function(cmd,origin,output,results)` - When the registered command is executed, the interface automatically calls the callback function. + +- Parameters: + - callback : `Function(cmd,origin,output,results)` + When the registered command is executed, the interface automatically calls the callback function. - Return value: Whether setting succeeded or not. - Return value type: `Boolean` !!! tip - The parameters of the command callback function are relatively complex, which will be explained in detail below. +The parameters of the command callback function are relatively complex, which will be explained in detail below. #### Installation Instructions -After all the configuration of the command is completed, use this function to register the command to the BDS command system. +After all the configuration of the command is completed, use this function to register the command to the BDS command +system. `Command.setup()` @@ -210,7 +230,8 @@ After all the configuration of the command is completed, use this function to re ## Command Callback Function -The **command callback function** mentioned above is a relatively complex callback function, and some explanations of the parameters are given below. +The **command callback function** mentioned above is a relatively complex callback function, and some explanations of +the parameters are given below. Command callback function prototype: `Function(cmd,origin,output,results)` #### Parameters `cmd` : Own Command Object @@ -219,11 +240,12 @@ This parameter gives the directive object with which you registered this command #### Parameters `origin` : The Executor of the Command -The parameter `origin` is of type `CommandOrigin` object. This object represents the executor of this command. Through this object, some operations can be performed on the executor. +The parameter `origin` is of type `CommandOrigin` object. This object represents the executor of this command. Through +this object, some operations can be performed on the executor. For a particular `CommandOrigin` object `ori`, there are the following properties: | Members | Meaning | Data Types | -| ------------ | ---------------------------------------------------- | ------------ | +|--------------|------------------------------------------------------|--------------| | ori.type | Command Execution Body Type | `OriginType` | | ori.name | The name of the command execution body | `String` | | ori.pos | The coordinates of the command exection body | `FloatPos` | @@ -233,18 +255,19 @@ For a particular `CommandOrigin` object `ori`, there are the following propertie #### Parameter `output` : Output the Execution Result of the Command to the Command Executor -Parameter `output` is of type `CommandOutput` object. Through this object, the execution result of the command can be output to the command executor. +Parameter `output` is of type `CommandOutput` object. Through this object, the execution result of the command can be +output to the command executor. For a particular `CommandOutput` object `outp`, the following member methods are available: ##### Output a Success Message `outp.success([msg][, parm])` -- Parameters: - - msg : `String` - The message to output. - - parm : `Array` - Parameters to be replaced +- Parameters: + - msg : `String` + The message to output. + - parm : `Array` + Parameters to be replaced - Return value: Whether the output is successful. - Return value type: `Boolean` @@ -252,11 +275,11 @@ For a particular `CommandOutput` object `outp`, the following member methods are `outp.error(msg[, parm])` -- Parameters: - - msg : `String` - The message to output. - - parm : `Array` - Parameters to be replaced +- Parameters: + - msg : `String` + The message to output. + - parm : `Array` + Parameters to be replaced - Return value: Whether the output is successful. - Return value type: `Boolean` @@ -264,22 +287,24 @@ For a particular `CommandOutput` object `outp`, the following member methods are `outp.addMessage(msg[, parm])` -- Parameters: - - msg : `String` - The message to output. - - parm : `Array` - Parameters to be replaced +- Parameters: + - msg : `String` + The message to output. + - parm : `Array` + Parameters to be replaced - Return value: Whether the output is successful. - Return value type: `Boolean` -#### Parameter `result` : The Result Obtained by Each Parameter of the Command +#### Parameter `result` : The Result Obtained by Each Parameter of the Command -The content of `results` is `object` key-value pair. The `command parameter name` is the `name` value of the parameter set when the command is registered, and the `data value` is the content filled in by the executor in the position of the current command parameter. +The content of `results` is `object` key-value pair. The `command parameter name` is +the `name` value of the parameter set when the command is registered, and the `data value` is the content filled in by +the executor in the position of the current command parameter. The relationship between command parameter types and data value types is as follows: | Command Parameter Type | Data Value Type | Meaning | -| ---------------------- | --------------- | --------------------------------------------------------------------------------------------------------------- | +|------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------| | `ParamType.Bool` | `Boolean` | Boolean Value | | `ParamType.Int` | `Integer` | Integer Value | | `ParamType.Float` | `Float` | Floating Point Value | @@ -299,9 +324,10 @@ The relationship between command parameter types and data value types is as foll | `ParamType.ActorType` | `String` | Entity Type String | | `ParamType.Command` | `String` | Command Name (For testing only) | -### Command Registration Example +### Command Registration Example [JavaScript] + ```js mc.listen("onServerStarted", () => { let cmd = mc.newCommand("manager", "Command Description", PermType.GameMasters); @@ -327,29 +353,32 @@ mc.listen("onServerStarted", () => { }); ``` -## Fake Command API +## Fake Command API -The fake command API here is reserved for **downward compatibility**. It is recommended to use the **true command** API written in the above document. +The fake command API here is reserved for **downward compatibility**. It is recommended to use the **true command** API +written in the above document. !!! warning - Although it looks relatively simple, fake commands have some important disadvantages, including that they can only be executed by the player or console, other objects (such as command blocks, NPCs, etc.) cannot be executed, all parameter data needs to be parsed by themselves, etc. - +Although it looks relatively simple, fake commands have some important disadvantages, including that they can only be +executed by the player or console, other objects (such as command blocks, NPCs, etc.) cannot be executed, all parameter +data needs to be parsed by themselves, etc. + Please try to use the real command API. -### Register a New Player Command (Fake Command) +### Register a New Player Command (Fake Command) `mc.regPlayerCmd(cmd,description,callback[,level])` -- Parameters: - - cmd : `String` - The command that will be registered. - - description : `String` - Command Description Text. - - callback : `Function(player,args)` - When the registered command is executed, the interface automatically calls the callback function. - - level : `Integer` - (Optional parameter) The registration level of the command, the default is 0, that is, everyone can execute it. - If the command registration level is set to 1, only the OP can execute this command. +- Parameters: + - cmd : `String` + The command that will be registered. + - description : `String` + Command Description Text. + - callback : `Function(player,args)` + When the registered command is executed, the interface automatically calls the callback function. + - level : `Integer` + (Optional parameter) The registration level of the command, the default is 0, that is, everyone can execute it. + If the command registration level is set to 1, only the OP can execute this command. - Return value: Whether the registration was successful. - Return value type: `Boolean` @@ -359,30 +388,31 @@ Note: The callback function prototype of the parameter callback: `function(playe The player that executes the command. - args : `Array` Arguments following the target command. Divide by spaces to form a string array. - If a custom command `land set` is registered, when `/land set abc 2333` is executed, the value of args will be `[ "abc","2333" ]` + If a custom command `land set` is registered, when `/land set abc 2333` is executed, the value of args will be + `[ "abc","2333" ]` [JavaScript] + ```js -mc.regPlayerCmd("fly on","Turn on the fly mode",function(pl,args){ +mc.regPlayerCmd("fly on", "Turn on the fly mode", function (pl, args) { pl.tell("Flying enabled."); //...... }); ``` - -### Register a New Background Console Command (Fake Command) +### Register a New Background Console Command (Fake Command) `mc.regConsoleCmd(cmd,description,callback)` -- Parameters: - - cmd : `String` - The command that will be registered. +- Parameters: + - cmd : `String` + The command that will be registered. - - description : `String` - Command Description Text. + - description : `String` + Command Description Text. - - callback : `Function` - When the registered command is executed, the interface automatically calls the callback function. + - callback : `Function` + When the registered command is executed, the interface automatically calls the callback function. - Return value: Whether the registration was successful. - Return value type: `Boolean` @@ -390,20 +420,23 @@ Note: The callback function prototype of the parameter callback: `function(args) - args : `Array` Arguments following the target command. Divide by spaces to form a string array. - If a custom command `land set` is registered, when `/land set abc 2333` is executed, the value of args will be `['abc','2333']` + If a custom command `land set` is registered, when `/land set abc 2333` is executed, the value of args will be + `['abc','2333']` [JavaScript] + ```js -mc.regConsoleCmd("backup","Start the backup",function(args){ - log("ID of this backup is:",args[0]); +mc.regConsoleCmd("backup", "Start the backup", function (args) { + log("ID of this backup is:", args[0]); //...... }); ``` !!! tip "Instructions on Fake Order Registration" - After setting the callback function, the callback function will be called when the fake command you registered is executed. - LLSE will automatically split the command arguments into arrays for you before calling them. - +After setting the callback function, the callback function will be called when the fake command you registered is +executed. +LLSE will automatically split the command arguments into arrays for you before calling them. + Take the JavaScript language as an example: Execute command @@ -414,17 +447,15 @@ mc.regConsoleCmd("backup","Start the backup",function(args){ As you can see, the values contained in `args` are **sequentially split** command arguments. If you have quotes in your command (for example to handle player names with spaces in them), LLSE will also do this when splitting. - - ## Other APIs Related to the Command System ### The Simulation Produces a Console Command Output `mc.sendCmdOutput(output)` -- Parameters: - - output : `String` - The command output produced by the simulation. +- Parameters: + - output : `String` + The command output produced by the simulation. - Return value: Whether the exection was successful. - Return value type: `Boolean` diff --git a/docs/apis/GameAPI/Command.zh.md b/docs/apis/GameAPI/Command.zh.md index f2b3e072..cf9c335f 100644 --- a/docs/apis/GameAPI/Command.zh.md +++ b/docs/apis/GameAPI/Command.zh.md @@ -2,50 +2,54 @@ 下面这些API提供了在游戏中注册、监听自定义命令的接口 -### 执行一条后台命令 +### 执行一条后台命令 `mc.runcmd(cmd)` - 参数： - - cmd : `String` - 待执行的命令 + - cmd : `String` + 待执行的命令 - 返回值：是否执行成功 - 返回值类型： `Boolean` [JavaScript] + ```js mc.runcmd("say Hello!"); ``` + [Lua] + ```lua mc.runcmd("say Hello!") ``` -### 执行一条后台命令（强化版） +### 执行一条后台命令（强化版） `mc.runcmdEx(cmd)` - 参数： - - cmd : `String` - 待执行的命令 + - cmd : `String` + 待执行的命令 -- 返回值：命令执行结果`Object` +- 返回值：命令执行结果`Object` - 返回值类型： `Object` - - 对于返回的某个执行结果对象res，有如下这些成员： + - 对于返回的某个执行结果对象res，有如下这些成员： | 成员 | 含义 | 类型 | - | ----------- | ----------------------- | --------- | + | ----------- | ----------------------- | --------- | | res.success | 是否执行成功 | `Boolean` | | res.output | BDS执行命令后的输出结果 | `String` | - !!! note - runcmdEx 与普通 runcmd 实现区别非常大，在于 Ex 版本拥有**隐藏输出**的机制，执行结果不会输出至控制台，因此如果有需要，要手动用 log 函数将结果输出 +runcmdEx 与普通 runcmd 实现区别非常大，在于 Ex 版本拥有**隐藏输出**的机制，执行结果不会输出至控制台，因此如果有需要，要手动用 +log 函数将结果输出 [JavaScript] + ```js var result = mc.runcmdEx("say Hello!"); log(result.output); @@ -53,9 +57,10 @@ log(result.output); ## 命令注册 API -这里提供了注册自定义命令的接口。通过对接 BDS 内置的命令系统，你注册的命令可以由玩家、控制台、命令方块、NPC等各种游戏中可以执行命令的对象所使用，在 addon 中，也可以使用这里所注册的命令。 +这里提供了注册自定义命令的接口。通过对接 BDS 内置的命令系统，你注册的命令可以由玩家、控制台、命令方块、NPC等各种游戏中可以执行命令的对象所使用，在 +addon 中，也可以使用这里所注册的命令。 !!! warning - 命令中除了可变参数(String, RawText, Message等)外，均不能包含非英文小写字母！ +命令中除了可变参数(String, RawText, Message等)外，均不能包含非英文小写字母！ ### 注册一条顶层命令 @@ -63,77 +68,80 @@ log(result.output); - 参数： - - cmd : `String` - 待注册的命令 + - cmd : `String` + 待注册的命令 - - description : `String` - 命令描述文本 + - description : `String` + 命令描述文本 - - permission : `PermType` - （可选参数）指令执行所需权限 + - permission : `PermType` + （可选参数）指令执行所需权限 - | 执行权限 | 含义 | - | ---------------------- | -------------------------------- | - | `PermType.Any` | 任何人都可以执行这条指令 | - | `PermType.GameMasters` | 只有OP可以执行这条指令（默认值） | - | `PermType.Console` | 只有控制台可以执行这条指令 | + | 执行权限 | 含义 | + | ---------------------- | -------------------------------- | + | `PermType.Any` | 任何人都可以执行这条指令 | + | `PermType.GameMasters` | 只有OP可以执行这条指令（默认值） | + | `PermType.Console` | 只有控制台可以执行这条指令 | - - flag : `Integer` - （可选参数）默认值 `0x80` - 目前直接按此输入即可，后续会进行相关修改 + - flag : `Integer` + （可选参数）默认值 `0x80` + 目前直接按此输入即可，后续会进行相关修改 - - alias : `String` - （可选参数）命令的别名 - 可以为命令设置多个别名，执行的时候相当于触发同一条命令 + - alias : `String` + （可选参数）命令的别名 + 可以为命令设置多个别名，执行的时候相当于触发同一条命令 - 返回值：指令对象 - 返回值类型：`Command` !!! tip - 顶层命令，也就是类似 `list` `gamerule` 这种，在 / 之后第一个输入的部分 - +顶层命令，也就是类似 `list` `gamerule` 这种，在 / 之后第一个输入的部分 + 注册完顶层命令后，此函数会返回一个指令对象。接下来，对于这个命令的功能扩展都需要在这个指令对象中进行 ### 指令对象 - 函数 -通过指令对象，你可以为这个命令注册各式各样的形式、功能。假设有一个叫 `Command` 的指令对象，则有下面这些成员函数 +通过指令对象，你可以为这个命令注册各式各样的形式、功能。假设有一个叫 `Command`的指令对象，则有下面这些成员函数 #### 设置指令别名 `Command.setAlias(alias)` + - 参数： - - alias : `String` - 指令别名 + - alias : `String` + 指令别名 - 返回值：是否成功设置 - 返回值类型：`Boolean` #### 新增一个指令枚举选项 `Command.setEnum(name,values)` + - 参数： - - name : `String` - 枚举名，用于设置参数时区分枚举 - - values : `Array` - 枚举的有效值 + - name : `String` + 枚举名，用于设置参数时区分枚举 + - values : `Array` + 枚举的有效值 - 返回值：新增枚举选项的标识名称 - 返回值类型：`String` #### 新增一个必选参数 `Command.mandatory(name,type[,enumName,identifier,enumOptions])` + - 参数： - - name : `String` - 参数名，用于执行指令时识别参数 - - type : `ParamType` - 命令参数类型 - - enumName : `String` - 枚举名（仅 `ParamType` 为 `Enum` 时有效，用于区分枚举选项） - - identifier : `String` - 参数标识，特殊情况下用于唯一识别参数，一般可用 `enumName` 或 `name` 代替 - - enumOptions : `Integer` - 参数选项，设置为 `1` 可在指令提示中展开枚举选项 - 如 `` 会变成 `` + - name : `String` + 参数名，用于执行指令时识别参数 + - type : `ParamType` + 命令参数类型 + - enumName : `String` + 枚举名（仅 `ParamType` 为 `Enum` 时有效，用于区分枚举选项） + - identifier : `String` + 参数标识，特殊情况下用于唯一识别参数，一般可用 `enumName` 或 `name` 代替 + - enumOptions : `Integer` + 参数选项，设置为 `1` 可在指令提示中展开枚举选项 + 如 `` 会变成 `` - 返回值：是否成功设置 - 返回值类型：`Boolean` @@ -142,71 +150,74 @@ log(result.output); `Command.optional(name,type[,enumName,identifier,enumOptions])` - 参数： - - name : `String` - 参数名，用于执行指令时识别参数 - - type : `ParamType` - 命令参数类型 - - enumName : `String` - 枚举名（仅 `ParamType` 为 `Enum` 时有效，用于区分枚举选项） - - identifier : `String` - 参数标识，特殊情况下用于唯一识别参数，一般可用 `enumName` 或 `name` 代替 - - enumOptions : `Integer` - 参数选项，设置为 `1` 可在指令提示中展开枚举选项 - 如 `` 会变成 `` + - name : `String` + 参数名，用于执行指令时识别参数 + - type : `ParamType` + 命令参数类型 + - enumName : `String` + 枚举名（仅 `ParamType` 为 `Enum` 时有效，用于区分枚举选项） + - identifier : `String` + 参数标识，特殊情况下用于唯一识别参数，一般可用 `enumName` 或 `name` 代替 + - enumOptions : `Integer` + 参数选项，设置为 `1` 可在指令提示中展开枚举选项 + 如 `` 会变成 `` - 返回值：是否成功设置 - 返回值类型：`Boolean` #### 有效的命令参数类型及解释 -| 命令参数类型 | 含义 | -| --------------------- | -------------------------------------------------------------------- | -| `ParamType.Bool` | 布尔值参数 | -| `ParamType.Int` | 整数参数 | -| `ParamType.Float` | 浮点数参数 | -| `ParamType.String` | 字符串参数 | -| `ParamType.Actor` | 实体目标选择器参数 | -| `ParamType.Player` | 玩家目标选择器参数 | -| `ParamType.BlockPos` | 整数坐标参数 | -| `ParamType.Vec3` | 浮点数坐标参数 | +| 命令参数类型 | 含义 | +|-----------------------|-------------------------------------| +| `ParamType.Bool` | 布尔值参数 | +| `ParamType.Int` | 整数参数 | +| `ParamType.Float` | 浮点数参数 | +| `ParamType.String` | 字符串参数 | +| `ParamType.Actor` | 实体目标选择器参数 | +| `ParamType.Player` | 玩家目标选择器参数 | +| `ParamType.BlockPos` | 整数坐标参数 | +| `ParamType.Vec3` | 浮点数坐标参数 | | `ParamType.RawText` | 原始字符串参数(可包含特殊字符，如逗号空格，只能作为最后一个参数使用) | -| `ParamType.Message` | 消息类型参数(同 `/say` 指令参数，会自动展开目标选择器等) | -| `ParamType.JsonValue` | JSON字符串参数 | -| `ParamType.Item` | 物品类型参数 | -| `ParamType.Block` | 方块类型参数 | -| `ParamType.Effect` | 效果类型参数 | -| `ParamType.Enum` | 枚举参数 | -| `ParamType.SoftEnum` | 可变枚举参数 | -| `ParamType.ActorType` | 实体类型参数 | -| `ParamType.Command` | 指令名称参数（仅供测试） | +| `ParamType.Message` | 消息类型参数(同 `/say` 指令参数，会自动展开目标选择器等) | +| `ParamType.JsonValue` | JSON字符串参数 | +| `ParamType.Item` | 物品类型参数 | +| `ParamType.Block` | 方块类型参数 | +| `ParamType.Effect` | 效果类型参数 | +| `ParamType.Enum` | 枚举参数 | +| `ParamType.SoftEnum` | 可变枚举参数 | +| `ParamType.ActorType` | 实体类型参数 | +| `ParamType.Command` | 指令名称参数（仅供测试） | #### 新增一条指令重载 -要想让命令正常运行，必须至少添加一条重载。所谓重载，本质上相当于参数的组合，譬如重载`['a', 'b', 'c']`相当于命令可以被执行为`/cmd `，而重载`[]`相当于可以被执行为`/cmd`。重载的参数标识符可以是参数名、枚举名、参数标识符，但不能使用无法区分具体参数的标识符，如两个参数都叫 `action` 但枚举选项不同，此时应该使用枚举名而不是参数名。 +要想让命令正常运行，必须至少添加一条重载。所谓重载，本质上相当于参数的组合，譬如重载`['a', 'b', 'c']`相当于命令可以被执行为 +`/cmd `，而重载`[]`相当于可以被执行为`/cmd`。重载的参数标识符可以是参数名、枚举名、参数标识符，但不能使用无法区分具体参数的标识符，如两个参数都叫 +`action` 但枚举选项不同，此时应该使用枚举名而不是参数名。 `Command.overload(params)` - 参数： - - params : `Array` - 参数标识符，重载所用到的参数列表，可用 参数标识符、枚举名、参数名。 - 注意不能使用无法区分具体参数的标识符，如两个参数都叫 `action` 但枚举选项不同，此时应该使用枚举名而不是参数名 + - params : `Array` + 参数标识符，重载所用到的参数列表，可用 参数标识符、枚举名、参数名。 + 注意不能使用无法区分具体参数的标识符，如两个参数都叫 `action` 但枚举选项不同，此时应该使用枚举名而不是参数名 - 返回值：是否成功设置 - 返回值类型：`Boolean` !!! tip - 指令重载是 BDS 区分不同指令形式的方法，每一种不同的指令形式对应着一种指令重载。 - 如你所见，指令重载中提供的各项参数名组成了一种新的指令形式 +指令重载是 BDS 区分不同指令形式的方法，每一种不同的指令形式对应着一种指令重载。 +如你所见，指令重载中提供的各项参数名组成了一种新的指令形式 #### 设置指令回调 `Command.setCallback(callback)` + - 参数： - - callback : `Function(cmd,origin,output,results)` - 注册的这个命令被执行时，接口自动调用的回调函数。 + - callback : `Function(cmd,origin,output,results)` + 注册的这个命令被执行时，接口自动调用的回调函数。 - 返回值：是否成功设置 - 返回值类型：`Boolean` !!! tip - 指令回调函数的参数相对复杂，在下面将进行详细解释 +指令回调函数的参数相对复杂，在下面将进行详细解释 #### 安装指令 @@ -231,11 +242,11 @@ log(result.output); 参数 `origin`的类型为 `CommandOrigin` 对象。此对象表示此次命令的执行者，通过这个对象，可以对执行者进行一些操作 对于某个特定的 `CommandOrigin` 对象`ori`，有以下这些属性 -| 属性 | 含义 | 类型 | -| ------------ | ---------------------- | ------------ | -| ori.type | 指令执行主体类型 | `OriginType` | -| ori.name | 指令执行主体的名称 | `String` | -| ori.pos | 指令执行主体的坐标 | `FloatPos` | +| 属性 | 含义 | 类型 | +|--------------|-------------|--------------| +| ori.type | 指令执行主体类型 | `OriginType` | +| ori.name | 指令执行主体的名称 | `String` | +| ori.pos | 指令执行主体的坐标 | `FloatPos` | | ori.blockPos | 指令执行主体的方块坐标 | `IntPos` | | ori.entity | 执行指令的实体（可空） | `Entity` | | ori.player | 执行指令的玩家（可空） | `Player` | @@ -250,10 +261,10 @@ log(result.output); `outp.success([msg][, parm])` - 参数： - - msg : `String` - 要输出的信息 - - parm : `Array` - 要替换的参数 + - msg : `String` + 要输出的信息 + - parm : `Array` + 要替换的参数 - 返回值：是否成功输出 - 返回值类型：`Boolean` @@ -262,10 +273,10 @@ log(result.output); `outp.error(msg[, parm])` - 参数： - - msg : `String` - 要输出的信息 - - parm : `Array` - 要替换的参数 + - msg : `String` + 要输出的信息 + - parm : `Array` + 要替换的参数 - 返回值：是否成功输出 - 返回值类型：`Boolean` @@ -274,43 +285,45 @@ log(result.output); `outp.addMessage(msg[, parm])` - 参数： - - msg : `String` - 要输出的信息 - - parm : `Array` - 要替换的参数 + - msg : `String` + 要输出的信息 + - parm : `Array` + 要替换的参数 - 返回值：是否成功输出 - 返回值类型：`Boolean` #### 参数 `result` ：命令各项参数获取的结果 -`results` 的内容为 `object<命令参数名-数据值>` 键值对。其中 `命令参数名` 为命令注册时设置的参数的 `name`值，而`数据值`即为执行者在当前命令参数的位置填上的内容 +`results` 的内容为 `object<命令参数名-数据值>` 键值对。其中 `命令参数名` 为命令注册时设置的参数的 `name`值，而`数据值` +即为执行者在当前命令参数的位置填上的内容 命令参数类型 和 数据值类型 的对应关系如下 -| 命令参数类型 | 数据值类型 | 含义 | -| --------------------- | --------------- | ---------------------------------------------------------------- | -| `ParamType.Bool` | `Boolean` | 布尔值 | -| `ParamType.Int` | `Integer` | 整数 | -| `ParamType.Float` | `Float` | 浮点数 | -| `ParamType.String` | `String` | 字符串 | -| `ParamType.Actor` | `Array` | 实体目标选择器 选中的实体 | -| `ParamType.Player` | `Array` | 玩家目标选择器 选中的实体 | -| `ParamType.BlockPos` | `IntPos` | 整数坐标对象 | -| `ParamType.Vec3` | `FloatPos` | 浮点数坐标对象 | -| `ParamType.RawText` | `String` | 原始字符串(可包含特殊字符，如逗号空格，只能作为最后一个参数使用) | -| `ParamType.Message` | `String` | 消息类型字符串(同 `/say` 指令参数，会自动展开目标选择器等) | -| `ParamType.JsonValue` | `String` | JSON字符串 | -| `ParamType.Item` | `Item` | 物品类型 | -| `ParamType.Block` | `Block` | 方块类型 | -| `ParamType.Effect` | `String` | 效果类型字符串 | -| `ParamType.Enum` | `String` | 枚举字符串 | -| `ParamType.SoftEnum` | `String` | 可变枚举字符串 | -| `ParamType.ActorType` | `String` | 实体类型字符串 | -| `ParamType.Command` | `String` | 指令名称（仅供测试） | +| 命令参数类型 | 数据值类型 | 含义 | +|-----------------------|-----------------|------------------------------------| +| `ParamType.Bool` | `Boolean` | 布尔值 | +| `ParamType.Int` | `Integer` | 整数 | +| `ParamType.Float` | `Float` | 浮点数 | +| `ParamType.String` | `String` | 字符串 | +| `ParamType.Actor` | `Array` | 实体目标选择器 选中的实体 | +| `ParamType.Player` | `Array` | 玩家目标选择器 选中的实体 | +| `ParamType.BlockPos` | `IntPos` | 整数坐标对象 | +| `ParamType.Vec3` | `FloatPos` | 浮点数坐标对象 | +| `ParamType.RawText` | `String` | 原始字符串(可包含特殊字符，如逗号空格，只能作为最后一个参数使用) | +| `ParamType.Message` | `String` | 消息类型字符串(同 `/say` 指令参数，会自动展开目标选择器等) | +| `ParamType.JsonValue` | `String` | JSON字符串 | +| `ParamType.Item` | `Item` | 物品类型 | +| `ParamType.Block` | `Block` | 方块类型 | +| `ParamType.Effect` | `String` | 效果类型字符串 | +| `ParamType.Enum` | `String` | 枚举字符串 | +| `ParamType.SoftEnum` | `String` | 可变枚举字符串 | +| `ParamType.ActorType` | `String` | 实体类型字符串 | +| `ParamType.Command` | `String` | 指令名称（仅供测试） | ### 命令注册样例 [JavaScript] + ```js mc.listen("onServerStarted", () => { const cmd = mc.newCommand("manager", "Command Description", PermType.GameMasters); @@ -341,28 +354,28 @@ mc.listen("onServerStarted", () => { 这里的假命令API为 **向下兼容** 而留存，推荐使用上面文档所写的的 **真命令** API !!! warning - 尽管看起来比较简单，但是假命令有一些很重要的缺点，包括只能由玩家或控制台执行，其他对象（如命令方块、NPC等）都无法执行、所有参数数据都需要自行解析等等。 - +尽管看起来比较简单，但是假命令有一些很重要的缺点，包括只能由玩家或控制台执行，其他对象（如命令方块、NPC等）都无法执行、所有参数数据都需要自行解析等等。 + 请尽量使用 真命令API -### 注册一个新的玩家命令（假命令） +### 注册一个新的玩家命令（假命令） `mc.regPlayerCmd(cmd,description,callback[,level])` - 参数： - - cmd : `String` - 待注册的命令 - - description : `String` - 命令描述文本 - - callback : `Function(player,args)` - 注册的这个命令被执行时，接口自动调用的回调函数。 - - level : `Integer` - （可选参数）命令的注册等级，默认为 0 ，即所有人都可以执行 - 如果设置命令注册等级为1，则只有OP可以执行此命令 + - cmd : `String` + 待注册的命令 + - description : `String` + 命令描述文本 + - callback : `Function(player,args)` + 注册的这个命令被执行时，接口自动调用的回调函数。 + - level : `Integer` + （可选参数）命令的注册等级，默认为 0 ，即所有人都可以执行 + 如果设置命令注册等级为1，则只有OP可以执行此命令 - 返回值：是否成功注册 - 返回值类型：`Boolean` -注：参数callback的回调函数原型：`function(player,args)` +注：参数callback的回调函数原型：`function(player,args)` - player : `Player` 执行命令的玩家对象 @@ -371,48 +384,49 @@ mc.listen("onServerStarted", () => { 如注册了自定义命令 `land set`，当执行 `/land set abc 2333` 时，args的值将为 `[ "abc","2333" ]` [JavaScript] + ```js -mc.regPlayerCmd("fly on","Turn on the fly mode",function(pl,args){ +mc.regPlayerCmd("fly on", "Turn on the fly mode", function (pl, args) { pl.tell("Flying enabled."); //...... }); ``` - -### 注册一个新的控制台命令（假命令） +### 注册一个新的控制台命令（假命令） `mc.regConsoleCmd(cmd,description,callback)` - 参数： - - cmd : `String` - 待注册的命令 + - cmd : `String` + 待注册的命令 - - description : `String` - 命令描述文本 + - description : `String` + 命令描述文本 - - callback : `Function` - 注册的这个命令被执行时，接口自动调用的回调函数。 + - callback : `Function` + 注册的这个命令被执行时，接口自动调用的回调函数。 - 返回值：是否成功注册 - 返回值类型：`Boolean` -注：参数callback的回调函数原型：`function(args)` +注：参数callback的回调函数原型：`function(args)` - args : `Array` 目标命令后面的参数。按空格为分界分割，组成字符串数组。 如注册了自定义命令 `land set`，当执行 `/land set abc 2333` 时，args的值将为 `['abc','2333']` [JavaScript] + ```js -mc.regConsoleCmd("backup","Start the backup",function(args){ - log("ID of this backup is:",args[0]); +mc.regConsoleCmd("backup", "Start the backup", function (args) { + log("ID of this backup is:", args[0]); //...... }); ``` !!! tip "假命令注册相关说明" - 设置了回调函数之后，在你注册的这个假命令被执行的时候，回调函数就会被调用。 - 在调用之前，脚本引擎会自动帮你把命令参数分割成数组。 - +设置了回调函数之后，在你注册的这个假命令被执行的时候，回调函数就会被调用。 +在调用之前，脚本引擎会自动帮你把命令参数分割成数组。 + 以JavaScript语言为例： 执行命令 @@ -423,8 +437,6 @@ mc.regConsoleCmd("backup","Start the backup",function(args){ 正如所见，`args` 中包含的值是被 **按顺序分割好的** 命令参数。 如果你的命令中有引号（比如说为了处理含有空格的玩家名字），脚本引擎在分割时也会做处理。 - - ## 其他与命令系统有关的 API ### 模拟产生一个控制台命令输出 @@ -432,8 +444,8 @@ mc.regConsoleCmd("backup","Start the backup",function(args){ `mc.sendCmdOutput(output)` - 参数： - - output : `String` - 模拟产生的命令输出 + - output : `String` + 模拟产生的命令输出 - 返回值：是否成功执行 - 返回值类型：`Boolean`