PlayTimes - Track Player PlayTime - PlayTimes - 玩家在线时长统计

简介

PlayTimes 是一款功能强大的服务器插件，旨在通过展示玩家游戏时长、设立排行榜来提升游戏体验。它不仅能让您轻松查看在线与离线玩家的游玩时间，还能追踪服务器运行时长。此外，插件未来还将推出更多激动人心的功能，包括游戏时长奖励、等级系统以及内置商店。

---

💡核心功能

• 游戏时长追踪与显示：准确记录并展示每位玩家的总游戏时长。
• 实时排行榜：生成基于游戏时长的玩家排行榜，激励竞争。
• 服务器运行时长监控：查看服务器的总在线时间。
• AFK 状态检测：自动检测并可能排除玩家挂机时间（需配置）。
• 跨平台支持：支持 BungeeCord 网络，并兼容多种数据库。
• 高度可扩展：为未来的奖励系统、商店和 GUI 界面预留了架构。

近期新增

• 数据库支持（SQLite等）
• BungeeCord 网络支持
• AFK 状态追踪器

---

🎮安装与配置

前置要求

• 您的世界文件夹中必须包含一个 stats 文件夹，PlayTimes 依赖此文件夹内的统计数据来工作。
• PlayTimes 本身不记录时间，而是读取并展示世界 stat 文件夹中的数据。

检查与设置

如果您的服务器没有 stats 文件夹，请按以下步骤操作：

• 打开 spigot.yml 配置文件。
• 找到 stats 部分。
• 确保将 disable-saving 选项设置为 false。
• 重启服务器以生成 stats 文件夹和数据。

---

🔧使用与命令

您可以通过游戏内命令或查看在线文档来管理插件。

• 使用 /playtimes 查看主命令帮助。
• 使用 /playtime [玩家名] 查询特定玩家的游戏时长。
• 更多详细命令与权限，请查阅官方文档或 Wiki。

资源链接

• 查看完整文档：请访问插件的文档页面。
• 查看 Wiki：获取详细的配置与使用指南。
• 报告问题：如果您遇到任何问题，请先到问题反馈页面提交。

---

✨开发路线图

以下是 PlayTimes 未来的开发计划

版本 1.6

• 数据库支持与 AFK 检查器

版本 1.6.1

• 完整的 SQLite 支持及更多占位符

版本 1.6.2

• 支持 Minecraft 1.20.6 及性能优化

版本 1.6.3

• 基于权限的消息系统与昵称支持

版本 1.6.4

• 易于配置的悬停提示信息

版本 1.7

• 游戏时长奖励、商店与图形用户界面 (GUI)

---

❓常见问题与支持

插件工作异常？

如果插件未能按预期工作，请按以下顺序寻求帮助

• 确保您的 stats 文件夹已正确设置（见上方“安装与配置”部分）。
• 查阅在线文档和 Wiki，寻找解决方案。
• 通过 Discord、Spigot 私信或插件讨论页面联系开发者。

重要提示

• 请勿在评论中直接报告错误。在评论中留下错误信息并不会加快问题解决速度。请先通过上述支持渠道联系开发者，以便更高效地诊断和修复问题。

PlayTimes 是一款功能强大的 Minecraft 插件，用于精确追踪和展示玩家的游戏时长、服务器运行时间，并提供丰富的排行榜与占位符功能，支持单服务器与跨服数据库。

💡核心功能

• 精确追踪玩家的总游戏时长、活跃时长（排除 AFK 时间）和 AFK 时长。
• 提供 /playtime、/uptime、/toppt 等命令，方便玩家和管理员查询。
• 支持丰富的内置占位符和 PlaceholderAPI 占位符，可用于其他插件或聊天栏。
• 可配置的 AFK 检测系统，带有进入/离开 AFK 状态的通知。
• 支持 MySQL 数据库，实现多服务器间的数据同步与统一查询。
• 提供完整的 API，供开发者集成使用。

🎮命令与权限

主要命令

• /playtime - 查看自己的游戏时长统计。
• /playtime <玩家名> - 查看其他玩家的游戏时长统计。
• /playtime block <玩家名> - 将玩家从排行榜中屏蔽。
• /playtime unblock <玩家名> - 解除玩家在排行榜中的屏蔽。
• /playtime top - 查看排行榜（/toppt 的快捷方式）。
• /playtime help - 显示管理员命令帮助。
• /playtime version - 用于错误报告的版本信息。
• /uptime - 查看服务器运行时间。
• /playtime reload - 重载插件配置。
• /topplaytime - 查看游戏时长排行榜。

命令别名

• Playtime 别名: /playerinfo, /playt, /pt
• Uptime 别名: /serveruptime, /serverupt
• TopPlayTime 别名: /toppt

权限节点

• pt.use - 允许使用 /playtime 命令。
• pt.others - 允许查看其他玩家的游戏时长。
• pt.uptime - 允许使用 /uptime 命令。
• pt.reload - 允许重载插件。
• pt.block - 允许屏蔽/解封排行榜玩家。
• pt.top - 允许使用 /toppt 命令。
• pt.block-cooldown - 使用 /toppt 时无冷却时间。

✨占位符

PlayTimes 提供了大量占位符，可用于插件消息或通过 PlaceholderAPI 在其他插件中使用。

内置占位符（用于插件内消息配置）

• %player% - 玩家名称。
• %rawtime% - 玩家的原始总游戏时长。
• %afktime% - 玩家的 AFK 时长。
• %playtime% - 玩家的活跃时长（rawtime 减去 afktime）。
• %timesjoined% - 玩家加入服务器的次数。
• %joindate% - 玩家的首次加入日期。
• %place% - 在排行榜中的名次（仅用于 /toppt）。
• %timeleft% - /toppt 命令的剩余冷却时间（秒）。

数据库占位符（用于多服数据）

• %rawtime_serverId% - 在指定服务器（serverId）上的原始总时长。
• %afktime_serverId% - 在指定服务器上的 AFK 时长。
• %playtime_serverId% - 在指定服务器上的活跃时长。
• %global_playtime% - 所有服务器的总活跃时长。
• %global_rawtime% - 所有服务器的总原始时长。
• %global_afktime% - 所有服务器的总 AFK 时长。

PlaceholderAPI 占位符

若需在其他支持 PAPI 的插件中使用 PlayTimes 的占位符，请确保已安装 PlaceholderAPI。

基础占位符

• %PlayTimes_playtime% - 玩家的活跃时长。
• %PlayTimes_uptime% - 服务器运行时间。
• %PlayTimes_joindate% - 玩家的加入日期。
• %PlayTimes_timesjoined% - 玩家的加入次数。

排行榜占位符

你可以获取第 1 到第 10 名的玩家名称和时长。

• 名称占位符：%PlayTimes_topname1% 到 %PlayTimes_topname10%
• 时长占位符：%PlayTimes_toptime1% 到 %PlayTimes_toptime10%

示例：获取第三名玩家的名称和时长

• %PlayTimes_topname3%
• %PlayTimes_toptime3%

在其他插件中使用 PlayTimes 占位符

• 确保 PlayTimes 插件已安装在 plugins 文件夹中。
• 插件会自动注册占位符，无需额外操作。
• 在支持 PAPI 的插件中直接使用上述占位符即可。

在 PlayTimes 中使用其他插件的占位符

若想在 PlayTimes 的配置消息中使用来自 PlaceholderAPI 的其他占位符（如来自其他插件的），请按以下步骤操作：

• 下载并安装 PlaceholderAPI。
• 下载所需的扩展包：/papi ecloud download <扩展包名称>。
• 重载 PAPI：/papi reload。
• 在 PlayTimes 的 config.yml 中，确保 use-papi-placeholders: 设置为 true。
• 重载 PlayTimes 插件。
• 现在即可在 PlayTimes 的配置消息中使用任何 PAPI 占位符。

🔧配置要点

以下为 config.yml 中的关键配置项说明。

基本设置

• prefix：插件消息的前缀。
• use-papi-placeholders：是否启用对 PlaceholderAPI 占位符的支持。

游戏时长显示格式

• playtime.message：使用 /playtime 命令时显示的消息格式，可使用内置占位符。
• playtime.name：定义时间单位（秒、分钟、小时、天）的显示文本。
• only-hours：是否仅以小时为单位显示时长（启用后会覆盖 show-seconds 和 show-days）。
• show-seconds：是否显示秒数。
• show-days：是否显示天数。
• round-numbers：当 only-hours 启用时，是否将时长四舍五入为整数。

AFK 设置

• afk-settings.enabled：是否启用 AFK 检测。
• afk-settings.threshold：判定为 AFK 的无操作时间（分钟）。
• broadcast-afk：控制玩家进入/退出 AFK 状态时是否发送通知。
• cancel-afk：哪些玩家动作可以取消 AFK 状态（移动、聊天、交互）。

排行榜设置 (`/toppt`)

• top-playtime.header/content/footer：排行榜的头部、内容和脚部消息格式。
• enable-cooldown：是否启用命令冷却。
• cooldown-seconds：冷却时间（秒）。
• track-rawtime：排行榜是否基于原始时长 (rawtime) 而非活跃时长 (playtime)。

数据库配置 (`database.yml`)

要启用多服务器数据同步，需编辑 database.yml。

• enabled：设置为 true 以启用数据库。
• type：数据库类型，mysql 或 sqlite。
• serverId：必须为每个服务器设置唯一标识符（例如 survival, skyblock）。此 ID 也用于占位符，如 %playtime_survival%。
• purge-database：可配置自动清理超过指定月份的老旧数据（仅针对当前 serverId）。

消息与格式

• date-format：自定义日期显示格式。
• messages：自定义各类提示消息，如无权限、玩家未找到等。
• 颜色代码：使用 <#123456> 格式支持 HEX 颜色。
• JSON 文本：支持使用 JSON 格式创建复杂的可交互聊天消息（如悬停文本、点击命令等）。在配置中写入时，需在引号前添加反斜杠进行转义。

⭐API 使用指南

PlayTimes 提供了易于使用的 API，主要包含 TimelessPlayer 和 TimelessServer 两个类。

TimelessPlayer

代表一个玩家（可在线或离线）。

创建在线玩家对象

TimelessPlayer player = new TimelessPlayer(event.getPlayer());

创建离线玩家对象

TimelessPlayer player = new TimelessPlayer(uuid);

主要方法

• getPlayTime() - 返回格式化后的玩家游戏时长。

TimelessServer

用于获取服务器信息。

创建服务器对象

TimelessServer server = new TimelessServer();

主要方法

• getTop10Players() - 返回前10名玩家的列表。
• getNumberOne() - 返回排行榜第一名玩家。
• getNumberTwo() - 返回第二名。
• getNumberThree() ... 依此类推直到 getNumberTen()。
• getUptime() - 返回格式化后的服务器运行时间。
• getUptimeInSeconds() - 返回服务器运行时间（秒）。

注意：建议在处理多个排名位置时使用 getTop10Players() 方法。

❓常见问题与提示

数据记录与更新

• PlayTimes 依赖于 Minecraft 服务器生成的玩家统计数据。请确保你的世界文件夹中包含 stats 文件夹。
• 如果不存在 stats 文件夹，请检查 spigot.yml，确保 stats 部分下的 disable-saving 设置为 false。
• 如果玩家游戏时长更新不及时，可以尝试调整 bukkit.yml 中的 ticks-per.autosave 值为 20（这可能会增加服务器负载，请谨慎调整）。

版本与兼容性

• 旧版 API 目前仍可使用，但将在未来 2-3 个更新后被移除。
• 对于非常旧的 Minecraft 版本，可能需要参考 Legacy MC Version Help 页面。

获取帮助

• 遇到问题？请首先查阅官方 Wiki。
• 如需提交 Bug 或功能请求，请访问插件的 GitHub Issues 页面。