Custom Slash Command Wrapper

Custom slash commands are complicated additions to your add-ons. Let's fix that.

You can add a custom command in 5 steps using this library. Keep scrolling down to find out how.

Quick Example

Obviously, ensure you first import the functions and classes. You'll need to import from @minecraft/server too:

import { system, CustomCommandParamType, CommandPermissionLevel } from "@minecraft/server";
import { CommandRegister, defineCommand, defineParameter } from "command-wrapper";

Configure the register.

const commandRegister = new CommandRegister("hello", CommandPermissionLevel.GameDirectors, true)

Pick your parameters.

const targetParam = defineParameter({
    name: "target",
    type: CustomCommandParamType.EntitySelector,
    mandatory: true
})

Create the command.

const smiteCommand = defineCommand({
    name: "smite",
    description: "Smites selected entities.",
    parameters: [targetParam],
    callbackFunction(_origin, players) {
        system.run(() => {
            players.forEach(player => {
                player.runCommand("summon lightning_bolt")
            })
        })
    }
})

Recite to the register.

commandRegister.registerCommand(smiteCommand)

Altogether, you'll finish with this file.

import { system, CustomCommandParamType, CommandPermissionLevel } from "@minecraft/server"
import { CommandRegister, defineCommand, defineParameter } from "command-wrapper";

const commandRegister = new CommandRegister("hello", CommandPermissionLevel.GameDirectors, true)

const targetParam = defineParameter({
    name: "target",
    type: CustomCommandParamType.EntitySelector,
    mandatory: true
})

const smiteCommand = defineCommand({
    name: "smite",
    description: "Smites selected entities.",
    parameters: [targetParam],
    callbackFunction(_origin, players) {
        system.run(() => {
            players.forEach(player => {
                player.runCommand("summon lightning_bolt")
            })
        })
    }
})

commandRegister.registerCommand(smiteCommand)

Now, you can strike yourself with lightning using /hello:smite @s.

Details

The CommandRegister needs you to define the command prefix, and, optionally, the defaultPermissionLevel and whether cheats are required to run them.

You can also tell it to suppressWarnings about registering duplicate Enum parameters. Errors cannot be suppressed.

[!IMPORTANT] Don't create more than one CommandRegister. Instead, export it as a global constant for your project.

new CommandRegister(namespace: string, defaultPermissionLevel?: CommandPermissionLevel, cheatsRequired?: boolean, suppressWarnings?: boolean)

Individual commands can override the defaultPermissionLevel and cheatsRequired setting defined here.

If not provided, the defaultPermissionLevel is set to CommandPermissionLevel.GameDirectors, and cheatsRequired is set to true.

The defineParameter function accepts this object for non Enum parameters.

interface CommandParameterGeneric {
  name: string;
  mandatory: boolean;
  type: Exclude<CustomCommandParamType, CustomCommandParamType.Enum>>;
}

For an Enum parameter, there is an extra values property. values must not be an empty array.

interface CommandParameterEnum {
  name: string;
  mandatory: boolean;
  type: CustomCommandParamType.Enum;
  values: string[];
}

[!NOTE] Each Enum parameter must have a unique name. Multiple registrations are not permitted by the underlying Script API.

As the same parameter may be legitimately registered several times for separate commands, doing this will only result in the first Enum being used.

No prefixes are required, they are handled automatically.

The defineCommand function accepts an object like this.

interface CommandInfo {
  callbackFunction: CommandCallback<P>;
  successMessage?: string;
  failureMessage?: string;
  cheatsRequired?: boolean;
  name: string;
  description: string;
  permissionLevel?: CommandPermissionLevel;
  parameters?: (CommandParameterGeneric | CommandParameterEnum)[];
}

[!IMPORTANT] Optional parameters must come after mandatory parameters in the array.

Again, no prefixes are required for the name property. It is handled automatically.