From 559bdc17cb4ca1d37ccb9328256491bc7993656c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20S=C3=B6derberg?= Date: Thu, 18 Jan 2024 11:10:03 +0100 Subject: [PATCH] feat(discord): document cloud-kord --- .wordlist.txt | 2 + docs/discord/index.md | 2 + docs/discord/kord.md | 170 ++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 175 insertions(+) create mode 100644 docs/discord/kord.md diff --git a/.wordlist.txt b/.wordlist.txt index 1714c05..2df6333 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -92,3 +92,5 @@ ExecutionCoordinator autocompletion MENTIONABLE Subcommands +kord +Kord diff --git a/docs/discord/index.md b/docs/discord/index.md index 580406e..3384616 100644 --- a/docs/discord/index.md +++ b/docs/discord/index.md @@ -7,5 +7,7 @@ The [cloud-discord](https://github.com/incendo/cloud-discord) repository houses Notably, the module contains tooling for integrating with slash commands. - [cloud-jda](./jda.md): Integration for JDA4. No slash command support. - [cloud-jda5](./jda5.md): Integration for JDA5 slash commands. +- [cloud-kord](./kord.md): Integration for Kord slash commands. - [cloud-javacord](./javacord.md): Integration for Javacord. - [example-jda5](https://github.com/Incendo/cloud-discord/tree/master/examples/example-jda5): Example bot using JDA5. +- [example-kord](https://github.com/Incendo/cloud-discord/tree/master/examples/example-kord): Example bot using Kord. diff --git a/docs/discord/kord.md b/docs/discord/kord.md new file mode 100644 index 0000000..93bf94b --- /dev/null +++ b/docs/discord/kord.md @@ -0,0 +1,170 @@ +# cloud-kord + +Cloud integration for [Kord](https://github.com/kordlib/kord) slash commands. + +An example bot using cloud-kord can be found [here](https://github.com/Incendo/cloud-discord/tree/master/examples/example-kord). + +## Installation + +Cloud Annotations is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework). + + +=== "Maven" + + ```xml + + + org.incendo + cloud-kord + 1.0.0-SNAPSHOT + + + ``` + +=== "Gradle (Kotlin)" + + ```kotlin + implementation("org.incendo:cloud-kord:1.0.0-SNAPSHOT") + ``` + +=== "Gradle (Groovy)" + + ```groovy + implementation 'org.incendo:cloud-kord:1.0.0-SNAPSHOT' + ``` + +## Usage + +### Command Manager + +```kotlin +// Using the "native" KordInteraction sender type: +val commandManager: KordCommandManager = KordCommandManager(executionCoordinator) { + it +} + +// Using a custom sender type: +val commandManager: KordCommandManager = KordCommandManager(executionCoordinator) { + it -> senderType +} +``` + +where `executionCoordinator` is an +[ExecutionCoordinator](../core/index.md#execution-coordinators) instance. + +You then register the command manager as a Kord event listener. Example: + +```kotlin +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](../kotlin/extensions.md) +and [cloud-kotlin-coroutines](../kotlin/coroutines.md). 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](../kotlin/annotations.md). + +```kotlin title="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](../core/index.md#suggestions) will be invoked for option types that support +auto completions. +You may also use constant choices by using `DiscordChoices` as the suggestion provider. Example: + +```kotlin +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: + +```java +// 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: + +```java +commandManager.commandFactory().commandScopePredicate = { node, scope -> yourLogicHere } +``` + +#### Annotations: + +If using annotated commands you may use the `@CommandScope` annotation. You must first install the builder modifier: + +```kotlin +CommandScopeBuilderModifier.install(annotationParser) +``` + +You may then use the annotation: + +```kotlin +@CommandScope(guilds = { 1337 }) +@Command("command") +public suspend void yourCommand() { /* ... */ } +``` + +### Permissions + +You may set the default permissions by using `DiscordPermission.of(Long)` as the command permission. Example: + +```kotlin +commandBuilder.permission(1337) +``` + +You may use ordinary permissions by setting the permission function in `KordCommandManager`. + +### Settings + +You may modify certain behaviors using the `KordSetting`s. You may do this by +accessing the `Configurable` instance using `KordCommandManager.kordSettings()`. diff --git a/mkdocs.yml b/mkdocs.yml index 491b26e..ac1621d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,6 +22,7 @@ nav: - cloud-javacord: discord/javacord.md - cloud-jda: discord/jda.md - cloud-jda5: discord/jda5.md + - cloud-kord: discord/kord.md - cloud-minecraft: - cloud-minecraft: minecraft/index.md - cloud-brigadier: minecraft/brigadier.md