This page covers API version up 2.3.0 and will be updated in the future.
Otherwise we recommend downloading source to check current code.
Developer API
This page documents the EternalCombat API for plugin developers who want to integrate with EternalCombat.
For Server Administrators This page is intended for developers creating plugins that integrate with EternalCombat. If you're a server administrator, you don't need to read this.
Getting started
Add repository
Add the EternalCode repository to your build configuration:
Gradle.kts Gradle Maven
repositories {
maven ( "https://repo.eternalcode.pl/releases" )
}
Add dependency
Current Version The latest API version is 2.4.0-SNAPSHOT . Check GitHub releases for the most recent version.
📄 Gradle (Kotlin)📄 Gradle (Groovy) Maven
dependencies {
compileOnly ( "com.eternalcode:eternalcombat-api:2.4.0-SNAPSHOT" )
}
Plugin dependency
Declare EternalCombat as a dependency in your plugin's configuration:
📄 plugin.yml📄 paper-plugin.yml
name : YourPlugin
version : 1.0.0
main : com.example.YourPlugin
depend :
- EternalCombat
Accessing the API
Get the API instance in your plugin's onEnable :
import com. eternalcode. combat. EternalCombatApi ;
import com. eternalcode. combat. EternalCombatProvider ;
public class YourPlugin extends JavaPlugin {
private EternalCombatApi combatApi;
@Override
public void onEnable ( ) {
this . combatApi = EternalCombatProvider . provide ( ) ;
}
}
Available services
The API provides access to several services:
Service Method Description FightManager getFightManager() Core combat state management RegionProvider getRegionProvider() Region-based features FightPearlService getFightPearlService() Ender pearl mechanics FightTagOutService getFightTagOutService() Combat tag-out system FightEffectService getFightEffectService() Combat potion effects DropService getDropService() Item drop management DropKeepInventoryService getDropKeepInventoryService() Keep inventory handling
Common use cases
Check combat status
public class CombatChecker {
private final FightManager fightManager;
public CombatChecker ( EternalCombatApi api) {
this . fightManager = api. getFightManager ( ) ;
}
public boolean isPlayerInCombat ( UUID playerId) {
return fightManager. isInCombat ( playerId) ;
}
public Optional < Instant > getCombatEndTime ( UUID playerId) {
return fightManager. getEndOfCombatTime ( playerId) ;
}
}
Tag a player
import com. eternalcode. combat. fight. CauseOfTag ;
public class CombatTagger {
private final FightManager fightManager;
public CombatTagger ( EternalCombatApi api) {
this . fightManager = api. getFightManager ( ) ;
}
public void tagPlayer ( UUID playerId, Duration duration) {
fightManager. tag ( playerId, duration, CauseOfTag . COMMAND ) ;
}
public void tagTwoPlayers ( UUID attacker, UUID victim, Duration duration) {
fightManager. tag ( attacker, victim, duration, CauseOfTag . PLAYER ) ;
}
}
Remove from combat
import com. eternalcode. combat. fight. CauseOfUnTag ;
public class CombatRemover {
private final FightManager fightManager;
public CombatRemover ( EternalCombatApi api) {
this . fightManager = api. getFightManager ( ) ;
}
public void untagPlayer ( UUID playerId) {
fightManager. untag ( playerId, CauseOfUnTag . COMMAND ) ;
}
}
Event system
EternalCombat provides events you can listen to for combat state changes.
FightTagEvent
Fired when a player enters combat:
import com. eternalcode. combat. event. FightTagEvent ;
import com. eternalcode. combat. fight. CauseOfTag ;
import java. time. Duration ;
import java. util. UUID ;
import org. bukkit. Bukkit ;
import org. bukkit. entity. Player ;
import org. bukkit. event. EventHandler ;
import org. bukkit. event. Listener ;
public class CombatListener implements Listener {
@EventHandler
public void onCombatStart ( FightTagEvent event) {
UUID playerId = event. getPlayer ( ) ;
CauseOfTag cause = event. getCause ( ) ;
Duration duration = event. getDuration ( ) ;
Player player = Bukkit . getPlayer ( playerId) ;
if ( player != null ) {
player. sendMessage ( "Combat started! Cause: " + cause) ;
}
}
}
FightUntagEvent
Fired when a player leaves combat:
import com. eternalcode. combat. event. FightUntagEvent ;
import com. eternalcode. combat. fight. CauseOfUnTag ;
import java. util. UUID ;
import org. bukkit. Bukkit ;
import org. bukkit. entity. Player ;
import org. bukkit. event. EventHandler ;
import org. bukkit. event. Listener ;
public class CombatEndListener implements Listener {
@EventHandler
public void onCombatEnd ( FightUntagEvent event) {
UUID playerId = event. getPlayer ( ) ;
CauseOfUnTag cause = event. getCause ( ) ;
Player player = Bukkit . getPlayer ( playerId) ;
if ( player != null ) {
switch ( cause) {
case TIMER_EXPIRED -> player. sendMessage ( "Combat ended - timer expired" ) ;
case DEATH -> player. sendMessage ( "Combat ended - you died" ) ;
case COMMAND -> player. sendMessage ( "Combat ended - admin command" ) ;
case LOGOUT -> player. sendMessage ( "Combat ended - logout" ) ;
}
}
}
}
Event cancellation
Both events can be cancelled to prevent the action:
@EventHandler
public void onCombatStart ( FightTagEvent event) {
Player player = Bukkit . getPlayer ( event. getPlayer ( ) ) ;
if ( player != null && player. hasPermission ( "yourplugin.vip" ) ) {
event. setCancelled ( true ) ;
}
}
Tag causes
CauseOfTag
Cause Description PLAYER Combat started by another player COMMAND Combat started by admin command CRYSTAL Combat from end crystal explosion RESPAWN_ANCHOR Combat from respawn anchor explosion DAMAGE_CAUSE Combat from environmental damage
CauseOfUnTag
Cause Description TIMER_EXPIRED Combat timer ran out DEATH Player died COMMAND Admin removed player's combat using command LOGOUT Player logged out WORLD_CHANGE Player changed world
Best practices
API Guidelines
Cache the API reference - Get EternalCombatApi once in onEnable
Use soft dependency - Handle cases where EternalCombat isn't installed
Don't store player objects - Always use UUIDs and fetch players when needed
Register events properly - Register your listener in onEnable
Soft dependency example
public class YourPlugin extends JavaPlugin {
private EternalCombatApi combatApi;
private boolean eternalCombatEnabled;
@Override
public void onEnable ( ) {
if ( getServer ( ) . getPluginManager ( ) . getPlugin ( "EternalCombat" ) != null ) {
this . combatApi = EternalCombatProvider . provide ( ) ;
this . eternalCombatEnabled = true ;
getLogger ( ) . info ( "EternalCombat integration enabled!" ) ;
} else {
this . eternalCombatEnabled = false ;
getLogger ( ) . info ( "EternalCombat not found, integration disabled." ) ;
}
}
public boolean isPlayerInCombat ( UUID playerId) {
if ( ! eternalCombatEnabled) {
return false ;
}
return combatApi. getFightManager ( ) . isInCombat ( playerId) ;
}
}
Need help?
JavaDocs - Check inline documentation in the API
Discord - discord.gg/FQ7jmGBd6c
GitHub - EternalCombat Repository