Lamp Command Framework

The CooldownHandle interface provides fine-grained control over command cooldowns. It can be used in two primary ways depending on whether you want static or dynamic cooldown durations.

1. Using the @Cooldown annotation (Static)

If you want a fixed cooldown duration, annotate the CooldownHandle parameter (not the method) with @Cooldown. This allows you to use shortcut methods that automatically reference the annotated values.

Note: You must place the @Cooldown annotation on the parameter itself. Placing it on the method will result in an error.

2. Manual/Dynamic Cooldowns (Dynamic)

If you need to specify durations at runtime (e.g., from a configuration file), do not use the @Cooldown annotation. Instead, pass the duration and TimeUnit directly to the methods, or use withCooldown to create a specialized handle that supports shortcut methods.

// Static approach using annotation on the parameter
@Command("foo")
public void foo(
     ...,
     @Cooldown(value = 10, unit = TimeUnit.SECONDS) CooldownHandle cooldownHandle
) {
     cooldownHandle.requireNotOnCooldown(); // Uses 10s from annotation
     // ... action
     cooldownHandle.cooldown(); // Uses 10s from annotation
}

// Dynamic approach using withCooldown
@Command("foo")
public void foo(
     ...,
     CooldownHandle cooldownHandle
) {
     // Create a handle with a specific duration
     cooldownHandle = cooldownHandle.withCooldown(10, TimeUnit.SECONDS);

     cooldownHandle.requireNotOnCooldown(); // Uses the 10s set above
     // ... action
     cooldownHandle.cooldown(); // Uses the 10s set above
}

The ExecutableCommand<A> interface represents a complete, immutable command path that can be executed within the Lamp framework. It acts as the primary abstraction for a command, encompassing its path, usage, description, and the underlying function that performs the action.

Key characteristics include:

• Hierarchy: Commands are structured as a sequence of CommandNode objects. You can navigate the command tree using firstNode(), lastNode(), childrenCommands(), or siblingCommands().
• Execution: Commands can be tested for validity using test(actor, input) (returning a Potential) or executed directly via execute(actor, input) or execute(context).
• Visibility: A command's visibility to an actor is determined by whether it is marked as a SecretCommand and whether the actor has the required permissions.
• Metadata: It provides access to command metadata like path(), usage(), description(), and commandPriority().
• Parameters: You can inspect the command's parameters (including required inputs and optional parameters) and access specific parameters by name using parameter(name) or parameterOrNull(name).

The @Cooldown annotation allows you to restrict how frequently a command can be executed. It can be applied in two distinct ways depending on the level of control you need:

1. Automatic Cooldown (Simple)

Apply @Cooldown directly to a class or a method.

• Behavior: If the command executes successfully, the user is automatically placed on cooldown.
• Error Handling: If a user attempts to execute the command while on cooldown, a revxrsal.commands.exception.CooldownException is thrown.

2. Manual Cooldown (Flexible)

Apply @Cooldown to a parameter of type CooldownHandle. This gives you manual control over when the cooldown starts and how to handle users currently on cooldown.

• Behavior: The cooldown is not applied automatically. You must explicitly call cooldownHandle.cooldown() within your method logic to trigger the cooldown.
• Capabilities: You can check if a user is on cooldown using isOnCooldown(), retrieve the remaining time via remainingTime(TimeUnit), or force a check using requireNotOnCooldown() (which throws a CooldownException).
• Note: A CooldownHandle parameter can be used even without the @Cooldown annotation.

// Example 1: Automatic Cooldown
@Command("foo")
@Cooldown(value = 10, unit = TimeUnit.SECONDS)
public void foo() {
    // Command action here. User is automatically put on cooldown after success.
}

// Example 2: Manual Cooldown with custom logic
@Command("foo")
public void foo(@Cooldown(value = 10, unit = TimeUnit.SECONDS) CooldownHandle cooldownHandle) {
    if (cooldownHandle.isOnCooldown()) {
        long secondsLeft = cooldownHandle.remainingTime(TimeUnit.SECONDS);
        actor.reply("You must wait " + secondsLeft + " second(s) before using this command again!");
        return;
    }
    
    // ... command action here

    // Manually trigger the cooldown
    cooldownHandle.cooldown();
}

The AnnotationList interface represents an immutable collection of annotations. It provides a high-level API for querying, mapping, and transforming annotations while respecting Lamp's specialized annotation behaviors like @DistributeOnMethods and AnnotationReplacers.

Key Capabilities

• Creation: Create lists from AnnotatedElement (which accounts for distributed annotations), or from existing collections/maps (which do not).
• Querying: Retrieve specific annotations by type using get(), contains(), or require().
• Functional Mapping: Transform annotation data using map(), mapOr(), or mapOrGet().
• Transformation: Create new lists by adding annotations via withAnnotations() or applying dynamic replacements via replaceAnnotations().

// Creating a list from an element (respects @DistributeOnMethods)
AnnotationList list = AnnotationList.create(someAnnotatedElement);

// Querying an annotation
MyAnnotation annotation = list.get(MyAnnotation.class);

// Mapping an annotation value safely
String value = list.mapOr(MyAnnotation.class, ann -> ann.value(), "default");