🎯 Command Related API

The following APIs provide interfaces for registering and listening to custom commands in the game:

Execute a Background Command

mc.runcmd(cmd)

• Parameters:
  • cmd : String
    The command to be executed.
• Return value: Whether the execution was successful.
• Return value type: Boolean

[JavaScript]

mc.runcmd("say Hello!");

[Lua]

mc.runcmd("say Hello!")

Execute a Background Command (Enhanced Version)

mc.runcmdEx(cmd)

• Parameters:

  • cmd : String
    The command to be executed.

• Return value: Command Execution Result Object

• Return value type: Object<Boolean,String>

  • For a returned execution result object res, there are the following members:

[JavaScript]

var result = mc.runcmdEx("say Hello!");
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.

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)
  • 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

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.

Set Command Alias

Command.setAlias(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<String>
    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 <action : TagChangeAction> will become <add|remove>.
• Return value: Whether setting succeeded or not.
• Return value type: Boolean

Add an Optional Parameter

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 <action : TagChangeAction> will become <add|remove>.
• Return value: Whether setting succeeded or not.
• Return value type: Boolean

Valid Command Parameter Types and Explanations

Add a New Command Overload

Command.overload(params)

• Parameters:
  • params : Array<String>
    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

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.
• Return value: Whether setting succeeded or not.
• Return value type: Boolean

Installation Instructions

After all the configuration of the command is completed, use this function to register the command to the BDS command system.

Command.setup()

• Return value: Whether the installation was successful.
• Return value type: Boolean

Command Callback Function

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

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. For a particular CommandOrigin object ori, there are the following properties:

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. 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
• Return value: Whether the output is successful.
• Return value type: Boolean

Output an Error Message

outp.error(msg[, parm])

• Parameters:
  • msg : String
    The message to output.
  • parm : Array Parameters to be replaced
• Return value: Whether the output is successful.
• Return value type: Boolean

Output a General Message

outp.addMessage(msg[, parm])

• 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

The content of results is object<command parameter name-data value> 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 Registration Example

[JavaScript]

mc.listen("onServerStarted", () => {
    let cmd = mc.newCommand("manager", "Command Description", PermType.GameMasters);
    cmd.setAlias("mgr");
    cmd.setEnum("ChangeAction", ["add", "remove"]);
    cmd.setEnum("ListAction", ["list"]);
    cmd.mandatory("action", ParamType.Enum, "ChangeAction", 1);
    cmd.mandatory("action", ParamType.Enum, "ListAction", 1);
    cmd.mandatory("name", ParamType.RawText);
    cmd.overload(["ChangeAction", "name"]);
    cmd.overload(["ListAction"]);
    cmd.setCallback((_cmd, _ori, out, res) => {
        switch (res.action) {
            case "add":
                return out.success(`add "${res.name}"`);
            case "remove":
                return out.success(`remove "${res.name}"`);
            case "list":
                return out.success(`Name List:`);
        }
    });
    cmd.setup();
});

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.

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.
• Return value: Whether the registration was successful.
• Return value type: Boolean

Note: The callback function prototype of the parameter callback: function(player, args)

• player : Player
  The player that executes the command.
• args : Array<String,String...>
  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" ]

[JavaScript]

mc.regPlayerCmd("fly on", "Turn on the fly mode", function (pl, args) {
    pl.tell("Flying enabled.");
    //......
});

Register a New Background Console Command (Fake Command)

mc.regConsoleCmd(cmd,description,callback)

• Parameters:

  • cmd : String
    The command that will be registered.

  • description : String
    Command Description Text.

  • 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

Note: The callback function prototype of the parameter callback: function(args)

• args : Array<String,String...>
  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']

[JavaScript]

mc.regConsoleCmd("backup", "Start the backup", function (args) {
    log("ID of this backup is:", args[0]);
    //......
});

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.

• Return value: Whether the exection was successful.

• Return value type: Boolean