cloud-kord

Cloud integration for Kord slash commands.

An example bot using cloud-kord can be found here.

Installation

Cloud for Kord is available through Maven Central.

MavenGradle (Kotlin)Gradle (Groovy)

<dependencies>
    <dependency>
        <groupId>org.incendo</groupId>
        <artifactId>cloud-kord</artifactId>
        <version>1.0.0-beta.3</version>
    </dependency>
</dependencies>

implementation("org.incendo:cloud-kord:1.0.0-beta.3")

implementation 'org.incendo:cloud-kord:1.0.0-beta.3'

Usage

Command Manager

// Using the "native" KordInteraction sender type:
val commandManager: KordCommandManager<KordInteraction> = KordCommandManager(executionCoordinator) {
  it
}

// Using a custom sender type:
val commandManager: KordCommandManager<KordInteraction> = KordCommandManager(executionCoordinator) {
  it -> senderType
}

where executionCoordinator is an ExecutionCoordinator instance.

You then register the command manager as a Kord event listener. Example:

commandManager.installListener(kord)

The event listener handles command synchronization, command execution and autocompletion. You may manually synchronize commands using commandManager.commandFactory.createGuildCommands(Guild) or commandManager.commandFactory.createGlobalCommands(Kord).

cloud-kord depends on cloud-kotlin-extensions and cloud-kotlin-coroutines. Because Kord is coroutine-based it is recommended that you make use of MutableCommandBuilder as well as suspending command execution handlers. If you use annotated commands you will also want to depend on cloud-kotlin-coroutines-annotations.

Example command registration

commandManager.buildAndRegister("command") {
    required("user", KordParser.userParser())

    suspendingHandler { context ->
        // Always available through an extension function.
        val interaction: KordInteraction = context.interaction
        val user: User = context.get("user")

        interaction.respondEphemeral {
          content = "Hello ${user.mention}"
        }
    }
}

Parsers

Mappings to all existing option types are supported:

• INTEGER: IntegerParser
• NUMBER: DoubleParser
• BOOLEAN: BooleanParser
• STRING: StringParser
• USER: KordParser.userParser()
• CHANNEL: KordParser.channelParser()
• ROLE: KordParser.roleParser()
• MENTIONABLE: KordParser.mentionableParser()
• ATTACHMENT: KordParser.attachmentParser()

Subcommands and subcommand groups are mapped to Cloud literals. Other parsers are by default be mapped to the string option type.

Choices

The suggestion providers will be invoked for option types that support auto completions. You may also use constant choices by using DiscordChoices as the suggestion provider. Example:

commandBuilder.required(
    "integer",
    integerParser(),
    DiscordChoices.integers(1, 2, 3)
)

Choices may be used for custom parsers that get mapped to string choices.

Command Scopes

You may choose where a command is registered to by using CommandScope. You apply the scope to the command builder using:

// Available everywhere (DMs, guilds, etc):
mutableCommandBuilder.scope(CommandScope.global())

// Available in all guilds:
mutableCommandBuilder.scope(CommandScope.guilds())

// Available in specific guilds:
mutableCommandBuilder.scope(CommandScope.guilds(some, guild, ids))

You may implement custom filtering by overriding the command scope predicate for the command factory:

commandManager.commandFactory().commandScopePredicate = { node, scope -> yourLogicHere }

Annotations:

If using annotated commands you may use the @CommandScope annotation. You must first install the builder modifier:

CommandScopeBuilderModifier.install(annotationParser)

You may then use the annotation:

@CommandScope(guilds = { 1337 })
@Command("command")
public suspend void yourCommand() { /* ... */ }

Permissions

You may set the default permissions of the command using Command.Builder.permissions(Permissions) or MutableCommandBuilder.permissions(Permissions) using an instance of Kord’s Permissions class:

commandManager.buildAndRegister("command") {
  // Using a permissions builder
  permissions(Permissions(Permission.Administrator))

  // Using the vararg overload
  permissions(Permission.Administrator)
}

You may use ordinary permissions by setting the permission function in KordCommandManager. This will not hide the commands from the users, so you must do that manually through the server settings.

Settings

You may modify certain behaviors using the KordSettings. You may do this by accessing the Configurable<KordSetting> instance using KordCommandManager.kordSettings().