Location arguments
In the CommandAPI, there are two arguments used to represent location. The LocationArgument
argument, which represents a 3D location \( (x, y, z) \) and the Location2DArgument
, which represents 2D location \( (x, z) \).
Location (3D space)
The LocationArgument
class is used to specify a location in the command sender's current world, returning a Bukkit Location
object. It allows the user to enter three numbers as coordinates, or use relative coordinates (i.e. the ~
and ^
operators).
The LocationArgument
constructor requires a LocationType
, which specifies the type of location that is accepted by the command. The LocationType
enum consists of two values:
LocationType.BLOCK_POSITION
BLOCK_POSITION
refers to integer block coordinates. When in-game as a player, the suggested location is the coordinates of block you are looking at when you type the command.
LocationType.PRECISE_POSITION
PRECISE_PRECISION
uses exact coordinates, using the double
primitive type. When in-game as a player, the suggested location is the exact coordinates of where your cursor is pointing at when you type the command.
If no LocationType
is provided, the LocationArgument
will use PRECISE_POSITION
by default.
The LocationArgument
constructor can also accept a boolean centerPosition
. If set to true
, when using LocationType.PRECISE_POSITION
, if an integer is provided in the value, it will add 0.5 to the x and z coordinates to center the position within a block. If set to false
, the integer value will be provided as is.
If no centerPosition
parameter is provided, the LocationArgument
will use centerPosition = true
by default.
Example - LocationArgument precise position centering
Say you use the following constructor, which sets centerPosition
to true
:
new LocationArgument("location", LocationType.PRECISE_POSITION, true);
LocationArgument("location", LocationType.PRECISE_POSITION, true)
Integer positions are centered
Let's also say you use the following location using this location argument in a command:
10 20 30
The resulting location will be the following, which centers the position of the x and z coordinates. This does not change the y coordinate:
10.5 20 30.5
Non-integer positions remain as normal
If you use the following location using this location argument in a command:
10.2 20.2 30.2
The resulting location will be the following, which does not change the x and z coordinates, because the positions are not integers:
10.2 20.2 30.2
Say you use the following constructor, which sets centerPosition
to false
:
new LocationArgument("location", LocationType.PRECISE_POSITION, false);
LocationArgument("location", LocationType.PRECISE_POSITION, false)
Integer positions are not centered
Let's also say you use the following location using this location argument in a command:
10 20 30
The resulting location will be the following, which does not modify the position of the x and z coordinates:
10 20 30
Example - Break block using coordinates
We can declare a simple command to break a block:
/break <location>
Simply put, given the coordinates provided to the command, "break" the block by setting it's type to Material.AIR
. For this example, we're referring to block specific coordinates, so we want to use LocationType.BLOCK_POSITION
:
new CommandAPICommand("break")
// We want to target blocks in particular, so use BLOCK_POSITION
.withArguments(new LocationArgument("block", LocationType.BLOCK_POSITION))
.executesPlayer((player, args) -> {
Location location = (Location) args.get("block");
location.getBlock().setType(Material.AIR);
})
.register();
CommandAPICommand("break")
// We want to target blocks in particular, so use BLOCK_POSITION
.withArguments(LocationArgument("block", LocationType.BLOCK_POSITION))
.executesPlayer(PlayerCommandExecutor { _, args ->
(args["block"] as Location).block.type = Material.AIR
})
.register()
commandAPICommand("break") {
// We want to target blocks in particular, so use BLOCK_POSITION
locationArgument("block", LocationType.BLOCK_POSITION)
playerExecutor { _, args ->
(args["block"] as Location).block.type = Material.AIR
}
}
Location (2D space)
The Location2DArgument
is pretty much identical in use to the LocationArgument
for 3D coordinates, except instead of returning a Location
object, it instead returns a Location2D
object that extends Location
(thus, being compatible anywhere you would normally be able to use Location
).