Package dev.itsharshxd.zentrix.api.phase

Interface PhaseService

public interface PhaseService
Service for accessing game phase information within Zentrix.

This service provides access to phase configurations, current phase state, and phase-related queries for active games.

Example Usage


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

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

 // Get current phase for a game
 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

    • 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. This method performs in-memory registration 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.

      This method performs in-memory removal 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. This replaces the phase configuration while maintaining 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 builders.

      Returns:
      A new PhaseBuilder
      Since:
      1.1.0