The bot class - ExtensibleBot is the absolute core of anything that makes use of Kord Extensions. It's the jumping-off point for your bot, dispatching commands, handling events and keeping track of extensions.
The class itself also contains several useful APIs - but before we get into that, let's go over how it can be set up.
To make it easier to configure, your bot should be created using the ExtensibleBot factory function. This function always requires a Discord bot token parameter and executable body.
val bot = ExtensibleBot(TOKEN) { // this: ExtensibleBotBuilder
}
Within this builder, you'll find many, many ways to configure your bot. These settings are broken up into their own builders, which helps to keep things separated.
The cache builder allows you to change the settings for Kord's cache. By default, Kord Extensions does two things over Kord's defaults:
lruCache for caching messages, with a maximum size of 10,000cacheWithCachingRestFallback, which means that Kord will cache entities that come from REST as well as those from Discord's gateway - not just the latterIt's possible that using this strategy may give you incomplete data, when dealing with types of data that aren't fully cached automatically - for example, if a member is banned from a guild and you didn't have all the bans in the cache, Kord will only return bans that the bot has seen happen. If this is a problem for you, you have a few options:
- Fill the cache yourself - for example: for guild members, set up your
membersbuilder to request all guild members and set up the required intents- Change the default strategy to
cacheWithRestFallback, which won't cache anything retrieved via REST calls- Temporarily use another supply strategy when retrieving types of data that is affected by this - for example:
guild.withStrategy(EntitySupplyStrategy.cachingRest).bans- Use one of the equivalent
fetchfunctions to skip the cache entirelyFor most purposes, the first approach will be the most sensible - but it's really going to depend on your bot, and how you need the cache to work.
cache {
cachedMessages = 10_000
defaultStrategy = EntitySupplyStrategy.cacheWithCachingRestFallback
}
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
kord |
KordCacheBuilder |
ClientResources |
Register a builder used to configure Kord's cache directly |
transformCache |
Kord |
DataCache |
Register a builder used to modify Kord's data cache settings directly |
| Name | Type | Default | Description |
|---|---|---|---|
cachedMessages |
Int? |
10_000 |
The number of messages to store in Kord's cache by default - set to null to disable |
defaultStrategy |
EntitySupplyStrategy |
cacheWithCachingRestFallback |
The caching strategy to configure Kord with |
The components builder allows you to change the settings for the Kord Extensions components system. Currently, there isn't much to configure here - the builder as added to avoid breaking the components settings API later on down the line.
components {
registry(::MyComponentRegistrySubclass)
}
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
callbackRegistry |
Register a callable (usually a constructor) used to construct a ComponentCallbackRegistry subclass |
||
registry |
Register a callable (usually a constructor) used to construct a ComponentRegistry subclass |
The applicationCommands builder allows you to configure how your bot handles application commands - which include message commands, slash commands and user commands.
In previous versions of Kord Extensions, application commands were disabled by default. As Discord will be requiring that all verified bots exclusively use application commands, they are now enabled by default. Please remember to configure them as needed, and make sure you test them before you deploy them!
applicationCommands {
// Register all global commands on this guild for testing
defaultGuild(TEST_GUILD_ID)
}
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
applicationCommandRegistry |
- | - | If you have a custom application command registry, you can register it by passing the constructor (or a builder) here |
messageCommandCheck |
MessageCommandCheck |
- | Register a check to apply to all message commands in all extensions |
slashCommandCheck |
SlashCommandCheck |
- | Register a check to apply to all message commands in all extensions |
userCommandCheck |
UserCommandCheck |
- | Register a check to apply to all message commands in all extensions |
| Function | Parameters | Description |
|---|---|---|
defaultGuild |
Snowflake |
Specify a guild that all application commands will be registered to if none are specified directly - this is intended for testing |
defaultGuild |
String |
Specify a guild that all application commands will be registered to if none are specified directly - this is intended for testing |
defaultGuild |
ULong |
Specify a guild that all application commands will be registered to if none are specified directly - this is intended for testing |
| Name | Type | Default | Description |
|---|---|---|---|
defaultGuild |
Snowflake? |
null |
Specify a guild that all application commands will be registered for if none are specified directly - this is intended for testing |
enabled |
Boolean |
true |
Whether to enable the application commands system at all |
register |
Boolean |
true |
Whether to attempt to register application commands with Discord - you'll want to disable this on everything but your first shard, if you're working with advanced sharding logic |
The chatCommands builder allows you to configure how your bot handles chat commands - prefixed commands sent as text directly within Discord messages. This includes configuration of the command prefix, as well as a few other things.
In previous versions of Kord Extensions, chat commands were enabled by default. As Discord will be requiring that all verified bots exclusively use application commands, they are now disabled by default. If you'd like to use them, you'll need to enable them by setting
enabledtotruebelow.
chatCommands {
defaultPrefix = "!"
enabled = true
invokeOnMention = true
}
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
check |
- | MessageCreateEvent |
Register a check to apply to all message commands in all extensions |
prefix |
MessageCreateEvent |
String |
Register the prefix callback, used for different command prefixes in different contexts - the string property represents the default prefix, which should be returned if no modifications are made |
registry |
If you have a custom message command registry, you can register it by passing the constructor (or a builder) here |
| Name | Type | Default | Description |
|---|---|---|---|
defaultPrefix |
String |
"!" |
The default command prefix to use when there's no prefix callback, or it doesn't return a custom prefix |
enabled |
Boolean |
false |
Whether to enable the message commands system at all |
invokeOnMention |
Boolean |
true |
Whether to allow people to run commands by mentioning the bot instead of using a command prefix |
The extension builder allows you to register extensions for loading, and configure bundled (and external) extensions. If you're writing an extension of your own, you should register it here - and you can provide an extension method to do so if you're creating a module for other people to use.
extensions {
add(::TestExtension)
help {
pingInReply = false
color { DISCORD_BLURPLE }
}
semtry {
enable = true
dsn = "abc123"
}
}
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
add |
- | - | Register an extension to be loaded - you'll usually want to pass the extension's constructor here, using ::ClassName |
help |
HelpExtensionBuilder |
- | Configure the bundled help extension, and options that all help extensions may use |
sentry |
SentryExtensionBuilder |
- | Configure the bundled Sentry extension and integration |
The help builder is used to configure options for the help extension, as well as disabling the bundled one if you're using an alternative. If you're writing your own help extension, please note that it's expected to respect these options as far as is possible.
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
color / colour |
MessageCreateEvent |
- | Define a callback that returns a Kord Color object to use for help embed colours - this will be called for every page generated, so you can disco it up if you'd like! |
check |
MessageCreateEvent |
- | Define an extra check that must pass for help commands to be executed |
| Name | Type | Default | Description |
|---|---|---|---|
deleteInvocationOnPaginatorTimeout |
Boolean |
false |
Whether to remove the user's help command invocation after the paginator timeout is reached |
deletePaginatorOnTimeout |
Boolean |
false |
Whether to delete the help command's paginator after the paginator timeout is reached |
enableBundledExtension |
Boolean |
true |
Whether to enable the built-in help extension |
paginatorTimeout |
Long |
60 |
Time to wait before the help paginator times out, in seconds |
pingInReply |
Boolean |
true |
Whether to ping users in reply to their help command invocation |
The sentry builder is used to configure the Kord Extensions Sentry integration, as well as enabling the bundled extension for collecting feedback.
Note: Enabling Sentry here without configuring it properly will result in strange errors!
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
builder |
- | Register a builder used to construct a SentryAdapter instance, returning it - usually the constructor of a custom subclass, if you have one |
|
setup |
SentryAdapter |
- | Register the function in charge of setting up the SentryAdapter by calling its setup function, if you need to customise that |
| Name | Type | Default | Description |
|---|---|---|---|
enable |
Boolean |
false |
Whether to enable the Sentry integration |
feedbackExtension |
Boolean |
false |
Wheher to enable the bundled Sentry feedback extension, which adds feedback commands and give users Sentry error IDs to provide feedback for |
pingInreply |
Boolean |
true |
Whether to ping users in response to their feedback command invocations |
debug |
Boolean |
false |
Whether to enable Sentry's debug mode |
dsn |
String? |
null |
Your Sentry DSN, required to enable |
distribution |
String? |
null |
Distribution name to send to Sentry |
environment |
String? |
null |
Environment name to send to Sentry |
release |
String? |
null |
Release version to send to Sentry |
serverName |
String? |
null |
Server name to send to Sentry |
The hooks builder allows you to register callbacks to be run during various stages of the bot's lifecycle - for example, to register a Koin module after Koin has been set up.
hooks {
kordShutdownHook = true
afterKoinSetup {
println("Koin has been set up!")
}
}
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
beforeExtensionsAdded |
ExtensibleBot |
Register a callback to run before any extensions are loaded | |
afterExtensionsAdded |
ExtensibleBot |
Register a callback to run after all extensions are loaded | |
beforeKoinSetup |
Register a callback to run before Koin has been set up | ||
afterKoinSetup |
Register a callback to run after Koin has been set up | ||
beforeStart |
ExtensibleBot |
Register a callback to run just before the bot tries to connect to Discord | |
created |
ExtensibleBot |
Register a callback to run just after the bot has been created | |
setup |
ExtensibleBot |
Register a callback to run just after the bot has been created and fully set up | |
extensionAdded |
ExtensibleBot |
Extension |
Register a callback to run for every extension loaded by the bot |
| Name | Type | Default | Description |
|---|---|---|---|
kordShutdownHook |
Boolean |
true |
Whether to register Kord's shutdown hook, which formally disconnects from the gateway on shutdown |
The intents builder allows you to directly provide a set of intents to Kord. Intents define what events your bot gets and what data it has access to, and it can be useful to define a limited set of intents to cut down on event processing. There are also priveleged intents, which are disabled by default and must be enabled in the developer console for your bot.
Intents may be added and removed using the unary + and - operators. There are also two additional parameters you can pass to the intents builder function:
| Parameter | Type | Default | Description |
|---|---|---|---|
addDefaultIntents |
Boolean |
true |
Whether to add all non-privileged intents to the builder automatically |
addExtensionIntents |
Boolean |
true |
Whether to add all required intents from the bot's loaded extensions to the builder automatically |
The above properties also mirror the default behavior of the intents builder - if you don't configure it yourself, Intents.nonPrivileged and all required intents from the bot's loaded extensions will be added.
intents {
+Intent.GuildMembers
+Intent.GuildPresences
}
The i18n builder allows you to configure internationalisation settings, allowing you to tell the bot what Locale it should be using in various contexts.
Where LocaleResolver is mentioned below, it's defined as a typealias like this:
typealias LocaleResolver = suspend (
guild: GuildBehavior?,
channel: ChannelBehavior?,
user: UserBehavior?
) -> Locale?
i18n {
defaultLocale = SupportedLocales.GERMAN
}
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
localeResolver |
- | - | Register a LocaleResolver that returns a locale based on the parameters passed to it, as defined above |
translationsProvider |
- | Locale | If required, register a builder (usually the class constructor) for a custom TranslationProvider subclass |
| Name | Type | Default | Description |
|---|---|---|---|
defaultLocale |
Locale |
SupportedLocales.ENGLISH |
The default Locale to fall back to if the configured locale resolvers don't return a different one |
Two DSL functions are provided for advanced use-cases.
kord {
// Directly interact with the KordBuilder while creating the Kord instance
}
customKordBuilder { token, builder ->
// Return a custom Kord instance here, probably a subtype
}
| Builder | Receiver | Parameters | Description |
|---|---|---|---|
kord |
KordBuilder |
- | Directly interact with the KordBuilder being used to construct the Kord instance, if required - can be called multiple times to register multiple callbacks |
customKordBuilder |
- | String, KordBuilder.() |
Call this to register a callback mimicking the Kord factory function, which you can use to supply a Kord subclass if you need to |
The members builder allows you to configure a few member-related settings, including whether to request guild members from Discord when the bot connects or joins a guild.
To make use of
fillPresences, you must specify theGuildPresencesintent in theintentsbuilder, and enable it in your bot's developer console.To request all members from any guild using the functions, you must specify the
GuildMembersintent in theintentsbuilder, and enable it in your bot's developer console.These intents may be subject to approval from Discord, and require official verification from them when your bot reaches 100 guilds.
members {
fillPresences = true
all()
}
| Function | Parameters | Description |
|---|---|---|
all |
Specify that you want to receive all members from all guilds | |
none |
Specify that you don't want to receive any members from any guilds - this is the default behaviour | |
fill |
Collection<Snowflake> |
Specify a list of specific guild IDs that you want to receive all members from |
fill |
Collection<String> |
Specify a list of specific guild IDs that you want to receive all members from |
fill |
Collection<ULong> |
Specify a list of specific guild IDs that you want to receive all members from |
fill |
Snowflake |
Specify a guild ID that you want to receive all members from |
fill |
String |
Specify a guild ID that you want to receive all members from |
fill |
ULong |
Specify a guild ID that you want to receive all members from |
| Name | Type | Default | Description |
|---|---|---|---|
fillPresences |
Boolean? |
null |
Whether to also request members' presences when requesting member lists for specific guilds - null for Kord's default behaviour, which is equivalent to false at the moment |
lockMemberRequests |
Boolean |
false |
Setting this to true will make guild member requests sequential, preventing extended rate-limiting on large sharded bots |
The plugins builder allows you to configure the settings for the KordEx dynamic plugin-loading system. By default, this will load plugins from the plugins/ folder located within the bot's working directory.
Plugins are not quite ready for use. While functional, there is no configuration or data storage tooling provided, which significantly limits the usefulness of the plugin system at the moment.
plugins {
fillPresences = true
all()
}
| Function | Parameters | Description |
|---|---|---|
disable |
String |
Specify a plugin ID that should not be loaded by the plugin manager - can be called multiple times for multiple plugins |
pluginPath |
Path |
Add a path to a folder that plugins should be loaded from |
pluginPath |
String |
Add a path to a folder that plugins should be loaded from |
| Name | Type | Default | Description |
|---|---|---|---|
enabled |
Boolean |
true |
Whether the plugin system should be enabled at all |
manager |
(List<Path>) -> PluginManager |
::PluginManager |
If you need to use a custom plugin manager class, you can specify the constructor here |
The presence builder allows you to set the initial presence your bot will have when it connects. This will not lock the bot's presence, though - you can still change it later.
This provides direct access to Kord's PresenceBuilder.
presence {
status = PresenceStatus.DoNotDisturb
watching("for intruders")
}
The sharding builder allows you to configure Kord's sharding settings, which by default will automatically shard your bot across multiple gateways in a single process.
This provides direct access to Kord's own sharding builder. You should only need this for advanced use-cases.
sharding { recommended ->
Shards(recommended)
}
The ExtensibleBot object itself has some API methods that you may find useful when writing your own extensions.
| Function | Parameters | Description |
|---|---|---|
findExtension |
T: Extension |
Find the first extension matching the given type, or null if none were found |
findExtensions |
T: Extension |
Find all extensions matching the given type |
loadExtension |
String |
If an extension was unloaded, call this to load it by name |
send |
Event |
Send a custom event through the bot's events flow, for other extensions to react to |
unloadExtension |
String |
If an extension is loaded, call this to unload it by name |