LiteCommands Framework

LiteCommands is an annotation-based command framework supporting multiple platforms (Velocity, Bukkit, Paper, BungeeCord, Minestom, Sponge, Fabric, JDA, TelegramBots).

Key features include:

• Argument Types: Supports basic types (int, double, Duration, LocalDateTime, Location), collection types (List, Set, TreeSet, Queue, arrays), and specialized annotations like @Quoted for quoted input.
• Argument Modifiers: @Arg, @OptionalArg, @Flag, @Join (joins remaining arguments into a string), and @Literal.
• Context Providers: Use annotations like @Sender Player or @Context World to inject environment data.
• Asynchronous Support: Use the @Async annotation for asynchronous command execution and parsing.
• Extensibility: Supports custom validators, programmatic API for dynamic commands, and extensions for Jakarta EE, ChatGPT, and Adventure Kyori.

To use LiteCommands, you must first add the Panda repository to your build configuration and then add the appropriate platform-specific artifact as a dependency.

Important: You must add the -parameters flag to your Java compiler to enable all LiteCommands features (such as parameter name reflection).

### Gradle (Kotlin DSL)

```kts
// Add Panda Repository
maven("https://repo.panda-lang.org/releases")

// Add LiteCommands dependency
// Replace {artifact} with your platform artifact (e.g., litecommands-bukkit)
implementation("dev.rollczi:{artifact}:3.11.0")

Maven

<!-- Add Panda Repository -->
<repository>
    <id>panda-repository</id>
    <url>https://repo.panda-lang.org/releases</url>
</repository>

<!-- Add LiteCommands dependency -->
<!-- Replace {artifact} with your platform artifact (e.g., litecommands-bukkit) -->
<dependency>
    <groupId>dev.rollczi</groupId>
    <artifactId>{artifact}</artifactId>
    <version>3.11.0</version>
</dependency>

The CommandExecuteService follows a specific lifecycle that allows developers to intercept and modify execution via events. The following events are published during the process:

1. CommandExecutorNotFoundEvent: Published if no suitable executor is found for the provided CommandRoute.
2. CommandExecutorFoundEvent: Published after an executor is found and its arguments are successfully matched via the RequirementMatchService.
3. CommandPreExecutionEvent: Published after matching is successful but before the command is actually executed. This event can be used to cancel execution.
4. CommandPostExecutionEvent: Published after the command has finished executing. This event allows for post-processing the CommandExecuteResult.

If any of these events are cancelled (e.g., via matchEvent.isCancelled() or executionEvent.isCancelled()), the service returns a failed CommandExecuteResult with the corresponding cancel reason.

The AdventurePlatformAudienceProvider is used to map command senders to Kyori Adventure Audience objects within a Bukkit environment. It determines the correct audience based on the Invocation and the PlatformSender's Identifier.

Resolution logic follows this priority:

1. Direct Audience: If the command sender is already an instance of net.kyori.adventure.audience.Audience, it is returned directly.
2. Console: If the PlatformSender identifier is Identifier.CONSOLE, it returns the audience provided by audienceProvider.console().
3. Player: If the identifier contains a UUID, it returns the audience provided by audienceProvider.player(UUID).
4. Raw Text: If the PlatformSender implements PlatformReceiver, it wraps the sender in a RawTextAudience.

If none of these conditions are met, it throws an IllegalArgumentException indicating an unsupported command sender type.

The CommandNode<SENDER> interface represents any node within the command tree structure. It serves as a base component that can be part of a command hierarchy. Every CommandNode implements MetaHolder, allowing it to hold metadata.

Key characteristics:

• Generics: It is parameterized by SENDER, representing the type of the object that triggers the command (e.g., a player in a game engine or a user in a shell).
• Hierarchy: Each node can access its parent via getParent(), which returns a CommandRoute<SENDER>.
• Metadata: Through the parentMeta() default method, a node can access the metadata of its parent node in the tree.

/**
 * CommandNode is an any node of the command tree.
 * @see CommandRoute
 * @see dev.rollczi.litecommands.command.executor.CommandExecutor
 */
public interface CommandNode<SENDER> extends MetaHolder {
    CommandRoute<SENDER> getParent();

    @Override
    @Nullable
    default MetaHolder parentMeta() {
        return getParent();
    }
}

Commands in LiteCommands can be nested to create subcommands. Use the following methods to manage the hierarchy:

• appendChild(String name, UnaryOperator<CommandBuilder<SENDER>> operator): Creates a new child command with the specified name and configures it using the provided operator.
• appendChild(CommandBuilder<SENDER> context): Adds an existing CommandBuilder instance as a child.
• editChild(String name, UnaryOperator<CommandBuilder<SENDER>> operator): Finds an existing child by name and applies a configuration operator to it.
• getChild(String name): Returns an Optional<CommandBuilder<SENDER>> containing the child if it exists.
• children(): Returns a collection of all child commands.

CommandBuilder<MySender> builder = CommandBuilder.create()
    .name("main")
    .appendChild("sub", sub -> sub.name("subcommand"))
    .editChild("sub", sub -> sub.aliases("alt-sub"));