Skip to content

A high-level, robust, customizable framework making Discord bot development easy using the JDA library

License

Notifications You must be signed in to change notification settings

Pringlers/Colossus

 
 

Repository files navigation

Colossus

A high-level, robust, customizable framework making Discord bot development easy using the JDA library

Wiki

See the wiki for various guides and more information to get started

Features

  • Slash and text (prefixed) commands
    • May be generic, which means a command can be a slash and text command simultaneously while only writing the code for it once
    • You could add more features of your own using OOP
    • Extensive argument system
      • Automatic parsing
      • Automatic exception handling
      • Possibility to create custom arguments
      • Optional arguments with custom fallback functions
      • Multi-step arguments using CompleteableFuture<T>
      • Supports all Discord option features, such as autocomplete
    • Automatic exception handling; throwing a CommandException in the middle of your command execution code will automatically send an error message, same for regular exceptions
    • Subcommands and nested subcommands
    • Categories
    • Permission system, also allows for custom permissions (e.g. bot tester)
    • Cooldowns, with the option to create your own CooldownManager to handle cooldowns in a custom way
    • Inhibitors - custom conditions that should be checked before any command is executed
    • Finalizers - custom code that is run after a command was successfully executed
    • Disabled command handler - handles the enabling/disabling of commands and offers a default disable/enable command (can be removed)
    • Command localization - add localizations to slash commands
    • Help command - provides a default help command, can be disabled
  • User/message context commands
  • Custom interactions/components system
    • Automatic event handling - provide a condition and consumer beforehand
    • Buttons
      BaseButton button = BaseButton.user(userId,
          Button.primary("click", "Click me!"),
          clickEvent -> clickEvent.reply("Clicked!"));
      presetBuilder.addButtons(button);
      event.reply(presetBuilder);
    • Select Menus
      SelectMenu menu = //... jda select menu
      aseSelectMenu selectMenu = BaseSelectMenu.user(userId, menu,
          submitEvent -> submitEvent.reply("Submitted!"));
      presetBuilder.addComponentRows(selectMenu);
      event.reply(presetBuilder);
    • Modals
      Modal modal = // ... jda modal
      event.reply(modal,
          submitEvent -> submitEvent.reply("Submitted!"));
  • Custom interaction menus; you can either create your own or use one of the pre-made ones:
    • ConfirmMenu - a menu to either cancel or confirm an action
    • TabMenu - a menu to browse custom defined pages and (nested) subpages using tabs. The default help command uses this menu
    • SelectRowMenu - a menu to switch between pages using a select menu, useful for e.g. a settings command
    • ScrollPageMenu - a menu to browse pages using buttons
  • PresetBuilder - a helper class to create rich embed messages
    • Preset types - these can be used to create PresetBuilders with default values. Error messages use a (customizable) PresetType for example.
    • Easily add components using the previously mentioned custom component system
    • Ephemeral messages
  • Automatic JSON config system; allowing for extra custom key entries and grouping
  • Database driver system to easily manage, write and read a database
    • Either create your own or use the pre-made SQLDatabaseDriver, JsonDatabaseDriver or MongoDatabaseDriver
    • Automatically takes care of caching, see the DatabaseDriver javadoc for specifics
    • Update and read database values easily using a Supply and Colossus entities
      event.getUser().modifyValue("coins", coins -> coins * 10); // multiply coins by 10
      event.getUser().increaseValue("coins", 10); // add 10 coins
  • LocalFile - extended File class, with useful methods such as getContent() or parseJson(), also comes with a helpful LocalFileBuilder
  • An event waiter to await events with ease
    • Conditions; the waiter will only proceed if the condition is met
    • Timeout; optionally wait a specific amount of time before the waiter stops listening and runs a timeout action
    • Run once; whether the waiter should stop listening after it has been successfully run once or not
    • Returns an EventWaiterListener so you can optionally stop listening for the event earlier
    • Example:
      /* Await a MessageReceivedEvent.
       * Condition: The message must contain 'cookie'
       * Once the condition is met the bot replies with 'nom nom'
       * The waiter does not run once, it will listen until the timeout is over
       * The waiter will time out after 5 minutes, when it will say 'I got all the cookies!'
       */
       EventWaiter.awaitEvent(MessageReceivedEvent.class,
           msgEvent -> msgEvent.getMessage().getContent().contains("cookie"),
           (msgEvent, listener) -> msgEvent.reply("nom nom").queue(),
           false, 5, TimeUnit.MINUTES, () -> cmdEvent.reply("I got all cookies!"));
  • RepliableEvent interface implemented by all Colossus events to easily reply to events with strings, messages, embeds, PresetBuilders, modals or InteractionMenus. Some examples can be seen throughout this feature list
  • WebUtil utility class for easily retrieving data from web APIs
    WebUtil.requestJson("https://some-random-api.ml/facts/dog").get("fact").getAsString();
  • ExecutorUtil utility class for scheduling and cancelling tasks

Prerequisites

  • Java 17
  • Project with Gradle/Maven
  • An IDE (IntelliJ IDEA recommended)

Installation

Gradle

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

dependencies {
    implementation 'com.github.RyanLandDev:Colossus:VERSION'
}

Maven

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

<dependency>
   <groupId>com.github.RyanLandDev</groupId>
   <artifactId>Colossus</artifactId>
   <version>VERSION</version>
</dependency>

Support

If you need help using the framework, please join our Discord server.

About

A high-level, robust, customizable framework making Discord bot development easy using the JDA library

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Java 100.0%