Arguments

Arguments in the CommandAPI are registered by using an Argument[] or List<Argument> object. There are two things you need to keep in mind when creating arguments:

  • The order which they will be used
  • The type of each argument

By definition of a List, the order of the elements inserted into it are preserved, meaning the order you add arguments to the List will be the resulting order of which arguments are presented to the user when they run that command.

Adding arguments for registration is simple:

// Create a List
List<Argument> arguments = new ArrayList<>();

// Add an argument with the node "target", which is a PlayerArgument
arguments.add(new PlayerArgument("target"));

The String value is the node that is registered into Minecraft's internal command graph. This is name is also used as a prompt that is shown to a player when they are entering the command.


The CommandAPI is very flexible when it comes to registering arguments, and lets you use a number of different methods to suit your preference:

new CommandAPICommand("mycommand")
    .withArguments(new StringArgument("arg0"))
    .withArguments(new StringArgument("arg1"))
    .withArguments(new StringArgument("arg2"))
    // And so on
CommandAPICommand("mycommand")
    .withArguments(StringArgument("arg0"))
    .withArguments(StringArgument("arg1"))
    .withArguments(StringArgument("arg2"))
    // And so on
commandAPICommand("mycommand") {
    stringArgument("arg0")
    stringArgument("arg1")
    stringArgument("arg2")
    // And so on
}
new CommandAPICommand("mycommand")
    .withArguments(new StringArgument("arg0"), new StringArgument("arg1"), new StringArgument("arg2"))
    // And so on
CommandAPICommand("mycommand")
    .withArguments(StringArgument("arg0"), StringArgument("arg1"), StringArgument("arg2"))
    // And so on
commandAPICommand("mycommand") {
    arguments(StringArgument("arg0"), StringArgument("arg1"), StringArgument("arg2"))
    // And so on
}
List<Argument<?>> arguments = new ArrayList<>();
arguments.add(new StringArgument("arg0"));
arguments.add(new StringArgument("arg1"));
arguments.add(new StringArgument("arg2"));

new CommandAPICommand("mycommand")
    .withArguments(arguments)
    // And so on
val arguments = listOf(
    StringArgument("arg0"),
    StringArgument("arg1"),
    StringArgument("arg2")
)

CommandAPICommand("mycommand")
    .withArguments(arguments)
    // And so on
val arguments = listOf(
    StringArgument("arg0"),
    StringArgument("arg1"),
    StringArgument("arg2")
)

commandAPICommand("mycommand") {
    arguments(*arguments.toTypedArray())
    // And so on
}

Argument Casting

To access arguments, they have to be casted to the type that the argument represents. The order of the arguments in the CommandArguments args is the same as the order in which the arguments were declared.

List<Argument<?>> commandArguments = new ArrayList<>();
commandArguments.add(new StringArgument("arg0"));
commandArguments.add(new PotionEffectArgument("arg1"));
commandArguments.add(new LocationArgument("arg2"));

new CommandAPICommand("cmd")
    .withArguments(commandArguments)
    .executes((sender, args) -> {
        String stringArg = (String) args.get("arg0");
        PotionEffectType potionArg = (PotionEffectType) args.get("arg1");
        Location locationArg = (Location) args.get("arg2");
    })
    .register();
val commandArguments = listOf(
    StringArgument("arg0"),
    PotionEffectArgument("arg1"),
    LocationArgument("arg2")
)

CommandAPICommand("cmd")
    .withArguments(commandArguments)
    .executes(CommandExecutor { _, args ->
        val stringArg = args["arg0"] as String
        val potionArg = args["arg1"] as PotionEffectType
        val locationArg = args["arg2"] as Location
    })
    .register()
val args = listOf(
    StringArgument("arg0"),
    PotionEffectArgument("arg1"),
    LocationArgument("arg2")
)

commandAPICommand("cmd") {
    arguments(*args.toTypedArray())
    anyExecutor { _, args ->
        val stringArg = args["arg0"] as String
        val potionArg = args["arg1"] as PotionEffectType
        val locationArg = args["arg2"] as Location
    }
}

The type to cast each argument (declared in the dev.jorel.commandapi.arguments package) is listed below:

Argument classData type
AngleArgumentfloat
AdvancementArgumentorg.bukkit.advancement.Advancement
AdventureChatArgumentnet.kyori.adventure.text.Component
AdventureChatColorArgumentnet.kyori.adventure.text.format.NamedTextColor
AdventureChatComponentArgumentnet.kyori.adventure.text.Component
AxisArgumentjava.util.EnumSet<org.bukkit.Axis>
BiomeArgumentorg.bukkit.block.Biome
BiomeArgument.NamespacedKeyorg.bukkit.NamespacedKey
BlockPredicateArgumentjava.util.function.Predicate
<org.bukkit.block.Block>
BlockStateArgumentorg.bukkit.block.data.BlockData
BooleanArgumentboolean
ChatArgumentnet.md_5.bungee.api.chat.BaseComponent[]
ChatColorArgumentorg.bukkit.ChatColor
ChatComponentArgumentnet.md_5.bungee.api.chat.BaseComponent[]
CommandArgumentdev.jorel.commandapi.wrappers.CommandResult
CustomArgument<T, B>T
DoubleArgumentdouble
EnchantmentArgumentorg.bukkit.enchantments.Enchantment
EntitySelectorArgument.ManyEntitiesCollection<org.bukkit.entity.Entity>
EntitySelectorArgument.ManyPlayersCollection<org.bukkit.entity.Player>
EntitySelectorArgument.OneEntityorg.bukkit.entity.Entity
EntitySelectorArgument.OnePlayerorg.bukkit.entity.Player
EntityTypeArgumentorg.bukkit.entity.EntityType
FloatArgumentfloat
FloatRangeArgumentdev.jorel.commandapi.wrappers.FloatRange
FunctionArgumentdev.jorel.commandapi.wrappers.FunctionWrapper[]
GreedyStringArgumentString
IntegerArgumentint
IntegerRangeArgumentdev.jorel.commandapi.wrappers.IntegerRange
ItemStackArgumentorg.bukkit.inventory.ItemStack
ItemStackPredicateArgumentjava.util.function.Predicate
<org.bukkit.inventory.ItemStack>
ListArgumentjava.util.Collection<T>
LiteralArgumentN/A
Location2DArgumentdev.jorel.commandapi.wrappers.Location2D
LocationArgumentorg.bukkit.Location
LongArgumentlong
LootTableArgumentorg.bukkit.loot.LootTable
MapArgumentjava.util.LinkedHashMap
MathOperationArgumentdev.jorel.commandapi.wrappers.MathOperation
MultiLiteralArgumentString
NamespacedKeyArgumentorg.bukkit.NamespacedKey
NBTCompoundArgument<T>The cast type changes depending on whether you're shading the CommandAPI or using the CommandAPI as a plugin:
  • Shading:
    T (implemented yourself)

  • Plugin:
    dev.jorel.commandapi.nbtapi.NBTContainer
ObjectiveArgumentorg.bukkit.scoreboard.Objective
ObjectiveCriteriaArgumentString
OfflinePlayerArgumentorg.bukkit.OfflinePlayer
ParticleArgumentdev.jorel.commandapi.wrappers.ParticleData
PlayerArgumentorg.bukkit.entity.Player
PotionEffectArgumentorg.bukkit.potion.PotionEffectType
PotionEffectArgument.NamespacedKeyorg.bukkit.NamespacedKey
RecipeArgumentThe cast type changes depending on your Minecraft version:
  • Version 1.14.4 and below:
    org.bukkit.inventory.Recipe

  • 1.15 and above:
    org.bukkit.inventory.ComplexRecipe
RotationArgumentdev.jorel.commandapi.wrappers.Rotation
ScoreboardSlotArgumentdev.jorel.commandapi.wrappers.ScoreboardSlot
ScoreHolderArgument.SingleString
ScoreHolderArgument.MultipleCollection<String>
SoundArgumentorg.bukkit.Sound
SoundArgument.NamespacedKeyorg.bukkit.NamespacedKey
StringArgumentString
TeamArgumentorg.bukkit.scoreboard.Team
TextArgumentString
TimeArgumentint
UUIDArgumentjava.util.UUID
WorldArgumentorg.bukkit.World