v3.2.1

Small bugfix release.

Fixes

Components

• Fixed org.postgresql.util.PSQLException: Cannot change transaction read-only property in the middle of a transaction.

Misc

• Fixed java.lang.IllegalArgumentException: argument type mismatch sometimes occurring when dispatching events in parallel

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.2.0...v3.2.1

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.2.1")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.2.1</version>
</dependency>

v3.2.0

---

Changes

Dependencies

• Kotlin 2.3.20
• kotlinx.coroutines 1.11.0
• JDA 6.4.2

Text commands

• Text commands sharing the same path must be in the same class

---

Fixes

Text commands

• Class annotations now apply again

Modals

• Getting an empty non-null string from empty text inputs has been fixed

Misc

• Fixed support for reflectively-accessed inner class constructors
• Fixed support for reflectively-accessed object instance methods

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.1.0...v3.2.0

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.2.0")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.2.0</version>
</dependency>

v3.1.0 | Checkboxes, radio groups and checkbox groups

Updated to JDA 6.4.0 and added support for checkboxes, radio groups and checkbox groups.

---

Checkboxes, checkbox groups and radio groups (#253)

This adds support for reading values in modal handlers, and Kotlin extensions + DSL builders for the new modals components.

Values of those new components can now be read as:

• Checkbox -> Boolean
• CheckboxGroup -> List<String>, String for single values (can be null)
• RadioGroup -> String (can be null)

Example command

private const val MODAL_NAME = "SlashModal: modal"
private const val CHECKBOX_ID = "checkbox-id"
private const val RADIO_GROUP_ID = "radio_group-id"
private const val CHECKBOX_GROUP_ID = "checkbox_group-id"

@Command
class SlashModal(private val modals: Modals) {
    @JDASlashCommand(name = "modal", description = "Test new modal features!")
    fun onSlashModal(event: GuildSlashEvent) {
        val modal = modals.create("Modal") {
            label("I like checking boxes") {
                child = Checkbox(CHECKBOX_ID, isDefault = true)
            }

            label("Which Discord client do you use?") {
                child = RadioGroup(RADIO_GROUP_ID) {
                    option("Discord (Stable)", "stable", "The vanilla option", default = true)
                    option("Discord PTB", "ptb", "A peek into the future")
                    option("Discord Canary", "canary", "Living on the edge")
                }
            }

            label("Which modal components do you use?") {
                child = CheckboxGroup(CHECKBOX_GROUP_ID) {
                    option("Text Inputs", "textinputs")
                    option("Select Menus", "selectmenus")
                    option("File Uploads", "fileuploads")
                    option("Checkbox groups", "checkboxgroups", default = true)
                }
            }

            bindTo(MODAL_NAME)
        }

        event.replyModal(modal).queue()
    }

    @ModalHandler(MODAL_NAME)
    fun onModal(
        event: ModalEvent,
        @ModalInput(CHECKBOX_ID) doTheyLikeCheckingBoxes: Boolean,
        @ModalInput(RADIO_GROUP_ID) client: String,
        @ModalInput(CHECKBOX_GROUP_ID) features: List<String>,
    ) {
        event.reply("""
            Do you like checking boxes? $doTheyLikeCheckingBoxes
            On what client? $client
            Using what features? $features
        """.trimIndent())
            .setEphemeral(true)
            .queue()
    }
}

JDA PR: discord-jda/JDA#3010

---

New feature

jda-ktx

• Added RestActionReasonContext and withRestActionReasonContext
  • Coroutine support for JDA's ThreadLocalReason

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0...v3.1.0

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.1.0")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.1.0</version>
</dependency>

v3.0.0

It's finally here, after almost 4 years and nearly 2500 commits.

This is quite different from BC v2, so there is no clear migration guide, but I would recommend looking at the setup wiki along with dependency injection.

For those running on v3 pre-release builds, you can upgrade to 3.0.0-beta.10, then do a full build to catch all the deprecations before upgrading.

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-beta.10...v3.0.0

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.0.0")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.0.0</version>
</dependency>

v3.0.0-beta.10 | Hot restarting module

Overview

This release adds hot restarting and a few fixes. The wiki has also been greatly updated, feedback is welcome.

Added hot restarting (#232)

This new development-only module restarts your app automatically upon build, while keeping the same JVM, leading to much faster restarts, as it doesn't need to recompile most of the code.

Look at the README for more details.

---

Deprecations

Localization

• getDiscordLocale of all locale providers (UserLocaleProvider, GuildLocaleProvider, TextCommandLocaleProvider) were deprecated
  • You must implement getLocale instead

Event waiter

• BConfig#ignoredEventIntents was deprecated
  • This has been replaced by EventWaiterBuilder#ignoreMissingIntents

---

Changes

• Updated to JDA 6.3.2
• Updated to Jackson 2.21.1

---

Fixes

Database

• Fixed schema not being reset-ed correctly when returning to the connection pool in some cases

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-beta.9...v3.0.0-beta.10

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.0.0-beta.10")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.0.0-beta.10</version>
</dependency>

v3.0.0-beta.9

Important

JDA is no longer included as a transitive dependency, you will need to include it in your project.

Preparation for configuration of modules (#254)

In newer 3.X modules, and for most, if not all features in 4.X, each feature/module added by the user will contain their own configuration.

Each configuration is registered on the main configuration, Kotlin users are able to use an extension.

Registering the module's configuration means enabling the feature.

Changes

• Added methods to get/add configurations:
  • getConfigOrNull (on the built root configuration)
  • registerModule (on the root configuration builder)

---

Added shutdown functions (#255)

Changes

• Added isDaemon to namedDefaultScope
• Added new statuses
• Added shutdown functions
• Added functions to await shutdown
• Added shutdown hooks, enabled by default

---

Migration from DiscordLocale to Locale in localization (#260)

As mapping Locale between DiscordLocale is not perfect, and the underlying localization is using Locale, getting messages should be using Locale. Implicit convertions should be avoided, so methods using DiscordLocale are deprecated.

If you wish to continue using DiscordLocale, you will have to use toLocale().

Commands are still localized using DiscordLocale, any feature that is limited to the locales Discord supports, should use DiscordLocale.

Warning

Breaking changes

• AppLocalizationContext.userLocale now returns Locale
• TextLocalizationContext.guildLocale now returns Locale
• LocalizationContext.effectiveLocale now returns Locale

Deprecations

• getDiscordLocale was deprecated in all locale providers (UserLocaleProvider, GuildLocaleProvider, TextCommandLocaleProvider)
• Deprecated all reply/edit methods accepting DiscordLocale

Additions

• Added new overloads accepting Locale

---

Warning

Breaking changes

Components

• Exceptions changed when awaiting on a component:
  • ComponentTimeoutException is thrown when the timeout is reached while awaiting
  • RemovedComponentException is thrown when a component is removed while awaiting

Modals

• Exceptions changed when awaiting on a modal:
  • ModalTimeoutException is thrown when the timeout is reached while awaiting

Misc

• Removed dependency on kotlinx.datetime
  • All kotlinx.datetime imports were replaced by kotlin.time

---

New features

Typesafe messages

• Added more create overloads in IMessageSourceFactory
  • To create message sources from message events (text commands) and arbitrary locales

Kotlin extensions

• Added TimeFormat.atInstant with kotlin.time.Instant

---

Deprecations

Application commands

• Deprecated configuration property slashGuildIds, renamed as guildsToUpdate

Localization

LocalizationContext factories are deprecated and were replaced by a builder (LocalizationContext.builder)

---

Changes

Dependencies

• Updated to Kotlin 2.3.10

Modals

• You can now have @ModalInput refer to an input absent from the submitted modal, if the parameter is nullable or optional
• String parameters (from string selects) and Message.Attachment parameters (from file uploads) are now supported in modal handlers
• Modal#await() now throws ModalTimeoutException instead of TimeoutCancellationException

Components

• await() now throws ComponentTimeoutException instead of TimeoutCancellationException
• await() throws RemovedComponentException when the component is removed while it is awaited

Method accessors

• BotCommands#preferClassFileAccessors was moved to MethodAccessorsConfig

Localization

• Locales are evaluated lazily

---

Fixes

Components

• Fixed checking PostgreSQL driver version

Application commands

• Fixed global commands sometimes unnecessarily updating when using database-backed cache

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-beta.8...v3.0.0-beta.9

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.0.0-beta.9")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.0.0-beta.9</version>
</dependency>

v3.0.0-beta.8 | Safe localization module, command improvements and fixes

Overview

Added a safer localization module, removed superclass requirements of annotated commands and fixed stuff.

New module with much safer localization (#237)

A new incubating module has been added to enable you more pre-emptive checks for your localization needs!

It allows you to define interfaces to retrieve your messages, meaning cleaner commands, less chance to misspell something, and much, much earlier error messages if something isn't configured correctly.

See the README for more details.

Split and deprecate ApplicationCommand and TextCommand (#252)

This removes the requirement of extending ApplicationCommand/TextCommand by splitting them in optional interfaces for each feature.

Deprecations

• Deprecated ApplicationCommand and TextCommand

Changes

• Split ApplicationCommand into optional interfaces
  • SlashOptionChoiceProvider
  • ApplicationGeneratedValueSupplierProvider
• Split TextCommand into optional interfaces
  • TextCommandHelpConsumer
  • TextGeneratedValueSupplierProvider

---

New features

Introspection

• Added method, declaringKClass and declaringClass to Executable

Event listeners

• Added support for lists and lazy services in event listener parameters

Misc

• Added support for Kotlin 2.3.0
  • Haven't updated to it yet because of some (rare) reflection bugs

---

Deprecations

Text commands

• Deprecated and split HelpBuilderConsumer#accept into two methods
  • acceptGlobal
  • acceptCommand

Changes

Dependencies

• Updated to JDA 6.3.0
• Updated to Caffeine 3.2.3
• Updated to ClassGraph 4.8.184
• Updated to JEmoji 1.7.5
• Updated to Spring Boot 3.5.8 and Spring Framework 6.2.14
  • It will likely not get updated to Spring Boot 4, however, this library is compatible with it, you can upgrade it on your project with no issue

Built-in DI

• @Dependencies, @ConditionalService and custom @Condition annotations are now searched on supplied services
  • Supplied services are those added at runtime, will not affect anyone

Annotated commands

• Removed exception thrown when both @TopLevelSlashCommandData and @SlashCommandData had a description (on a top-level command)
  • @TopLevelSlashCommandData will get prioritized instead

Interactions

• Events of external components and modals are now logged on the DEBUG level

Interaction filters

• Filters that do not acknowledge the interaction are now logged on the WARN level

---

Fixes

Annotated application commands

• Fixed @DeclarationFilter being applied incorrectly

Built-in DI

• Fixed initialization exceptions not interrupting program startup when using ClassFile-based method accessors

Misc

• Fixed building message with pre-CV2 content when the Components V2 flag is enabled by default

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-beta.7...v3.0.0-beta.8

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.0.0-beta.8")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.0.0-beta.8</version>
</dependency>

v3.0.0-beta.7 | Modal file uploads

Overview

This release primarily adds support for file uploads in modals.

Creating a Modal accepting file uploads

Kotlin

modals.create("modal-id") {
    label("Banner image") {
        child = AttachmentUpload("banner-file")
    }
}

Java

modals.create("modal-id")
  .addComponents(Label.of("Banner Image", AttachmentUpload.of("banner-file")))
  .build()

Using the uploaded file

If you use @ModalHandler, you can add a @ModalInput parameter with a List<Message.Attachment> type.

@ModalHandler(name = "modal-id")
fun onModal(event: ModalEvent, @ModalInput("banner-file") bannerAttachments: List<Message.Attachment>) { ... }

If you use coroutines, you can use modalEvent[attachmentUpload] instead.

val bannerFileComponent = AttachmentUpload("banner-file")

val modal = modals.create("modal-id") {
    label("Banner image") {
        child = bannerFileComponent
    }
}

// Reply with the modal 

val event = modal.await()
val bannerFile = event[bannerFileComponent].asAttachmentList.single()

---

Changes

Dependencies

• Updated to JDA 6.1.0
• Updated to Kotlin 2.2.20

jda-ktx

• Added customId to [Type]SelectMenu and TextInput DSLs

---

Fixes

jda-ktx

• Fixed Label DSL not checking if a label was set

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-beta.6...v3.0.0-beta.7

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.0.0-beta.7")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.0.0-beta.7</version>
</dependency>

v3.0.0-beta.6 | Components V2 and new modal components

Overview

This release updates to JDA 6 and adds support for Components V2 as well as new modal components such as text displays, labels and select menus.

Components V2 (#233)

Please refer to the JDA 6.0.0-rc.1 release for details on this feature.

Deprecations

• UsedComponentSet#setComponents(Iterable) was deprecated
  • Replaced by setComponents(ComponentTree)

New features

• Added deleteTree in services which can create components (Buttons/SelectMenus)

Kotlin extensions

Several factory functions were added:

• ActionRow
• Container
• FileDisplay
• MediaGallery
• MediaGalleryItem
• Section
• Separator
• TextDisplay
• Thumbnail

Additionally, functions were added in inline builders to directly insert components where they can:

• actionRow
  • linkButton
• container
• fileDisplay
• mediaGallery
  • item
• section
• separator
• text

For example,

val message = MessageCreate {
    components += Container { /* */ }
}

can also be written as

val message = MessageCreate {
    container { /* */ }
}

Note: These functions are available only in components which accept multiple child components (ActionRow, Container, Section content), for fields such as the accessory of Section, you will need to set the component manually.

---

Labels and string select menus in modals (#242)

Alongside with the new JDA additions, instead of having "input names" to match with your handler's @ModalInput, you can now use the native custom ID, note that it must be unique per modal.

Adding a text input, a label or a string select menu, now only uses the native JDA components.

See the JDA 6.0.0-rc.4 release for more details.

Example changes:

@Command
public class SlashFormat extends ApplicationCommand {

    private static final String MODAL_NAME = "SlashFormat: formatModal";
-   private static final String CODE_INPUT_NAME = "SlashFormat: formatModal codeInput";
+   private static final String CODE_INPUT_ID = "SlashFormat: formatModal codeInput";

    private final Modals modals;

    public SlashFormat(Modals modals) {
        this.modals = modals;
    }

    @JDASlashCommand(name = "format")
    public void onSlashFormat(GuildSlashEvent event) {
        Modal modal = modals.create("Format your code")
                .bindTo(MODAL_NAME)
                .addComponents(
-                       modals.createTextInput(CODE_INPUT_NAME, "Code", TextInputStyle.SHORT)
+                       Label.of(
+                               "Code",
+                               TextInput.create(CODE_INPUT_ID, TextInputStyle.SHORT).build()
+                       )
                )
                .build();

        event.replyModal(modal).queue();
    }

    @ModalHandler(MODAL_NAME)
-   public void onFormatModal(ModalEvent event, @ModalInput(CODE_INPUT_NAME) String code) {
+   public void onFormatModal(ModalEvent event, @ModalInput(CODE_INPUT_ID) String code) {
        // ...
    }
}

You can see a more complete example in the "Entity select menus and text displays in modals" section.

Breaking changes

• (Kotlin only) name of @ModalInput has been updated to customId
• Removed custom TextInputBuilder
  • Use TextInput.create (Java) or TextInput(...) { ... } (Kotlin) instead
  • The given custom ID will be used to match against @ModalInput parameters

New features

• @ModalInput(...) List<String> parameters can now be resolved
• Added Kotlin DSLs:
  • Modals (Modals#create(...) { ... })
  • Labels (Label(...) { ... })
  • Text inputs (TextInput(...) { ... })
  • String select menus (StringSelectMenu(...) { ... })

Entity select menus and text displays in modals

Similarly to string select menus, entity select menus can now be added to modals using the native JDA component, the same can be said for text displays.

Please see the JDA 6.0.0-rc.5 release for more details.

Here is an example modal using text inputs, text displays, labels, string select menus and entity select menus:

Kotlin example

private const val MODAL_NAME = "request role"
private const val INPUT_REASON = "reason"
private const val INPUT_ROLE = "role"
private const val INPUT_DETAILS = "details"

@Command
class SlashRequestRole(private val modals: Modals) {

    @JDASlashCommand(name = "request_role", description = "Request a role")
    fun onSlashRequestRole(event: GuildSlashEvent) {
        val modal = modals.create("Role Request Form") {
            text(
                """
                    ### Welcome!
                    Please read the following before continuing:
                    1. Select the role you wish to get
                    2. Select the reason why you want this role
                    3. (Optional) Add any detail about your request
                    
                    -# Abuse of this system may result in penalties
                """.trimIndent()
            )

            label("Role") {
                child = EntitySelectMenu(INPUT_ROLE, SelectTarget.ROLE)
            }

            label("Reason") {
                child = StringSelectMenu(INPUT_REASON) {
                    option("It looks cool!", "cool")
                    option("I like the color", "color")
                    option("I am interested in the relevant discussions", "discussions")
                }
            }

            label("Details") {
                child = TextInput(INPUT_DETAILS, TextInputStyle.PARAGRAPH, isRequired = false)
            }

            bindTo(MODAL_NAME)
        }

        event.replyModal(modal).queue()
    }

    @ModalHandler(MODAL_NAME)
    fun onRequestRoleModal(
        event: ModalEvent,
        @ModalInput(INPUT_REASON) reason: List<String>,
        @ModalInput(INPUT_ROLE) roles: List<Role>,
        @ModalInput(INPUT_DETAILS) details: String,
    ) {
        event.reply("Your request has been submitted!")
            .setEphemeral(true)
            .queue()
    }
}

Java example

@Command
public class SlashRequestRole extends ApplicationCommand {

    private static final String MODAL_NAME = "request role";
    private static final String INPUT_ROLE = "role";
    private static final String INPUT_REASON = "reason";
    private static final String INPUT_DETAILS = "details";

    private final Modals modals;

    public SlashRequestRole(Modals modals) {
        this.modals = modals;
    }

    @JDASlashCommand(name = "request_role", description = "Request a role")
    public void onSlashRequestRole(GuildSlashEvent event) {
        var modal = modals.create("Role Request Form")
                .addComponents(
                        TextDisplay.of("""
                                ### Welcome!
                                Please read the following before continuing:
                                1. Select the role you wish to get
                                2. Select the reason why you want this role
                                3. (Optional) Add any detail about your request
                                
                                -# Abuse of this system may result in penalties
                                """),
                        Label.of(
                                "Role",
                                EntitySelectMenu.create(INPUT_ROLE, SelectTarget.ROLE).build()
                        ),
                        Label.of(
                                "Reason",
                                StringSelectMenu.create(INPUT_REASON)
                                        .addOption("It looks cool!", "cool")
                                        .addOption("I like the color", "color")
                                        .addOption("I am interested in the relevant discussions", "discussions")
                                        .build()
                        ),
                        Label.of(
                                "Details",
                                TextInput.create(INPUT_DETAILS, TextInputStyle.PARAGRAPH)
                                        .setRequired(false)
                                        .build()
                        )
                )
                .bindTo(MODAL_NAME)
                .build();

        event.replyModal(modal).queue();
    }

    @ModalHandler(MODAL_NAME)
    public void onRequestRoleModal(
            ModalEvent event,
            @ModalInput(INPUT_ROLE) List<Role> roles,
            @ModalInput(INPUT_REASON) List<String> reason,
            @ModalInput(INPUT_DETAILS) String details
    ) {
        event.reply("Your request has been submitted!")
                .setEphemeral(true)
                .queue();
    }
}

New features

• @ModalInput parameters can now resolve Mentions and T/List<T> where T is one of: IMentionable, Role, User, InputUser, Member, GuildChannel
• Added Kotlin DSLs:
  • text(...) in InlineModal
  • EntitySelectMenu(...) { ... } factory

---

Breaking changes

• Updated to JDA 6.0.0-rc.5

---

New features

• Added Mentions.inputUsers
  • Ret...

v3.0.0-beta.5

Bug fix release, please refer to previous release for the changelog.

---

Changes

• Removed BotCommands-method-accessor-classfile
  • Can now be optionally included

---

Bug fixes

• Fixed assignment of parameters
• Fixed handling of value class return types

---

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-beta.4...v3.0.0-beta.5

---

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.0.0-beta.5")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.0.0-beta.5</version>
</dependency>