Package com.ohacd.matchbox.api

Class ApiGameSession

java.lang.Object
com.ohacd.matchbox.api.ApiGameSession
public class ApiGameSession extends Object
API wrapper for GameSession that provides a clean interface for external integration.

This class wraps the internal GameSession class and provides methods for managing game state, players, and phases without exposing internal implementation details.

All methods are thread-safe and handle null inputs gracefully.

Since:
0.9.5

  • Constructor Details

    • ApiGameSession

      public ApiGameSession(@NotNull @NotNull com.ohacd.matchbox.game.session.GameSession session)
      Creates a new API game session wrapper.
      Parameters:
      session - the internal game session to wrap
      Throws:
      IllegalArgumentException - if session is null

  • Method Details

    • getName

      @NotNull public @NotNull String getName()
      Gets the name of this session.
      Returns:
      the session name, never null

    • isActive

      public boolean isActive()
      Gets whether this session is currently active.
      Returns:
      true if the session is active

    • getCurrentPhase

      @Nullable public @Nullable com.ohacd.matchbox.game.utils.GamePhase getCurrentPhase()
      Gets the current game phase.
      Returns:
      the current phase, or null if no game is active

    • getCurrentRound

      public int getCurrentRound()
      Gets the current round number.
      Returns:
      the current round number, or -1 if no game is active

    • getPlayers

      @NotNull public @NotNull Collection<org.bukkit.entity.Player> getPlayers()
      Gets all players in this session.
      Returns:
      an unmodifiable collection of all players in the session

    • getAlivePlayers

      @NotNull public @NotNull Collection<org.bukkit.entity.Player> getAlivePlayers()
      Gets all currently alive players in this session.
      Returns:
      an unmodifiable collection of alive players

    • getPlayerRole

      @NotNull public @NotNull Optional<com.ohacd.matchbox.game.utils.Role> getPlayerRole(@Nullable @Nullable org.bukkit.entity.Player player)
      Gets the role of a player in this session.
      Parameters:
      player - the player to check
      Returns:
      optional containing the player's role, empty if not found or not in game

    • startGame

      public boolean startGame()
      Starts the game for this session.
      Returns:
      true if the game was started successfully

    • endGame

      public boolean endGame()
      Ends the game for this session.
      Returns:
      true if the game was ended successfully

    • addPlayer

      public boolean addPlayer(@Nullable @Nullable org.bukkit.entity.Player player)
      Adds a player to this session.
      Parameters:
      player - the player to add
      Returns:
      true if the player was added successfully

    • removePlayer

      public boolean removePlayer(@Nullable @Nullable org.bukkit.entity.Player player)
      Removes a player from this session.
      Parameters:
      player - the player to remove
      Returns:
      true if the player was removed successfully

    • getPhaseController

      @NotNull public @NotNull PhaseController getPhaseController()
      Gets the phase controller for this session.
      Returns:
      a phase controller instance for managing game phases

    • skipToNextPhase

      @Deprecated public boolean skipToNextPhase()
      Deprecated.
      Use getPhaseController() and PhaseController.skipToNextPhase() for better error handling
      Skips to the next phase in the game.
      Returns:
      true if the phase was skipped successfully

    • forcePhase

      @Deprecated public boolean forcePhase(@Nullable @Nullable com.ohacd.matchbox.game.utils.GamePhase phase)
      Deprecated.
      Use getPhaseController() and PhaseController.forcePhase(GamePhase) for better error handling
      Forces the game to a specific phase.
      Parameters:
      phase - the phase to force
      Returns:
      true if the phase was forced successfully

    • isPlayerAlive

      public boolean isPlayerAlive(@Nullable @Nullable org.bukkit.entity.Player player)
      Checks if a specific player is alive in this session.
      Parameters:
      player - the player to check
      Returns:
      true if the player is alive, false if dead or not in session

    • getAlivePlayerCount

      public int getAlivePlayerCount()
      Gets the number of alive players in this session.
      Returns:
      the count of alive players

    • getTotalPlayerCount

      public int getTotalPlayerCount()
      Gets the total number of players in this session.
      Returns:
      the total player count

    • isInGamePhase

      public boolean isInGamePhase()
      Checks if the session is currently in an active game phase.
      Returns:
      true if in a game phase, false if not started or ended

    • getStatusDescription

      @NotNull public @NotNull String getStatusDescription()
      Gets a human-readable status description of the session.
      Returns:
      a descriptive status string

    • getInternalSession

      @Internal @Deprecated public com.ohacd.matchbox.game.session.GameSession getInternalSession()
      Deprecated.
      This method exposes internal implementation details. Use the provided API methods instead.
      Gets the internal GameSession object. This method is for internal use only and should not be used by external plugins.
      Returns:
      the wrapped GameSession

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object