Package dev.itsharshxd.zentrix.api.elimination

Interface EliminationService

public interface EliminationService
Ending a player's or a team's match without a death.

An alternative win condition, an objective, a countdown or a wager all need the same thing: put somebody out of the match exactly the way dying would, minus the rewards nobody earned. Doing that by hand means reproducing Zentrix's whole death pipeline — team removal, statistics, spectator conversion, team-elimination detection, the addon events, the win-condition check — and getting one step wrong leaves a match that can never end. This service is that pipeline, exposed.

What is awarded is entirely up to EliminationOptions; removal, team bookkeeping and the addon events are not optional and always happen. The eliminated players become spectators of the match they were in, so they keep watching rather than being thrown back to the lobby.

The win condition is the one part of the pipeline a caller may decline, with EliminationOptions.checkWinCondition(). Left on, as every preset leaves it, a request checks once at the end and a batch that wipes out the field ends the match inside the call.

Example: an objective decides the match


 EliminationService eliminations = ZentrixAPI.get().getEliminationService();

 // Everybody except the team that completed the objective is out, in one atomic batch.
 // The winning team is left alive, so Zentrix's own last-team-standing rule crowns it
 // and the ordinary win rewards are paid out.
 eliminations.eliminateOtherTeams(
         this, game, winningTeamId,
         EliminationOptions.scenario()
                 .messageKey("scenarios.my-objective.eliminated")
                 .build());

Every method must be called from the server main thread.

Since:
1.6.0

  • Method Details

    • eliminate

      @NotNull @NotNull EliminationResult eliminate(@NotNull @NotNull org.bukkit.plugin.Plugin owner, @NotNull @NotNull ZentrixGame game, @NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull EliminationOptions options)
      Ends one player's match.
      Parameters:
      owner - the plugin asking for it, for diagnostics
      game - the match the player is in
      player - the player to eliminate
      options - what the elimination awards and announces
      Returns:
      what happened

    • creditDeath

      boolean creditDeath(@NotNull @NotNull org.bukkit.plugin.Plugin owner, @NotNull @NotNull ZentrixGame game, @NotNull @NotNull org.bukkit.entity.Player victim, @NotNull @NotNull EliminationOptions options)
      Pays out a death that did not end anybody's match.

      The awards half of the pipeline on its own, for a rule that takes a death over and puts the player straight back into the match — a revive scenario, a life system, a role that respawns. Nobody is removed, nobody becomes a spectator and no win condition is checked, because nobody left: this only settles what the death was worth.

      Answering GameplayHooks.PLAYER_DEATH with a replacement tells Zentrix to stand down from a death completely, which also means the killer's kill, the kill reward, first blood and the victim's recorded death all stop happening. This is how a scenario hands back the parts it still wants, and EliminationOptions decides which those are — the attacker has to be named for any of the kill awards to reach anybody.

      Call it while the victim is still a living participant of the match, which for a death that is being taken over means from inside the death itself.

      Parameters:
      owner - the plugin asking for it, for diagnostics
      game - the match the death happened in
      victim - the player who died and is staying in the match
      options - what the death awards and announces
      Returns:
      true when the death was credited, false when the victim was not a living participant
      Since:
      1.6.0

    • eliminateTeam

      @NotNull @NotNull EliminationResult eliminateTeam(@NotNull @NotNull org.bukkit.plugin.Plugin owner, @NotNull @NotNull ZentrixGame game, @NotNull @NotNull String teamId, @NotNull @NotNull EliminationOptions options)
      Ends the match for every living member of one team, atomically.

      The win condition is checked once, after the last member is out, so a team of four never ends the match three times over — and not at all if EliminationOptions.checkWinCondition() is off.

      Parameters:
      teamId - the team's ID, as ZentrixTeam#getId() reports it

    • eliminateOtherTeams

      @NotNull @NotNull EliminationResult eliminateOtherTeams(@NotNull @NotNull org.bukkit.plugin.Plugin owner, @NotNull @NotNull ZentrixGame game, @NotNull @NotNull Collection<String> survivingTeamIds, @NotNull @NotNull EliminationOptions options)
      Ends the match for every living team of a match except the ones named, atomically.

      This is the objective-win call. Every other team is eliminated in one batch and the win condition is checked once at the end, which leaves the surviving team standing alone and lets Zentrix's ordinary last-team-standing rule declare and reward it. Naming no surviving team at all is refused rather than ending the match with nobody left.

      Parameters:
      survivingTeamIds - the teams that stay in the match; must not be empty

    • eliminateOtherTeams

      @NotNull default @NotNull EliminationResult eliminateOtherTeams(@NotNull @NotNull org.bukkit.plugin.Plugin owner, @NotNull @NotNull ZentrixGame game, @NotNull @NotNull String survivingTeamId, @NotNull @NotNull EliminationOptions options)
      Convenience for eliminateOtherTeams(org.bukkit.plugin.Plugin, dev.itsharshxd.zentrix.api.game.ZentrixGame, java.util.Collection<java.lang.String>, dev.itsharshxd.zentrix.api.elimination.EliminationOptions) with a single surviving team.