Commander provides a robust system for handling command parameters with automatic type conversion and validation. This page explains the available parameter types and how to use them effectively.

Parameters in Commander are defined using the TypedParameter class, which specifies:

• The parameter name (used in help messages)
• The parameter type (from the ParameterType enum)
• Optionally, a supplier function that provides tab completion suggestions

Commander supports the following parameter types through the ParameterType enum:

// A simple string parameter
TypedParameter playerParam = new TypedParameter("player", ParameterType.STRING);

// An integer parameter
TypedParameter amountParam = new TypedParameter("amount", ParameterType.INT);

// A string parameter with tab completion suggestions
TypedParameter playerParam = new TypedParameter(
    "player",
    ParameterType.STRING,
    () -> {
        // Return a list of online player names
        return Bukkit.getOnlinePlayers().stream()
            .map(Player::getName)
            .collect(Collectors.toList());
    }
);

The STRING type represents a simple string without spaces. It's the most basic parameter type and is useful for usernames, identifiers, and other single-word inputs.

TypedParameter nameParam = new TypedParameter("name", ParameterType.STRING);

When a user enters a command, the first word after the command name will be captured as the parameter value. For example, in /mycommand john, "john" would be the value of the parameter.

The QUOTED_STRING type represents a string that can contain spaces, enclosed in double quotes. This is useful for inputs that need to include spaces, like messages or descriptions.

TypedParameter messageParam = new TypedParameter("message", ParameterType.QUOTED_STRING);

When a user enters a command, everything between the opening and closing quotes will be captured as a single parameter value. For example, in /mycommand "Hello, world!", "Hello, world!" would be the value of the parameter.

If the user doesn't provide closing quotes, Commander will display an error message.

The GREEDY_STRING type represents a string that consumes all remaining arguments. This is useful for inputs that should capture everything the user types after a certain point, like messages or commands to execute.

TypedParameter messageParam = new TypedParameter("message", ParameterType.GREEDY_STRING);

When a user enters a command, all remaining words will be captured as a single parameter value. For example, in /mycommand Hello, world!, "Hello, world!" would be the value of the parameter.

Note that GREEDY_STRING parameters should always be the last parameter in a command, as they will consume all remaining input.

The SHORT, INT, and LONG types represent integer values of different sizes. They're useful for numeric inputs like amounts, durations, or IDs.

TypedParameter amountParam = new TypedParameter("amount", ParameterType.INT);

When a user enters a command, Commander will attempt to parse the input as a number. If the parsing fails or the number is out of range for the specified type, Commander will display an error message.

The DOUBLE type represents a 64-bit floating-point number (double in Java). It's useful for precise numeric inputs, such as coordinates, percentages, or rates.

TypedParameter rateParam = new TypedParameter("rate", ParameterType.DOUBLE);

Example Input:

/command 42.75

Behavior:

• Accepts decimal numbers using a dot (.) as the decimal separator.
• Rejects non-numeric input with an error message.
• If the input exceeds the limits of double, an error is displayed.

Parsed Type: double

The FLOAT type represents a 32-bit floating-point number (float in Java). Use it for less precise numeric inputs where memory or performance efficiency matters slightly more.

TypedParameter valueParam = new TypedParameter("value", ParameterType.FLOAT);

Example Input:

/command 3.14

Behavior:

• Accepts decimal numbers using a dot (.) as the decimal separator.
• Less precise than DOUBLE.
• Rejects invalid float input with an error.

Parsed Type: float

The BOOL type represents a boolean value (boolean in Java). It's ideal for toggle or true/false input.

TypedParameter enabledParam = new TypedParameter("enabled", ParameterType.BOOL);

Example Inputs:

/command true
/command false

Behavior:

• Accepts only true or false (case-insensitive).
• Any other input triggers an error.
• Useful for flags or enabling/disabling

Commander automatically validates parameters based on their types:

• For string types, it checks that the input matches the expected format (e.g., quoted strings must have opening and closing quotes)
• For numeric types, it checks that the input is a valid number and within the range of the specified type

If validation fails, Commander will display an appropriate error message to the user.

When Commander executes a command, it passes the parsed parameters to the command executor as a List<Object>. The objects in the list will be of the appropriate Java types based on the parameter definitions.

CommandActionNode myCommand = new CommandActionNode(
    "mycommand",
    "My command description",
    "MyPlugin",
    List.of(
        new TypedParameter("player", ParameterType.STRING),
        new TypedParameter("amount", ParameterType.INT)
    ),
    (sender, args) -> {
        // Access the parsed parameters
        String playerName = (String) args.get(0);
        int amount = (int) args.get(1);
        
        // Use the parameters
        sender.sendMessage("Giving " + amount + " items to " + playerName);
    }
);

• Place required parameters before optional ones
• Place GREEDY_STRING parameters last, as they consume all remaining input

• Use clear, descriptive names for parameters
• Use consistent naming conventions
• Keep names concise but meaningful

• Provide tab completion suggestions whenever possible
• Keep suggestion lists reasonably sized
• Update suggestions dynamically when appropriate

List<TypedParameter> parameters = List.of(
    new TypedParameter("player", ParameterType.STRING, () -> {
        // Return online player names
        return Bukkit.getOnlinePlayers().stream()
            .map(Player::getName)
            .collect(Collectors.toList());
    }),
    new TypedParameter("amount", ParameterType.INT),
    new TypedParameter("reason", ParameterType.QUOTED_STRING)
);

CommandActionNode giveCommand = new CommandActionNode(
    "give",
    "Give items to a player",
    "MyPlugin",
    parameters,
    (sender, args) -> {
        String playerName = (String) args.get(0);
        int amount = (int) args.get(1);
        String reason = (String) args.get(2);
        
        sender.sendMessage("Giving " + amount + " items to " + playerName + " for: " + reason);
        // Command logic here
    }
);

List<TypedParameter> parameters = List.of(
    new TypedParameter("channel", ParameterType.STRING, () -> {
        // Return available chat channels
        return List.of("global", "local", "team", "admin");
    }),
    new TypedParameter("message", ParameterType.GREEDY_STRING)
);

CommandActionNode chatCommand = new CommandActionNode(
    "chat",
    "Send a chat message",
    "MyPlugin",
    parameters,
    (sender, args) -> {
        String channel = (String) args.get(0);
        String message = (String) args.get(1);
        
        sender.sendMessage("Sending to " + channel + ": " + message);
        // Chat logic here
    }
);

Now that you understand parameter types, check out these pages for more information:

• Tab Completion - Learn how to implement tab completion
• Advanced Usage - Discover advanced features and techniques