Annotated text commands

Annotated commands are quick to use but are more limited and may look complex with multiple subcommands, for text commands, the command method must be annotated with @JDATextCommandVariation.

To set the order in which text command variations are checked, set JDATextCommandVariation.order.

Kotlin Java

@Command
@Category("Utility")
class TextPing {
    // There are other properties you can set
    @JDATextCommandVariation(
        // Add more for subcommands
        path = ["ping"],
        description = "Pong!"
    )
    suspend fun onTextPing(
        // Fallback command event since we have no args
        event: CommandEvent
    ) {
        val message = event.reply("Pong!").await()

        val ping = event.jda.getRestPing().await()
        message.editMessage("Pong! $ping ms").queue()
    }
}

@Command
public class TextPing {
    // There are other properties you can set
    @JDATextCommandVariation(
            // Add more for subcommands
            path = { "ping" },
            description = "Pong!"
    )
    public void onTextPing(
            // Fallback command event since we have no args
            CommandEvent event
    ) {
        event.reply("Pong!").queue(message -> {
            event.getJDA().getRestPing().queue(ping -> {
                message.editMessage("Pong! " + ping + " ms").queue();
            });
        });
    }
}

Additional data

You can set more stuff that applies to all variations of a command, use @TextCommandData on one of the variations.

There are other attributes, see references in @JDATextCommandVariation's docs.

Adding options

Options can be added with a parameter annotated with @TextOption.

All supported types are documented under TextParameterResolver, and other types can be added.

Example

Kotlin Java

@Command
class TextSay {
    @JDATextCommandVariation(
        path = ["say"],
        description = "Says something",
        // This will show up in the help command, if the prefix is '!' then it will show:
        // !say I like trains
        example = "I like trains",
    )
    suspend fun onTextSay(event: BaseCommandEvent, @TextOption content: String) {
        event.reply(content).await()
    }
}

@Command
public class TextSay {
    @JDATextCommandVariation(
            path = "say",
            description = "Says something",
            // This will show up in the help command, if the prefix is '!' then it will show:
            // !say I like trains
            example = "I like trains"
    )
    public void onTextSay(BaseCommandEvent event, @TextOption String content) {
        event.reply(content).queue();
    }
}

Inferred option names

Display names of options can be set on the annotation, but can also be deduced from the parameter name, this is natively supported in Kotlin, but for Java, you will need to enable parameter names on the Java compiler.

Generated values

Generated values are parameters that get their values from a lambda everytime a command is run.

You must give one by implementing TextGeneratedValueSupplierProvider.

As always, make sure to check against the command path as well as the option's name.

Example

Kotlin Java

@Command
class TextCreateTime : TextGeneratedValueSupplierProvider {

    override fun getGeneratedValueSupplier(
        commandPath: CommandPath,
        optionName: String,
        parameterType: ParameterType
    ): TextGeneratedValueSupplier {
        if (commandPath.name == "create_time") {
            if (optionName == "timestamp") {
                // Create a snapshot of the instant the command was created
                val now = Instant.now()
                // Give back the instant snapshot, as this will be called every time the command runs
                return TextGeneratedValueSupplier { now }
            }
        }

        error("Unknown generated option: $optionName")
    }

    @JDATextCommandVariation(path = ["create_time"], description = "Shows the creation time of this command")
    suspend fun onTextCreateTime(
        event: CommandEvent,
        @GeneratedOption timestamp: Instant
    ) {
        event.reply("I was created on ${TimeFormat.DATE_TIME_SHORT.format(timestamp)}").await()
    }
}

@Command
@NullMarked // Everything is non-null unless @Nullable
public class TextCreateTime implements TextGeneratedValueSupplierProvider {
    @Override
    public TextGeneratedValueSupplier getGeneratedValueSupplier(CommandPath commandPath, String optionName, ParameterType parameterType) {
        if (commandPath.getName().equals("create_time")) {
            if (optionName.equals("timestamp")) {
                // Create a snapshot of the instant the command was created
                final Instant now = Instant.now();
                // Give back the instant snapshot, as this will be called every time the command runs
                return event -> now;
            }
        }

        throw new IllegalArgumentException("Unknown generated option: " + optionName);
    }

    @JDATextCommandVariation(path = "create_time", description = "Shows the creation time of this command")
    public void onTextCreateTime(
            CommandEvent event,
            @GeneratedOption Instant timestamp
    ) {
        event.reply("I was created on " + TimeFormat.DATE_TIME_SHORT.format(timestamp)).queue();
    }
}

Rate limiting

This lets you reject text commands if the user tries to use them too often, see "Using rate limiters in commands".