Commands

Kord Extensions provides a rich, type-safe commands framework which is only as complex as you need it to be. At the moment, these basic types of commands are supported:

Chat Commands, prefix-based commands that are sent directly within messages on Discord.
Application Commands, which are based on Discord's interactions system and show up in the client's UI.
- Context Commands, which are special commands that appear in right-click (or tap-and-hold) menus in the Discord client.
- Slash Commands, which are invoked by typing a slash character (/) into the Discord chat input.

Each type of command has a specific set of use-cases and functionality, and thus provides a different API surface. However, all commands have quite a few things in common.

The following sections describe commands in generic terms. For more information on the specific types of supported commands (and how to use them), please see the pages linked above.

Arguments Classes

While Context Commands don't support command arguments, the other command types do. To specify your command's arguments, you'll need to create a class that extends the Arguments type.

This class must make use of the available converter builder functions. Kord Extensions provides a large number of these, but it's possible to write your own or use those provided by third-party libraries.

See below for an example Arguments subclass.

inner class MyArguments : Arguments() { val target by user { name = "target" description = "Target user" } }

Your argument class' constructor must then be provided to your command's builder function. The parsed arguments will be available via the arguments property in your command's action block.

publicSlashCommand(arguments = ::MyArguments) { name = "my-command" action { respond { content = "Target user: ${arguments.user.mention}" } } }

The Arguments type provides the following API properties:

Name	Type	Description
`parseForAutocomplete`	`Boolean`	When working with Slash Commands, your arguments may make use of Discord's autocomplete system. If you have later arguments with an autocompletion that requires the value of a previous argument, setting this to `true` will tell Kord Extensions to fill in those arguments before calling your `autocomplete` block. As some converter types provide a default `autocomplete` block, you may need to enable this when you're using them, even when you don't provide your own. For more information, see the dedicated documentation.

Name

Type

Description

parseForAutocomplete

Boolean

When working with Slash Commands, your arguments may make use of Discord's autocomplete system. If you have later arguments with an autocompletion that requires the value of a previous argument, setting this to true will tell Kord Extensions to fill in those arguments before calling your autocomplete block.

As some converter types provide a default autocomplete block, you may need to enable this when you're using them, even when you don't provide your own. For more information, see the dedicated documentation.

For more information on the converter system (and the available argument types), see the dedicated documentation.

A modal form is Kord Extensions' way of representing the settings and contents of a Discord modal. Chat commands don't support modals, but all other command types do.

If you want to make use of modals, you'll need to create a class that extends the `ModalForm` type. This class must make use of the provided input functions to define the modal's contents. It may also override the properties defined by the ModalForm type.

class MyModal : ModalForm() { override var title: String = "My Modal" val line = lineText { label = "Line of Text" placeholder = "Enter something..." } }

Just like with command arguments, the constructor for your ModalForm subtype must be passed to your command's builder function. When your command is executed, the modal is provided as an argument to your command's action function.

publicSlashCommand(modal = ::MyModal) { name = "my-command" action { modal -> respond { content = "Text: ${modal.line.value}" } } }

For more information on the Modal system (and to get a few tips on how else to use it), see the dedicated documentation.

Command Objects

When you register a command, the builder function will return an object that extends the Command type. This type provides generic access to basic command data and functionality.

The intended public API is described below. However, it's possible to extend this type (and the other command types) if you want to implement your own customized command types.

The Command type extends the Lockable and KordExKoinComponent types. For more information on the other APIs provided by this type, we recommend examining it in your IDE.

Functions

Name	Arguments	Description
`requireBotPermissions`	`varargPermission`	If your bot requires any permissions to be able to execute the command, use this function to register those permissions. If the command is executed while the bot does not have the specified permissions, an error will be sent to the user, explaining which permissions the bot is missing.

Properties

Mutable properties may be set in the builder function used to register your command.

	Name	Type	Description
🏷️	`bundle`	`String?`	Translation bundle to use - default to `null`, which falls back to the extension's defined bundle.
	`extension`	`Extension`	The extension that this command belongs to.
	`kord`	`Kord`	Quick access to the bot's Kord instance.
	`locking`	`Boolean`	Whether to use a Mutex to prevent this command from being run concurrently with itself. Defaults to `false`, allowing the command to run multiple times concurrently.
🌐	`name`	`String`	The command's name, which is used for invocation. This property must be set for the command to be registered, and has no default value.
	`sentry`	`SentryAdapter`	Quick access to the bot's Sentry adapter.
	`translationsProvider`	`TranslationsProvider`	Quick access to the bot's translations provider.

Context Objects

When a command is executed, the provided action block is run. This block is a receiver function against a subtype of the CommandContext type, which provides an API that allows you to work with the command's execution data and respond to the user.

The CommandContext type extends the TranslatableContext and KordExKoinComponent types.

Functions

Name	Description
`getChannel`	Returns the relevant `ChannelBehavior` for this command execution.
`getGuild`	Returns the relevant `GuildBehavior` for this command execution, or `null` if this command was executed in a DM.
`getLocale`	Resolves and returns the relevant `Locale` object for this command execution, using the bot's configured locale resolvers.
`getMember`	Returns the relevant `MemberBehavior` for this command execution, or `null` if this command was executed in a DM.
`getUser`	Returns the relevant `UserBehavior` for this command execution, or `null` if this command was executed by a webhook.
`translate`	There are a number of overloads for this function, which allows you to translate a given string key based on the resolved locale or another given locale. For more information on translations, see the dedicated documentation, and examine the functions in your IDE for more information on their parameters.

Properties

Name	Type	Description
🏷️ `bundle`	`String?`	The command's translation bundle, falling back to the extension's if not defined.
`cache`	`MutableStringKeyedMap <Any>`	The cache object used for this execution, which may contain data set by the current command's defined Checks.
`command`	`Command`	Quick access to the object representing the current command. No generic is used for this property, but subtypes will provide a separate property with a more concrete type.
`commandName`	`String`	The command's name. For chat commands, this will be the name used to execute the command, which may be an alias.
`eventObj`	`Event`	The event object that caused this command execution. No generic is used for this property, but subtypes will provide a separate property with a more concrete type, generally named `event`.
`sentry`	`SentryContext`	Quick access to the bot's Sentry context.
`translationsProvider`	`TranslationsProvider`	Quick access to the bot's translations provider.

Last modified: 03 September 2024

Commands

Arguments Classes

Modal Forms

Command Objects

Functions

Properties

Context Objects

Functions

Properties