Interface PlaytimeService

public interface PlaytimeService
Service for managing player playtime tracking and statistics. Handles initialization, session updates, and retrieval of playtime data. Playtime tracking can be enabled or disabled via configuration.
Since:
1.10.1
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    @NonNull List<PlayTime>
    getAllPlayTimes(int limit, int offset)
    Gets a paginated list of all playtime records from the database.
    @Nullable PlayTime
    getPlayTime(FPlayer fPlayer)
    Gets the playtime statistics for a specific player.
    int
    getPlayTimesCount()
    Gets the total count of all playtime records in the database.
    void
    initialize()
    Initializes playtime tracking by migrating legacy data from platform adapters.
    void
    invalidate(@NonNull UUID uuid)
    Invalidates cached playtime data for a specific player.
    void
    saveAfkSession(FPlayer fPlayer, boolean afk)
    Saves a player's AFK session status change and invalidates cache.
    void
    updateJoinSession(@NonNull FPlayer fPlayer)
    Updates a player's join session when they connect to the server.
    void
    updateLastSession(@NonNull FPlayer fPlayer)
    Updates a player's last seen timestamp when they disconnect from the server.

  • Method Details

    • initialize

      void initialize()
      Initializes playtime tracking by migrating legacy data from platform adapters. Only runs if playtime tracking is enabled and no existing records are found. This serves as a migration for versions prior to 1.9.0 where playtime data was not stored in the database.

    • invalidate

      void invalidate(@NonNull UUID uuid)
      Invalidates cached playtime data for a specific player. Only executes if playtime tracking is enabled.
      Parameters:
      uuid - the UUID of the player whose playtime cache should be invalidated

    • saveAfkSession

      void saveAfkSession(FPlayer fPlayer, boolean afk)
      Saves a player's AFK session status change and invalidates cache. Only executes if playtime tracking is enabled.
      Parameters:
      fPlayer - the player whose AFK status is being updated
      afk - true if the player is going AFK, false if returning from AFK

    • updateJoinSession

      void updateJoinSession(@NonNull FPlayer fPlayer)
      Updates a player's join session when they connect to the server. Saves the session and invalidates cached playtime data. Only executes if playtime tracking is enabled.
      Parameters:
      fPlayer - the player whose join session is being updated

    • updateLastSession

      void updateLastSession(@NonNull FPlayer fPlayer)
      Updates a player's last seen timestamp when they disconnect from the server. Saves the quit session and invalidates cached playtime data. Only executes if playtime tracking is enabled.
      Parameters:
      fPlayer - the player whose last seen time is being updated

    • getPlayTime

      @Nullable PlayTime getPlayTime(FPlayer fPlayer)
      Gets the playtime statistics for a specific player. Returns null if playtime tracking is disabled.
      Parameters:
      fPlayer - the player to get playtime statistics for
      Returns:
      the player's playtime statistics, or null if tracking is disabled or not found

    • getPlayTimesCount

      int getPlayTimesCount()
      Gets the total count of all playtime records in the database. Returns -1 if playtime tracking is disabled.
      Returns:
      the total number of playtime records, or -1 if tracking is disabled

    • getAllPlayTimes

      @NonNull List<PlayTime> getAllPlayTimes(int limit, int offset)
      Gets a paginated list of all playtime records from the database. Returns an empty list if playtime tracking is disabled.
      Parameters:
      limit - the maximum number of records to retrieve
      offset - the number of records to skip before returning results
      Returns:
      list of playtime records within the specified range, or empty list if tracking is disabled