Commands API

Overview

Minestom’s command system provides a powerful builder API for creating commands with auto-completion, argument parsing, and condition checking.

CommandManager

Manager used to register and execute commands.

Registration

void

Registers a command

Show parameters

command

Command

The command to register

Throws IllegalStateException if a command with the same name already exists

unregister

void

Removes a command from registered commands

Show parameters

command

Command

The command to remove

getCommand

Command

Gets a registered command by name

Show parameters

commandName

String

The command name (case-insensitive)

Returns null if not found

commandExists

boolean

Checks if a command exists

Show parameters

commandName

String

The command name to check

Execution

execute

CommandResult

Executes a command for a CommandSender

Show parameters

sender

CommandSender

The sender of the command

command

String

The raw command string (without prefix)

executeServerCommand

CommandResult

Executes a command using a ServerSender (silent, nothing printed to console)

Show parameters

command

String

The command to execute

Callbacks

setUnknownCommandCallback

void

Sets the callback executed when an unknown command is run

Show parameters

callback

CommandCallback

The callback (null to remove)

getConsoleSender

ConsoleSender

Gets the ConsoleSender instance for executing commands from console

createDeclareCommandsPacket

DeclareCommandsPacket

Creates the commands packet for a specific player (for auto-completion)

Show parameters

player

Player

The player to get the commands packet for

Command

Represents a command with suggestion/auto-completion support.

Creating Commands

Command command = new Command("teleport", "tp");

command.setDefaultExecutor((sender, context) -> {
    sender.sendMessage("Usage: /teleport <player>");
});

command.addSyntax((sender, context) -> {
    Player target = context.get("target");
    if (sender instanceof Player player) {
        player.teleport(target.getPosition());
    }
}, ArgumentType.Entity("target").onlyPlayers(true));

MinecraftServer.getCommandManager().register(command);

Command Methods

addSyntax

Collection<CommandSyntax>

Adds a new syntax to the command

Show parameters

executor

CommandExecutor

The executor called when syntax is matched

args

Argument<?>...

The arguments for this syntax

Returns the created syntaxes (multiple if optional arguments are used)

addConditionalSyntax

Collection<CommandSyntax>

Adds a syntax with a condition

Show parameters

condition

CommandCondition

The condition to use the syntax

executor

CommandExecutor

The executor

args

Argument<?>...

The arguments

setDefaultExecutor

void

Sets the executor called when no syntax matches

Show parameters

executor

CommandExecutor

The default executor (null to remove)

setCondition

void

Sets the command condition (checked before execution)

Show parameters

condition

CommandCondition

The condition (null to remove)

setArgumentCallback

void

Sets a callback for argument errors

Show parameters

callback

ArgumentCallback

The callback

argument

Argument<?>

The argument to attach callback to

addSubcommand

void

Adds a subcommand

Show parameters

command

Command

The subcommand to add

getName

String

Gets the main command name

getAliases

String[]

Gets all command aliases

getSyntaxes

Collection<CommandSyntax>

Gets all syntaxes of this command

Argument Types

The ArgumentType class provides factory methods for all built-in argument types.

Basic Arguments

ArgumentType.Boolean(id)

ArgumentBoolean

Parses boolean values (true/false)

ArgumentType.Integer(id)

ArgumentInteger

Parses integer values

Show methods

min(int) - Set minimum value
max(int) - Set maximum value
between(int, int) - Set range

ArgumentType.Double(id)

ArgumentDouble

Parses double values

Show methods

min(double) - Set minimum value
max(double) - Set maximum value
between(double, double) - Set range

ArgumentType.Float(id)

ArgumentFloat

Parses float values

ArgumentType.Long(id)

ArgumentLong

Parses long values

ArgumentType.String(id)

ArgumentString

Parses string values (quoted or single word)

ArgumentType.Word(id)

ArgumentWord

Parses a single word (no spaces)

Show methods

from(String...) - Restrict to specific words

ArgumentType.StringArray(id)

ArgumentStringArray

Parses remaining arguments as string array

Minecraft-Specific Arguments

ArgumentType.Entity(id)

ArgumentEntity

Parses entity selectors (@p, @a, @e, etc.)

Show methods

onlyPlayers(boolean) - Only allow player selection
singleEntity(boolean) - Only allow single entity

ArgumentType.ItemStack(id)

ArgumentItemStack

Parses item stack with optional NBT

ArgumentType.BlockState(id)

ArgumentBlockState

Parses block state with properties

ArgumentType.Color(id)

ArgumentColor

Parses chat colors

ArgumentType.Component(id)

ArgumentComponent

Parses JSON text components

ArgumentType.NBT(id)

ArgumentNbtTag

Parses NBT tags

ArgumentType.NbtCompound(id)

ArgumentNbtCompoundTag

Parses NBT compound tags

ArgumentType.RelativeBlockPosition(id)

ArgumentRelativeBlockPosition

Parses block positions (supports relative coordinates)

ArgumentType.RelativeVec3(id)

ArgumentRelativeVec3

Parses 3D vectors (supports relative coordinates)

ArgumentType.UUID(id)

ArgumentUUID

Parses UUIDs

ArgumentType.Time(id)

ArgumentTime

Parses time values (with units: s, t, d)

ArgumentType.Resource(id, identifier)

ArgumentResource

Parses resource locations from a registry

ArgumentType.Particle(id)

ArgumentParticle

Parses particle types with data

Argument Utilities

ArgumentType.Literal(id)

ArgumentLiteral

Matches a literal string (for subcommands)

ArgumentType.Group(id, args)

ArgumentGroup

Groups multiple arguments

ArgumentType.Loop(id, args)

ArgumentLoop<T>

Repeats argument pattern

Argument Customization

All argument types extend the base Argument<T> class with these methods:

setDefaultValue

Argument<T>

Sets a default value (makes argument optional)

Show parameters

defaultValue

T | Supplier<T> | Function<CommandSender, T>

The default value or supplier

setSuggestionCallback

Argument<T>

Sets custom tab-completion suggestions

Show parameters

callback

SuggestionCallback

The suggestion callback

setCallback

void

Sets error callback for this argument

Show parameters

callback

ArgumentCallback

The error callback

map

Argument<O>

Maps argument output to another type

Show parameters

mapper

Function<T, O>

The mapper function

filter

Argument<T>

Adds a filter predicate

Show parameters

predicate

Predicate<T>

The filter predicate

Usage Examples

Command gamemode = new Command("gamemode", "gm");

gamemode.addSyntax((sender, context) -> {
    if (!(sender instanceof Player player)) {
        sender.sendMessage("Only players can use this command");
        return;
    }
    
    int mode = context.get("mode");
    player.setGameMode(GameMode.values()[mode]);
    player.sendMessage("Gamemode changed to " + mode);
}, ArgumentType.Integer("mode").between(0, 3));

MinecraftServer.getCommandManager().register(gamemode);

Commands are registered globally through the CommandManager. Each syntax is tried in order until one matches.

Core

Systems

Utilities

Overview

CommandManager

Registration

Execution

Callbacks

Command

Creating Commands

Command Methods

Argument Types

Basic Arguments

Minecraft-Specific Arguments

Argument Utilities

Argument Customization

Usage Examples

Build docs developers (and LLMs) love

Core

Systems

Utilities

​Overview

​CommandManager

​Registration

​Execution

​Callbacks

​Command

​Creating Commands

​Command Methods

​Argument Types

​Basic Arguments

​Minecraft-Specific Arguments

​Argument Utilities

​Argument Customization

​Usage Examples

Build docs developers (and LLMs) love

Overview

CommandManager

Registration

Execution

Callbacks

Command

Creating Commands

Command Methods

Argument Types

Basic Arguments

Minecraft-Specific Arguments

Argument Utilities

Argument Customization

Usage Examples