JDA-Commands

A lightweight, easy-to-use command framework for building Discord bots with JDA with full support for interactions. JDA-Commands goal is to remove any boilerplate code, so you can focus solely on the business logic of your bot - writing bots has never been easier!

Version Overview

jda-commands	JDA	Text Commands	Interactions	Stable
4.0.0-beta.2	5	❌	✅	✅
3.0.0	5	✅	❌	✅
2.2.0	4	✅	❌	✅

Features

• Simple and intuitive syntax following an annotation-driven and declarative style

• Built-in support for slash commands, components, context menus and modals

• Type adapting of parameters

• Expandable execution chain including type adapters, filters, permissions and constraints

• Built-in support for ephemeral replies, permissions, localization

---

The following example will demonstrate how easy it is not only to write commands, but also to integrate components with them:

@Interaction
public class CookieClicker {

    private int count;

    @SlashCommand(value = "cookie clicker", desc = "Play cookie clicker")
    public void onCommand(CommandEvent event) {
        event.withButtons("onClick").reply("You have %d cookies(s)!", count);
    }

    @Button(value = "Click me!", emoji = "🍪")
    public void onClick(ComponentEvent event) {
        count++;
        event.reply("You have %d cookies(s)!", count);
    }
}

Additionally, let's rebuild the official slash commands example from the JDA Readme as a more complex example:

@Interaction
public class BanCommand {

    @Permissions("BAN_MEMBERS")
    @SlashCommand(value = "ban", enabledFor = Permission.BAN_MEMBERS, desc = "Bans a user", ephemeral = true)
    public void onBan(CommandEvent event, @Param("The member to ban") Member target, @Optional("no reason") @Param("The ban reason") String reason) {
        event.getGuild().ban(target, 0, TimeUnit.SECONDS).reason(reason).queue(
                success -> event.reply("**%s** was banned by **%s**", target.getAsMention(), event.getUser().getAsMention()),
                error -> event.reply("Some error occurred, try again!")
        );
    }
}

Finally, start the framework by calling:

JDACommands.start(jda, Main.class, "com.package");

---

You can find a detailed list of all features down below (click on the ▶ for details):

Execution

Request-scoped Instances

For every command execution a new instance of the controller class is created. Subsequent executions of components are executed in the same instance. This allows you to store stateful objects, like the target of a ban command, inside the controller class.

Private Channel Support

If enabled, commands can also be executed in direct messages.

Parameters

Type Adapting

As seen in the example, the method signature will be translated into a command syntax. When a command gets called, this framework will adapt the raw String input to the types specified in the method signature. As a result all the boilerplate code for parsing parameters becomes obsolete.

Parameter Validation

Parameters can have additional constraints, such as min or max value, etc. When a constraint fails, an error message will be sent automatically. You can also define your own constraints.

Constraints

Permissions System

Besides the default permissions system of slash commands, this framework comes in with an own system, supporting both discord and custom permissions. By default, you can use all permissions defined inside JDAs Permission Embed. By adding your own permission validator, you can use custom permission strings and bind permissions to certain roles or members.

Filter Chain

You can define filters that will run before each command execution. This can be useful to perform additional checks, which aren't supported by this framework by default.

Cooldown System

Commands can have a per-user cooldown to rate limit the execution of commands.

Misc

Error Messages

There are default error embeds for all validation systems of this framework, i.e. parameter constraints, permissions, etc.

Localization

This framework supports the use of JDAs LocalizationFunction for localizing slash commands.

Furthermore, you can adapt the auto generated bot responses. All embeds sent can also be loaded from a json file, which uses placeholders. example

Embed Deserialization

You can serialize and deserialize JDAs EmbedBuilder object to json. This comes in pretty handy, because for example you don't have to recompile the whole project if you find one typo inside your embed. example

Dependency Injection

This framework has a basic implementation of dependency injection, since you don't construct your command classes on your own.

Reflect API

Just like Javas Reflect API this framework also supports accessing and modifying command definitions at runtime.

If you want to learn more, check out the Wiki or the Javadoc.

Download

You can download the latest version here.

Maven

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

<dependency>
    <groupId>com.github.kaktushose</groupId>
    <artifactId>jda-commands</artifactId>
    <version>VERSION</version>
</dependency>

Gradle

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

dependencies {
    implementation 'com.github.kaktushose:jda-commands:VERSION'
}

Contributing

If you think that something is missing, and you want to add it yourself, feel free to open a pull request. Please try to keep your code quality as good as mine and stick to the core concepts of this framework.

Special thanks to all contributors <3