游戏时长
无需额外存储的游戏时长追踪——/playtime [玩家] 可查看玩家的总游戏小时数、排名和当前会话,/tophours [页码] 可查看游玩时间最长的排行榜。适用于 Paper/Purpur 26.3,Java 25。
为什么还要另一个游戏时长插件?
因为服务器本身已经在追踪它。原版统计数据 minecraft:play_time(以刻为单位,每秒 20 刻——在 Bukkit API 中为 Statistic.PLAY_ONE_MINUTE,这是一个遗留名称)是权威来源:
- 在线玩家的数据直接从内存中实时读取(
player.getStatistic(...))。
- 离线玩家的数据来自
<mainWorld>/stats/<uuid>.json,名称信息则取自 usercache.json(备用方案:使用服务器的离线玩家配置文件缓存)。
因此,该插件无需数据库支持,并且在服务器启动时就已经掌握了每位玩家自服务器运行以来的完整历史记录。无需进行数据迁移,不会丢失任何数据,也无需保持同步——移除该插件后,不会产生任何孤立数据。
设计
PlaytimeService 按计时器刷新(refresh-minutes,默认 5 分钟):一次廉价的 同步 快照会捕获在线玩家的实时刻数,随后一个 异步 任务扫描统计文件 + usercache,合并数据(实时获胜——因为文件在服务器自动保存前会有延迟),排序,并通过单个 volatile 引用发布一个不可变快照。
- 命令和占位符 仅读取快照 —— 命令路径上零 I/O,主线程任何地方都无文件 I/O。
- 每个统计文件都在其自身的 try/catch 中解析:一个损坏的 JSON 永远不会导致扫描失败。无法解析名称的玩家会被跳过排行榜(他们的刻数仍通过 UUID 保留)。
- 玩家退出时,排行榜条目会根据实时统计数据修补:退出处理程序仅入队值(O(1)),然后一个合并后的异步任务重建快照 —— 大规模退出(重启、机器人)不会在主线程上对排行榜进行排序。
- 处理重复的可见名称(认证插件或 Geyser 背后的正版/离线配对):名称查找解析为排名最高的持有者,而你自己的排名和占位符始终通过 UUID 解析。
onDisable 仅取消计时器 —— 数据由原版 Minecraft 拥有,无需刷新。
在非常大的服务器上(数万份统计文件),扫描仍然是完全异步的,但你可能需要提高 refresh-minutes 以减少 I/O 开销。
命令
| 命令 |
描述 |
权限(默认) |
/playtime |
你个人的游戏时长、排名和当前会话 |
playtime.use (true) |
/playtime <player> |
其他玩家的游戏时长(在线或离线) |
playtime.use (true) |
/playtime reload |
重载配置文件 + 语言文件,强制重新扫描 |
playtime.admin (op) |
/tophours [page] (别名 /toph) |
排行榜,金/银/铜领奖台,页脚显示自己的排名;支持从控制台/RCON 执行 |
playtime.top (true) |
playtime.admin 包含 playtime.use 和 playtime.top 作为子权限。
玩家名称参数在任何查找之前都会根据 ^[a-zA-Z0-9_]{2,16}$ 进行验证;超出范围的页码会被钳制。
占位符(PlaceholderAPI,可选软依赖)
%playtime_formatted% — 总游戏时长,例如 2d 4h 32m
%playtime_hours% — 服务器默认语言环境下的十进制小时数(52.3 / 52,3)
%playtime_rank% — 排行榜排名(3,若未排名则为 —)
所有占位符均从内存快照解析:调用线程无 I/O 操作,可安全用于逐刻记分板。
语言
面向玩家的消息提供英文(lang/en_US.yml)和葡萄牙文(lang/pt_PT.yml),采用 MiniMessage 格式。在 config.yml 中使用 locale 设置服务器全局默认语言;编辑这些文件或添加额外的 lang/<locale>.yml 文件即可自定义。安装同作者开发的可选插件 PlayerSettings 后,每位玩家将以自己的语言查看该插件。控制台日志始终为英文。
配置
locale: pt_PT # 服务器全局消息语言(参见 lang/)
refresh-minutes: 5 # 排行榜缓存刷新间隔,最小值为 1
top:
page-size: 10 # /tophours 命令每页条目数(5-25)
构建
mvn -B -DskipTests package # -> target/Playtime-2.0.0.jar
需要 Java 25。基于 paper-api 26.3 构建。
源代码
许可证:GPL-3.0
Playtime
Playtime tracking with zero storage of its own — /playtime [player] shows a
player's total hours, rank and current session, /tophours [page] shows the
leaderboard of who played the most. For Paper/Purpur 26.3, Java 25.
Why another playtime plugin?
Because the server already tracks it. The vanilla statistic
minecraft:play_time (ticks, 20/s — Statistic.PLAY_ONE_MINUTE in the Bukkit
API, a legacy name) is the source of truth:
- Online players are read live from memory (
player.getStatistic(...)).
- Offline players come from
<mainWorld>/stats/<uuid>.json, names from
usercache.json (fallback: the server's offline-player profile cache).
So the plugin needs no database and starts already knowing the full
history of every player since the server began. Nothing to migrate, nothing to
lose, nothing to keep in sync — remove the plugin and no data is orphaned.
Design
PlaytimeService refreshes on a timer (refresh-minutes, default 5): a
cheap sync pass snapshots online players' live ticks, then an async
task scans the stats files + usercache, merges (live wins — the files lag
until the server autosaves), sorts, and publishes one immutable snapshot
through a single volatile reference.
- Commands and placeholders read only the snapshot — zero I/O on the
command path, zero file I/O on the main thread anywhere.
- Every stats file is parsed inside its own try/catch: one corrupt JSON never
kills the scan. Players whose name can't be resolved are skipped from the
leaderboard (their ticks are still kept by UUID).
- On quit the leaderboard entry is patched from the live stat: the quit
handler only enqueues values (O(1)) and one coalescing async task rebuilds
the snapshot — a mass quit (restart, bots) never sorts the board on the
main thread.
- Duplicate visible names (premium/offline pairs behind an auth plugin or
Geyser) are handled: name lookups resolve to the best-ranked holder, while
your own rank and placeholders always resolve by UUID.
onDisable only cancels the timer — vanilla owns the data, there is
nothing to flush.
On very large servers (tens of thousands of stats files) the scan is still
fully async, but you may want to raise refresh-minutes to reduce I/O churn.
Commands
| Command |
Description |
Permission (default) |
/playtime |
Your own playtime, rank and current session |
playtime.use (true) |
/playtime <player> |
Someone else's playtime (online or offline) |
playtime.use (true) |
/playtime reload |
Reload config + language files, force a rescan |
playtime.admin (op) |
/tophours [page] (alias /toph) |
Leaderboard, gold/silver/bronze podium, own rank in the footer; works from console/RCON |
playtime.top (true) |
playtime.admin includes playtime.use and playtime.top as children.
Player-name arguments are validated against ^[a-zA-Z0-9_]{2,16}$ before any
lookup; out-of-range page numbers are clamped.
Placeholders (PlaceholderAPI, optional softdepend)
%playtime_formatted% — total playtime, e.g. 2d 4h 32m
%playtime_hours% — decimal hours in the server's default locale (52.3 / 52,3)
%playtime_rank% — leaderboard position (3, or — if unranked)
All placeholders resolve from the in-memory snapshot: no I/O on the calling
thread, safe for per-tick scoreboards.
Languages
Player-facing messages ship in English (lang/en_US.yml) and
Portuguese (lang/pt_PT.yml), MiniMessage format. Pick the server-wide
default with locale in config.yml; edit the files or drop extra
lang/<locale>.yml files to customize. With the optional PlayerSettings
plugin (same author) installed, each player sees the plugin in their own
language. Console logs stay in English.
Config
locale: pt_PT # server-wide message language (see lang/)
refresh-minutes: 5 # leaderboard cache refresh interval, minimum 1
top:
page-size: 10 # /tophours entries per page (5-25)
Build
mvn -B -DskipTests package # -> target/Playtime-2.0.0.jar
Requires Java 25. Built against paper-api 26.3.
Source code
License: GPL-3.0
评论 0
登录后参与评分
还没有评论,来抢沙发吧