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!
| jda-commands | JDA | Text Commands | Interactions | Stable |
|---|---|---|---|---|
| 4.0.0-beta.2 | 5 | ❌ | ✅ | ✅ |
| 3.0.0 | 5 | ✅ | ❌ | ✅ |
| 2.2.0 | 4 | ✅ | ❌ | ✅ |
-
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):
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.
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.
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.
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.
You can download the latest version here.
<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>allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}dependencies {
implementation 'com.github.kaktushose:jda-commands:VERSION'
}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
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent