Package dev.itsharshxd.zentrix.api.profile

Interface ProfileService

public interface ProfileService
Service for accessing player profile statistics.

This service provides access to persistent player statistics such as wins, kills, deaths, and other lifetime achievements.

Example Usage


 ProfileService profileService = ZentrixProvider.get().getProfileService();

 // Get player stats asynchronously
 profileService.getStats(player.getUniqueId()).thenAccept(stats -> {
     int wins = stats.getWins();
     int kills = stats.getKills();
     double kd = stats.getKDRatio();

     player.sendMessage("Wins: " + wins + ", K/D: " + kd);
 });

 // Or get cached stats synchronously
 PlayerStats cached = profileService.getCachedStats(player.getUniqueId());
Since:
1.0.0

  • Method Details

    • getStats

      @NotNull @NotNull CompletableFuture<PlayerStats> getStats(@NotNull @NotNull UUID playerId)
      Gets a player's statistics asynchronously.

      This method fetches stats from storage if not cached. For synchronous access, use getCachedStats(UUID).

      Parameters:
      playerId - The player's UUID
      Returns:
      CompletableFuture containing the player's stats

    • getStats

      @NotNull @NotNull CompletableFuture<PlayerStats> getStats(@NotNull @NotNull org.bukkit.entity.Player player)
      Gets a player's statistics asynchronously.
      Parameters:
      player - The player
      Returns:
      CompletableFuture containing the player's stats

    • getCachedStats

      @NotNull @NotNull PlayerStats getCachedStats(@NotNull @NotNull UUID playerId)
      Gets a player's cached statistics for immediate access.

      Returns the cached stats if available, or empty stats if not yet loaded. Use this for scoreboards and GUIs where async operations are not desirable.

      Parameters:
      playerId - The player's UUID
      Returns:
      The cached stats (may be empty if not loaded)

    • getCachedStats

      @NotNull @NotNull PlayerStats getCachedStats(@NotNull @NotNull org.bukkit.entity.Player player)
      Gets a player's cached statistics for immediate access.
      Parameters:
      player - The player
      Returns:
      The cached stats (may be empty if not loaded)

    • loadStats

      @NotNull @NotNull CompletableFuture<PlayerStats> loadStats(@NotNull @NotNull UUID playerId)
      Preloads a player's statistics into the cache.

      Call this when a player joins the server to ensure their stats are available for quick access.

      Parameters:
      playerId - The player's UUID
      Returns:
      CompletableFuture that completes when loading is done

    • loadStats

      @NotNull @NotNull CompletableFuture<PlayerStats> loadStats(@NotNull @NotNull org.bukkit.entity.Player player)
      Preloads a player's statistics into the cache.
      Parameters:
      player - The player
      Returns:
      CompletableFuture that completes when loading is done

    • isCached

      boolean isCached(@NotNull @NotNull UUID playerId)
      Checks if a player's stats are currently cached.
      Parameters:
      playerId - The player's UUID
      Returns:
      true if stats are in the cache

    • formatSurvivalTime

      @NotNull @NotNull String formatSurvivalTime(double seconds)
      Formats a survival time in seconds to a human-readable format.

      Examples:

      • 45 seconds → "45s"
      • 150 seconds → "2m 30s"
      • 3700 seconds → "1h 1m"

      Parameters:
      seconds - The time in seconds
      Returns:
      Formatted time string (never null)

    • getWins

      int getWins(@NotNull @NotNull UUID playerId)
      Gets the total number of wins for a player (cached).

      Convenience method for quick access to win count.

      Parameters:
      playerId - The player's UUID
      Returns:
      The win count, or 0 if not cached

    • getKills

      int getKills(@NotNull @NotNull UUID playerId)
      Gets the total number of kills for a player (cached).
      Parameters:
      playerId - The player's UUID
      Returns:
      The kill count, or 0 if not cached

    • getDeaths

      int getDeaths(@NotNull @NotNull UUID playerId)
      Gets the total number of deaths for a player (cached).
      Parameters:
      playerId - The player's UUID
      Returns:
      The death count, or 0 if not cached

    • getMatchesPlayed

      int getMatchesPlayed(@NotNull @NotNull UUID playerId)
      Gets the total matches played for a player (cached).
      Parameters:
      playerId - The player's UUID
      Returns:
      The match count, or 0 if not cached

    • getKDRatio

      double getKDRatio(@NotNull @NotNull UUID playerId)
      Gets the K/D ratio for a player (cached).
      Parameters:
      playerId - The player's UUID
      Returns:
      The K/D ratio, or 0 if not cached

    • getWinRate

      double getWinRate(@NotNull @NotNull UUID playerId)
      Gets the win rate percentage for a player (cached).
      Parameters:
      playerId - The player's UUID
      Returns:
      The win rate (0-100), or 0 if not cached