Skip to content

ZelCombat

Developer API

ZelCombat ships a stable, public API (com.zeltuv.zelcombat.api.ZelCombatAPI) plus a few Bukkit events other plugins can listen to.

Setting up

Add ZelCombat to your plugin's softdepend (or depend) in plugin.yml so it loads first, then compile against the ZelCombat jar (compileOnly / provided scope).

Getting the API

Either through the main class:

ZelCombatAPI api = CombatPlugin.getAPI();

Or, without depending on ZelCombat's main class, through the Bukkit services manager:

RegisteredServiceProvider<ZelCombatAPI> rsp =
        Bukkit.getServicesManager().getRegistration(ZelCombatAPI.class);
ZelCombatAPI api = rsp != null ? rsp.getProvider() : null;

Methods that change state (tagging, toggling, granting protection) should be called from the server / region thread, like any other Bukkit mutation.

Combat tagging

boolean   isInCombat(Player player);
boolean   isInCombat(UUID playerId);
long      getRemainingCombatMillis(UUID playerId);
int       getRemainingCombatSeconds(UUID playerId);   // rounded up
UUID      getOpponentId(UUID playerId);               // null if none
Player    getOpponent(Player player);                 // null if offline/none
boolean   tag(Player player, Player attacker);        // default duration
boolean   tag(Player player, Player attacker, int seconds);
void      untag(Player player);
void      untag(UUID playerId);
int       getDefaultCombatDurationSeconds();

tag(...) fires a cancellable PlayerCombatTagEvent and returns whether the player ended up in combat. untag(...) fires a PlayerCombatUntagEvent.

PvP preference

boolean isPvpEnabled(Player player);
boolean isPvpEnabled(UUID playerId);
boolean togglePvp(Player player);               // returns the resulting state
boolean setPvpEnabled(Player player, boolean enabled);

When allow-pvp-toggle is off, or the player lacks zelcombat.togglepvp, these are no-ops that return true.

Death messages

boolean areDeathMessagesEnabled(Player player);
boolean areDeathMessagesEnabled(UUID playerId);
boolean toggleDeathMessages(Player player);     // returns the resulting state

Newbie protection

boolean hasNewbieProtection(Player player);
boolean hasNewbieProtection(UUID playerId);
void    grantNewbieProtection(Player player);   // uses the configured duration
void    removeNewbieProtection(Player player);
void    removeNewbieProtection(UUID playerId);

PvP statistics

boolean isStatsEnabled();
int     getKills(UUID playerId);
int     getDeaths(UUID playerId);
int     getKillStreak(UUID playerId);
int     getBestKillStreak(UUID playerId);
double  getKdr(UUID playerId);
PlayerStats getStats(UUID playerId);            // online, cached snapshot; null if not loaded
void    getOfflineStats(String playerName, Consumer<PlayerStats> callback); // async, may be null
List<PlayerStats> getLeaderboard(StatsManager.Category category, int limit);

Stat getters return 0 when a player's stats are not loaded. getOfflineStats looks up a possibly-offline player by name; its callback may run on an async thread and receives null when stats are disabled or the player is unknown.

Leaderboard categories: KILLS, DEATHS, KDR, KILLSTREAK, BEST_KILLSTREAK.

Events

All in com.zeltuv.zelcombat.api.events.

PlayerCombatTagEvent — cancellable. Fired when a player is about to be tagged.

MethodReturns
getPlayer()The player being tagged.
getAttacker()The opponent.
isAlreadyInCombat()Whether they were already tagged.
getDurationSeconds() / setDurationSeconds(int)Read/adjust the tag length.

PlayerCombatUntagEvent — fired when a player leaves combat.

MethodReturns
getPlayerId()The player's UUID.
getPlayer()The player, or null if offline.
getReason()An UntagReason.

UntagReason values: EXPIRED, DEATH, QUIT, COMMAND, BORDER, API, PLUGIN.

PlayerTogglePvpEvent — cancellable. Fired when a player's PvP preference changes.

MethodReturns
getPlayer()The player.
getPreviousState()PvP state before the change.
getNewState()PvP state after the change.
@EventHandler
public void onTag(PlayerCombatTagEvent event) {
    if (event.getPlayer().hasPermission("myplugin.notag")) {
        event.setCancelled(true);
    }
}