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.*

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.)

• 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).

• 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

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") + ").");
    }
}