Script API - v1.21.120.21
    Preparing search index...

    Class CustomCommandRegistry

    Provides the functionality for registering custom commands.

    import {
    CustomCommandRegistry,
    CustomCommand,
    CustomCommandParameter,
    CustomCommandParamType,
    CommandPermissionLevel,
    CustomCommandOrigin,
    CustomCommandResult,
    CustomCommandStatus,
    } from "@minecraft/server";

    // Example of registering custom commands using CustomCommandRegistry
    function registerCustomCommands(registry: CustomCommandRegistry) {
    // Register an enum for command parameters
    registry.registerEnum("teleportTargets", ["spawn", "home", "end", "nether"]);

    // Define a simple teleport command
    const teleportCommand: CustomCommand = {
    name: "custom:teleport",
    description: "Teleport to predefined locations",
    permissionLevel: CommandPermissionLevel.Admin,
    cheatsRequired: true,
    mandatoryParameters: [
    {
    name: "destination",
    type: CustomCommandParamType.Enum,
    },
    ],
    optionalParameters: [
    {
    name: "player",
    type: CustomCommandParamType.PlayerSelector,
    },
    ],
    };

    // Register the command with a callback
    registry.registerCommand(teleportCommand, (origin: CustomCommandOrigin, args: any[]) => {
    const destination = args[0] as string;
    const targetPlayer = args[1]; // Optional player parameter

    console.log(`Teleport command executed by ${origin.sourceType}`);
    console.log(`Destination: ${destination}`);

    if (origin.sourceEntity) {
    console.log(`Command source entity: ${origin.sourceEntity.typeId}`);
    }

    // Perform teleportation logic here
    const result: CustomCommandResult = {
    status: CustomCommandStatus.Success,
    message: `Teleported to ${destination}`,
    };

    return result;
    });

    // Define a more complex command with multiple parameter types
    const giveItemCommand: CustomCommand = {
    name: "custom:giveitem",
    description: "Give items to players with custom parameters",
    permissionLevel: CommandPermissionLevel.GameDirectors,
    cheatsRequired: false,
    mandatoryParameters: [
    {
    name: "item",
    type: CustomCommandParamType.ItemType,
    },
    {
    name: "amount",
    type: CustomCommandParamType.Integer,
    },
    ],
    optionalParameters: [
    {
    name: "target",
    type: CustomCommandParamType.PlayerSelector,
    },
    ],
    };

    registry.registerCommand(giveItemCommand, (origin: CustomCommandOrigin, args: any[]) => {
    const itemType = args[0];
    const amount = args[1] as number;
    const target = args[2]; // Optional

    // Command execution logic
    return {
    status: CustomCommandStatus.Success,
    message: `Gave ${amount} ${itemType} to player`,
    };
    });
    }

    // Example usage during startup
    // This would typically be called in a startup event handler
    // registerCustomCommands(startupEvent.customCommandRegistry);

    Custom Command APIs are released as part of Scripting API 2.0 Beta in Minecraft v1.21.80. Here's a video from Mojang that covers the custom command APIs.

    Index

    Constructors

    Methods

    • Parameters

      Returns void

      Registers a custom command that when executed triggers a script callback.

      This function can't be called in read-only mode.

      This function can be called in early-execution mode.

      // This sample is from Mojang, see an updated sample at
      // https://github.com/microsoft/minecraft-scripting-samples/tree/main/custom-commands
      import {
      system,
      StartupEvent,
      CommandPermissionLevel,
      CustomCommand,
      CustomCommandParamType,
      CustomCommandStatus,
      CustomCommandOrigin,
      CustomCommandResult,
      world,
      Entity,
      Vector3,
      } from "@minecraft/server";

      system.beforeEvents.startup.subscribe((init: StartupEvent) => {
      const dirtsterCommand: CustomCommand = {
      name: "creator:dirtster",
      description: "Adds some dirt, ster",
      permissionLevel: CommandPermissionLevel.GameDirectors,
      mandatoryParameters: [{ type: CustomCommandParamType.Location, name: "dirtLocation" }],
      };
      init.customCommandRegistry.registerCommand(dirtsterCommand, dirtster);
      });

      function dirtster(origin: CustomCommandOrigin, loc: Vector3): CustomCommandResult {
      world.sendMessage("Lets get dirty!");

      system.run(() => {
      const dim = world.getDimension("overworld");

      dim.setBlockType(loc, "minecraft:dirt");

      // it's a mini dirt pyramid
      dim.setBlockType({ x: loc.x + 2, y: loc.y + 1, z: loc.z }, "minecraft:dirt");
      dim.setBlockType({ x: loc.x - 2, y: loc.y + 1, z: loc.z }, "minecraft:dirt");
      dim.setBlockType({ x: loc.x + 1, y: loc.y + 1, z: loc.z }, "minecraft:dirt");
      dim.setBlockType({ x: loc.x - 1, y: loc.y + 1, z: loc.z }, "minecraft:dirt");
      dim.setBlockType({ x: loc.x, y: loc.y + 1, z: loc.z }, "minecraft:dirt");

      dim.setBlockType({ x: loc.x + 1, y: loc.y + 2, z: loc.z }, "minecraft:dirt");
      dim.setBlockType({ x: loc.x - 1, y: loc.y + 2, z: loc.z }, "minecraft:dirt");
      dim.setBlockType({ x: loc.x, y: loc.y + 2, z: loc.z }, "minecraft:dirt");

      dim.setBlockType({ x: loc.x, y: loc.y + 3, z: loc.z }, "minecraft:dirt");
      }); //

      return {
      status: CustomCommandStatus.Success,
      };
      }
      // This sample is from Mojang, see an updated sample at
      // https://github.com/microsoft/minecraft-scripting-samples/tree/main/custom-commands
      import {
      system,
      StartupEvent,
      CommandPermissionLevel,
      CustomCommand,
      CustomCommandParamType,
      CustomCommandStatus,
      CustomCommandOrigin,
      CustomCommandResult,
      world,
      } from "@minecraft/server";

      system.beforeEvents.startup.subscribe((init: StartupEvent) => {
      const helloCommand: CustomCommand = {
      name: "creator:hellocustomcommand",
      description: "Celebration super party hello",
      permissionLevel: CommandPermissionLevel.Any,
      optionalParameters: [{ type: CustomCommandParamType.Integer, name: "celebrationSize" }],
      };
      init.customCommandRegistry.registerCommand(helloCommand, helloCustomCommand);
      });

      function helloCustomCommand(origin: CustomCommandOrigin, celebrationSize?: number): CustomCommandResult {
      world.sendMessage("Hello Custom Command!");
      const player = origin.sourceEntity;

      if (celebrationSize && player) {
      system.run(() => {
      player.dimension.createExplosion(player.location, celebrationSize);
      });
      }

      return {
      status: CustomCommandStatus.Success,
      };
      }
      // This sample is from Mojang, see an updated sample at
      // https://github.com/microsoft/minecraft-scripting-samples/tree/main/custom-commands
      import {
      system,
      StartupEvent,
      CommandPermissionLevel,
      CustomCommand,
      CustomCommandParamType,
      CustomCommandStatus,
      CustomCommandOrigin,
      CustomCommandResult,
      world,
      Entity,
      } from "@minecraft/server";

      system.beforeEvents.startup.subscribe((init: StartupEvent) => {
      const partyCommand: CustomCommand = {
      name: "creator:party",
      description: "Cause selected entities to party",
      permissionLevel: CommandPermissionLevel.GameDirectors,
      mandatoryParameters: [{ type: CustomCommandParamType.EntitySelector, name: "partyParticipants" }],
      };
      init.customCommandRegistry.registerCommand(partyCommand, party);
      });

      function party(origin: CustomCommandOrigin, entities: Entity[]): CustomCommandResult {
      world.sendMessage("Entity party!");

      system.run(() => {
      for (const entity of entities) {
      entity.applyImpulse({ x: 0, y: 1, z: 0 });
      entity.dimension.spawnParticle("minecraft:ominous_spawning_particle", entity.location);
      }
      }); //

      return {
      status: CustomCommandStatus.Success,
      };
      }
    • Parameters

      • name: string
      • values: string[]

      Returns void

      Registers a custom command enum.

      Important

      • registerEnum() must be called before registerCommand() for the custom command to be registered successfully.
      • The command enum name must match the registered enum name declared in the custom command object.
      system.beforeEvents.startup.subscribe((init: StartupEvent) => {
      const command: CustomCommand = {
      name: "creator:command",
      // ... more required parameters
      mandatoryParameters: [
      { type: CustomCommandParamType.Enum, name: "creator:enum" },
      ],
      };
      // registerEnum() must be called before registerCommand()
      init.customCommandRegistry.registerEnum("creator:enum", ['value1', 'value2']); // The command enum name must match the registered enum name declared above.
      init.customCommandRegistry.registerCommand(command, callback);
      });

      This function can't be called in read-only mode.

      This function can be called in early-execution mode.

      import {
      system,
      StartupEvent,
      CustomCommand,
      CommandPermissionLevel,
      CustomCommandParamType,
      CustomCommandOrigin,
      CustomCommandResult,
      CustomCommandStatus,
      world,
      } from "@minecraft/server";

      system.beforeEvents.startup.subscribe((init: StartupEvent) => {
      const dimensionsEnum: string[] = ["overworld", "nether", "the_end"];
      const switchDimensionCommand: CustomCommand = {
      name: "jayly:switchdimension",
      description: "Switch dimension",
      permissionLevel: CommandPermissionLevel.GameDirectors,
      mandatoryParameters: [{ type: CustomCommandParamType.Enum, name: "jayly:dimension" }],
      };
      // registerEnum() must be called before registerCommand()
      init.customCommandRegistry.registerEnum("jayly:dimension", dimensionsEnum);
      init.customCommandRegistry.registerCommand(switchDimensionCommand, switchDimensionsCommand);
      });

      function switchDimensionsCommand(origin: CustomCommandOrigin, dimensionId: string): CustomCommandResult {
      const entity = origin.sourceEntity;
      if (!entity) return { status: CustomCommandStatus.Failure, message: "No entity found" };

      system.run(() => {
      entity.teleport(entity.location, { dimension: world.getDimension(dimensionId) });
      });

      return {
      status: CustomCommandStatus.Success,
      message: `Teleported ${entity.typeId.replace("minecraft:", "")} to ${dimensionId}`,
      };
      }