Primitive arguments

Primitive arguments are arguments that represent Java primitive types, such as int, float, double, boolean and long. These arguments are defined in their respective classes:

Primitive typeCommandAPI class
intIntegerArgument
floatFloatArgument
doubleDoubleArgument
longLongArgument
booleanBooleanArgument

These arguments simply cast to their primitive type and don't need any extra work.

Boolean arguments

A boolean argument showing the suggestions 'false' and 'true'

The BooleanArgument class represents the Boolean values true and false.

Example - Config editing plugin

Say we want to create a plugin that lets you edit its own config.yml file using a command. To do this, let's create a command with the following syntax:

/editconfig <config-key> <value>

We first retrieve the keys from the configuration file using the typical Bukkit API. We construct our List to hold our arguments, with the first parameter being a String key (in the form of a TextArgument, overridden with an array of suggestions). Finally, we register our command and update the config, ensuring that we cast the BooleanArgument to boolean:

// Load keys from config file
String[] configKeys = getConfig().getKeys(true).toArray(new String[0]);

// Register our command
new CommandAPICommand("editconfig")
    .withArguments(new TextArgument("config-key").replaceSuggestions(ArgumentSuggestions.strings(info -> configKeys)))
    .withArguments(new BooleanArgument("value"))
    .executes((sender, args) -> {
        // Update the config with the boolean argument
        getConfig().set((String) args.get("config-key"), (boolean) args.get("value"));
    })
    .register();

// Load keys from config file
val configKeys: Array<String> = config.getKeys(true).toTypedArray()

// Register our command
CommandAPICommand("editconfig")
    .withArguments(TextArgument("config-key").replaceSuggestions(ArgumentSuggestions.strings { _ -> configKeys }))
    .withArguments(BooleanArgument("value"))
    .executes(CommandExecutor { _, args ->
        // Update the config with the boolean argument
        config.set(args["config-key"] as String, args["value"] as Boolean)
    })
    .register()

// Load keys from config file
val configKeys: Array<String> = getConfig().getKeys(true).toTypedArray()

// Register our command
commandAPICommand("editconfig") {
    argument(TextArgument("config-key").replaceSuggestions(ArgumentSuggestions.strings { configKeys }))
    booleanArgument("value")
    anyExecutor { _, args ->
        // Update the config with the boolean argument
        getConfig().set(args["config-key"] as String, args["value"] as Boolean)
    }
}

Numerical arguments

Numbers are represented using the designated number classes:

ClassDescription
IntegerArgumentWhole numbers between Integer.MIN_VALUE and Integer.MAX_VALUE
LongArgumentWhole numbers between Long.MIN_VALUE and Long.MAX_VALUE
DoubleArgumentDouble precision floating point numbers
FloatArgumentSingle precision floating point numbers

Each numerical argument can have ranges applied to them, which restricts the user to only entering numbers from within a certain range. This is done using the constructor, and the range specified:

ConstructorDescription
new IntegerArgument()Any range
new IntegerArgument(min)Values greater than or equal to min
new IntegerArgument(min, max)Values greater than or equal to min and less than or equal to max

Each range is inclusive, so it includes the number given to it. If the minimum value provided is larger than the maximum value, an InvalidRangeException is thrown.