> For the complete documentation index, see [llms.txt](https://medieval-kingdoms.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://medieval-kingdoms.gitbook.io/docs/implementation/markdown.md).

# Commands

## Introduction

The command framework builds on top of Bukkits native command system, extending it with additional features for structure and flexibility:

* **Annotation-based labels** for defining command names and metadata
* **Registrable integration** for seamless lifecycle management within the plugin system
* **Built-in subcommand support** for hierarchical command structures
* **Permission and usage utilities** for consistent validation and feedback
* **Specialized command providers** (`PlayerCommandProvider`, `ConsoleCommandProvider`, etc.) for type-safe sender handling

## Definition

To define a new command:

1. Annotate the class with `@CommandAnnotation`
2. Implement the `Command` interface or extend `AbstractCommand`
3. Provide your execution logic in `onCommand`

```java
@CommandAnnotation(label = "hello")
public class HelloCommand extends AbstractCommand {

    @Override
    public void onCommand(CommandSender sender, String[] args) {
        sender.sendMessage("Hello from MedievalKingdoms!");
    }
}
```

## Annotation

`@CommandAnnotation` is a runtime annotation used to declare **metadata** for commands. It provides the framework with the **command label** (the root name of the command).

## Permission and Usage

The `Command` interface supports optional **permission** and **usage** messages via `Parseable`. 

```java
@Override
public Parseable getPermission() {
    return () -> "You do not have permission to run this command.";
}

@Override
public Parseable getUsage() {
    return label -> "Usage: /hello " + label;
}
```

## Sub Commands

To add subcommands, implement `SubCommand<T>` where `T` is a `CommandSender` type (`Player`, `ConsoleCommandSender`, or `CommandSender`).

Example of a sub command:

```java
@CommandAnnotation(label = "player")
public class GreetPlayerSubCommand implements SubCommand<Player> {

    @Override
    public void onCommand(Player player, String[] args) {
        player.sendMessage("Hello, " + player + "!");
    }
}
```

Adding the subcommand to the base command:

```java
@CommandAnnotation(label = "greet", ignoreSubCommands = false)
public class GreetCommand extends AbstractCommand {

    @Override
    public void onCommand(CommandSender sender, String[] args) {
        sender.sendMessage("Available subcommands: greet <player>");
    }
    
    @Override
    public void registerSubCommands(MedievalPlugin plugin) {
        subCommands.add(new GreetPlayerSubCommand());
    }
}
```

## Tab Completion

`AbstactCommand` and `SubCommand` both support tab completion. Remember that sub commands by default are auto completed in `AbstractCommand`&#x20;

```java
@Override
public List<String> onTabComplete(CommandSender sender, String[] args) {
    if (args.length == 1) {
        return List.of("world", "server", "player");
    }
    return List.of();
}
```