WeeklyTime

Tracks player playtime and reports it to admins via a Telegram bot. Admins (by Telegram ID) can request the player list with playtime for any period — week, month, all-time or custom — in private chats, groups and supergroups.

Features

• Playtime tracking: session-based, auto-saved every N minutes, stored in SQLite
• Calendar periods: week resets Monday 00:00, month resets on the 1st 00:00 (configurable timezone), automatic cleanup of old records
• Telegram bot (no external libraries, native HTTP API):
  • /time week — stats for the current week
  • /time month — stats for the current month
  • /time alltime — all-time stats
  • /time <days> — custom period (1–365)
  • /player <name> [days] — single player stats
  • /reset [days] — reset data with /confirm / /cancel confirmation
  • /stats — plugin statistics
  • /reload — reload configuration
  • /help — command list
  • Old aliases still work: /week, /month, /alltime
• Works in private chats, groups and supergroups; chat access control (all / whitelist / blacklist)
• Only configured admin Telegram IDs can use the bot
• Rank emojis for top-3, configurable time formats, message splitting for large lists
• Localization: locale: en by default, messages-en.yml and messages-ru.yml bundled, custom languages supported

Compatibility

• Server software: Paper, Spigot, Bukkit, Purpur, Pufferfish, Leaves and any other Bukkit fork. On Fabric/Quilt it works through Banner/CardBoard
• Minecraft versions: 1.21 – 26.x (Java 21+)
• Folia: fully compatible (no Bukkit scheduler usage)
• No required dependencies: Telegram API is called via the JDK HTTP client, SQLite is bundled

Installation

1. Download WeeklyTime-1.00.jar
2. Place it in the server's plugins folder
3. Restart the server
4. Edit plugins/WeeklyTime/config.yml:
   • telegram.bot-token — token from @BotFather
   • telegram.admins — your Telegram IDs (find yours via @userinfobot)
5. Restart the server (or run /weeklytime reload — token changes still need a restart)

To find the chat ID of a group: add the bot to the group, send any message, then check the plugin logs — or use @userinfobot.

In-game commands

Configuration

locale: en

telegram:
  bot-token: "YOUR_BOT_TOKEN_HERE"
  bot-username: "WeeklyTimeBot"
  admins:
    - 123456789
  access-control:
    allowed-chats-mode: "all"
    allowed-chats: []

database:
  path: "plugins/WeeklyTime/player_times.db"

tracking:
  save-interval-minutes: 5
  min-session-seconds: 30
  disabled-worlds: []
  timezone: "system"        # "system" or IANA name, e.g. "Europe/Minsk"
  keep-records-days: 90     # auto-cleanup of old records

output:
  max-players-per-message: 30
  min-time-minutes: 1
  time-format: "short"
  show-rank-emojis: true
  divider-char: "━"

performance:
  cache-duration-seconds: 60

Localization

The plugins/WeeklyTime/lang/ folder contains messages-en.yml and messages-ru.yml (both are extracted on first start). To add your own language, copy a file as messages-<code>.yml, edit it and set locale: <code> in the config. Missing strings fall back to the bundled English template, then to Russian.

Notes

• Session data is saved on quit and every save-interval-minutes minutes
• Players in disabled-worlds are not tracked
• Playtime is stored per player UUID, so renames keep the history
• /reset requires confirmation to avoid accidental data loss

License

MIT. Author: Sooqwess