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
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
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
Argument Casting
To access arguments, they have to be casted to the type that the argument represents. The order of the arguments in the args[] is the same as the order in which the arguments were declared.
List<Argument<?>> arguments = new ArrayList<>();
arguments.add(new StringArgument("arg0"));
arguments.add(new PotionEffectArgument("arg1"));
arguments.add(new LocationArgument("arg2"));
new CommandAPICommand("cmd")
.withArguments(arguments)
.executes((sender, args) -> {
String stringArg = (String) args[0];
PotionEffectType potionArg = (PotionEffectType) args[1];
Location locationArg = (Location) args[2];
})
.register();
val arguments = listOf(
StringArgument("arg0"),
PotionEffectArgument("arg1"),
LocationArgument("arg2")
)
CommandAPICommand("cmd")
.withArguments(arguments)
.executes(CommandExecutor { _, args ->
val stringArg = args[0] as String
val potionArg = args[1] as PotionEffectType
val locationArg = args[2] as Location
})
.register()
The type to cast each argument (declared in the dev.jorel.commandapi.arguments package) is listed below:
| Argument class | Data type |
|---|---|
AngleArgument | float |
AdvancementArgument | org.bukkit.advancement.Advancement |
AdventureChatArgument | net.kyori.adventure.text.Component |
AdventureChatComponentArgument | net.kyori.adventure.text.Component |
AxisArgument | java.util.EnumSet<org.bukkit.Axis> |
BiomeArgument | org.bukkit.block.Biome |
BiomeArgument.NamespacedKey | org.bukkit.NamespacedKey |
BlockPredicateArgument | java.util.function.Predicate<org.bukkit.block.Block> |
BlockStateArgument | org.bukkit.block.data.BlockData |
BooleanArgument | boolean |
ChatArgument | net.md_5.bungee.api.chat.BaseComponent[] |
ChatColorArgument | org.bukkit.ChatColor |
ChatComponentArgument | net.md_5.bungee.api.chat.BaseComponent[] |
CommandArgument | dev.jorel.commandapi.wrappers.CommandResult |
CustomArgument<T, B> | T |
DoubleArgument | double |
EnchantmentArgument | org.bukkit.enchantments.Enchantment |
EntitySelectorArgument.ManyEntities | Collection<org.bukkit.entity.Entity> |
EntitySelectorArgument.ManyPlayers | Collection<org.bukkit.entity.Player> |
EntitySelectorArgument.OneEntity | org.bukkit.entity.Entity |
EntitySelectorArgument.OnePlayer | org.bukkit.entity.Player |
EntityTypeArgument | org.bukkit.entity.EntityType |
EnvironmentArgument | org.bukkit.World.Environment |
FloatArgument | float |
FloatRangeArgument | dev.jorel.commandapi.wrappers.FloatRange |
FunctionArgument | dev.jorel.commandapi.wrappers.FunctionWrapper[] |
GreedyStringArgument | String |
IntegerArgument | int |
IntegerRangeArgument | dev.jorel.commandapi.wrappers.IntegerRange |
ItemStackArgument | org.bukkit.inventory.ItemStack |
ItemStackPredicateArgument | java.util.function.Predicate<org.bukkit.inventory.ItemStack> |
ListArgument | java.util.Collection<T> |
LiteralArgument | N/A |
Location2DArgument | dev.jorel.commandapi.wrappers.Location2D |
LocationArgument | org.bukkit.Location |
LongArgument | long |
LootTableArgument | org.bukkit.loot.LootTable |
MathOperationArgument | dev.jorel.commandapi.wrappers.MathOperation |
MultiLiteralArgument | String |
NamespacedKeyArgument | org.bukkit.NamespacedKey |
NBTCompoundArgument<T> | The cast type changes depending on whether you're shading the CommandAPI or using the CommandAPI as a plugin:
|
ObjectiveArgument | String |
ObjectiveCriteriaArgument | String |
OfflinePlayerArgument | org.bukkit.OfflinePlayer |
ParticleArgument | dev.jorel.commandapi.wrappers.ParticleData |
PlayerArgument | org.bukkit.entity.Player |
PotionEffectArgument | org.bukkit.potion.PotionEffectType |
RecipeArgument | The cast type changes depending on your Minecraft version:
|
RotationArgument | dev.jorel.commandapi.wrappers.Rotation |
ScoreboardSlotArgument | dev.jorel.commandapi.wrappers.ScoreboardSlot |
ScoreHolderArgument.Single | String |
ScoreHolderArgument.Multiple | Collection<String> |
SoundArgument | org.bukkit.Sound |
SoundArgument.NamespacedKey | org.bukkit.NamespacedKey |
StringArgument | String |
TeamArgument | String |
TextArgument | String |
TimeArgument | int |
UUIDArgument | java.util.UUID |
WorldArgument | org.bukkit.World |
Optional/Different Arguments
Sometimes, you want to register a command that has a different effect whether arguments are included or not. For example, take the /kill command. If you run /kill on its own, it will kill the command sender. If however you run /kill <target>, it will kill the target. In other words, we have the following command command syntax:
/kill - Kills yourself
/kill <target> - Kills a target player
As shown by the command syntax, we need to register two commands.
Example - /kill command with two separate arguments
For example, say we're registering a command /kill:
/kill - Kills yourself
/kill <target> - Kills a target player
We first register the first /kill command as normal:
new CommandAPICommand("kill")
.executesPlayer((player, args) -> {
player.setHealth(0);
})
.register();
CommandAPICommand("kill")
.executesPlayer(PlayerCommandExecutor { player, _ ->
player.setHealth(0.0)
})
.register()
Now we declare our command with arguments for our second command. Then, we can register our second command /kill <target> as usual:
// Register our second /kill <target> command
new CommandAPICommand("kill")
.withArguments(new PlayerArgument("target"))
.executesPlayer((player, args) -> {
((Player) args[0]).setHealth(0);
})
.register();
// Register our second /kill <target> command
CommandAPICommand("kill")
.withArguments(PlayerArgument("target"))
.executesPlayer(PlayerCommandExecutor { _, args ->
(args[0] as Player).setHealth(0.0)
})
.register()
This gives us the ability to run both /kill and /kill <target> with the same command name "kill", but have different results based on the arguments used.
In this example, we use the simpler, inline .withArguments(Argument... arguments) method to register our argument. There is no difference to using this method as opposed to explicitly declaring a list and using .withArguments(List<Argument> arguments), so feel free to use whichever method you want!