Command conditions

This page explains how to use the CommandCondition interface to restrict command execution based on custom conditions

The CommandCondition interface allows you to define conditions that must be met for a command invocation to proceed. This is useful for performing checks based on specific annotations or other criteria to control command execution flow.

Implementing a Custom CommandCondition

In this example, we will create a custom condition that checks if the command actor is an operator (op). We will use a custom annotation @IsOpped to mark commands that should only be executable by ops. If the condition is not met, the condition will throw an exception, preventing the command from executing.

Step 1: Define the @IsOpped Annotation

The @IsOpped annotation will be used to mark commands that require the actor to be an operator:

Java

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface IsOpped {}

Kotlin

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.FUNCTION)
annotation class IsOpped

Step 2: Implement the IsOppedCondition

Next, we create a CommandCondition implementation that checks if the actor is an operator by inspecting the @IsOpped annotation:

Java

public enum IsOppedCondition implements CommandCondition<BukkitCommandActor> {
    INSTANCE;

    @Override
    public void test(@NotNull ExecutionContext<BukkitCommandActor> context, @NotNull StringStream input) {
        boolean requiresOp = context.command().annotations().contains(IsOpped.class);
        if (requiresOp && !context.actor().sender().isOp()) {
            throw new CommandErrorException("You must be an operator to execute this command.");
        }
    }
}

Kotlin

object IsOppedCondition : CommandCondition<BukkitCommandActor> {

    override fun test(context: ExecutionContext<BukkitCommandActor>, input: StringStream) {
        val requiresOp = context.command().annotations().contains(IsOpped::class.java)
        if (requiresOp && !context.actor().sender().isOp()) {
            throw CommandErrorException("You must be an operator to execute this command.")
        }
    }
}

Step 3: Register the Condition

To use the IsOppedCondition, you need to register it with your Lamp instance, specifying that it should be used whenever the @IsOpped annotation is present:

Java

var lamp = BukkitLamp.builder(this)
    .condition(IsOppedCondition.INSTANCE)
    .build();

Kotlin

val lamp = BukkitLamp.builder(this)
    .condition(IsOppedCondition)
    .build()

Step 4: Applying the @IsOpped Annotation to Commands

Now, you can apply the @IsOpped annotation to any command method that should only be accessible by operators:

Java

@IsOpped
@Command("some admin command")
public void opOnlyCommand(Player player) {
    /* ... */
}

Kotlin

@IsOpped
@Command("some admin command")
fun opOnlyCommand(Player player) {
    /* ... */
}

In this example, the opOnlyCommand method is marked with the @IsOpped annotation, indicating that it requires the actor to be an operator. If a non-operator attempts to use this command, the IsOppedCondition will throw a CommandErrorException, and the command framework will handle the exception appropriately.