Package dev.itsharshxd.zentrix.api.profile

Interface ProfileService

public interface ProfileService
Provides persistent player statistics.

It exposes wins, kills, deaths, and other lifetime totals.

Example


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

 // Load 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 read 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.

      If the stats are not cached, this loads them from storage. Use getCachedStats(UUID) for synchronous access.

      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 so their stats are ready 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).

      Returns the cached 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