Add HYTL plugin core, config, heartbeat, and vote logic

Introduces the HYTL plugin core implementation, including configuration management, heartbeat service, vote polling and processing, and command registration. Adds support for exponential backoff, HTTP client setup with serialization, online player tracking, processed vote persistence, and a default vote rewarder. Also provides a public API for external plugins to hook into vote rewards, and implements setup, reload, and status commands for plugin management. Updates build scripts to include required dependencies and improves clean scripts to not error on missing directories.

Author: CoasterFreakDE

build.gradle.kts

@@ -7,6 +7,7 @@ import java.util.TimeZone
 plugins {
     val kotlin_version: String by System.getProperties()
     kotlin("jvm").version(kotlin_version)
+    kotlin("plugin.serialization").version(kotlin_version)
 
     id("com.gradleup.shadow") version "8.3.6"
 }
@@ -16,7 +17,7 @@ val ktor_version: String by project
 
 group = "cc.modlabs"
 version = System.getenv("VERSION_OVERRIDE") ?: Calendar.getInstance(TimeZone.getTimeZone("UTC")).run {
-    "${get(Calendar.YEAR)}.${get(Calendar.MONTH) + 1}.${get(Calendar.DAY_OF_MONTH)}.${
+    "${get(Calendar.YEAR)}.${get(Calendar.MONTH) + 1}.${get(Calendar.DAY_OF_MONTH)}-${
         String.format("%02d%02d", get(Calendar.HOUR_OF_DAY), get(Calendar.MINUTE))
     }"
 }
@@ -29,7 +30,9 @@ val shadowDependencies = listOf(
     "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version",
     "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version",
     "io.ktor:ktor-client-core:$ktor_version",
-    "io.ktor:ktor-client-cio:$ktor_version"
+    "io.ktor:ktor-client-cio:$ktor_version",
+    "io.ktor:ktor-client-content-negotiation:$ktor_version",
+    "io.ktor:ktor-serialization-kotlinx-json:$ktor_version"
     //"cc.modlabs:ktale:${project.ext["ktaleVersion"] as String}",
     //"cc.modlabs:KlassicX:2025.12.4.1928"
 )

cleanlibs.bat

@@ -5,7 +5,7 @@ set "TARGET_DIR=.\build\libs"
 REM Check if the directory exists
 if not exist "%TARGET_DIR%" (
     echo The directory %TARGET_DIR% does not exist.
-    exit /b 1
+    exit /b 0
 )
 
 REM Delete all .jar files in the directory

cleanlibs.sh

@@ -6,7 +6,7 @@ TARGET_DIR="./build/libs"
 # Check if the directory exists
 if [ ! -d "$TARGET_DIR" ]; then
   echo "The directory $TARGET_DIR does not exist."
-  exit 1
+  exit 0
 fi
 
 # Delete all .jar files in the directory

src/main/java/cc/modlabs/api/VoteRewarder.java

@@ -0,0 +1,10 @@
+package cc.modlabs.api;
+
+@FunctionalInterface
+public interface VoteRewarder {
+    /**
+     * @return true if the reward was granted successfully and it is safe to ACK the vote.
+     */
+    boolean reward(PendingVote vote);
+}
+

src/main/kotlin/cc/modlabs/Backoff.kt

@@ -0,0 +1,27 @@
+package cc.modlabs
+
+import kotlin.math.min
+import kotlin.random.Random
+
+class ExponentialBackoff(
+    private val baseSeconds: Long = 1,
+    private val maxSeconds: Long = 60,
+    private val jitterRatio: Double = 0.2
+) {
+    private var failures: Int = 0
+
+    fun reset() {
+        failures = 0
+    }
+
+    fun nextDelaySeconds(): Long {
+        failures = min(failures + 1, 30) // avoid overflow
+        val exp = 1L shl min(failures - 1, 20)
+        val raw = min(maxSeconds, baseSeconds * exp)
+
+        val jitter = (raw * jitterRatio).toLong().coerceAtLeast(0)
+        val delta = if (jitter == 0L) 0L else Random.nextLong(-jitter, jitter + 1)
+        return (raw + delta).coerceIn(1, maxSeconds)
+    }
+}
+

src/main/kotlin/cc/modlabs/DefaultVoteRewarder.kt

@@ -0,0 +1,43 @@
+package cc.modlabs
+
+import cc.modlabs.api.PendingVote
+import cc.modlabs.api.VoteRewarder
+import com.hypixel.hytale.logger.HytaleLogger
+
+class DefaultVoteRewarder(
+    private val cfg: HytlPluginConfig,
+    private val logger: HytaleLogger
+) : VoteRewarder {
+    override fun reward(vote: PendingVote): Boolean {
+        val mode = cfg.voteRewards.mode.uppercase()
+        if (mode == "DISABLED") return false
+
+        val tier = computeTier(vote.streak)
+        val multiplier = cfg.voteRewards.tierMultipliers.getOrNull(tier - 1) ?: 1
+        val amount = cfg.voteRewards.baseAmount * multiplier
+
+        val who = vote.playerUuid ?: vote.playerName ?: "<unknown>"
+        logger.info("Rewarding voteId=${vote.voteId} player=$who streak=${vote.streak} tier=$tier amount=$amount (default LOG_ONLY)")
+
+        // Default implementation is intentionally "log only" because reward systems are server-specific.
+        // External plugins can hook in via HytlDevApi.setVoteRewarder(...) to grant actual items/currency/etc.
+        return true
+    }
+
+    private fun computeTier(streak: Int): Int {
+        val thresholds = cfg.voteRewards.tierStreakThresholds
+            .map { it.coerceAtLeast(1) }
+            .sorted()
+            .distinct()
+            .ifEmpty { listOf(1) }
+
+        var tier = 1
+        for (t in thresholds) {
+            if (streak >= t) tier++
+        }
+        // If thresholds=[1,3,7,14,30], tiers become 1..5. Clamp to multipliers length if provided.
+        val maxTier = cfg.voteRewards.tierMultipliers.size.takeIf { it > 0 } ?: 1
+        return (tier - 1).coerceIn(1, maxTier)
+    }
+}
+

src/main/kotlin/cc/modlabs/HytlApiModels.kt

@@ -0,0 +1,77 @@
+package cc.modlabs
+
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class HeartbeatPayload(
+    val serverId: String,
+    val ts: String,
+    val game: GameInfo,
+    val universe: UniverseInfo? = null,
+    val players: List<PlayerInfo>? = null,
+    val mods: ModsInfo? = null
+)
+
+@Serializable
+data class GameInfo(
+    val host: String? = null,
+    val port: Int? = null,
+    val version: String? = null,
+    val patchline: String? = null,
+    val maxPlayers: Int? = null,
+    val motd: List<String>? = null
+)
+
+@Serializable
+data class UniverseInfo(
+    val currentPlayers: Int? = null,
+    val defaultWorld: String? = null
+)
+
+@Serializable
+data class PlayerInfo(
+    val name: String,
+    val uuid: String? = null,
+    val world: String? = null
+)
+
+@Serializable
+data class ModsInfo(
+    val enabled: Boolean,
+    val list: List<ModEntry>? = null
+)
+
+@Serializable
+data class ModEntry(
+    val id: String,
+    val version: String? = null,
+    val state: String? = null
+)
+
+@Serializable
+data class PendingVotesResponse(
+    val serverId: String,
+    val events: List<VoteEvent> = emptyList()
+)
+
+@Serializable
+data class VoteEvent(
+    val voteId: String,
+    val createdAt: String? = null,
+    val playerName: String? = null,
+    val playerUuid: String? = null,
+    val streak: Int? = null
+)
+
+@Serializable
+data class VoteAckRequest(
+    val serverId: String,
+    val voteId: String
+)
+
+@Serializable
+data class VoteAckResponse(
+    val ok: Boolean = false,
+    val acked: Boolean = false
+)
+

src/main/kotlin/cc/modlabs/HytlConfig.kt

@@ -0,0 +1,88 @@
+package cc.modlabs
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import java.nio.file.Files
+import java.nio.file.Path
+
+@Serializable
+data class HytlPluginConfig(
+    val serverId: String = "",
+    val serverSecret: String = "",
+    val backendBaseUrl: String = "https://hytl.dev/api/plugin",
+    val heartbeatSeconds: Int = 10,
+    val votePollSeconds: Int = 15,
+    val privacy: PrivacyConfig = PrivacyConfig(),
+    val voteRewards: VoteRewardsConfig = VoteRewardsConfig(),
+    val httpTimeoutMs: Long = 3_000,
+    val maxBackoffSeconds: Int = 60,
+    // Optional convenience: override the public host/port shown in HYTL.
+    val publicHost: String? = null,
+    val publicPort: Int? = null,
+    // Optional convenience: override server version/patchline reported to HYTL.
+    val gameVersion: String? = null,
+    val patchline: String? = null
+)
+
+@Serializable
+data class PrivacyConfig(
+    val shareMods: Boolean = true,
+    val sharePlayerCount: Boolean = true,
+    val sharePlayerNames: Boolean = true,
+    val sharePlayerUUIDs: Boolean = false
+)
+
+@Serializable
+data class VoteRewardsConfig(
+    /**
+     * LOG_ONLY: logs what would be rewarded and ACKs votes (default).
+     * DISABLED: does not reward and does not ACK (votes stay pending).
+     */
+    val mode: String = "LOG_ONLY",
+    val baseAmount: Int = 1,
+    /**
+     * Tier thresholds (inclusive) by streak. Example default tiers:
+     * 1 -> tier 1, 3 -> tier 2, 7 -> tier 3, 14 -> tier 4, 30 -> tier 5.
+     */
+    val tierStreakThresholds: List<Int> = listOf(1, 3, 7, 14, 30),
+    /**
+     * Amount multipliers per tier index (1-based). Default: [1,2,3,4,5].
+     */
+    val tierMultipliers: List<Int> = listOf(1, 2, 3, 4, 5)
+)
+
+object HytlConfigIO {
+    private val json = Json {
+        prettyPrint = true
+        encodeDefaults = true
+        ignoreUnknownKeys = true
+        explicitNulls = false
+    }
+
+    const val CONFIG_FILE_NAME: String = "config.json"
+
+    fun configPath(dataDir: Path): Path = dataDir.resolve(CONFIG_FILE_NAME)
+
+    /**
+     * Loads config from the plugin data directory. If missing, writes a starter file and returns defaults.
+     */
+    fun loadOrCreate(dataDir: Path): HytlPluginConfig {
+        Files.createDirectories(dataDir)
+        val path = configPath(dataDir)
+        if (!Files.exists(path)) {
+            val starter = HytlPluginConfig()
+            Files.writeString(path, json.encodeToString(HytlPluginConfig.serializer(), starter))
+            return starter
+        }
+        val raw = Files.readString(path)
+        return json.decodeFromString(HytlPluginConfig.serializer(), raw)
+    }
+
+    fun save(dataDir: Path, cfg: HytlPluginConfig) {
+        Files.createDirectories(dataDir)
+        val path = configPath(dataDir)
+        Files.writeString(path, json.encodeToString(HytlPluginConfig.serializer(), cfg))
+    }
+}
+