KordEx Plugin

The KordEx Gradle plugin is a Gradle plugin designed to make it easier to correctly configure Gradle projects containing Kord Extensions bots and plugins. This plugin is the recommended way to configure your project, but you can also set things up manually if you're not using a Kotlin Gradle build script, or otherwise can't (or don't wish to) use the plugin.

Features

The KordEx plugin is designed to automatically set up your Gradle project to work with Kord Extensions. As of this writing, it can handle the following for you:

Automatic configuration of Maven repositories:
- KordEx, Google, Maven Central and OSSRH.
- When using the Mappings module: FabricMC, QuiltMC, Shedaniel and JitPack.
Automatic configuration of relevant dependencies:
- Both Kord and Kord Extensions.
- Any dependencies required by configured first-party modules:
  - When using the MongoDB data adapter: The latest versions of the Kotlin Coroutines MongoDB driver, and the BSON adapter for kotlinx.serialization.
Configuration of several Gradle plugins:
- The Kotlin plugin — Setting the required Kotlin compiler arguments and setting the same JVM target used by Kord Extensions.
- The Java plugin — Setting the same Java source/target compatibility settings used by Kord Extensions.
- If the KSP plugin is applied, automatically adding the Kord Extensions annotation processor.
Validation checks, including checking whether you're using the correct version of the Kotlin plugin for the version of Kord Extensions you're working with. You can disable this if needed.
When configured for bot development:
- Automatic configuration of the application plugin and jar task.
- New in v1.3.1: Creation of the dev task, used to run your bot in development mode.
  This task will recursively parse .env files in your project directories, adding them to your in-development bot's runtime environment variables:
  - First, it parses the .env file in your project's root directory.
  - Then, if your bot is in a subproject/submodule, it'll parse .env files found while traversing the directory tree down to it, and overriding any previously set variables.
  - Finally, it'll parse the .env file in your bot's module, as previously described.
  - This may be configured by setting processDotEnv as explained below.
- Easy configuration of Kord Extensions' default data collection settings.
- Generation of the kordex.properties resource file, which is automatically added to your bot's resources. This file contains:
  - Your configured data collection settings.
  - The version of Kord and Kord Extensions you're using.
  - A list of first-party Kord Extensions modules you're using.
  You should not provide this yourself, as missing some data will break parts of Kord Extensions.
When configured for plugin development:
- Automatic configuration of the distribution plugin.
- Generation of the plugin.properties resource file, which is automatically added to your plugin's distribution. This file contains plugin metadata based on your configuration.
- Automatic plugin packaging via the distZip task, including:
  - Your plugin's classes, placed within the classes directory.
  - Your plugin's resources, also placed within the classes directory.
  - Your plugin's runtime dependencies, placed within the lib directory.
  - Your plugin's metadata, in the plugin.properties file.

Setting Up

First, add the KordEx Gradle plugin to your build.gradle.kts.

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

Then, if needed, configure it as explained below.

            kordEx {
                // Settings go here.
            }
        

Configuration

All settings must be provided within the kordEx { } builder. If you don't configure it for either bot or plugin development, then the plugin won't do anything.

All settings are defined using Gradle Property objects.

Basic Settings

The following settings apply to both the bot and plugin modes, but they'll also be used when neither mode is specified.

Property	Default	Description
`addDependencies`	`true`	New in v1.2.1: Whether to automatically add the required dependencies for a standard Kord Extensions setup. If you need to create a "common" module depended on by bots, you may wish to set this property to `false` in your bot modules to avoid duplicate dependencies.
`addRepositories`	`true`	Whether to automatically add the required Maven repositories for a standard Kord Extensions setup. If you need to use a fork of either Kord or Kord Extensions, you may want to disable this and set up your repositories manually.
`configurations`		A list of dependency configurations to use for the automatically added dependencies, overriding the default configuration used. The default configuration is `implementation`, or `compileOnly` in plugin mode.
`ignoreIncompatibleKotlinVersion`	`false`	By default, your build will fail if the version of the Kotlin Gradle plugin you're using doesn't match the version of Kotlin used to compile Kord Extensions. If you wish to use a different Kotlin version (and you know what you're doing), setting this property to `true` will make this a warning instead.
`jvmTarget`		An integer, representing the JVM version your project should target. By default, this will be set to the minimum JVM version required by Kord Extensions, but you may need to change this setting if one of your dependencies requires a newer JVM version. The minimum JDK version required by Kord Extensions is version 13.
`kordVersion`		Specify a specific Kord version if you need to. Alternatively, supply `"latest"` and the plugin will try to find the latest non-feature-branch version of Kord. By default, the Kord version used to build the selected version of Kord Extensions is used. You'll want to specify a version yourself if you need to use your own fork of Kord.
`kordExVersion`	`latest`	Specify a specific Kord Extensions version if you need to. Alternatively, supply `"latest"` and the plugin will try to find the latest version of Kord Extensions. By default, the latest released version of Kord Extensions is used, which will usually be a snapshot. Depending on snapshots is the intended way to use Kord Extensions, but you'll want to specify a version yourself if you need to hold back an update or use your own fork of Kord Extensions.

Modules

Many first-party Kord Extensions modules exist that provide extra development tools and various user-facing bot functions.

The repository layout is currently a bit messy, but it'll be cleaned up for the upcoming 2.0.0 release of Kord Extensions.

In the meantime, check the above link for information on how to find our first-party modules. Modules are named according to their containing folder — for example, the PluralKit module is located in extra-modules/extra-pluralkit, so the module name is extra-pluralkit.

Function	Description
`module`	Add a first-party Kord Extensions module by name. The KordEx plugin will also automatically add any extra dependencies and repositories that the specified module requires.

Bot Development

To configure your project for bot development, use the bot { } builder in the kordEx { } builder. For example:

Bots should be built by running the build task.

kordEx { bot { // https://kordex.dev/blog/2024-07-23/kordex-2#levels dataCollection(DataCollection.Standard) mainClass = "my.package.MyMainClass" } }

Property	Default	Description
Required Properties
`mainClass`		Your bot's main class, which will usually refer to a top-level `main` function. Providing this will automatically apply and configure the `application` plugin, and add the main class reference to your bot's JAR manifest, making the built JAR executable.
Optional Properties
`processDotEnv`	`true`	New in v1.3.1: Whether to recursively parse `.env` files when setting up the `dev` task, as explained here.
`voice`	`true`	Whether to use Kord's voice-enabled core module when depending on it. By default, this is enabled, which means that `kord-core-voice` will be used. However, if your bot doesn't need to support Discord voice, you can set this property to `false` and `kord-core` will be used instead. Using a version of Kord that doesn't support Discord voice may result in a smaller JAR when your bot is built.

Data Collection

The default data collection level is Standard.

Function	Description
`dataCollection`	Set your bot's default Data Collection level to the given argument. Note: Users may override this at runtime using a system property or an environmental variable. It may also be manually configured in code, as explained here.

Function

Description

dataCollection

Set your bot's default Data Collection level to the given argument.

Note: Users may override this at runtime using a system property or an environmental variable. It may also be manually configured in code, as explained here.

Plugin Development

To configure your project for plugin development, use the plugin { } builder in the kordEx { } builder. For example:

kordEx { plugin { id = "my-plugin-id" pluginClass = "my.package.MyPluginClass" version = "1.0.0" } }

Plugins should be built by running the distZip task.

Property	Description
Required Properties
`id`	A unique ID that identifies your plugin. This should be a short string, written using `lower-kebab-case`.
`pluginClass`	A reference to your plugin's main class, which must extend `KordExPlugin`. This must include both the package and class name — for example, `my.package.here.ClassNameHere`
`version`	Your plugin's version number, which must be a valid semantic version number.
Optional Properties
`author`	Whoever is responsible for this plugin. This can be a single person, a comma-separated list of people, an email address, an organization, or anything else you feel is appropriate.
`description`	A block of text that explains what your plugin is, what it does, and provides any other relevant information.
`license`	The license your plugin is distributed under. This does not have to be an open-source license.
Optional Functions
`dependency`	Call this function to add a dependency on another plugin. This function expects the following arguments: `id` — the ID of the plugin you wish to depend on. `versionSpecifier` (Optional) — A JSemver range expression describing which versions of the specified plugin are compatible with your plugin. `optional` (Default: `false`) — Whether this is an optional dependency. Optional dependencies are useful when your plugin optionally integrates with others, ensuring that the other plugin is a compatible version before your plugin is loaded.
`kordExVersion`	Call this function to specify which versions of Kord Extensions your plugin is compatible with. You must provide a JSemver range expression as the first argument to this function.

Last modified: 03 September 2024