A clean, modular combat engine for modern Minecraft servers.

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.

Highlights

• 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

Platforms

Runtime	Distribution	Java	Integration
Bukkit-compatible / Paper 1.21.10	Kombat-Bukkit-<version>.jar	21+	Drop-in plugin
Folia 1.21.10	Kombat-Folia-<version>.jar	21+	Drop-in, region-safe plugin
Minestom 1.21.10	Kombat-Minestom-<version>.jar	25+	Embeddable library

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

Installation

Bukkit-compatible, Paper, and Folia

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.

Minestom

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

importgit.immutabled.kombat.minestorm.StormKombatPlugin;
importnet.minestom.server.MinecraftServer;
importjava.nio.file.Path;
MinecraftServerserver = MinecraftServer.init();
StormKombatPluginkombat = newStormKombatPlugin(
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.

Commands

Command	Purpose
/kombat help	Show available commands
/kombat status	Show runtime state and loaded data
/kombat toggle	Toggle classic mechanics for yourself
/kombat stats [player]	Show combat statistics
/kombat reload	Reload the configuration
/kombat enable|disable	Change the global runtime state
/knockback list	List available profiles
/knockback info <profile>	Inspect a profile
/knockback set <profile> [player]	Assign a profile
/knockback reset [player]	Return to the default profile
/knockback default <profile>	Change the global default

The Bukkit/Folia distributions expose these permissions:

Permission	Default
kombat.command	Everyone
kombat.toggle	Everyone
kombat.stats	Everyone
kombat.stats.others	Operators
kombat.knockback	Everyone
kombat.knockback.assign	Operators
kombat.admin	Operators

Configuration

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

combat:
attack-speed: 24.0enable-sweep: falsehit-delay-ms: 450base-damage-multiplier: 1.0critical-damage-multiplier: 1.5first-hit-damage-boost: 1.0critical-enabled: trueknockback:
default-profile: classicprofiles:
classic:
horizontal: 0.40vertical: 0.36friction: 0.60sprint-multiplier: 1.35max-distance: 1.20air-movement: truesprint-knockback: truefeatures:
knockback: truestatistics: truecombos: true

See the complete defaults in config.yml.

API

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

importgit.immutabled.kombat.api.KombatAPI;
importgit.immutabled.kombat.api.KombatProvider;
importgit.immutabled.kombat.api.events.defaults.PlayerDamageEvent;
importgit.immutabled.kombat.api.events.priority.EventPriority;
KombatAPIapi = 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.

Architecture

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

Building

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.

Contributing

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

License

Kombat is source-available proprietary software. See LICENSE.