Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/azuyamat/kormmand
Lightweight command manager for Kord (The Kotlin Discord API wrapper)
https://github.com/azuyamat/kormmand
discord kord kotlin
Last synced: 1 day ago
JSON representation
Lightweight command manager for Kord (The Kotlin Discord API wrapper)
- Host: GitHub
- URL: https://github.com/azuyamat/kormmand
- Owner: Azuyamat
- License: mit
- Created: 2023-10-09T22:03:12.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2023-10-16T03:34:37.000Z (about 1 year ago)
- Last Synced: 2024-04-24T03:22:28.344Z (7 months ago)
- Topics: discord, kord, kotlin
- Language: Kotlin
- Homepage:
- Size: 215 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Kormmand
A simple `command`, `button`, `select menu` and `modal` manager for [Kord](https://github.com/kordlib/kord), a Kotlin Discord
API
wrapper.
> This project is no longer being maintained. Short-lived, resting in peace, awaiting its **sequel**.
**Planned features:**
- [x] Slash command manager
- [X] Button manager
- [X] Select menu manager
- [X] Modal manager
- [ ] Automatic help menu
## Made with love by [@azuyamat](https://azuyamat.com)
# Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)
## Installation
Kormmand is available on [Jitpack](https://jitpack.io). Here is how to add it to your project.
> Note: Replace `Tag` with the latest version of Kormmand.
Maven
#### Repository
```xml
jitpack.io
https://jitpack.io
```
#### Dependency
```xml
com.github.Azuyamat
Kormmand
Tag
```
Gradle
#### Repository
```groovy
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
```
#### Dependency
```groovy
dependencies {
implementation 'com.github.Azuyamat:Kormmand:Tag'
}
```
Kotlin Gradle
#### Repository
```groovy
repositories {
mavenCentral()
maven("https://jitpack.io")
}
```
#### Dependency
```groovy
dependencies {
implementation("com.github.Azuyamat:Kormmand:Tag")
}
```
## Usage
Commands
### Creating a command
To create a command, start by initializing a class that extends the `Command` interface.
Don't forget to include `@CommandClass` and `@InteractionClass` annotations. Otherwise, the command won't be registered.
```kotlin
@InteractionClass
@CommandClass
class HelpCommand : Command {
override val name: String = "help"
override val description: String = "Show the help menu."
override suspend fun execute(event: GuildChatInputCommandInteractionCreateEvent) {
event.interaction.respondPublic {
content = "This is a test" }
}
}
```
### Registering commands
For commands to function, they must first be registered. To do this, you must create a `CommandManager` and register
the commands via their package name.
Multiple command
#### Global commands
```kotlin
val commandManager = CommandManager(kord).apply {
registerInteractions("commands")
}
```
#### Guild commands
Registering guild commands only requires that you add the guild id as a parameter.
```kotlin
val commandManager = CommandManager(kord).apply {
registerInteractions("commands", "GUILDID")
}
```
### Permission requirements
To add permission requirements to a command, you must add the `permission` property to the command.
```kotlin
@InteractionClass
@CommandClass
class HelpCommand : Command {
override val name: String = "help"
override val description: String = "Show the help menu."
override val permission: Permission = Permission.Administrator
override suspend fun execute(event: GuildChatInputCommandInteractionCreateEvent) {
event.interaction.respondPublic {
content = "You are an admin!" }
}
}
```
### Adding subcommands
To add subcommands to a command, you must add the `builder` property to the command.
```kotlin
@InteractionClass
@CommandClass
class HelpCommand : Command {
override val name: String = "help"
override val description: String = "Show the help menu."
override val builder: GlobalChatInputCreateBuilder.() -> Unit = {
subCommand("info", "Get info about a user."){
user("user", "The user to get info about.")
}
}
override suspend fun execute(event: GuildChatInputCommandInteractionCreateEvent) {
val interaction = event.interaction
val c = interaction.command
val subCommandName = when (c) {
is RootCommand -> null
is GroupCommand -> c.name
is SubCommand -> c.name
}
if (subCommandName == "info") {
interaction.respondPublic {
content = "This is a test"
}
}
}
}
```
Buttons
### Creating a button
To create a button, start by initializing a class that extends the `Button` interface.
Don't forget to add the `@InteractionClass` annotation. Otherwise, the button won't be registered.
```kotlin
@InteractionClass
class HelpButton : Button {
override val id: String = "help"
override val name: String = "help" // Not required for buttons
override val description: String = "Show the help menu." // Not required for buttons
override suspend fun execute(event: ButtonInteractionCreateEvent) {
event.interaction.respondPublic {
content = "This is a test" }
}
}
```
### Registering buttons
For a button to function, it must be registered by the bot at runtime. To do this, you must create a `ButtonManager`
and register the button.
Multiple buttons
```kotlin
val buttonManager = ButtonManager(kord).apply {
registerInteractions("buttons")
}
```
Guild-specific buttons
Don't know why you'd do this but you can register buttons that will only run in specific guilds
```kotlin
val buttonManager = ButtonManager(kord).apply {
registerInteractions("buttons", "GUILDID")
}
```
### Permission requirements
To add permission requirements to a button, you must add the `permission` property to the button.
```kotlin
@InteractionClass
class HelpButton : Button {
override val name: String = "help" // Not required for buttons
override val description: String = "Show the help menu." // Not required for buttons
override val permission: Permission = Permission.Administrator
override suspend fun execute(event: ButtonInteractionCreateEvent) {
event.interaction.respondPublic {
content = "You are an admin!" }
}
}
```
Modals
### Creating a modal
To create a modal, start by initializing a class that extends the `Modal` interface.
Don't forget to add the `@InteractionClass` annotation. Otherwise, the modal won't be registered.
```kotlin
@InteractionClass
class HelpModal : Modal {
override val id: String = "modal"
override val name: String = "modal" // Not required for modals
override val description: String = "Show the help menu." // Not required for modals
override suspend fun execute(event: ModalSubmitInteractionCreateEvent) {
event.interaction.respondPublic {
content = "This is a test" }
}
}
```
### Registering modals
For a modal to function, it must be registered by the bot at runtime. To do this, you must create a `ModalManager`
and register the modal's package.
Multiple modals
```kotlin
val modalManager = ModalManager(kord).apply {
registerInteractions("modals")
}
```
Guild-specific modals
Don't know why you'd do this but, you can register guild-specific modals
```kotlin
val modalManager = ModalManager(kord).apply {
registerInteractions("modals", "GUILDID")
}
```
### Permission requirements
To add permission requirements to a command, you must add the `permission` property to the modal.
```kotlin
@InteractionClass
class HelpModal : Modal {
override val name: String = "help" // Not required for modals
override val description: String = "Show the help menu." // Not required for modals
override val permission: Permission = Permission.Administrator
override suspend fun execute(event: ModalSubmitInteractionCreateEvent) {
event.interaction.respondPublic {
content = "You are an admin!" }
}
}
```
Select Menus
### Creating a select menu
To create a select menu, start by initializing a class that extends the `SelectMenu` interface.
Don't forget to add the `@InteractionClass` annotation. Otherwise, the select menu won't be registered.
```kotlin
@InteractionClass
class HelpMenu : SelectMenu {
override val id: String = "jeff"
override val name: String = "jeff" // Not required for select menus
override val description: String = "Show the help menu." // Not required for select menus
override suspend fun execute(event: SelectMenuInteractionCreateEvent) {
event.interaction.respondPublic {
content = "This is a test" }
}
}
```
### Registering a menu
For a select menu to function, it must be registered by the bot at runtime. To do this, you must create a
`SelectMenuManager`
and register the select menu's package.
Multiple select menus
```kotlin
val selectMenuManager = ModalManager(kord).apply {
registerInteractions("selectMenus")
}
```
Guild-specific select menus
Once again, don't know why you'd do this but you can register guild-specific select menus
```kotlin
val selectMenuManager = ModalManager(kord).apply {
registerInteractions("selectMenus", "GUILDID")
}
```
### Permission requirements
To add permission requirements to a command, you must add the `permission` property to the select menu.
```kotlin
@InteractionClass
class HelpMenu : SelectMenu {
override val name: String = "help" // Not required for select menu
override val description: String = "Show the help menu." // Not required for select menu
override val permission: Permission = Permission.Administrator
override suspend fun execute(event: SelectMenuInteractionCreateEvent) {
event.interaction.respondPublic {
content = "You are an admin!" }
}
}
```
> *Note: Buttons, modals and select menus use the first part of the interaction id. This means you can split your
> interaction id by `//` and use the first part as the id while having the rest as interaction parameters.*
>
> Example:
> ```kotlin
> val task = interaction.modalId.split("//")[1]
> ```
## Contributing
Contributions are welcome! If you have any issues or feature requests, please open an issue or a pull request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.