Beginner Tutorial

Requirements

Before getting started, you'll need to install and set up some pieces of software.

• Java Development Kit (JDK): At least version 13, but at most version 20 — we recommend Adoptium

• IDE: We recommend IntelliJ IDEA Community (via JetBrains Toolbox), which is a free IDE created by the same people that maintain Kotlin — but this page provides more information on which editors you can use for Kotlin development

Creating the Project

Once you've set up the above requirements, it's time to create your project.

Configuring Gradle

Once you've created your project, you'll need to configure Gradle and set up your project's dependencies. This is done by creating and editing some of your project's files.

1. First, set up your dependencies. Within the gradle/ folder, create a file named libs.versions.toml with the following contents, replacing KOTLIN_VERSION with the same version used by Kord Extensions:

   [versions] kotlin = "KOTLIN_VERSION" # Kotlin version must be updated in build.gradle.kts too kord-extensions = "2.2.1-SNAPSHOT" slf4j = "2.0.9" [libraries] kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib-jdk8" } slf4j = { module = "org.slf4j:slf4j-simple", version.ref = "slf4j" }

2. Next, configure your build script by editing your build.gradle.kts file. You'll need to replace its contents with the following, replacing KOTLIN_VERSION with the same version used by Kord Extensions:

   plugins { // Update this if you change the Kotlin version in libs.versions.toml kotlin("jvm") version "KOTLIN_VERSION" // The KordEx plugin id("dev.kordex.gradle.kordex") version "1.4.2" } dependencies { implementation(libs.kotlin.stdlib) implementation(libs.slf4j) } kordEx { mainClass = "com.example.bot.AppKt" }

3. In IntelliJ IDEA, click on the Gradle tab on the right side of the window, and then click the Reload All Gradle Projects button — this will tell IDEA to refresh the project and index its dependencies

4. If your editor supports Gradle, you may need to tell it to reload your Gradle project. If this is the case, then please see your editor's documentation for more information.

Cleanup and Testing

If a folder named src/test was created, delete it for now. If you'd like to write unit tests later, you can always recreate it.

Before continuing, create a file containing a main function:

• Right-click the src/main/kotlin folder in the left sidebar, select New -> Package, and enter com.example.bot

• Right-click the bot folder you just created, select New -> Kotlin Class/File, select File from the list, and enter App

• Add the following code to the file you just created:

  suspend fun main() { // We'll add code here later }

• Within the src/main/kotlin folder, create folders matching this structure: com/example/bot

• Within the bot folder you just created, create a new file named App.kt (the path should be src/main/kotlin/com/example/bot)

• Add the following code to the file you just created:

  package com.example.bot suspend fun main() { // We'll add code here later }

Let's make sure your project compiles. In the Gradle tab on the right side of the window, expand example-bot-> Tasks-> build, and double-click on the build task. Once Gradle has finished building your project, you should see BUILD SUCCESS in the new pane at the bottom of the window.

Let's make sure your project compiles. Open a terminal (or Command Prompt on Windows) within your project's folder, and run the following:

• Mac/Linux: ./gradlew build

• Windows: ./gradlew.bat build

Once Gradle has finished building your project, you should see BUILD SUCCESS in the output.

If this is not the case, please review the steps above. You may also ask for help on our Discord server.

A Simple Bot

Now that your project has been set up, let's get down to business and create your first bot.

Within the App.kt file you created earlier, add the following code before your main function:

Within the main function, replace the comment with the following code:

Your file should now look like this:

Next, create a new file named .env in the same folder as your build.gradle.kts file. Add the following to that file, replacing DISCORD_TOKEN with the token for a Discord bot you created via the Discord Developer Portal.

At this point, you should have the simplest possible bot. You can start it by running the run Gradle task, but it won't do very much yet. In the next section, let's add some functionality to your bot.

Adding Some Functionality

Using "Extensions," let's create a basic command. This command is an updated version of the classic !slap command that was a common feature present in IRC bots a long time ago.

First, create a folder named extensions within your bot folder, and then create a new file within it named SlapExtension.kt, containing the following code:

The above code creates a new extension named "slap," but it doesn't currently do anything. Let's start by adding a basic command, by replacing the comment in the setup function:

Let's also make the bot load this extension. Head back to App.kt, and replace the comment in the main function with the following:

If you were to run the bot now, a new command should be available on all servers you've added it to. It should be named /slap — go ahead and give it a try!

Adding An Argument

Our slap command is now functional, but it's not very fun. Let's add an argument, so we can slap other users!

After the setup function in SlapExtension.kt, add the following inner class:

Next, modify the command you registered earlier:

If you restart the bot, you should now be able to slap other users. Give it a try!

Next Steps

As you may have realized, the above tutorial only showcases a tiny fraction of what you can do with Kord Extensions. We recommend you experiment with the code you've written above for a while, and then read the rest of this documentation.

If you run into any problems, feel free to join our Discord server for support!