An extendable, declarative and annotation driven command framework for JDA.
The following example will demonstrate how easy it is to write a command:
@CommandController
@Permission("BAN_MEMBERS")
public class BanCommand {
@Command(value="ban", name="Ban Member", usage="{prefix}ban @Member", category="Moderation")
public void ban(CommandEvent event, @NotRole("admin") Member member, @Max(7) int delDays, @Optional @Concat String reason) {
event.getGuild().ban(member, delDays).queue();
event.reply("%s got banned for reason %s", member.getAsMention(), reason);
}
}Finally, start the framework by calling:
JDACommands.start(jda, Main.class);JDA-Commandas also comes in with auto-generated, "plug and play" help messages:
As shown in the example, JDA-Commands makes it possible to focus only on the business logic inside your command classes. All other chores like permission checks, argument parsing and validation, cooldowns, etc. are dealt with on the site of the framework.
Utility classes and methods for help and error messages, documentation, internationalization, embed generation, etc. further improve the workflow when writing bots.
You can find a detailed list of all features down below (click on the ▶ for details):
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.
Levenshtein Distance
The Levenshtein distance between two words is the minimum number of single-character edits (insertions, deletions or
substitutions) required to change one word into the other. For instance, the input tpyo will match the command
label typo.
Label Shortening
Label shortening can be compared to the auto complete feature of a terminal. For instance, the command label foo will
also match the input
f or fo as long as only one command that starts with f (or respectively fo) exists. This also works for sub
command labels.
Quote Parsing
Normally arguments are split at every empty space. This makes it impossible to pass one argument that contains several
words. In order to fix this issue, the default event parser can parse quotes. In other words: The
input label "arg0 arg1" arg2 will be parsed to [label, arg0 arg1, arg2] instead of [label, "arg0, arg1", arg2].
Private Channel Support
If enabled, commands can also be called by sending a private message to the Bot.
Permissions System
The permission system supports both using discord permissions 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.
Guild Settings
Settings, such as the prefix, ignore case or muted channels, are available on a per-guild level. By default, all settings apply globally.
Help & Error Messages
The @Command annotation has additional attributes to document commands. These attributes are used to automatically
create Help Embeds. Furthermore, there are default Error Embeds for all validation systems of this framework. (Parameter
Constraints, Permissions, etc.)
Documentation
It's possible to generate command documentation in markdown format. A GitHub Action as well as html output for this is also planned.
Internationalization
This framework and all the output it generates are in English. However, you can easily change the language. 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.
Persistence
This framework has builtin classes to store settings as json.
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:
The following dependencies were used to build this framework: