Package dev.itsharshxd.zentrix.api.phase

Interface PhaseService

public interface PhaseService
Provides game phase information for Zentrix games.

Use it to read phase configurations, current phase state, and other phase data for active games.

Example


 PhaseService phaseService = ZentrixProvider.get().getPhaseService();

 // List configured phases
 Collection<GamePhase> phases = phaseService.getAllPhases();

 // Get the current phase
 Optional<GamePhase> currentPhase = phaseService.getCurrentPhase(game);
 currentPhase.ifPresent(phase -> {
     String name = phase.getName();
     int timeLeft = phaseService.getTimeRemaining(game);
     player.sendMessage("Phase: " + name + " - Time left: " + timeLeft + "s");
 });
Since:
1.0.0

  • Method Details

    • getAllPhases

      @NotNull @NotNull Collection<GamePhase> getAllPhases()
      Gets all configured game phases.

      These are the phases defined in the phases.yml configuration file. The collection is ordered by phase sequence.

      Returns:
      An unmodifiable collection of all phases (never null, may be empty)

    • getPhase

      @NotNull @NotNull Optional<GamePhase> getPhase(@NotNull @NotNull String phaseName)
      Gets a phase by its name.
      Parameters:
      phaseName - The phase name (case-insensitive)
      Returns:
      Optional containing the phase, or empty if not found

    • getCurrentPhase

      @NotNull @NotNull Optional<GamePhase> getCurrentPhase(@NotNull @NotNull ZentrixGame game)
      Gets the current active phase for a game.

      Returns empty if the game hasn't started or has ended.

      Parameters:
      game - The game
      Returns:
      Optional containing the current phase, or empty if not in a phase

    • getCurrentPhaseIndex

      int getCurrentPhaseIndex(@NotNull @NotNull ZentrixGame game)
      Gets the index of the current phase for a game (0-based).

      Returns -1 if no phase is active.

      Parameters:
      game - The game
      Returns:
      The phase index, or -1 if not in a phase

    • getPhaseIndex

      int getPhaseIndex(@NotNull @NotNull String phaseName)
      Gets the index of a configured phase by name (0-based).

      The counterpart of getCurrentPhaseIndex(ZentrixGame): comparing the two is how a caller decides whether a match has reached a named point in its sequence yet, without assuming anything about how the server ordered or named its phases.

      Parameters:
      phaseName - The phase name (case-insensitive)
      Returns:
      The phase index, or -1 when no phase of that name is configured
      Since:
      1.6.0

    • getTimeRemaining

      int getTimeRemaining(@NotNull @NotNull ZentrixGame game)
      Gets the time remaining in the current phase, in seconds.

      Returns 0 if no phase is active.

      Parameters:
      game - The game
      Returns:
      Seconds remaining in current phase

    • getTimeElapsed

      int getTimeElapsed(@NotNull @NotNull ZentrixGame game)
      Gets the elapsed time in the current phase, in seconds.

      Returns 0 if no phase is active.

      Parameters:
      game - The game
      Returns:
      Seconds elapsed in current phase

    • getPhaseCount

      int getPhaseCount()
      Gets the total number of configured phases.
      Returns:
      The phase count

    • getNextPhase

      @NotNull @NotNull Optional<GamePhase> getNextPhase(@NotNull @NotNull ZentrixGame game)
      Gets the next phase after the current one for a game.

      Returns empty if there is no next phase (current is the last) or if no phase is active.

      Parameters:
      game - The game
      Returns:
      Optional containing the next phase, or empty if none

    • getPreviousPhase

      @NotNull @NotNull Optional<GamePhase> getPreviousPhase(@NotNull @NotNull ZentrixGame game)
      Gets the previous phase before the current one for a game.

      Returns empty if there is no previous phase (current is the first) or if no phase is active.

      Parameters:
      game - The game
      Returns:
      Optional containing the previous phase, or empty if none

    • isInPhase

      boolean isInPhase(@NotNull @NotNull ZentrixGame game, @NotNull @NotNull String phaseName)
      Checks if a game is currently in a specific phase.
      Parameters:
      game - The game
      phaseName - The phase name to check
      Returns:
      true if the game is in the specified phase

    • hasCompletedAllPhases

      boolean hasCompletedAllPhases(@NotNull @NotNull ZentrixGame game)
      Checks if a game has completed all phases.

      Returns true if the game has finished its last phase.

      Parameters:
      game - The game
      Returns:
      true if all phases are complete

    • isPaused

      boolean isPaused(@NotNull @NotNull ZentrixGame game)
      Checks if phase system is paused for a game.
      Parameters:
      game - The game
      Returns:
      true if phases are paused

    • getTotalPhaseDuration

      int getTotalPhaseDuration()
      Gets the total duration of all phases combined, in seconds.
      Returns:
      Total phase duration

    • getPhaseByIndex

      @NotNull @NotNull Optional<GamePhase> getPhaseByIndex(int index)
      Gets a phase by its index (0-based).
      Parameters:
      index - The phase index
      Returns:
      Optional containing the phase, or empty if index is out of bounds

    • hasBorderShrinkage

      boolean hasBorderShrinkage(@NotNull @NotNull ZentrixGame game)
      Checks if the current phase for a game has border shrinkage enabled.
      Parameters:
      game - The game
      Returns:
      true if current phase has border shrinkage

    • getTargetBorderSize

      double getTargetBorderSize(@NotNull @NotNull ZentrixGame game)
      Gets the target border size for the current phase.

      Returns 0 if no phase is active or no border config exists.

      Parameters:
      game - The game
      Returns:
      The target border size, or 0 if not applicable

    • registerPhase

      boolean registerPhase(@NotNull @NotNull PhaseBuilder builder)
      Registers a custom phase from a builder.

      The phase is added at the end of the phase sequence. The registration is kept in memory only.

      Parameters:
      builder - The phase builder with configuration
      Returns:
      true if registration was successful
      Throws:
      IllegalArgumentException - if the builder is invalid
      Since:
      1.1.0

    • registerPhaseAsync

      @NotNull @NotNull CompletableFuture<Boolean> registerPhaseAsync(@NotNull @NotNull PhaseBuilder builder)
      Registers a custom phase asynchronously with persistence.

      The phase is added at the end of the phase sequence and saved to the phases.yml configuration file.

      Parameters:
      builder - The phase builder with configuration
      Returns:
      A future that completes with true if successful
      Throws:
      IllegalArgumentException - if the builder is invalid
      Since:
      1.1.0

    • registerPhaseAt

      boolean registerPhaseAt(@NotNull @NotNull PhaseBuilder builder, int index)
      Registers a custom phase at a specific index in the phase sequence.

      This method performs in-memory registration only.

      Parameters:
      builder - The phase builder with configuration
      index - The index to insert at (0-based)
      Returns:
      true if registration was successful
      Throws:
      IllegalArgumentException - if the builder is invalid or index is out of bounds
      Since:
      1.1.0

    • unregisterPhase

      boolean unregisterPhase(@NotNull @NotNull String phaseName)
      Unregisters a phase by name.

      The removal affects memory only.

      Parameters:
      phaseName - The name of the phase to unregister
      Returns:
      true if the phase was found and removed
      Since:
      1.1.0

    • unregisterPhaseAndDelete

      @NotNull @NotNull CompletableFuture<Boolean> unregisterPhaseAndDelete(@NotNull @NotNull String phaseName)
      Unregisters a phase and removes it from the configuration file.
      Parameters:
      phaseName - The name of the phase to unregister
      Returns:
      A future that completes with true if successful
      Since:
      1.1.0

    • updatePhase

      boolean updatePhase(@NotNull @NotNull PhaseBuilder builder)
      Updates an existing phase with new configuration.

      The phase must already exist. Its configuration is replaced without changing its position in the sequence.

      Parameters:
      builder - The phase builder with updated configuration
      Returns:
      true if the phase was found and updated
      Since:
      1.1.0

    • getPhasesByAddon

      @NotNull @NotNull Collection<GamePhase> getPhasesByAddon(@NotNull @NotNull String addonId)
      Gets all phases registered by a specific addon.
      Parameters:
      addonId - The addon identifier
      Returns:
      Collection of phases registered by the addon (never null, may be empty)
      Since:
      1.1.0

    • createPhaseBuilder

      @NotNull default @NotNull PhaseBuilder createPhaseBuilder()
      Creates a new PhaseBuilder instance.

      Convenience method for creating a builder.

      Returns:
      A new PhaseBuilder
      Since:
      1.1.0