Playtime Tracker 1.1.0

Features

• Tracks total playtime and AFK time for each player individually.
• Fully exposed API for other plugins to fetch player time data.
• Customizable AFK detection using movement and idle timeout settings.
• Provides commands for checking and resetting player time data.
• Leaderboard showing top players with the most active playtime.
• Optional player exclusion list to prevent tracking certain SteamIDs.
• Data resets automatically on new map saves.
• Clean and formatted time output (e.g. 02h:45m:12s).

Permissions

• playtimetracker.use - Required to use the /playtime command and view your stats or leaderboard entries.

Commands

• /playtime - Displays your total tracked playtime and AFK time.
• /playtime top - Shows the top players on the server ranked by total playtime, up to the configured max entries.
• playtime <nameOrId> - Console-only command that displays a player's tracked time and AFK time. Can be used from server console or by an admin.
• playtime reset <nameOrId> - Console-only command to remove all stored time data for the given player ID or partial name.

Configuration

{
  "Version": "1.0.0",
  "Update Interval Seconds": 60,
  "Enable Afk Tracking": true,
  "Idle Timeout Seconds": 300,
  "Data Autosave Interval Seconds": 300,
  "Reset Data On New Save": false,
  "Top Leaderboard Entries": 10,
  "Do Not Track Players": []
}

• Update Interval Seconds - How often (in seconds) the plugin updates player time, including both playtime and AFK tracking.
• Enable Afk Tracking - Enables detection of whether a player is idle (AFK) based on their movement.
• Idle Timeout Seconds - How long (in seconds) a player must remain unmoving before being marked as AFK.
• Data Autosave Interval Seconds - How often (in seconds) the plugin saves all tracked data to disk to prevent data loss.
• Reset Data On New Save - If true, all saved playtime data will be deleted automatically on map wipe.
• Top Leaderboard Entries - The maximum number of players to include in the /playtime top leaderboard command.
• Do Not Track Players - List of specific player Steam64 IDs that should be excluded from tracking entirely.

Stored Data

{
  "Players": {
    "76561198000000000": {
      "Name": "PlayerOne",
      "Playtime Seconds": 4580.5,
      "Afk Seconds": 900.0,
      "Last Logout Epoch": 1718000000.0,
      "Last Session Active Seconds": 3680.5
    },
    "76561198000000001": {
      "Name": "PlayerTwo",
      "Playtime Seconds": 1220.0,
      "Afk Seconds": 300.0,
      "Last Logout Epoch": 1717990000.0,
      "Last Session Active Seconds": 920.0
    }
  }
}

• Players - A dictionary where the key is the player's Steam64 ID, and the value contains their individual tracked data.

• Name - The player's display name (captured at the time of tracking).
• Playtime Seconds - Total number of seconds the player has been tracked as actively playing (not AFK).
• Afk Seconds - Total number of seconds the player has been tracked as AFK.
• Last Logout Epoch - The exact Unix timestamp of when the player last disconnected from the server.
• Last Session Active Seconds - How many non-AFK seconds the player actively played during their most recent session before disconnecting.

Localization

{
  "Info.SelfTime": "Playtime: {0} (AFK {1})",
  "Info.ResetSuccess": "Reset stats for {0}.",
  "Help.General": "Type /playtime top to see the leaders.",
  "Usage.Console.General": "Usage: playtime <nameOrId> | playtime reset <nameOrId>",
  "Usage.Console.Reset": "Usage: playtime reset <nameOrId>",
  "Leaderboard.Header": "Top playtimes:",
  "Leaderboard.Entry": "{0}. {1} – {2}",
  "Error.NoPermission": "You do not have permission to use this command.",
  "Error.PlayerNotFound": "Player '{0}' not found.",
  "Error.NoDataStored": "No data stored for that player.",
  "Error.NoDataForPlayer": "No data for that player.",
  "Error.UnknownSubCommand": "Unknown sub-command."
}

Developer API

double API_GetPlaytimeSeconds(ulong playerId)

• playerId - Steam64 ID of the player.
• Returns the playtime in seconds as a double.

double API_GetAfkSeconds(ulong playerId)

• playerId - Steam64 ID of the player.
• Returns the AFK time in seconds as a double.

string API_GetFormattedPlaytime(ulong playerId)

• playerId - Steam64 ID of the player.
• Returns a formatted string.

List<Dictionary<string, object>> API_GetTopPlaytimes(int count = 10)

• count - The maximum number of players to include (default is 10).
• Returns a list of dictionaries with PlayerId and PlaytimeSeconds.

double API_GetLastSessionActiveSeconds(ulong playerId)

• playerId - Steam64 ID of the player.
• Returns the active session time in seconds as a double.

double API_GetLastLogoutEpoch(ulong playerId)

• playerId - Steam64 ID of the player.
• Returns the logout time in Unix epoch seconds as a double.

Developer Hooks

void OnPlaytimeUpdate(BasePlayer player, Dictionary<string, object> data)

• player - The player whose stats were updated.
• data- Dictionary containing:
  • PlaytimeSeconds - Total active time.
  • AfkSeconds - Total AFK time.
  • IsCurrentlyAfk - Whether the player is AFK during this update.

void OnPlayerSessionEnded(BasePlayer player, double sessionActiveSeconds, double logoutEpoch)

• player - The player who disconnected.
• sessionActiveSeconds - Total non-AFK seconds played in their most recent session.
• logoutEpoch - Unix timestamp of when the player disconnected.