Lamp

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!

• Lamp is small: The overall size of Lamp does not exceed 300 KB. Built to be lightweight and dependency-less, Lamp is convenient to package and ship.

• Lamp is extendable: Lamp has been built thoroughly with this in mind. You can create custom annotations for commands, parameters, permissions and resolvers, with their very own functionality. This gives so much space for your own extendability, and also helps make sure the code you write is minimal.

• Lamp is portable: Created with a high-level command API and an extendable codebase, Lamp has been produced to provide first-class support to as many platforms as possible. As of now, Lamp supports the following platforms:

  • Bukkit / Spigot
  • BungeeCord
  • VelocityPowered
  • SpongePowered
  • Java Discord API (JDA)
  • Mojang's Brigadier
  • Command line interface (CLI)

  With the help of the built-in APIs for dispatching commands and auto-completions, it is possible to support almost any platform out-of-the-box.

• Lamp is easy: Despite all the powerful features and extendability, getting started with Lamp couldn't be easier. Simply create a command handler for your appropriate platform, then proceed with creating your command with the main @Command and @Subcommand annotations, and finally registering it with CommandHandler#register().

• Lamp is powerful: Lamp allows you to leverage some of the command features which would be otherwise too burdensome to build:

  • @Switch parameters
  • @Flag (named) parameters
  • Simple dependency injection
  • Built-in localization API
  • A quote-aware argument parser
  • Context resolver factories and value resolver factories
  • Simple and powerful auto completions API
  • Built-in command cooldown handler
  • First-class Kotlin support: Lamp provides top-tier support for Kotlin features, such as:
    • Default parameters (with @Optional)
    • Suspend functions
    • Auxiliary Kotlin extensions

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]:[version]")
}

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

Available modules:

• bukkit for Bukkit/Spigot/Paper
• velocity for VelocityPowered
• sponge for SpongePowered
• bungee for BungeeCord
• jda for Java Discord API (JDA)
• brigadier for Mojang Brigadier
• cli for building console applications

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:

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);
        }
    }

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

• Overview: Lamp/wiki
• Examples: wiki/examples
• Javadocs: https://revxrsal.github.io/Lamp/

Sponsors

If Lamp has made your life significantly easier or you're feeling particularly generous, consider sponsoring the project! It's a great way to support the many hours I've spent maintaining this library and keeps me motivated. Please don't sponsor if you can't afford it.

Donate with PayPal

Huge thanks to those who donated! 😄

If I missed you or you would like to remain anonymous, feel free to shoot me a DM on Discord)

• Demeng ($50)