Extensions

Once you've created your bot and configured it to your needs, you can start adding functionality. Kord Extensions requires functionality to be separated out into Extensions, allowing commands and event handlers to be grouped by function and easily loaded and unloaded.

Extensions are the building blocks that make up your bot's features, and represent single units of functionality. For example:

A help extension that implements HelpProvider and contains all help-related commands and event handlers.
A PluralKit extension that provides an API for working with PluralKit, including code that fires custom events, and any relevant commands and event handlers.
An anti-phishing extension that downloads and maintains a database of known phishing domains, and contains the relevant commands and event handlers needed to automatically moderate messages containing them.

Conventions

While you can organize your extensions in any way you wish, the following is worth keeping in mind:

Consider placing your extensions within a package named extensions.
- If the extension only requires one file or class, name it $lt;Name$gt;Extension and place it directly within the extensions package.
- If the extension requires multiple files or classes, create a subpackage for it within the extensions package, named after the extension and containing it and everything it needs.
Extension classes should have descriptive names and end with the word "Extension." For example, use MinecraftExtension instead of MEx or Minecraft.
Extension names should be easy to guess, and written in lowered-kebab-case. For example, use minecraft or log-rotation instead of Mine_craft or LogRotation.
If your extension is intended to be used by others, consider prefixing the name to distinguish it from extensions written by other people. For example, if your org is named Acme Corp., consider using acme-minecraft or acme-log-rotation.
Extensions should be designed with a single purpose in mind, and shared functionality (for example, APIs) should be extracted into an interface or abstract class.
Don't put all of your bot's functionality into a single extension, especially if it has a lot of features. For example, use ModerationExtension, MinecraftExtension and LogRotationExtension instead of just MyBotExtension.
While your extension class can be laid out however you prefer, we suggest the following order:
- At the top, simple variables and constants, followed by variables and constants with custom getters and setters.
- Your setup function, followed by any other functions your extension needs. It's also generally a good idea to split up public API and private functions.
- Any command argument classes used by your extension, marked as inner classes. Alternatively, it may be useful to factor these out into separate classes in their own files.
- Any modal form classes used by your extension, marked as inner classes. Alternatively, it may be useful to factor these out into separate classes in their own files.
class MyExtension : Extension() { // Simple variables and constants override val name: String = "my" val chatCommands: ChatCommandRegistry by inject() // Setup function override suspend fun setup() { } // Public API suspend fun myAction() { } // Private functions private suspend fun doAction() { } // Command argument classes inner class CommandArgs : Arguments() { } // Modal form classes inner class MyForm : ModalForm() { } }

Structure

All extensions must extend the Extension type. This type provides most of the logic behind your extensions, and it implements Kord Extensions' KoinComponent types, giving you direct access to Koin's API.

All extensions must implement the following:

Name	Type	Description
`name`	`String`	Human-readable short extension name. This should be `lowered-kebab-case` and must be unique, as it's used for logging and by parts of the `ExtensibleBot` API to index and retrieve loaded extensions.
`setup`	`suspend () -> Unit`	This function is called when your extension is set up, and it should be used to register all of its commands, event handlers, and other functionality.

To react and respond to actions taken on Discord, you'll need to register the relevant abstractions in your setup function:

Event handlers, which allow your bot to react to all kinds of things as they happen.
Commands, which may be executed by users that share servers with your bot.

For more information, please see the relevant links above.

Extension API

The Extension type provides a fairly comprehensive API, which you can use to build out your bot's functionality. It also extends KoinComponent, providing easy access to other parts of Kord Extensions as necessary.

Functions

Function	Description
`setup`	Extension setup function, as explained above.
`unload`	If your extension requires tear-down or cleanup steps to be run when it's unloaded, override this function. Called whenever the extension is disabled.

Properties

The following properties are marked open and are intended to be overridden by extensions.

Name	Type	Default	Description
`allowApplicationCommandsInDMs`	`Boolean`	`true`	Whether application commands registered by this extension should be allowed in DMs by default. May be overridden or set by your `setup` function.
`intents`	`MutableSet <Intent>`	`{ }`	Intents required by this extension, which will be automatically requested at bot startup. This is populated automatically by event handlers and chat commands, but you can always add other required intents if needed.
`name`	`String`		Human-readable short extension name, as explained above.

The following properties are set automatically, and you shouldn't need to modify them.

Name	Type	Description
`loaded`	`Boolean`	Whether the extension is currently loaded. This is a short-hand reference to `state`.
`state`	`ExtensionState`	The extension's loading state, which describes which state of its lifecycle it's currently in.

The following properties provide quick access to various parts of Kord Extensions, via Koin.

Name	Type
`applicationCommandRegistry`	`ApplicationCommandRegistry`
`bot`	`ExtensibleBot`
`chatCommandRegistry`	`ChatCommandRegistry`
`kord`	`Kord`

Last modified: 20 November 2024