jda-ktx

Collection of useful Kotlin extensions for JDA. Great in combination with kotlinx-coroutines.

For more details, checkout the README.

Examples

You can look at my own bot (strumbot) for inspiration, or look at the examples listed here.

The most useful feature of this library is the CoroutineEventManager which adds the ability to use suspending functions in your event handlers.

// enableCoroutines (default true) changes the event manager to CoroutineEventManager
// this event manager uses a default scope generated by getDefaultScope() 
// but can be configured to use a custom scope if you set it manually
val jda = light("token", enableCoroutines=true) {
    intents += listOf(GatewayIntent.GUILD_MEMBERS, GatewayIntent.MESSAGE_CONTENT)
}

// This can only be used with the CoroutineEventManager
jda.listener<MessageReceivedEvent> {
    val guild = it.guild
    val channel = it.channel
    val message = it.message
    val content = message.contentRaw

    if (content.startsWith("!profile")) {
        // Send typing indicator and wait for it to arrive
        channel.sendTyping().await()
        val user = message.mentionedUsers.firstOrNull() ?: run {
            // Try loading user through prefix loading
            val matches = guild.retrieveMembersByPrefix(content.substringAfter("!profile "), 1).await()
            // Take first result, or null
            matches.firstOrNull()
        }

        if (user == null) // unknown user for name
            channel.send("${it.author.asMention}, I cannot find a user for your query!").queue()
        else // load profile and send it as embed
            channel.send("${it.author.asMention}, here is the user profile:", embeds=profile(user).into()).queue()
    }
}

jda.onCommand("ban", timeout=2.minutes) { event -> // 2 minute timeout listener
    val user = event.getOption<User>("user")!!
    val confirm = danger("${user.id}:ban", "Confirm")
    event.reply_(
        "Are you sure you want to ban **${user.asTag}**?",
        components=confirm.into(),
        ephemeral=true
    ).queue()

    withTimeoutOrNull(1.minutes) { // 1 minute scoped timeout
        val pressed = event.user.awaitButton(confirm) // await for user to click button
        pressed.deferEdit().queue() // Acknowledge the button press
        event.guild.ban(user, 0).queue() // the button is pressed -> execute action
    } ?: event.hook.editMessage(/*id="@original" is default */content="Timed out.", components=emptyList()).queue()
}

jda.onButton("hello") { // Button that says hello
    it.reply_("Hello :)").queue()
}

Download

Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("net.dv8tion:JDA:${JDA_VERSION}")
    implementation("club.minnced:jda-ktx:${VERSION}")
}

Maven

<dependency>
  <groupId>net.dv8tion</groupId>
  <artifactId>JDA</artifactId>
  <version>$JDA_VERSION</version>
</dependency>
<dependency>
  <groupId>club.minnced</groupId>
  <artifactId>jda-ktx</artifactId>
  <version>$VERSION</version>
</dependency>