Gradle Plugin

Plugin Information

• Coordinate: dev.kordex.gradle.kordex
• Version:
• Requires Gradle:
• Minimum JDK:

The Kord Extensions Gradle Plugin (the KordEx Plugin) is an optional Gradle plugin that makes it easier to develop most Discord bots and plugins using Kord Extensions. We designed this plugin to be flexible and easy-to-use, and it is the preferred way to work with Kord Extensions.

Features

The KordEx Plugin handles the following automatically:

• Miscellaneous project configuration tasks:
  • Data collection settings.
  • Dependency metadata storage.
  • Run configurations for testing your bot.
• Adding relevant dependencies:
  • Kord Extensions and the correct version of Kord, with or without voice support.
  • Dependencies required by any specified first-party modules.
• Optional validations, which help to avoid less-obvious issues:
  • Checking for outdated Kotlin versions.
• Configuring required Maven repositories:
  • Repositories required to resolve Kord Extensions and its dependencies.
  • The Kord Extensions third-party repository, for approved community projects.
• Applying and configuring several Gradle plugins:
  • Application: Configuring and adding thee dev run configuration.
  • Distribution: Configuring for bots or plugins, as required by your project.
  • Java: Setting the Java source/target compatibility settings.
  • Kotlin: Setting the JVM target and required compiler arguments.
  • KSP: Adding the Kord Extensions annotation processor.
• Internationalisation preparation work:
  • Generating translations classes based on your translation bundle and keys.

Setting Up

Gradle Version Requirements

Because the KordEx Gradle plugin uses Gradle's problem reporting API, and the Gradle team has been dragging their heels on stabilising it, you'll need to use the same version of Gradle we build the plugin against.

This means you'll need to use Gradle with the latest plugin version.

We hope this API stabilises soon, and we can move on from this issue!

Included Dependencies

Kord Extensions includes the API dependencies listed on the version picker page. If you need to use them, remember not to depend on them directly.

Basic

First, add the required Maven repositories to your settings.gradle.kts:

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()

        maven("https://snapshots-repo.kordex.dev")
        maven("https://releases-repo.kordex.dev")
    }
}

Next, add the plugin to your project:

Please wait, loading versions...

Convention Plugin

First, add the required Maven repositories to your buildSrc/build.gradle.kts:

repositories {
    gradlePluginPortal()
    mavenCentral()

    maven("https://snapshots-repo.kordex.dev")
    maven("https://releases-repo.kordex.dev")
}

Next, add the plugin dependency:

Please wait, loading versions...

Then, add the plugin to any convention plugins or Gradle modules that need it:

plugins {
    id("dev.kordex.gradle.kordex")
}

Finally, configure the plugin:

kordEx {
    // Settings go here.
}

Configuration

You can configure the plugin using the kordEx { } builder provided. Please remember to configure the plugin for either bots or plugins, or it won't do anything!

General

The following settings are at root level, placed directly within the kordEx { } builder.

Properties

addDependenciesType: BooleanDefault: true

Whether to automatically add any dependencies required by Kord Extensions and any specified modules.

addRepositoriesType: BooleanDefault: true

Whether to automatically add any Maven repositories required by Kord Extensions and any specified modules.

addThirdPartyRepositoriesType: BooleanDefault: true

Whether to add a special Maven repository used by vetted third-party modules.

configurationsType: List<String>Default: emptyList()

Dependency configurations to add dependencies to, if addDependencies is true.

If you don't add anything to this:

• Bots: Defaults to implementation.
• Plugins: Defaults to compileOnly.

ignoreIncompatibleKotlinVersionType: BooleanDefault: false

Whether to stop the build from failing if you're using a potentially incompatible Kotlin version.

jvmTargetType: Int

JVM version to use as the project target, if you don't want to match the version Kord Extensions was built with.

kordExVersionType: String

The Kord Extensions version to use. Defaults to the latest version, .

kordVersionType: String

The Kord version to use. Defaults to whatever version was used to build the version of Kord Extensions you're using.

Functions

module(...)

Call this function to add a dependency on a Kord Extensions module, using the names provided in the linked README. This will automatically set up any required dependencies and repositories, assuming addDependencies and addRepositories are true.

Bots

To configure the plugin to build bots, add the bot { } builder within the kordEx { } builder, and configure it as explained below.

Required Settings

mainClassType: String

Required: Your bot's main class, including the Kt suffix.

This matches the configuration for the application plugin, and it will be used to configure that plugin automatically.

Optional Settings

dataCollection(...)

Set your bot's default data collection level.

processDotEnvType: BooleanDefault: true

Whether to process .env files containing environment variables, when you run the dev task.

If enabled, this will traverse your project's file tree, parsing .env files from the current Gradle module's directory, and adding values from any further .env files in containing directories, until it reaches the root module's directory.

versionType: StringDefault: project.version

Your bot's version.

Defaults to the current project's version.

voiceType: BooleanDefault: true

Whether to depend on a version of Kord that supports Discord voice communication.

If you don't need to support voice, setting this to false will reduce the size of your bot's distribution.

Plugins

To configure the plugin to build plugins, add the plugin { } builder within the kordEx { } builder, and configure it as explained below.

Required Settings

pluginClassType: String

Coordinates for your plugin's class. The class you provide must extend KordExPlugin.

idType: String

Your plugin's unique ID.

versionType: String

Your plugin's version, which must be a SemVer version. You need to set this manually, as plugin versions can't contain specifiers like -SNAPSHOT.

Compatibility Data

dependency(...)

Add a dependency on another plugin. Kord Extensions will try to load these plugins before your one, and will fail to load your plugin if any non-optional dependencies aren't found.

Arguments

idType: String

The unique ID for the plugin you want to depend on.

versionSpecifierType: String?Default: null

Optional version specifier, which must be a SemVer range.

optionalType: BooleanDefault: false

Whether this is an optional dependency. Optional dependencies will be loaded before your plugin, but a missing optional dependency won't stop your plugin from loading.

kordExVersion(...)

Specify which versions of Kord Extensions your plugin supports.

Note: Do not include -SNAPSHOT in your version specifier. Instead, just use the version number without it.

Arguments

versionSpecifierType: String

Version specifier, which must be a SemVer range.

Plugin Metadata

authorType: String

Who developed this plugin. This is a freeform string input, but we suggest using this format: Full Name (username), Full Name (username), ....

Please avoid including email addresses unless you want random bot users to email you!

descriptionType: String

A short description of what this plugin does. This is a freeform string input, but we suggest using a short, one-line description, optionally followed by two newlines (\n) and a longer, multi-line description.

Internationalisation (i18n)

This is moving!

Please note that we will be moving the i18n generator into a separate plugin. When this happens, you'll need to migrate your buildscript.

To configure the plugin to generate a translation class based on your project's translations, add the i18n { } builder within the kordEx { } builder, and configure it as explained below.

Required Settings

classPackageType: String

Package to place the generated translation class into. You should use a package within your bot's base package.

translationBundleType: String

The name of your translation bundle. This must match the name of the directory you created for your bundle, in src/main/resources/translations/.

If your bundle filenames start with a string other than strings, specify it in the bundle name, splitting with a .. For example, for bot/text.properties, specify bot.text.

Optional Settings

classNameType: StringDefault: Translations

The name to use for the generated translations class.

configureSourceSetType: BooleanDefault: true

Whether to automatically configure a Java source-set for the generated translations class.

If you disable this, you'll need to configure one manually, so Gradle will include the generated class when it builds your project.

outputDirectoryType: FileDefault: build/generated/kordex/main/kotlin/

Where to place generated source files.

messageFormatVersionType: IntDefault: 1

Which ICU message format to use for your bundle:

• Version 1: The older, current message format.
• Version 2: The new, in-development message format.

We recommend using version 2 for all new translation bundles, as it will eventually become the standard.

publicVisibilityType: BooleanDefault: true

Whether the generated translations class should be marked public.

Setting this to false will use internal instead.

Usage

Once you've finished configuring the plugin, you can continue to use the normal Gradle tasks you always would:

• build will assemble and build your project, as usual.
• distTar and distZip will create self-contained distributions:
  • Bots: The distributions will contain your bot, its dependencies, and startup scripts you can use to run it. These are also ideal for unpacking into a Docker container.
  • Plugins: distZip will create a plugin zip that you can use in any Kord Extensions bot.

The plugin also adds extra tasks, depending on how you configure it:

• dev will run your bot in development mode, automatically loading environment variables from .env files. We recommend using this task when testing your bot.
• generateTranslationsClass is usually run automatically, but you can run it to manually regenerate your translations class.