Skip to main content

Bukkit Arguments

The arguments described in this section return objects oftentime used in Bukkit API. They don't explicitly require to be from the org.bukkit package. An example for a non-bukkit object described here is the UUID Argument.

Block State Argument​

The block state argument is a very useful argument for getting use input on an exact block type and its data. It is particularly used for commands that modify blocks in some way, which requires precise input.

Example usage​

public static LiteralCommandNode<CommandSourceStack> blockStateArgument() {
    return Commands.literal("blockstateargument")
        .then(Commands.argument("arg", ArgumentTypes.blockState())
            .executes(ctx -> {
                final BlockState blockState = ctx.getArgument("arg", BlockState.class);
                
                ctx.getSource().getSender().sendMessage("You specified a " + blockState.getType() + "!");
                return Command.SINGLE_SUCCESS;
            }))
        .build();
}

In-game preview​

ItemStack Argument​

The item stack argument is a way to retrieve an ItemStack following the same argument format as the vanilla /give <player> <item> [<amount>] command as its second argument. The user may also define components to further customize the ItemStack. If you only require a material, you should instead check out the Registry Arguments (WIP).

Example usage​

public static LiteralCommandNode<CommandSourceStack> itemStackArgument() {
    return Commands.literal("itemstack")
        .then(Commands.argument("stack", ArgumentTypes.itemStack())
            .executes(ctx -> {
                final ItemStack itemStack = ctx.getArgument("stack", ItemStack.class);

                if (ctx.getSource().getExecutor() instanceof Player player) {
                    player.getInventory().addItem(itemStack);
                    ctx.getSource().getSender().sendRichMessage("<green>Successfully gave <player> a <item>",
                        Placeholder.component("player", player.name()),
                        Placeholder.component("item", Component.translatable(itemStack.translationKey()))
                    );
                }
                else {
                    ctx.getSource().getSender().sendRichMessage("<red>This argument requires a player!");
                }

                return Command.SINGLE_SUCCESS;
            }))
        .build();
}

In-game preview​

Bukkit NamespacedKey Argument​

Similar to the Key argument, this argument allows the user to provide any artificial (namespaced) key. The difference is that the return value of this argument is instead org.bukkit.NamespacedKey, which makes it particularly useful when dealing with Bukkit API.

Example usage​

public static LiteralCommandNode<CommandSourceStack> namespacedKeyArgument() {
    return Commands.literal("namespacedkey")
        .then(Commands.argument("key", ArgumentTypes.namespacedKey())
            .executes(ctx -> {
                final NamespacedKey key = ctx.getArgument("key", NamespacedKey.class);

                ctx.getSource().getSender().sendRichMessage("You put in <aqua><key></aqua>!",
                    Placeholder.unparsed("key", key.toString())
                );
                return Command.SINGLE_SUCCESS;
            }))
        .build();
}

In-game preview​

Time Argument​

The time argument allows the user to define a time frame, similar to the vanilla /time <set|time> <time> time argument. The user has 4 possible ways of inputting time:

  • Just as a number: This resolves to as usual ticks (/timearg 1 --> 1 tick)
  • With a t suffix: This also resolves to ticks (/timearg 1t --> 1 tick)
  • With a s suffix: This resolves as irl seconds, meaning multiplying the first number by 20. (/timearg 1s --> 20 ticks)
  • With a d suffix. This resolves as in-game days, meaning multiplying the first number by 24000. (/timearg 1d --> 24000 ticks)

If you choose to use this argument, it is advised to explain to the users what these suffixes mean, as here irl time (s suffix) is mixed with in-game time (t and d suffix).

The ArgumentType.time() method has one additional overload: ArgumentType.time(float mintime). This allows to set the minimum required amount of time. By default, this value is set to 0.

Example usage​

public static LiteralCommandNode<CommandSourceStack> timeArgument() {
    return Commands.literal("timearg")
        .then(Commands.argument("time", ArgumentTypes.time())
            .executes(ctx -> {
                final int timeInTicks = ctx.getArgument("time", int.class);

                if (ctx.getSource().getExecutor() instanceof Player player) {
                    player.getWorld().setFullTime(player.getWorld().getFullTime() + timeInTicks);
                    player.sendRichMessage("Moved time forward by " + timeInTicks + " ticks!");
                }
                else {
                    ctx.getSource().getSender().sendMessage("This argument requires a player!");
                }

                return Command.SINGLE_SUCCESS;
            })
        ).build();
}

In-game preview​

UUID Argument​

The uuid argument allows the user to input a valid uuid. You can retrieve that value as a UUID object, which is used in various places, like Bukkit.getOfflinePlayer(UUID). This argument is not very user-friendly, which is why it is suggested to only use this as a moderation or debug argument. For user input regarding offline player retrieval, the player profiles argument (WIP) is preferred, as it allows by-name lookup.

Example usage - Lookup command​

public static LiteralCommandNode<CommandSourceStack> uuidArgument() {
    return Commands.literal("uuid-lookup")
        .then(Commands.argument("uuid", ArgumentTypes.uuid())
            .executes(ctx -> {
                final UUID uuid = ctx.getArgument("uuid", UUID.class);
                final OfflinePlayer result = Bukkit.getOfflinePlayer(uuid);

                ctx.getSource().getSender().sendRichMessage("Has <aqua><uuid></aqua> played before: <result>",
                    Placeholder.unparsed("uuid", uuid.toString()),
                    Placeholder.parsed("result", result.hasPlayedBefore() ? "<green>true</green>" : "<red>false</red>")
                );

                return Command.SINGLE_SUCCESS;
            })
        ).build();
}

In-game preview​