/Lamp

A powerful, extendable, flexible yet simple to use commands annotation framework.

Primary LanguageJavaMIT LicenseMIT

Lamp

Discord JitPack License: MIT Build

Background

Click to expand Building commands has always been a core concept in many applications, and, lots of times, a really boring and cumbersome one to pull off: Having to think of all the possible input from the user, all the mistakes they will make, validating input and then finally executing the actual command logic.

We aren't supposed to mess our hands up with so much of this. We really shouldn't get ourselves dirty with the highly error-prone string manipulation, nor are we supposed to repeat 3 lines of code a thousand times. We also should not be forced to think of all the edge cases and possible output of the user side. Developers should focus on what's important, not what isn't.

Then after all that, we really should make sure our code is clean, maintainable, extendable and flexible.

Building upon this belief, Lamp was born.

Lamp has taken responsibility upon itself to take all the crap of the command creation process: parsing input, validating arguments, auto completions, tokenizing and redirection, and leaves you only to the important part of your job here: the actual command logic.

Through annotations, parameter resolvers, command conditions, permissions, argument validators, cooldowns, dependency injection, auto-completers, Lamp not only makes the command creation process much easier, it also becomes more fun, intuitive and less error prone.

There are many commands frameworks out there, why should I use Lamp?

Glad you asked!

Getting Started

See available versions and modules below.

Maven

pom.xml

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- Required for all platforms -->
    <dependency>
        <groupId>com.github.Revxrsal.Lamp</groupId>
        <artifactId>common</artifactId> 
        <version>[version]</version>
    </dependency>

    <!-- Add your specific platform module here -->
    <dependency>
        <groupId>com.github.Revxrsal.Lamp</groupId>
        <artifactId>[module]</artifactId>
        <version>[version]</version>
    </dependency>  
</dependencies>

Gradle

build.gradle (Groovy)

repositories {
    maven { url = 'https://jitpack.io' }
}

dependencies {
    // Required for all platforms
    implementation 'com.github.Revxrsal.Lamp:common:[version]'

    // Add your specific platform module here
    implementation 'com.github.Revxrsal.Lamp:[module]:[version]'
}

compileJava { // Preserve parameter names in the bytecode
    options.compilerArgs += ["-parameters"]
}

compileKotlin { // optional: if you're using Kotlin
    kotlinOptions.javaParameters = true
}

build.gradle.kts (Kotlin DSL)

repositories {
    maven(url = "https://jitpack.io")
}

dependencies {
    // Required for all platforms
    implementation("com.github.Revxrsal.Lamp:common:[version]")

    // Add your specific platform module here
    implementation("com.github.Revxrsal.Lamp:[module]:[verison]")
}

tasks.withType<JavaCompile> { // Preserve parameter names in the bytecode
    options.compilerArgs.add("-parameters")
}

tasks.withType<KotlinJvmCompile> { // optional: if you're using Kotlin
    compilerOptions {
        javaParameters = true
    }
}

Latest stable version

JitPack

Available modules:

Examples

Creating a command handler

public final class BansPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Create a command handler here
        BukkitCommandHandler handler = BukkitCommandHandler.create(this);
        handler.register(new BansCommand());
        // (Optional) Register colorful tooltips (Works on 1.13+ only) 
        handler.registerBrigadier();
    }
}

/epicbans ban <player> <days> <reason>

Add -silent to make the ban silent

    @Command("epicbans ban")
    public void banPlayer(
            Player sender,
            @Range(min = 1) long days,
            Player toBan,
            String reason,
            @Switch("silent") boolean silent
    ) {
        if (!silent)
            Bukkit.broadcastMessage(colorize("Player &6" + toBan.getName() + " &fhas been banned!"));
        Date expires = new Date(System.currentTimeMillis() + TimeUnit.DAYS.toMillis(days));
        Bukkit.getBanList(Type.NAME).addBan(toBan.getName(), reason, expires, sender.getName());
    }

Commands to switch game-modes

    @Command({"gmc", "gamemode creative"})
    public void creative(@Default("me") Player sender) {
        sender.setGameMode(GameMode.CREATIVE);
    }

    @Command({"gms", "gamemode survival"})
    public void survival(@Default("me") Player sender) {
        sender.setGameMode(GameMode.SURVIVAL);
    }

    @Command({"gma", "gamemode adventure"})
    public void adventure(@Default("me") Player sender) {
        sender.setGameMode(GameMode.ADVENTURE);
    }

    @Command({"gmsp", "gamemode spectator"})
    public void spectator(@Default("me") Player sender) {
        sender.setGameMode(GameMode.SPECTATOR);
    }

Commands to ping online operators, with 10 minutes delay

    @Command({"opassist", "opa", "helpop"})
    @Cooldown(value = 10, unit = TimeUnit.MINUTES)
    public void requestAssist(Player sender, String query) {
        for (Player player : Bukkit.getOnlinePlayers()) {
            if (player.isOp()) {
                player.playSound(player.getLocation(), Sound.ENTITY_ARROW_HIT_PLAYER, 1f, 1f);
                player.sendMessage(colorize("&a" + sender.getName() + " &fneeds help: &b" + query));
            }
        }
    }

Terminate all nearby entities command

    @Command("terminate")
    public void terminate(BukkitCommandActor sender, @Range(min = 1) int radius) {
        int killCount = 0;
        for (Entity target : sender.requirePlayer().getNearbyEntities(radius, radius, radius)) {
            if (target instanceof LivingEntity) {
                ((LivingEntity) target).setHealth(0);
                killCount++;
            }
        }
        sender.reply("&aSuccessfully killed &e" + killCount +" &aplayers!");
    }

With Brigadier:

Radius accepted as it is within range

Radius not accepted

Message players with player selectors

    @Command("pm")
    public void message(Player sender, EntitySelector<Player> players, String message) {
        for (Player player : players) {
            player.sendMessage(sender.getName() + " -> You: " + ChatColor.GOLD + message);
        }
    }

Example selector

Kotlin

Lamp provides first-class support for many Kotlin features, such as:

Default arguments

@Command("sum")
fun sum(
    actor: CommandActor,
    @Optional a: Int = 10,
    @Optional b: Int = Random.nextInt()
) {
    actor.reply("Result: ${a + b}")
}

Suspend functions Note: You must call this to allow Lamp to support suspend functions

myCommandHandler.supportSuspendFunctions()
@Command("countdown")
suspend fun countdown(
    actor: CommandActor,
    @Optional @Range(min = 1.0) value: Int = 20
) {
    var countdown = value
    while (countdown > 0) {
        countdown--
        delay(1000) // Coroutine function
        actor.reply("Countdown: $countdown")
    }
    actor.reply("Countdown finished!")
}

More examples available here

Documentation