Command Examples

Important

The Wiki has been moved! You can now find it here: https://docs.despical.dev/command-framework/

This particulare page can be found here: https://docs.despical.dev/command-framework/examples/

Table of contents

• Registering Commands
• Creating Command
• Creating Sub Command
• Creating Tab Completions
• Creating commands Without Arguments
• Creating Commands with Cooldowns
• Example Usage

Registering Commands

Create an CommandFramework object using the constructor then register the commands using CommandFramework#registerCommands method, then framework will register all the methods that have Command or Completer annotations and CommandArguments parameter as a command in the class.

public class ExampleClass extends JavaPlugin {

    private CommandFramework commandFramework;

    @Override
    public void onEnable() {
        // Initialize the framework with your plugin instance
        commandFramework = new CommandFramework(this);

        // Register the class containing your command methods.
        // There is no need to define these commands in your plugin.yml.
        commandFramework.registerCommands(this);
    }
}

Creating Command

Before creating commands, you must create a method body, then annotate the Command and don't forget to add CommandArguments as a parameter to your method. If you don't know what are the attributes that you can change, take a look at Commands page.

@Command(
    name = "example",
    aliases = {"firstAlias", "secondAlias"},
    permission = "example.permission",
    desc = "Sends an example message to sender",
    usage = "/example",
    min = 1,
    max = 5,
    onlyOp = false, // If true, ignores permission checks
    async = false,  // Set to true for async execution (ensure thread safety)
    senderType = Command.SenderType.CONSOLE
)
public void exampleCommand(CommandArguments arguments) {
    arguments.sendMessage("This is how you can create an example command using the framework.");
}

Creating Sub Command

Sub commands are separated by dots. For example if command is "one.two.three" then "one" will be the first part of the command, "two" is the second and "three" is the third. So the command will be "one two three <other arguments if there are>" and the command arguments will be splitted after sub commands like if the command is "one two three four five" then the command arguments will be [four, five].

@Command(
    name = "example.subcommand"
)
public void exampleSubCommandMethod(CommandArguments arguments) {
    // This method handles: /example subcommand
    arguments.sendMessage("You executed the sub-command!");
}

Creating Tab Completions

Before creating a tab completion, create a method body with List<String> return type or any other implementation of it but List is recommended and do not use the raw type. Then annotate the Completer and don't forget to add CommandArguments as a parameter to your method. Tab completions also support sub commands as the normal commands too. For example command's name can be "command.subcommand" and command will be "command subcommand <completions>"

@Completer(
    name = "example",
    aliases = {"firstAlias", "secondAlias"}
)
public List<String> exampleCommandCompletion(CommandArguments arguments) {
    // Returns suggestions for the target command
    return Arrays.asList("first", "second", "third");
}

Creating Commands Without Arguments

@Command(
    name = "nocommandargs"
)
public void noCommandArgsTest() {
    Logger.getLogger(this.getClass().getSimpleName()).info("This command is running without any parameters.");
}

Creating Commands With Cooldowns

public class ExampleClass extends JavaPlugin {

    @Override
    public void onEnable() {
        CommandFramework commandFramework = new CommandFramework(this);

        // 1. Register a simple custom parameter for "String"
        commandFramework.addCustomParameter(String.class, CommandArguments::getFirst);

        // 2. Register a complex custom parameter for "secondAsInt"
        commandFramework.addCustomParameter("secondAsInt", arguments -> arguments.getLength() > 1 ? arguments.getArgumentAsInt(1) : null);

        commandFramework.registerCommands(this);
    }

    // --- Standard Command with Cooldown ---
    @Command(
        name = "example",
        fallbackPrefix = "prefix",
        aliases = {"firstAlias", "secondAlias"},
        permission = "example.permission",
        desc = "Sends an example message to sender",
        usage = "/example",
        min = 1,
        max = 5,
        senderType = Command.SenderType.CONSOLE
    )
    @Cooldown(
        cooldown = 10,
        timeUnit = TimeUnit.SECONDS,
        bypassPerm = "command.cooldownBypass",
        overrideConsole = true // Console is also affected by cooldown
    )
    public void exampleCommand(CommandArguments arguments) {
        arguments.sendMessage("This is how you can create an example command using the framework.");
    }

    // --- Command without Parameters ---
    @Command(
        name = "noParams"
    )
    public void commandWithoutParameters() {
        Bukkit.getConsoleSender().sendMessage("This command is running without any parameters.");
    }

    // --- Custom Parameter Injection (Implicit) ---
    // Uses the "String" custom parameter registered in onEnable
    @Command(
        name = "customParamWithoutAnnotations",
        min = 1
    )
    public void customParamCommand(String firstParameter, CommandArguments arguments) {
        arguments.sendMessage("First parameter is " + firstParameter);
    }

    // --- Custom Parameter Injection (Explicit) ---
    // Uses @Param and @Default annotations
    @Command(
        name = "customParams",
        min = 1
    )
    public void customParamsCommand(
        CommandArguments arguments,
        @Param("secondAsInt")
        @Default("50")
        int secondArg
    ) {
        // If the argument is missing, it defaults to 50.
        arguments.sendMessage("Second argument as integer is " + secondArg);
    }

    // --- Command with Confirmation ---
    @Command(
        name = "confirmationTest"
    )
    @Confirmation(
        message = "Are you sure? Please execute the command again to confirm.",
        expireAfter = 10,
        bypassPerm = "confirmation.bypass",
        timeUnit = TimeUnit.SECONDS,
        overrideConsole = true
    )
    public void confirmationCommand(CommandArguments arguments) {
        arguments.sendMessage("Confirmation successful.");
    }

    // --- Tab Completer ---
    @Completer(
        name = "example",
        aliases = {"firstAlias", "secondAlias"}
    )
    public List<String> exampleCommandCompletion() {
        return Arrays.asList("first", "second", "third");
    }

    @Completer(
        name = "example",
        permission = "plugin.tabcompleter"
    )
    public List<String> onTabComplete(CommandArguments arguments, CompleterHelper helper) {
        int index = arguments.getLength() - 1;

        return switch (index) {
            case 0 -> helper.copyMatches(0, commands);
            case 1 -> switch (arguments.getFirst()) {
                case "delete", "edit", "join" -> helper.copyMatches(1, List.of("arena1", "arena2", "arena3"));
                case null, default -> helper.empty();
            };

            default -> helper.empty();
        };
    }
}