Skip to main content

Location Arguments

With the arguments described in this page, you can retrieve positional input from a user.

Block Position Argument​

The block position argument is used for retrieving the position of a block. It works the same way as the first argument of the /setblock <position> <block> vanilla command. In order to retrieve the BlockPosition variable from the BlockPositionResolver, we have to resolve it using the command source.

Example usage​

public static LiteralCommandNode<CommandSourceStack> blockPositionArgument() {
    return Commands.literal("blockpositionargument")
        .then(Commands.argument("arg", ArgumentTypes.blockPosition())
            .executes(ctx -> {
                final BlockPositionResolver blockPositionResolver = ctx.getArgument("arg", BlockPositionResolver.class);
                final BlockPosition blockPosition = blockPositionResolver.resolve(ctx.getSource());

                ctx.getSource().getSender().sendMessage("Put in " + blockPosition.x() + " " + blockPosition.y() + " " + blockPosition.z());
                return Command.SINGLE_SUCCESS;
            }))
        .build();
}

In-game preview​

Fine Position Argument​

The fine position argument works similarly to the block position argument, with the only difference being that it can accept decimal (precise) location input. The optional overload (ArgumentTypes.finePosition(boolean centerIntegers)), which defaults to false if not set, will center whole input, meaning 5 becomes 5.5 (5.0 would stay as 5.5 though), as that is the "middle" of a block. This only applies to X/Z. The y coordinate is untouched by this operation.

This argument returns a FinePositionResolver. You can resolve that by running FinePositionResolver#resolve(CommandSourceStack) to get the resulting FinePosition.

Example usage​

public static LiteralCommandNode<CommandSourceStack> finePositionArgument() {
    return Commands.literal("fineposition")
        .then(Commands.argument("arg", ArgumentTypes.finePosition(true))
            .executes(ctx -> {
                final FinePositionResolver resolver = ctx.getArgument("arg", FinePositionResolver.class);
                final FinePosition finePosition = resolver.resolve(ctx.getSource());

                ctx.getSource().getSender().sendRichMessage("Position: <red><x></red> <green><y></green> <blue><z></blue>",
                    Placeholder.unparsed("x", Double.toString(finePosition.x())),
                    Placeholder.unparsed("y", Double.toString(finePosition.y())),
                    Placeholder.unparsed("z", Double.toString(finePosition.z()))
                );
                return Command.SINGLE_SUCCESS;
            }))
        .build();
}

In-game preview​

World Argument​

This argument allows the user to select one of the currently loaded world. You can retrieve the result of that as a generic Bukkit World object.

Example usage​

public static LiteralCommandNode<CommandSourceStack> worldArgument() {
    return Commands.literal("teleport-to-world")
        .then(Commands.argument("world", ArgumentTypes.world())
            .executes(ctx -> {
                final World world = ctx.getArgument("world", World.class);
                
                if (ctx.getSource().getExecutor() instanceof Player player) {
                    player.teleport(world.getSpawnLocation(), PlayerTeleportEvent.TeleportCause.COMMAND);
                    ctx.getSource().getSender().sendRichMessage("Successfully teleported <player> to <aqua><world></aqua>",
                        Placeholder.component("player", player.name()),
                        Placeholder.unparsed("world", world.getName())
                    );
                }
                else {
                    ctx.getSource().getSender().sendRichMessage("<red>This command requires a player!");
                }

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

In-game preview​