The Bot

At the core of your bot is the ExtensibleBot class. This class is the most important part of Kord Extensions, as the jumping-off point for your bot. Among other things, it dispatches commands and event handlers, and keeps track of extensions. It also contains several useful APIs.

Creating a Bot

Before you do anything else, you'll need to create a bot via the ExtensibleBot factory function. This function is a builder that always requires a Discord bot token parameter. The builder can then be used to configure the bot.

            val bot = ExtensibleBot(TOKEN) {
                applicationCommands {
                    defaultGuild(envOrNull("TESTING_GUILD"))
                }

                extensions {
                    add(::MyExtension)

                    help {
                        color { getRandomColor() }
                    }
                }

                hooks {
                    beforeKoinSetup {
                        loadModule {
                            single { Database() } bind Database::class
                        }
                    }
                }

                @OptIn(PrivilegedIntent::class)
                intents {
                    +Intent.GuildMembers
                    +Intent.MessageContent
                }
            }
        

Configuration

The ExtensibleBot builder contains your bot's configuration, which is split up into a series of builder functions. For more information on what options are available and how to use them, see the Configuration section.

ExtensibleBot API

The ExtensibleBot type exposes a number of APIs that may be helpful for advanced use-cases. If you'd like to use them, you can get access to the current object via Koin ⏳.

Functions

Function	Parameters	Description
`close`		Stop the bot by shutting down the Kord instance and stopping the Kord Extensions Koin context. A bot that has been closed can no longer be used, and a new bot must be constructed. This function exists to close and clean up the bot, so a new one may be constructed.
`on`	`Boolean`, `CoroutineScope`, `suspend T.() -> Unit`	Manually subscribe to an event. Most developers will never need to use this directly. If you can register an event handler in an Extension, then that's a far better option.
`send`	`Event`	Send an event to the handlers listening for it. You can use this to send a custom event to be acted upon elsewhere. If possible, use the `KordExEvent` base type instead of Kord's `Event`, as it handles filling out the parameters for you.
`start`		Start up the bot and log into Discord. Blocks the current coroutine until the bot is shut down.
`startAsync`		Start up the bot and log into Discord. Launches the `start` function via Kord's coroutine scope, instead of blocking. Can be used to start the bot from synchronous code.
`stop`		Stop the bot by telling the Kord instances to log out of Discord. This will leave the Koin context intact, so the bot may be restarted later.

The following functions are all related to extension management.

Function	Parameters	Description
`addExtension`	`() -> Extension`	Manually install an extension by constructing and loading it. This is only exposed for advanced use-cases, and you should prefer loading extensions via the bot's configuration instead where possible.
`findExtension`	`reified T`	Find the first loaded extension that is an instance of (or extend) `T`.
`findExtensions`	`reified T`	Find all loaded extensions that are instances of (or extend) `T`.
`loadExtension`	`String`	Reload a previously loaded extension by name. If the extension isn't found or is already loaded, nothing happens.
`removeExtension`	`String`	Unload and remove a registered extension by name. This will prevent the extension from being loaded in the future. If the extension isn't found or loaded, nothing happens.
`unloadExtension`	`String`	Unloaded a currently installed extension by name. If the extension isn't found or loaded, nothing happens.

Properties

Property	Type	Description
`settings`	`ExtensibleBotBuilder`	The builder used when configuring the bot. Provided as a way to access the user-supplied configuration, excluding the bot token.
`events`	`SharedFlow <Any>`	Shared flow which combined the events sent by both Kord and Kord Extensions.
`eventPublisher`	`MutableSharedFlow <Any>`	Mutable shared flow used for event publishing. For most use-cases, you should use the `send` function instead of accessing this directly.

Last modified: 03 September 2024