cerus / jda-commands

A declarative, annotation driven command library for JDA

JDA-Commands

An extendable, declarative and annotation driven command framework for JDA.

Example

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:

Features

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):

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.

Routing

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.

Constraints

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.

Misc

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.

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:

Dependencies

The following dependencies were used to build this framework:

• JDA
  • Version: 4.4.0_352
  • Github
• Reflections
  • Version: 0.9.10
  • Github
• Gson
  • Version: 2.8.6
  • Github
• slf4j-api
  • Version: 1.7.30
  • Website
• markdowngenerator
  • Version: 1.3.2
  • Github