Events Reference

Custom Bukkit events fired by ShyamDuels during match setups, player deaths, and round transitions.

Event Listening Setup

Implement the standard Bukkit Listener interface and register it inside your plugin's onEnable block:

javaimport org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import com.shyamstudio.shyamduels.duel.event.DuelStartEvent;

public class MatchListener implements Listener {

    @EventHandler
    public void onDuelStart(DuelStartEvent event) {
        // Event logic here
    }
}

Available Custom Events

Tournament Events

Package: com.shyamstudio.shyamduels.tournament.event.*. All events below extend the abstract TournamentEvent base class, which exposes getTournament() returning the associated Tournament instance.

TournamentPlayerJoinEvent is cancellable - cancelling prevents the player from joining. Note: the manager silently returns false on cancel (no automatic message is sent).

PlayerCountryChangeEvent

Class path: com.shyamstudio.shyamduels.api.country.event.PlayerCountryChangeEvent
Fired on the main thread after a player's country flag is changed but before display refresh. Not cancellable; informational.

• getPlayerId(): Owner UUID.
• getPlayer(): Online Player or null if offline.
• getOldCountry() / getNewCountry(): ISO codes (UNKNOWN when cleared).
• getCause(): SELECT (menu/command), RESET, GEOIP (MaxMind), JOIN_RESOLVE.
• isManual(): True for player-chosen flags; false for automatic GeoIP resolves.

DuelCountdownStartEvent

Class path: com.shyamstudio.shyamduels.duel.event.DuelCountdownStartEvent
Fired when a duel countdown begins, before PvP damage is enabled.

• getDuel(): Returns the active Duel model.

DuelStartEvent

Class path: com.shyamstudio.shyamduels.duel.event.DuelStartEvent
Fired when a 1v1 duel starts, immediately after the countdown finishes and PvP damage is enabled. (Team duels fire PartyVsPartyStartEvent instead - DuelStartEvent is not fired for team sizes > 1.)

• getDuel(): Returns the active Duel model.

DuelEndEvent

Class path: com.shyamstudio.shyamduels.duel.event.DuelEndEvent
Fired when a duel match terminates (due to victory conditions, player forfeit, or admin termination commands). Team matches additionally fire their party-end variant (PartyVsPartyEndEvent, PartySplitEndEvent, or PartyFFAEndEvent) from the same finish path.

• getDuel(): Returns the concluded Duel model. Use the model to check final state, winner teams, and ELO calculations.

FightDeathEvent

Class path: com.shyamstudio.shyamduels.duel.event.FightDeathEvent
Fired when a player dies inside a match arena during a duel round.

• getPlayer(): Returns the victim player entity.
• getKiller(): Returns the killer player entity (returns null if death was caused by environment, fall damage, or potion effect).
• getDuel(): Returns the active Duel model.
• isFinalRound(): Returns true if this death concludes the entire match (meaning no further rounds will execute).

PlayerVirtualDeathEvent

Class path: com.shyamstudio.shyamduels.api.event.PlayerVirtualDeathEvent
Fired when a player experiences virtual death (e.g. during a duel match where damage is cancelled to bypass the standard death/respawn screen). Ideal for custom kill effects, cosmetics, or custom stats trackers.

• getPlayer(): Returns the victim player entity.
• getKiller(): Returns the killer player entity, if one exists (returns null if death was caused by environment or fall damage).
• getLocation(): Returns the Location where the virtual death occurred.
• getDamageCause(): Returns the Bukkit DamageCause that triggered the death (returns null if unknown).
• getDuel(): Returns the active Duel model in which the player died (returns null if not in a duel).

RoundStartEvent

Class path: com.shyamstudio.shyamduels.duel.event.RoundStartEvent
Fired at the moment a round begins in multi-round duels (e.g. Best of 3 matches), after the round's countdown finishes and the fight starts (rounds 2+).

• getDuel(): Returns the active Duel model.

RoundEndEvent

Class path: com.shyamstudio.shyamduels.duel.event.RoundEndEvent
Fired immediately after a round concludes (a player or team dies), before players are reset for the next round.

• getDuel(): Returns the active Duel model.

Party Match Events

AdvancementGrantEvent

Class path: com.shyamstudio.shyamduels.advancement.event.AdvancementGrantEvent
Fired on the main thread when a player completes an advancement. Informational and not cancellable.

• getPlayer(): Returns the player who earned the advancement.
• getAdvancement(): Returns the completed advancement definition.

Full Example: Tracking Match Results

A complete listener that registers in onEnable and reacts to several ShyamDuels events. It records a kill via the API on each fight death and announces the winner when a duel ends:

javaimport com.shyamstudio.shyamduels.api.ShyamDuelsAPI;
import com.shyamstudio.shyamduels.api.ShyamDuelsProvider;
import com.shyamstudio.shyamduels.duel.Duel;
import com.shyamstudio.shyamduels.duel.event.DuelEndEvent;
import com.shyamstudio.shyamduels.duel.event.DuelStartEvent;
import com.shyamstudio.shyamduels.duel.event.FightDeathEvent;
import com.shyamstudio.shyamduels.duel.event.RoundStartEvent;
import org.bukkit.Bukkit;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public class MatchTracker implements Listener {

    private final JavaPlugin plugin;

    public MatchTracker(JavaPlugin plugin) {
        this.plugin = plugin;
        Bukkit.getPluginManager().registerEvents(this, plugin);
    }

    @EventHandler
    public void onDuelStart(DuelStartEvent event) {
        Duel duel = event.getDuel();
        plugin.getLogger().info("Duel started on arena " + duel.getArena().getName());
    }

    @EventHandler
    public void onRoundStart(RoundStartEvent event) {
        plugin.getLogger().info("New round started.");
    }

    @EventHandler
    public void onFightDeath(FightDeathEvent event) {
        Player victim = event.getPlayer();
        Player killer = event.getKiller();
        if (killer != null) {
            ShyamDuelsAPI api = ShyamDuelsProvider.get();
            if (api != null) {
                api.stats().recordKill(killer, victim);
                killer.sendMessage("§aYou eliminated " + victim.getName()
                        + " §7(kills: " + api.stats().getKills(killer.getUniqueId()) + ")");
            }
        }
        if (event.isFinalRound()) {
            victim.sendMessage("§cYou lost the match.");
        }
    }

    @EventHandler
    public void onDuelEnd(DuelEndEvent event) {
        Duel duel = event.getDuel();
        plugin.getLogger().info("Duel ended (kit: "
                + (duel.getKit() != null ? duel.getKit().getName() : "unknown") + ").");
    }
}