Commands - litjisz/Astra GitHub Wiki

Commands

The Astra command system provides a streamlined way to create and manage commands in your plugin. It handles registration, permissions, tab completion, and more.

Creating Commands

Basic Command Structure

To create a command, extend the CommandBase class:

import lol.jisz.astra.command.CommandBase;
import org.bukkit.command.CommandSender;

import java.util.Arrays;
import java.util.List;

public class HelloCommand extends CommandBase {

    public HelloCommand() {
        // Parameters: command name, permission, player-only flag, aliases
        super("hello", "myplugin.command.hello", false, Arrays.asList("hi", "greet"));
    }

    @Override
    public boolean execute(CommandSender sender, String label, String[] args) {
        sender.sendMessage("Hello, " + sender.getName() + "!");
        return true;
    }
}

Command Parameters

The CommandBase constructor accepts these parameters:

public CommandBase(String name, String permission, boolean playerOnly, List<String> aliases)
  • name: The primary name of the command
  • permission: The permission required to use the command (can be null)
  • playerOnly: Whether the command can only be used by players
  • aliases: Alternative names for the command (can be null)

Tab Completion

Implement tab completion by overriding the onTabComplete method:

@Override
public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args) {
    List<String> completions = new ArrayList<>();
    
    if (args.length == 1) {
        String[] options = {"help", "info", "status"};
        for (String option : options) {
            if (option.toLowerCase().startsWith(args[0].toLowerCase())) {
                completions.add(option);
            }
        }
    } else if (args.length == 2 && args[0].equalsIgnoreCase("info")) {
        String[] subOptions = {"basic", "detailed", "full"};
        for (String option : subOptions) {
            if (option.toLowerCase().startsWith(args[1].toLowerCase())) {
                completions.add(option);
            }
        }
    }
    
    return completions;
}

Registering Commands

Manual Registration

Register commands in your main plugin class or in a module:

// In your main plugin class
@Override
protected void onInitialize() {
    getCommandManager().register(new HelloCommand());
    getCommandManager().register(new StatsCommand());
}

// Or in a module
@Override
public void onEnable() {
    getPlugin().getCommandManager().register(new ModuleSpecificCommand());
}

Automatic Registration with Annotations

You can use the @AutoRegisterCommand annotation to automatically register commands:

import lol.jisz.astra.command.AutoRegisterCommand;
import lol.jisz.astra.command.CommandBase;

@AutoRegisterCommand
public class AutoHelloCommand extends CommandBase {
    // Command implementation
}

Command Permissions

Basic Permission Handling

The CommandBase class automatically handles permission checking. If a user doesn't have the required permission, they'll receive a permission denied message.

// Command with permission requirement
public class AdminCommand extends CommandBase {
    public AdminCommand() {
        super("admin", "myplugin.admin", false, null);
    }
    
    @Override
    public boolean execute(CommandSender sender, String label, String[] args) {
        // This code only runs if the sender has the permission
        sender.sendMessage("Admin command executed!");
        return true;
    }
}

Subcommands

Implementing Subcommands

You can implement subcommands by parsing the arguments:

public class UserCommand extends CommandBase {
    public UserCommand() {
        super("user", "myplugin.user", false, Arrays.asList("u"));
    }
    
    @Override
    public boolean execute(CommandSender sender, String label, String[] args) {
        if (args.length == 0) {
            sendUsage(sender);
            return true;
        }
        
        String subcommand = args[0].toLowerCase();
        
        switch (subcommand) {
            case "add":
                return handleAddUser(sender, args);
            case "remove":
                return handleRemoveUser(sender, args);
            case "list":
                return handleListUsers(sender);
            default:
                sendUsage(sender);
                return true;
        }
    }
    
    private boolean handleAddUser(CommandSender sender, String[] args) {
        if (args.length < 2) {
            sender.sendMessage("§cUsage: /" + getName() + " add <username>");
            return true;
        }
        
        String username = args[1];
        sender.sendMessage("§aAdded user: " + username);
        return true;
    }
    
    private boolean handleRemoveUser(CommandSender sender, String[] args) {
        if (args.length < 2) {
            sender.sendMessage("§cUsage: /" + getName() + " remove <username>");
            return true;
        }
        
        String username = args[1];
        sender.sendMessage("§aRemoved user: " + username);
        return true;
    }
    
    private boolean handleListUsers(CommandSender sender) {
        sender.sendMessage("§aUser list:");
        sender.sendMessage("§7- User1");
        sender.sendMessage("§7- User2");
        sender.sendMessage("§7- User3");
        return true;
    }
    
    private void sendUsage(CommandSender sender) {
        sender.sendMessage("§cUsage:");
        sender.sendMessage("§c/" + getName() + " add <username> - Add a user");
        sender.sendMessage("§c/" + getName() + " remove <username> - Remove a user");
        sender.sendMessage("§c/" + getName() + " list - List all users");
    }
    
    @Override
    public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args) {
        List<String> completions = new ArrayList<>();
        
        if (args.length == 1) {
            String[] subcommands = {"add", "remove", "list"};
            for (String subcommand : subcommands) {
                if (subcommand.toLowerCase().startsWith(args[0].toLowerCase())) {
                    completions.add(subcommand);
                }
            }
        } else if (args.length == 2) {
            if (args[0].equalsIgnoreCase("add")) {
                // Suggest online players for the add command
                for (Player player : Bukkit.getOnlinePlayers()) {
                    if (player.getName().toLowerCase().startsWith(args[1].toLowerCase())) {
                        completions.add(player.getName());
                    }
                }
            } else if (args[0].equalsIgnoreCase("remove")) {
                // Suggest existing users for the remove command
                String[] existingUsers = {"User1", "User2", "User3"};
                for (String user : existingUsers) {
                    if (user.toLowerCase().startsWith(args[1].toLowerCase())) {
                        completions.add(user);
                    }
                }
            }
        }
        
        return completions;
    }
}
⚠️ **GitHub.com Fallback** ⚠️