Package dev.itsharshxd.zentrix.api.game

Interface ZentrixGame

public interface ZentrixGame
Represents a read-only view of a Zentrix Battle Royale game instance.

This interface provides access to game state, players, teams, and other game-related information. Addons cannot directly modify game state through this interface - use events and services instead.

Example Usage


 ZentrixGame game = ZentrixProvider.get().getGameService()
     .getPlayerGame(player).orElse(null);

 if (game != null) {
     // Get game information
     String arena = game.getArenaName();
     int playerCount = game.getPlayerCount();
     GameState state = game.getState();

     // Check phase
     game.getCurrentPhase().ifPresent(phase -> {
         String phaseName = phase.getName();
         int timeLeft = phase.getTimeRemaining();
     });
 }
Since:
1.0.0

  • Method Details

    • getGameId

      @NotNull @NotNull String getGameId()
      Gets the unique identifier for this game instance.

      This ID is unique across all active games and is typically a combination of arena name and instance number.

      Returns:
      The unique game ID (never null)

    • getArenaName

      @NotNull @NotNull String getArenaName()
      Gets the arena name this game is running on.

      Multiple game instances can run on copies of the same arena.

      Returns:
      The arena name (never null)

    • getState

      @NotNull @NotNull ZentrixGame.GameState getState()
      Gets the current state of this game.
      Returns:
      The current game state (never null)

    • isPlaying

      default boolean isPlaying()
      Checks if the game is currently in the playing state.
      Returns:
      true if the game state is ZentrixGame.GameState.PLAYING

    • isWaiting

      default boolean isWaiting()
      Checks if the game is waiting for players.
      Returns:
      true if the game state is ZentrixGame.GameState.WAITING

    • getPlayers

      @NotNull @NotNull Collection<ZentrixPlayer> getPlayers()
      Gets all players currently alive in this game.

      This does not include spectators or eliminated players.

      Returns:
      An unmodifiable collection of alive players (never null, may be empty)

    • getSpectators

      @NotNull @NotNull Collection<ZentrixPlayer> getSpectators()
      Gets all spectators watching this game.

      Spectators include eliminated players who stayed to watch and players who joined specifically to spectate.

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

    • getAllParticipants

      @NotNull @NotNull Collection<ZentrixPlayer> getAllParticipants()
      Gets all participants in this game (players and spectators).
      Returns:
      An unmodifiable collection of all participants (never null, may be empty)

    • getPlayer

      @NotNull @NotNull Optional<ZentrixPlayer> getPlayer(@NotNull @NotNull UUID playerId)
      Gets a player by their UUID.
      Parameters:
      playerId - The player's UUID
      Returns:
      Optional containing the player, or empty if not found

    • hasPlayer

      boolean hasPlayer(@NotNull @NotNull UUID playerId)
      Checks if a player is in this game (playing or spectating).
      Parameters:
      playerId - The player's UUID
      Returns:
      true if the player is in this game

    • getPlayerCount

      int getPlayerCount()
      Gets the number of alive players in this game.
      Returns:
      The count of alive players

    • getSpectatorCount

      int getSpectatorCount()
      Gets the number of spectators in this game.
      Returns:
      The count of spectators

    • getTeams

      @NotNull @NotNull Collection<ZentrixTeam> getTeams()
      Gets all teams in this game.
      Returns:
      An unmodifiable collection of teams (never null, may be empty)

    • getAliveTeams

      @NotNull @NotNull Collection<ZentrixTeam> getAliveTeams()
      Gets teams that still have alive members.
      Returns:
      An unmodifiable collection of alive teams (never null, may be empty)

    • getTeam

      @NotNull @NotNull Optional<ZentrixTeam> getTeam(@NotNull @NotNull String teamId)
      Gets a team by its ID.
      Parameters:
      teamId - The team ID (e.g., "team-1")
      Returns:
      Optional containing the team, or empty if not found

    • getAliveTeamCount

      int getAliveTeamCount()
      Gets the number of alive teams.
      Returns:
      The count of teams with at least one alive member

    • getCurrentPhase

      @NotNull @NotNull Optional<GamePhase> getCurrentPhase()
      Gets the current game phase, if the game is playing.

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

      Returns:
      Optional containing the current phase, or empty if not in a phase

    • getWorld

      @Nullable @Nullable org.bukkit.World getWorld()
      Gets the game world.

      May return null if the world hasn't been created yet (e.g., during WAITING state before arena copy).

      Returns:
      The game world, or null if not yet available

    • getGameTypeName

      @NotNull @NotNull String getGameTypeName()
      Gets the game type name (e.g., "solo", "duo", "squad").
      Returns:
      The game type name (never null)

    • getMaxPlayers

      int getMaxPlayers()
      Gets the maximum number of players for this game type.
      Returns:
      The maximum player capacity

    • getMinPlayers

      int getMinPlayers()
      Gets the minimum number of players required to start.
      Returns:
      The minimum player count

    • getTeamSize

      int getTeamSize()
      Gets the team size for this game type.

      Returns 1 for solo games.

      Returns:
      The team size

    • getPhaseTimeRemaining

      int getPhaseTimeRemaining()
      Gets the time remaining in the current phase, in seconds.

      Returns 0 if no phase is active.

      Returns:
      Seconds remaining in current phase

    • getGameDuration

      long getGameDuration()
      Gets the total game duration so far, in seconds.

      Starts counting from when the game enters PLAYING state.

      Returns:
      Game duration in seconds, or 0 if game hasn't started

    • getWorldBorderSize

      double getWorldBorderSize()
      Gets the current world border size.

      Returns 0 if the world is not available.

      Returns:
      The world border diameter in blocks

    • broadcast

      void broadcast(@NotNull @NotNull String message)
      Sends a message to all players and spectators in this game.

      Supports MiniMessage format and legacy color codes.

      Parameters:
      message - The message to send

    • broadcastLocalized

      void broadcastLocalized(@NotNull @NotNull String key, @NotNull @NotNull Object... placeholders)
      Sends a localized message to all players and spectators.

      Uses Zentrix's locale system with placeholder support.

      Parameters:
      key - The locale key
      placeholders - Placeholder pairs (key, value, key, value, ...)