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.
| Method | Returns |
|---|---|
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.
| Method | Returns |
|---|---|
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.
| Method | Returns |
|---|---|
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);
}
}