Custom Modules

plugins {
    kotlin("jvm") version "2.1.10"
}

repositories {
    mavenCentral()
}

dependencies {
    // Module API — the only required dependency
    compileOnly(files("libs/nimbus-module-api.jar"))

    // Needed for Ktor Route type and Exposed Database type
    compileOnly("io.ktor:ktor-server-core:3.1.1")
    compileOnly("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
    compileOnly("org.jetbrains.exposed:exposed-core:0.57.0")
    compileOnly("org.jetbrains.exposed:exposed-jdbc:0.57.0")
    compileOnly("org.slf4j:slf4j-api:2.0.16")
}

kotlin {
    jvmToolchain(21)
}

tasks.jar {
    // Include resources (ServiceLoader config, module.properties)
    from(sourceSets.main.get().output)
}

compileOnly(project(":nimbus-module-api"))

compileOnly(project(":nimbus-core"))

package dev.example.mymodule

import dev.nimbuspowered.nimbus.module.ModuleContext
import dev.nimbuspowered.nimbus.module.NimbusModule

class MyModule : NimbusModule {
    override val id = "my-module"
    override val name = "My Module"
    override val version = "1.0.0"
    override val description = "A minimal example module"

    override suspend fun init(context: ModuleContext) {
        // Register commands, routes, initialize state
    }

    override suspend fun enable() {
        // Called after all modules have been initialized
    }

    override fun disable() {
        // Clean up resources on shutdown
    }
}

id=my-module
name=My Module
description=A minimal example module
default=false
main_class=dev.example.mymodule.MyModule

loadAll()     →  init(context)  →  enable()  →  disable()
              ↑                  ↑              ↑
              Per module,        After ALL       Reverse order
              in load order      modules init    on shutdown

import dev.nimbuspowered.nimbus.module.service

val eventBus = context.service<EventBus>()!!
val registry = context.service<ServiceRegistry>()!!

import dev.nimbuspowered.nimbus.module.ModuleCommand

class HelloCommand : ModuleCommand {
    override val name = "hello"
    override val description = "Say hello"
    override val usage = "hello [name]"

    override suspend fun execute(args: List<String>) {
        val target = args.firstOrNull() ?: "World"
        println("Hello, $target!")
    }
}

override suspend fun init(context: ModuleContext) {
    context.registerCommand(HelloCommand())
}

context.unregisterCommand("hello")

import dev.nimbuspowered.nimbus.module.AuthLevel

override suspend fun init(context: ModuleContext) {
    context.registerRoutes({
        myModuleRoutes()
    }, AuthLevel.SERVICE)
}

import io.ktor.server.response.*
import io.ktor.server.request.*
import io.ktor.server.routing.*

fun Route.myModuleRoutes() {
    route("/api/my-module") {

        get {
            call.respond(mapOf("status" to "ok"))
        }

        post("/action") {
            val body = call.receive<ActionRequest>()
            // handle request
            call.respond(mapOf("result" to "done"))
        }
    }
}

import org.jetbrains.exposed.sql.Table

object MyRecords : Table("my_module_records") {
    val id = integer("id").autoIncrement()
    val name = varchar("name", 128)
    val value = integer("value")
    val createdAt = long("created_at")
    override val primaryKey = PrimaryKey(id)
}

override suspend fun init(context: ModuleContext) {
    val db = context.service<DatabaseManager>()!!
    db.createTables(MyRecords)
}

import org.jetbrains.exposed.sql.*
import org.jetbrains.exposed.sql.transactions.transaction

fun insertRecord(name: String, value: Int) {
    transaction(context.database) {
        MyRecords.insert {
            it[MyRecords.name] = name
            it[MyRecords.value] = value
            it[MyRecords.createdAt] = System.currentTimeMillis()
        }
    }
}

import dev.nimbuspowered.nimbus.event.EventBus
import dev.nimbuspowered.nimbus.event.NimbusEvent
import dev.nimbuspowered.nimbus.module.service

override suspend fun init(context: ModuleContext) {
    val eventBus = context.service<EventBus>()!!

    eventBus.on<NimbusEvent.ServiceReady> { event ->
        println("Service ready: ${event.serviceName} (group ${event.groupName})")
    }
}

import dev.nimbuspowered.nimbus.module.PluginDeployment
import dev.nimbuspowered.nimbus.module.PluginTarget

override suspend fun init(context: ModuleContext) {
    // Paper / Purpur / Pufferfish / Leaf / Folia — the usual backends.
    context.registerPluginDeployment(PluginDeployment(
        resourcePath = "plugins/my-plugin.jar",
        fileName = "my-plugin.jar",
        displayName = "MyPlugin",
        minMinecraftVersion = 17,          // Optional: deploy only on 1.17+
        foliaRequiresPacketEvents = false,
        target = PluginTarget.BACKEND       // Default.
    ))

    // Velocity proxies — different JAR format (uses @Plugin, not plugin.yml).
    context.registerPluginDeployment(PluginDeployment(
        resourcePath = "plugins/my-proxy-plugin.jar",
        fileName = "my-proxy-plugin.jar",
        displayName = "MyProxyPlugin",
        target = PluginTarget.VELOCITY
    ))
}

import dev.nimbuspowered.nimbus.module.Migration
import org.jetbrains.exposed.sql.SchemaUtils
import org.jetbrains.exposed.sql.Transaction

object MyV1_Baseline : Migration {
    override val version = 9000
    override val description = "Create my_module_records baseline table"
    override val baseline = false // true = mark as already applied on existing DBs

    override fun Transaction.migrate() {
        SchemaUtils.create(MyRecords)
    }
}

override suspend fun init(context: ModuleContext) {
    context.registerMigrations(listOf(MyV1_Baseline, MyV2_AddIndex))
}

import dev.nimbuspowered.nimbus.module.DoctorCheck
import dev.nimbuspowered.nimbus.module.DoctorFinding
import dev.nimbuspowered.nimbus.module.DoctorLevel

class MyDoctorCheck(private val storageDir: Path) : DoctorCheck {
    override val section = "MyModule"

    override suspend fun run(): List<DoctorFinding> = buildList {
        if (!Files.exists(storageDir)) {
            add(DoctorFinding(
                level = DoctorLevel.FAIL,
                message = "Storage dir missing: $storageDir",
                hint = "Check permissions on the Nimbus data directory."
            ))
        }
    }
}

context.registerDoctorCheck(MyDoctorCheck(storageDir))

context.registerEventFormatter("SOMETHING_HAPPENED") { data ->
    "${success("✓")} thing happened to ${BOLD}${data["target"]}${RESET}"
}

override suspend fun init(context: ModuleContext) {
    // Schedule a background loop that uses ServiceManager once available
    context.scope.launch {
        delay(10_000)
        val sm = context.service<ServiceManager>() ?: return@launch
        // … use sm …
    }
}

[INFO] Found 1 module JAR(s) in modules/
[INFO] Loaded module: My Module v1.0.0 (my-module)
[INFO] Initialized module: My Module

package dev.example.uptime

import dev.nimbuspowered.nimbus.database.DatabaseManager
import dev.nimbuspowered.nimbus.event.EventBus
import dev.nimbuspowered.nimbus.event.NimbusEvent
import dev.nimbuspowered.nimbus.module.*

class UptimeModule : NimbusModule {
    override val id = "uptime"
    override val name = "Uptime Tracker"
    override val version = "1.0.0"
    override val description = "Tracks service start/stop times"

    private lateinit var context: ModuleContext

    override suspend fun init(ctx: ModuleContext) {
        context = ctx

        // Create database table
        val db = ctx.service<DatabaseManager>()!!
        db.createTables(UptimeRecords)

        // Listen for service events
        val eventBus = ctx.service<EventBus>()!!
        eventBus.on<NimbusEvent.ServiceReady> { event ->
            UptimeStore.recordStart(ctx.database, event.serviceName)
        }
        eventBus.on<NimbusEvent.ServiceStopped> { event ->
            UptimeStore.recordStop(ctx.database, event.serviceName)
        }

        // Register console command
        ctx.registerCommand(UptimeCommand(ctx.database))

        // Register API route
        ctx.registerRoutes({
            uptimeRoutes(ctx.database)
        }, AuthLevel.SERVICE)
    }

    override suspend fun enable() {}

    override fun disable() {}
}

package dev.example.uptime

import org.jetbrains.exposed.sql.Table

object UptimeRecords : Table("uptime_records") {
    val id = integer("id").autoIncrement()
    val serviceName = varchar("service_name", 64)
    val startedAt = long("started_at")
    val stoppedAt = long("stopped_at").nullable()
    override val primaryKey = PrimaryKey(id)
}

package dev.example.uptime

import org.jetbrains.exposed.sql.*
import org.jetbrains.exposed.sql.transactions.transaction

object UptimeStore {
    fun recordStart(db: Database, name: String) {
        transaction(db) {
            UptimeRecords.insert {
                it[serviceName] = name
                it[startedAt] = System.currentTimeMillis()
            }
        }
    }

    fun recordStop(db: Database, name: String) {
        transaction(db) {
            UptimeRecords.update({
                (UptimeRecords.serviceName eq name) and UptimeRecords.stoppedAt.isNull()
            }) {
                it[stoppedAt] = System.currentTimeMillis()
            }
        }
    }

    fun getAll(db: Database): List<UptimeEntry> = transaction(db) {
        UptimeRecords.selectAll().map {
            UptimeEntry(
                it[UptimeRecords.serviceName],
                it[UptimeRecords.startedAt],
                it[UptimeRecords.stoppedAt]
            )
        }
    }
}

data class UptimeEntry(val serviceName: String, val startedAt: Long, val stoppedAt: Long?)

package dev.example.uptime

import dev.nimbuspowered.nimbus.module.ModuleCommand
import org.jetbrains.exposed.sql.Database

class UptimeCommand(private val db: Database) : ModuleCommand {
    override val name = "uptime"
    override val description = "Show service uptime records"
    override val usage = "uptime [service]"

    override suspend fun execute(args: List<String>) {
        val records = UptimeStore.getAll(db)
        val filtered = if (args.isNotEmpty()) {
            records.filter { it.serviceName == args[0] }
        } else {
            records
        }

        if (filtered.isEmpty()) {
            println("No uptime records found.")
            return
        }

        for (record in filtered) {
            val duration = (record.stoppedAt ?: System.currentTimeMillis()) - record.startedAt
            val minutes = duration / 60_000
            val status = if (record.stoppedAt == null) "running" else "stopped"
            println("${record.serviceName}: ${minutes}m ($status)")
        }
    }
}

package dev.example.uptime

import io.ktor.server.response.*
import io.ktor.server.routing.*
import org.jetbrains.exposed.sql.Database

fun Route.uptimeRoutes(db: Database) {
    route("/api/uptime") {
        get {
            val records = UptimeStore.getAll(db)
            call.respond(records.map { mapOf(
                "service" to it.serviceName,
                "startedAt" to it.startedAt,
                "stoppedAt" to it.stoppedAt
            )})
        }
    }
}

id=uptime
name=Uptime Tracker
description=Tracks service start/stop times
default=false
main_class=dev.example.uptime.UptimeModule

my-uptime-module/
├── build.gradle.kts
└── src/main/
    ├── kotlin/dev/example/uptime/
    │   ├── UptimeModule.kt
    │   ├── UptimeRecords.kt
    │   ├── UptimeStore.kt
    │   ├── UptimeCommand.kt
    │   └── UptimeRoutes.kt
    └── resources/
        └── module.properties

interface LocalServiceHandleFactory {
    fun isAvailable(): Boolean
    suspend fun create(
        service: Service,
        workDir: Path,
        command: List<String>,
        env: Map<String, String>,
        dockerConfig: DockerServiceConfig,
        readyPattern: Regex?
    ): ServiceHandle

    /** Reattach to surviving instances on controller restart. */
    fun recover(): Map<String, ServiceHandle> = emptyMap()
}

interface ServiceMemorySource {
    fun readRssMb(service: Service): Long?
}