Skip to content

Latest commit

 

History

History
252 lines (175 loc) · 8.12 KB

PLUGINS.md

File metadata and controls

252 lines (175 loc) · 8.12 KB

Plugins guide

This document neither explains Kotlin, Kord, nor Kord-Extensions, if you don't know these things stop reading now before complaining about these things not getting explained

Index

What is a plugin

To Mikbot a plugin is essentially a single file changing KordEx configurations, everything else is KordEx and therefor not explained here.

Kord-Extensions already provides "plugins", but KordEx calls them Extensions, a Mikbot plugin is simply one or more KordEx extensions + optional additional KordEx configuration housed in a zip file, therefor the plugin interface also has only 2 main functions

  • ExtensibleBotBuilder.ExtensionsBuilder.addExtensions() which is to add Extensions
  • ExtensibleBotBuilder.apply() which is to change the KordEx/ExtensibleBot configuration

And since you probably ignored the big warning at the top, you can read more about those here

How to write a plugin

If you want to make a plugin you should really use Gradle, using Maven, or no build tool at all is possible, but all official tooling is only provided for Gradle.

Example build.gradle.kts

This is the most basic configuration, for more options read the Gradle plugin documentation

plugins {
    id("com.google.devtools.ksp") version "1.6.21-1.0.5" // used for plugin-processor
    kotlin("jvm") version "1.6.21"
    id("dev.schlaubi.mikbot.gradle-plugin") version "2.2.0"
}

repositories {
    mavenCentral()
}

mikbotPlugin {
    description.set("This is a cool plugin!")
    provider.set("Schlaubi")
    license.set("MIT")
}

Example Plugin main class

import com.kotlindiscord.kord.extensions.builders.ExtensibleBotBuilder
import dev.schlaubi.mikbot.plugin.api.Plugin
import dev.schlaubi.mikbot.plugin.api.PluginMain
import dev.schlaubi.mikbot.plugin.api.PluginWrapper

@PluginMain
class MyCoolPlugin(wrapper: PluginWrapper) : Plugin(wrapper) {
    override suspend fun ExtensibleBotBuilder.ExtensionsBuilder.addExtensions() {
        add(::MyExtension123)
    }
}

How to assemble the plugin

You have 3 ways of building/distributing your plugin

  • The assemblePlugin task: Can be used to generate a single plugin.zip file (Found in build/plugin)

  • The bot distribution: Can be used to generate your own distribution of the bot bundling the plugin (Read more here)

  • Plugin publishing: You can read more about that here

In case of File not found exception

Set ksp("dev.schlaubi", "plugin-processor", "2.2.0") to implementation("dev.schlaubi", "plugin-processor", "2.2.0") and reload your dependencies. Then change it back again. (Workaround)

Alternatively to generating a zip file, you can also use shadowJar, but make sure to add the manifest is added. For more information about Packaging read the packaging documentation and the plugins documentation

How to run the bot

There are two ways to run the bot

How to dockerize the bot

If you want to dockerize a bot with bundled plugins, you can use this Dockerfile

FROM gradle:jdk22 as builder
WORKDIR /usr/app
COPY . .
RUN gradle --no-daemon installBotDist

FROM ibm-semeru-runtimes:open-22-jre-focal

WORKDIR /usr/app
COPY --from=builder /usr/app/install/bot-pluginName .

ENTRYPOINT ["/usr/app/bin/mikmusic"]

What are Extension points

Extension points are interfaces plugins can provide for other plugins to implement. A good example is the gdpr plugin, which provides an interface for other plugins to add GDPR data points

The GDPR plugin has an extension point like this.

/**
 * Extension point for GDPR functionalities.
 */
interface GDPRExtensionPoint : ExtensionPoint {
    /**
     * Provides the [DataPoints][DataPoint] of this module.
     */
    fun provideDataPoints(): List<DataPoint>
}

Then another plugin can implement this data point like this

Implementations of ExtensionPoints are called Extensions, but have nothing to do with KordExteensions Extensions, which are the extensions added in the plugin main

@Extension
class Connect4GDPRExtensionPoint : GDPRExtensionPoint {
    override fun provideDataPoints(): List<DataPoint> = listOf(Connect4StatsDataPoint, Connect4ProcessDataPoint)
}

The GDPR plugin can then access the data points like this

pluginSystem.getExtensions<GDPRExtensionPoint>().flatMap { it.provideDataPoints() }

The mikbot-api

The mikbot api itself provides some utilities itself in extension to kordex

The database API

The bot has a Connection to MongoDB using KMongo if database credentials are present, you can use these like this

object PluginDatabase : KordExKoinComponent {
    val stats = database.getCollection<PluginStats>("plugin_stats")
}

The config api

The bot bundles stdx-envconf for configuration, you can find the bots own configuration file here

The all shards ready event

The bot has an AllShardsReadyEvent which is fired once all shards fired a ReadyEvent

Predefined modules

The bot also has a Settings and Owner module, so you can group all related commands into a single KordExtensions Extension.

You can add commands to these extensions like this

@Extension
class YourPluginSettingsExtension : SettingsExtensionPoint {
    override suspend fun SettingsModule.apply() {
        disableBansCommand()
    }
}

For the OwnerModule use the OwnerExtensionPoint For the SettingsModule use the SettingsExtensionPoint

Both modules also have permission helpers

  • SlashCommand<*, *>.ownerOnly() - registers the command on OWNER_GUILD and requires the Permission ADMINISTRATOR
  • SlashCommand<*, *>.guildAdminOnly() - disables the command in dms and requires MANAGE_SERVER

Documentation

There is currently no hosted documentation for all the utility classes, but they all have doc comments, you can read here

Featured plugins

GDPR

Plugin adding functionality to comply with the GDPR

Dependency: plugin("dev.schlaubi", "mikbot-gdpr", "<version>")

Docs: README.md

ktor

An API to have a webserver in multiple plugins on the same port powered by Ktor

Dependency: plugin("dev.schlaubi", "mikbot-ktor", "<version>")

Docs: README.md

What's next