ETERNALCOMBAT / GUIDE

API for Developers

Developer guide for integrating with EternalCombat's API

Edit on GitHub

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.

Getting started#

Add repository#

Add the EternalCode repository to your build configuration:

repositories {
    maven("https://repo.eternalcode.pl/releases")
}

Add dependency#

dependencies {
    compileOnly("com.eternalcode:eternalcombat-api:2.4.0-SNAPSHOT")
}

Plugin dependency#

Declare EternalCombat as a dependency in your plugin's configuration:

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:

ServiceMethodDescription
FightManagergetFightManager()Core combat state management
RegionProvidergetRegionProvider()Region-based features
FightPearlServicegetFightPearlService()Ender pearl mechanics
FightTagOutServicegetFightTagOutService()Combat tag-out system
FightEffectServicegetFightEffectService()Combat potion effects
DropServicegetDropService()Item drop management
DropKeepInventoryServicegetDropKeepInventoryService()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());

    // Prevent VIP players from entering combat
    if (player != null && player.hasPermission("yourplugin.vip")) {
        event.setCancelled(true);
    }
}

Tag causes#

CauseOfTag#

CauseDescription
PLAYERCombat started by another player
COMMANDCombat started by admin command
CRYSTALCombat from end crystal explosion
RESPAWN_ANCHORCombat from respawn anchor explosion
DAMAGE_CAUSECombat from environmental damage

CauseOfUnTag#

CauseDescription
TIMER_EXPIREDCombat timer ran out
DEATHPlayer died
COMMANDAdmin removed player's combat using command
LOGOUTPlayer logged out
WORLD_CHANGEPlayer changed world

Best practices#

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?#