From d13571af4ae0fe808d95b9cd70c2b368208d247d Mon Sep 17 00:00:00 2001 From: Gareth Coles Date: Sun, 10 Dec 2023 14:46:54 +0000 Subject: [PATCH] Slash commands --- Writerside/topics/core/Commands.topic | 2 +- Writerside/topics/core/Events.topic | 18 +- Writerside/topics/core/Exceptions.topic | 6 +- Writerside/topics/core/Extensions.topic | 2 +- Writerside/topics/core/The-Bot.topic | 4 +- .../core/commands/Application-Commands.topic | 31 +- .../topics/core/commands/Chat-Commands.topic | 15 +- .../topics/core/commands/Converters.topic | 2 +- .../application/Context-Commands.topic | 103 ++++- .../commands/application/Slash-Commands.topic | 437 +++++++++++++++++- 10 files changed, 589 insertions(+), 31 deletions(-) diff --git a/Writerside/topics/core/Commands.topic b/Writerside/topics/core/Commands.topic index de8509bd..7f01a21b 100644 --- a/Writerside/topics/core/Commands.topic +++ b/Writerside/topics/core/Commands.topic @@ -437,7 +437,7 @@ cache - MutableStringKeyedMap<Any> + MutableStringKeyedMap <Any> The cache object used for this execution, which may contain data set by the current command's diff --git a/Writerside/topics/core/Events.topic b/Writerside/topics/core/Events.topic index 29d470c4..5fedb535 100644 --- a/Writerside/topics/core/Events.topic +++ b/Writerside/topics/core/Events.topic @@ -39,7 +39,7 @@
  • body - the function receiver which binds this tho - EventHandler<T>. + EventHandler <T>.
    • @@ -61,7 +61,7 @@ - EventContext<T> + EventContext <T> @@ -76,7 +76,7 @@ - CheckContext<T> + CheckContext <T> @@ -247,7 +247,7 @@ - MutableStringKeyedMap<Any> + MutableStringKeyedMap <Any> @@ -259,7 +259,7 @@ eventHandler - EventHandler<T> + EventHandler <T> The current event handler object. @@ -311,7 +311,7 @@

    Kord Extensions sets the customContext property for all events (Kord or otherwise) to an empty - MutableStringKeyedMap<Any>. + MutableStringKeyedMap <Any>. This allows you to store extra data on your events as part of processing.

    @@ -333,7 +333,7 @@ E.extraData - MutableStingKeyedMap<Any> + MutableStingKeyedMap <Any> Quick access to the properly-cast customContext property. @@ -345,9 +345,9 @@

    - The following functions are extensions on the StringKeyedMap<*> type. + The following functions are extensions on the StringKeyedMap <*> type. This will be represented using S below. - Additionally, MutableStringKeyedMap<*> will be represented using M + Additionally, MutableStringKeyedMap <*> will be represented using M below.

    diff --git a/Writerside/topics/core/Exceptions.topic b/Writerside/topics/core/Exceptions.topic index d99c8f27..12701d43 100644 --- a/Writerside/topics/core/Exceptions.topic +++ b/Writerside/topics/core/Exceptions.topic @@ -92,7 +92,7 @@ argument - Argument<*>? + Argument <*>? The Argument object representing the argument that failed to parse. @@ -257,7 +257,7 @@ builder - ConverterBuilder<*> + ConverterBuilder <*> The converter builder that failed to validate. @@ -392,7 +392,7 @@ clazz - KClass<out Extension> + KClass <out Extension> The invalid extension's class. diff --git a/Writerside/topics/core/Extensions.topic b/Writerside/topics/core/Extensions.topic index 11a27f65..3233b51b 100644 --- a/Writerside/topics/core/Extensions.topic +++ b/Writerside/topics/core/Extensions.topic @@ -337,7 +337,7 @@ intents - MutableSet<Intent> + MutableSet <Intent> { } diff --git a/Writerside/topics/core/The-Bot.topic b/Writerside/topics/core/The-Bot.topic index 96e6a047..0d22834c 100644 --- a/Writerside/topics/core/The-Bot.topic +++ b/Writerside/topics/core/The-Bot.topic @@ -249,7 +249,7 @@ events - SharedFlow<Any> + SharedFlow <Any> Shared flow which combined the events sent by both Kord and Kord Extensions. @@ -258,7 +258,7 @@ eventPublisher - MutableSharedFlow<Any> + MutableSharedFlow <Any> Mutable shared flow used for event publishing. diff --git a/Writerside/topics/core/commands/Application-Commands.topic b/Writerside/topics/core/commands/Application-Commands.topic index 5b8e07a6..0a6df88b 100644 --- a/Writerside/topics/core/commands/Application-Commands.topic +++ b/Writerside/topics/core/commands/Application-Commands.topic @@ -3,7 +3,7 @@ SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd"> + title="Application Commands" id="Application-Commands">

    Application commands are a special type of command that makes use of Discord's interaction system. @@ -67,7 +67,7 @@ check - CheckWithCache<E> + CheckWithCache <E> Register a check that must pass for the command's action to be run, which is @@ -121,6 +121,31 @@ Description + + + Required Properties + + + + + name + String + + + Required: The command's name, which is used to invoke the command + and is displayed on Discord. + Your command's name must follow + + Discord's naming requirements. + + + + + + Optional Properties + + + allowByDefault Boolean @@ -189,7 +214,7 @@ genericCommand - ApplicationCommand<*> + ApplicationCommand <*> Generic command object, representing the command this context belongs to. diff --git a/Writerside/topics/core/commands/Chat-Commands.topic b/Writerside/topics/core/commands/Chat-Commands.topic index 9f0d83ca..a94567a9 100644 --- a/Writerside/topics/core/commands/Chat-Commands.topic +++ b/Writerside/topics/core/commands/Chat-Commands.topic @@ -110,7 +110,7 @@ action { message.respond( - "User ${arguments.user.mention} has permission to mention everyone." + "Hey, ${arguments.user.mention}! Get pinged!" ) } } @@ -133,7 +133,7 @@ chatCommandCheck - CheckWithCache<MessageCreateEvent> + CheckWithCache <MessageCreateEvent> Register a check that must pass for the action @@ -203,14 +203,12 @@ action - ChatCommandContext<Arguments> + ChatCommandContext <Arguments> Required: Register the command's action, which will be run when the command is invoked. - Provide the constructor for an Arguments subtype as the first argument to this - function if your command takes any arguments. @@ -222,7 +220,7 @@ check - CheckWithCache<MessageCreateEvent> + CheckWithCache <MessageCreateEvent> Register a check that must pass for the command's action to be run. @@ -278,7 +276,7 @@ aliases - Array<String> + Array <String> Array of alternative names that may be used to invoke this command. @@ -421,6 +419,7 @@ This builder function mirrors the behavior of the chatCommand builder function defined at Extension level, which you'd normally use to register standalone commands. + Subcommands inherit the checks that are defined in their parent commands. @@ -432,6 +431,7 @@ This builder function allows you to nest grouped commands as deeply as is required. It mirrors the behavior of the chatGroupCommand builder function defined at Extension level. + Subcommands inherit the checks that are defined in their parent commands. @@ -584,7 +584,6 @@ - Data Properties diff --git a/Writerside/topics/core/commands/Converters.topic b/Writerside/topics/core/commands/Converters.topic index 2c13d072..0ca76328 100644 --- a/Writerside/topics/core/commands/Converters.topic +++ b/Writerside/topics/core/commands/Converters.topic @@ -3,7 +3,7 @@ SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd"> + title="Converters ✏️" id="Converters">

    Start typing here...

     \ No newline at end of file diff --git a/Writerside/topics/core/commands/application/Context-Commands.topic b/Writerside/topics/core/commands/application/Context-Commands.topic index c693cde9..bf55c988 100644 --- a/Writerside/topics/core/commands/application/Context-Commands.topic +++ b/Writerside/topics/core/commands/application/Context-Commands.topic @@ -13,11 +13,112 @@

    - When registered by a bot, context commands are visible in a menu named Apps. + When registered by your bot, context commands are visible in a menu named Apps. There are two types of context command — message commands and user commands. They have identical APIs, aside from the target data supplied to them by Discord.

    + + The following APIs are available on the Extension type, which you can use to define your + context commands and modify their behavior. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameReceiverDescription
    + Checks +
    messageCommandCheckCheckWithCache <MessageCommandInteractionCreateEvent> + Register a check that must pass for the action + belonging to all message commands defined within this extension to be run. + For more information on checks, see the dedicated documentation. +
    userCommandCheckCheckWithCache <UserCommandInteractionCreateEvent> + Register a check that must pass for the action + belonging to all user commands defined within this extension to be run. + For more information on checks, see the dedicated documentation. +
    + Commands +
    ephemeralMessageCommandEphemeralMessageCommand + Register an ephemeral message command. + + This builder function optionally takes the constructor of a + modal form class as the first argument, + representing the modal form to display and await input for when the command is executed. +
    ephemeralUserCommandEphemeralUserCommand + Register an ephemeral user command. + + This builder function optionally takes the constructor of a + modal form class as the first argument, + representing the modal form to display and await input for when the command is executed. +
    publicMessageCommandPublicMessageCommand + Register a public message command. + + This builder function optionally takes the constructor of a + modal form class as the first argument, + representing the modal form to display and await input for when the command is executed. +
    publicUserCommandPublicUserCommand + Register a public user command. + + This builder function optionally takes the constructor of a + modal form class as the first argument,s + representing the modal form to display and await input for when the command is executed. +
    +     +     +

    Message commands are registered by calling the relevant functions in diff --git a/Writerside/topics/core/commands/application/Slash-Commands.topic b/Writerside/topics/core/commands/application/Slash-Commands.topic index 42351817..acc6add5 100644 --- a/Writerside/topics/core/commands/application/Slash-Commands.topic +++ b/Writerside/topics/core/commands/application/Slash-Commands.topic @@ -3,7 +3,440 @@ SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd"> + title="Slash Commands" id="Slash-Commands"> -

    Start typing here...

    +

    + Slash commands are a form of application command, triggered by users + by typing a slash (/) followed by the command's name and arguments, and sending it via + Discord's message input box. +

    + +

    + When registered by your bot, slash commands are visible in a menu displayed above Discord's message + input box when a user types a slash (/) into it. + This menu allows users to browse a list of all available slash commands, and provides access to their + descriptions and arguments. +

    + + + Slash commands support command arguments and + modal forms. + However, there are features and types of argument converters that are unique to slash commands, + and other types of converters that slash commands do not support. + For more information on this, see the dedicated documentation. + + +

    + All builder functions should be called within your extension's setup function when you're + registering commands before the bot starts up. + However, it is also possible to register commands later on in the bot's lifecycle by calling the same + functions. +

    + + + publicSlashCommand(::MyArguments) { + name = "my-command" + description = "Description explaining command usage." + + check { hasPermission(Permission.MentionEveryone) } + + action { + respond { + // Note: Slash commands aren't actually able to mention + // users in most cases + + content = "Hey, ${arguments.user.mention}! Get pinged!" + } + } + } + + + + The following APIs are available on the Extension type, which you can use to define your + slash commands and modify their behavior. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameReceiverDescription
    + Checks +
    slashCommandCheckCheckWithCache <ChatInputCommandInteractionCreateEvent> + Register a check that must pass for the action + belonging to all slash commands defined within this extension to be run. + For more information on checks, see the dedicated documentation. +
    + Commands +
    ephemeralSlashCommandEphemeralSlashCommand + Register an ephemeral slash command. + This builder function optionally takes the constructor of an + arguments class, + the constructor of a modal form class, + or both. +
    publicSlashCommandPublicSlashCommand + Register a public slash command. + This builder function optionally takes the constructor of an + arguments class, + the constructor of a modal form class, + or both. +
    +     +     + + +

    + Standalone commands are the simplest type of slash command, and they're defined using the builder function + corresponding with the intended interaction response type: +

    + + +
  • ephemeralSlashCommand for slash commands that respond ephemerally.
    • +
  • publicSlashCommand for slash commands that respond publicly.
    • +     + +

    + Slash commands extend + the ApplicationCommand type, + and provide some additional APIs. + However, both ephemeral and public slash commands provide an identical API. +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameReceiverDescription
    + Required Builders +
    actionSlashCommandContext <Arguments> +

    + Required: Register the command's action, which will be run + when the command is invoked. + If you provide the constructor for a + modal form class to the registration + function, it will be passed to this builder as the first argument. +

    + +

    + Note: If your command contains any + subcommands or + command groups, + then you may not specify an action block. + Slash commands containing nested commands are not executable on their own. +

    +
    + Optional Builders +
    checkCheckWithCache <ChatInputCommandInteractionCreateEvent> + Register a check that must pass for this command's action to be run. + For more information on checks, see the dedicated documentation. +
    + Nested Command Builders +
    groupSlashGroup + Register a command group. + This builder function takes the name of the command group as its first argument. + Nested commands inherit the checks that are defined in their parent commands. +
    ephemeralSubCommandEphemeralSlashCommand + Register an ephemeral subcommand. + Nested commands inherit the checks that are defined in their parent commands. +
    publicSubCommandPublicSlashCommand + Register a public subcommand. + Nested commands inherit the checks that are defined in their parent commands. +
    +     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescription
    + Required Properties +
    descriptionString + Required: The command's description, which must be a string that + explains what the command does. + This string may not be longer than 100 characters. +
    + Other Properties +
    parentCommandSlashCommand? + This command's parent slash command, if it's a subcommand. +
    parentGroupSlashGroup? + This command's parent command group, if it's a + subcommand that's part of a group. +
    +     +     + + +

    + Slash commands may contain subcommands, which allow you to create a tree of executable commands. + Subcommands are executed by providing the name of the subcommand as an argument to its parent command. + They may be registered by calling the relevant builder functions from within a + standalone command or command group: +

    + + +
  • ephemeralSubCommand for slash commands that respond ephemerally.
    • +
  • publicSubCommand for slash commands that respond publicly.
    • +     + +

    + Subcommands have an identical API to standalone commands. + Additionally, they inherit the checks defined in their parent commands. +

    +     + + +

    + Slash commands may contain command groups, which allow you to provide a nested group of + subcommands. + Grouped commands inherit the checks that are defined in the group's parent command. +

    + +

    + Command groups are not executable on their own, acting only as containers for related subcommands. + Because of this, they provide a much smaller set of APIs. +

    + + + + + + + + + + + + + + + + + + + + + + +
    NameReceiverDescription
    ephemeralSubCommandEphemeralSlashCommand + Register an ephemeral subcommand to this group. + Grouped commands inherit the checks that are defined in the group's parent command. +
    publicSubCommandPublicSlashCommand + Register a public subcommand to this group. + Grouped commands inherit the checks that are defined in the group's parent command. +
    +     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescription
    + Required Properties +
    descriptionString +

    + Required: The command group's description, which must be a + string that explains what the group represents. + This string may not be longer than 100 characters. +

    + +

    + Command group descriptions are not currently displayed in the Discord client, but the API + still requires that you provide them. + Discord has stated that they may be displayed someday, so it's a good idea to write + proper descriptions regardless. +

    +
    + Other Properties +
    parentCommandSlashCommand? + This group's parent slash command. +
    +     +     + + +

    + The SlashCommandContext type is extended by types that match the intended interaction response + type, and these types are used as the receiver for the relevant slash command action blocks. + This type provides relevant APIs on top of the + base application command context object type, + allowing you to efficiently respond to command invocations. +

    + +

    + As mentioned in the + base application command context documentation, + all slash command context types inherit the relevant + interaction context type. +

    + +

    + The following additional APIs are provided: +

    + + + + + + + + + + + + + + + +
    NameTypeDescription
    argumentsT: Arguments +

    + The command's arguments, parsed into the + arguments class + you specified the constructor for when you registered this command. +

    + +

    + If you don't specify the aforementioned constructor, this will be an empty + Arguments object. +

    +
    +     +     \ No newline at end of file