Kombat

A clean, modular combat engine for modern Minecraft servers.

Build Java 21 and 25 Minecraft 1.21.10 Source-available license

Kombat brings responsive classic combat to Bukkit-compatible, Paper, Folia, and Minestom servers without coupling the combat rules to a single runtime. Its public API, combat engine, and platform adapters are separate modules so integrations stay small and predictable.

• Configurable attack speed, hit delay, damage, critical hits, and sweep attacks
• Named knockback profiles with per-player assignment and a live default
• Combos, kills, deaths, streaks, hits, and damage statistics
• Persistent player preferences and statistics on every supported platform
• Cancellable and mutable combat events through a typed, owner-aware event bus
• Safe configuration reloads and thread-safe runtime state
• Dedicated shaded distributions for Bukkit/Paper, Folia, and Minestom
• Region-owned entity scheduling in the Folia distribution

Use exactly one distribution for the server runtime. The Minestom artifact does not bundle Minestom itself.

1. Download the matching JAR from GitHub Releases.
2. Place it in the server's plugins directory.
3. Start the server once to generate the configuration.
4. Edit plugins/Kombat/config.yml, then run /kombat reload.

Player data is stored in plugins/Kombat/players.yml.

Add both Minestom and the Kombat Minestom JAR to the host classpath. Install Kombat after MinecraftServer.init() and close it during shutdown:

import git.immutabled.kombat.minestorm.StormKombatPlugin;
import net.minestom.server.MinecraftServer;
import java.nio.file.Path;
MinecraftServer server = MinecraftServer.init();
StormKombatPlugin kombat = new StormKombatPlugin(
 Path.of("plugins", "Kombat"),
 sender -> /* your permission check */ true
).install();
// During host shutdown:
kombat.close();

Minestom generates kombat.properties and players.properties in the supplied data directory. If no permission hook is supplied, administrative commands are restricted to non-player senders.

The Bukkit/Folia distributions expose these permissions:

The generated configuration contains two ready-to-use profiles: classic and boxing.

combat:
 attack-speed: 24.0
 enable-sweep: false
 hit-delay-ms: 450
 base-damage-multiplier: 1.0
 critical-damage-multiplier: 1.5
 first-hit-damage-boost: 1.0
 critical-enabled: true
knockback:
 default-profile: classic
 profiles:
 classic:
 horizontal: 0.40
 vertical: 0.36
 friction: 0.60
 sprint-multiplier: 1.35
 max-distance: 1.20
 air-movement: true
 sprint-knockback: true
features:
 knockback: true
 statistics: true
 combos: true

See the complete defaults in config.yml.

Other plugins can access the active runtime through KombatProvider. Listener registrations are removable individually or by owner:

import git.immutabled.kombat.api.KombatAPI;
import git.immutabled.kombat.api.KombatProvider;
import git.immutabled.kombat.api.events.defaults.PlayerDamageEvent;
import git.immutabled.kombat.api.events.priority.EventPriority;
KombatAPI api = KombatProvider.get();
api.getEventBus().register(
 this,
 PlayerDamageEvent.class,
 EventPriority.NORMAL,
 event -> {
 if (event.isCritical()) {
 event.setDamage(event.getDamage() * 1.10);
 }
 }
);
// On disable:
api.getEventBus().unregisterAll(this);

The API and core modules target Java 21. Minestom hosts require Java 25 because the current Minestom dependency does.

api Public contracts, events, profiles, and player model
└── core Platform-neutral engine and thread-safe runtime state
platform
├── paper-common Shared Bukkit/Paper/Folia lifecycle and listeners
│ ├── bukkit Standard scheduler distribution
│ └── folia Region scheduler distribution
└── minestorm Embeddable Minestom adapter

The complete build requires JDK 25. Gradle still compiles the API, core, Bukkit, and Folia bytecode for Java 21.

./gradlew clean build

Release-ready JARs are written to:

platform/bukkit/build/libs/Kombat-Bukkit-<version>.jar
platform/folia/build/libs/Kombat-Folia-<version>.jar
platform/minestorm/build/libs/Kombat-Minestom-<version>.jar

Tags matching v* trigger the release workflow and publish all three JARs with SHA-256 checksums.

Read CONTRIBUTING.md before opening a pull request. Security issues should follow SECURITY.md.

Kombat is source-available proprietary software. See LICENSE.