Command Flags

Command flags are useful for specifying extra parameters to be used for the processing of a command that doesn’t belong as a command argument.

To create a flag, we first need a builder for flags. We can simply use the GenericArguments#flags() method provided by GenericArguments to obtain the builder we need. From there, we can specify what type of flag we would like to create. Note that flags are specified as an argument.

import org.spongepowered.api.command.args.GenericArguments;
import org.spongepowered.api.command.spec.CommandSpec;

CommandSpec myCommand = CommandSpec.builder()
    .executor(new MyCommand())
    .arguments(GenericArguments.flags().flag("s").buildWith(GenericArguments.none()))
    .build();

This will create a command flag, so that when the player performs /our-command -s, the flag for s will be true. Note that building with GenericArguments#none() will prevent the command from having any arguments. If you wish for the command to have arguments and flags, you will need to specify your arguments within the CommandFlags.Builder#buildWith(CommandElement) method.

Now that we have specified that our command may be run with the flag, we can now get the value of the flag. For a simple boolean flag like the one we have specified above, we can simply just check if it exists. In the example below, we are checking if the CommandContext for the command has a value for s.

import org.spongepowered.api.text.Text;

if (args.hasAny("s")) {
    src.sendMessage(Text.of("The command flag s was specified!"));
}

Permission Flags

Our flags so far are great, but what if we wanted to have it so that a player needs a permission to use a flag? We can instead use the CommandFlags.Builder#permissionFlag(String, String…) method on our flag builder. This will require the player to have a specific permission to run the command with the flag. An example of this is below:

CommandSpec myCommand = CommandSpec.builder()
        .executor(new MyCommand())
        .arguments(GenericArguments.flags().permissionFlag("myplugin.command.flag",
            "s").buildWith(GenericArguments.none()))
        .build();

If a player does not have the permission myplugin.command.flag, then they will not be allowed to execute our command with the command flag s.

Value Flags

Booleans can be great, but what if we wanted flags for things such as strings or integers? This is where value flags come into play. We simply need to use the CommandFlags.Builder#valueFlag(CommandElement, String…) method on our flag builder. Using the valueFlag() method, we can specify the type of flag we want to create, such as an integer or string. Creating an integer value flag can be done like so:

CommandSpec myCommand = CommandSpec.builder()
        .executor(new MyCommand())
        .arguments(GenericArguments.flags().valueFlag(GenericArguments
                .integer(Text.of("value")), "s").buildWith(GenericArguments.none()))
        .build();

You may replace GenericArguments#integer(Text) with any other flag type you would like to specify, such as GenericArguments#string(Text).

Now to retrieve the flag value from our command, we can simply treat it like any other command argument. We simply need to check if it exists before retrieving it:

import java.util.Optional;

Optional<Integer> optional = args.<Integer>getOne("value");
if (optional.isPresent()) {
    int value = optional.get().intValue();
} else {
    src.sendMessage(Text.of("The value flag was not specified."));
}

Long Flags

As an alternative to short flags like the ones we have been using above, we can also use long flags. Using a long flag, you can specify a value along with the flag using equals (=) in the command. To create a long flag, simply prefix your normal flag with a dash -, like so:

CommandSpec myCommand = CommandSpec.builder()
        .executor(new MyCommand())
        .arguments(GenericArguments.flags().flag("-myflag")
            .buildWith(GenericArguments.none()))
        .build();

We can retrieve the value that was specified with our flag similarly to value flags:

Optional<String> optional = args.<String>getOne("myflag");
if (optional.isPresent()) {
    String value = optional.get();
}

So if a user runs /our-command --myflag=Flag_Value, the Flag_Value will be stored in the string value.

Unknown Flag Behavior

Now what if we didn’t specify a specific flag to go along with our command, but still wanted to accept unknown flags? We can set the unknown flag behavior of our command to achieve this:

import org.spongepowered.api.command.args.CommandFlags;

CommandSpec myCommand = CommandSpec.builder()
            .executor(new MyCommand())
            .arguments(GenericArguments.flags()
                    .setUnknownShortFlagBehavior(
                        CommandFlags.UnknownFlagBehavior.ACCEPT_VALUE)
                    .buildWith(GenericArguments.none()))
            .build();

Using this, we can specify that any short flag with a specified value will be accepted. Without this, attempting to use an unknown flag will throw an exception. Some of the possible unknown flag behaviors are ERROR, ACCEPT_NONVALUE, ACCEPT_VALUE, and IGNORE. Note that the default behavior for unknown flags is ERROR.