# ⏱️ PlayTimePulse
一个轻量级且准确的 Minecraft 插件，用于跟踪玩家游戏时间，无缝集成 PlaceholderAPI，并提供内置奖励系统，带有可认领的 GUI。
---
## 🌟 主要功能
- ⏳ **实时游戏时间跟踪** - 准确跟踪每个玩家在你的服务器上的游戏时间
- 🎁 **24+ 游戏时间奖励** - 基于里程碑的奖励，玩家随着游戏时间的增加可以认领
- 📖 **分页奖励 GUI** - 易于浏览的界面，包含多个页面以显示所有奖励
- 🧾 **简单命令** - 用于玩家的 `/playtime` 命令和管理员工具
- 🔌 **PlaceholderAPI 支持** - 通过占位符与流行的插件集成
- 🛡️ **空闲保护** - 防止玩家通过空闲状态作弊
- 💾 **高效数据存储** - 轻量级扁平文件存储，并自动保存
- ⚡ **高性能** - 优化后的代码，不会降低服务器性能
- 🛡️ **奖励错误处理** - 即使命令失败也能防止奖励垃圾信息
- ⚙️ **灵活的配置** - 轻松自定义所有奖励、GUI 和设置
## 📦 所有功能
- ⏳ 实时游戏时间跟踪（已保存 + 当前会话）
- 🧾 `/playtime` 命令：
- 显示格式化的游戏时间，例如 `Xd Yh Zm`
- 打开 GUI 以认领基于游戏时间的奖励
- 🎁 奖励系统：
- 基于里程碑的奖励 (当前配置文件中包含 24 个奖励，未来还会增加更多)
- 支持命令 (因为大多数内容都是通过命令给出的)
- 通过跟踪保存来阻止重复认领
- GUI 图标支持玩家头颅 (例如，自定义头颅，玩家骷髅头)
- 认领奖励时的自定义音效
- 失败命令的错误处理，以防止奖励垃圾信息
- 📖 分页奖励 GUI：
- 支持大量奖励的分页
- 可自定义的每页插槽
- 用于在页面之间移动的导航按钮
- 🧭 导航系统：
- 前一页/下一页按钮
- 关闭按钮退出 GUI
- 可自定义的导航按钮材质和名称
- 可选的导航按钮自定义头颅纹理
- 🛡️ 空闲保护：
- 防止空闲农游戏时间
- 可配置的交互阈值和时间窗口
- 跟踪有意义的玩家交互以验证活动
- 🔌 完全支持 PlaceholderAPI
- 📊 bStats 集成用于匿名使用统计数据
- 📁 具有自动保存功能的扁平文件存储
- ⚙️ 性能优化且易于配置
---
## 🔧 命令
| 命令 | 描述 | 权限 |
|------------------------------------------------|---------------------------------------------|----------------|
| `/playtime` | 显示游戏时间和奖励 GUI | playtime.use |
| `/playtime add h [m]` | 向玩家添加游戏时间 | playtime.admin |
| `/playtime reset ` | 重置玩家的游戏时间和已认领奖励 | playtime.admin |
---
## 🧩 PlaceholderAPI 支持
| 占位符 | 描述 |
|--------------------------------|----------------------------------------------------------|
| `%playtime_overall_formatted%` | 总时间（已保存 + 当前会话），格式为 `2d 4h 30m` |
| `%playtime_formatted%` | 当前会话仅限，格式化 |
| `%playtime_overall%` | 总时间（已保存 + 当前会话），以秒为单位 |
| `%playtime_saved%` | 仅保存的游戏时间（以秒为单位） |
| `%playtime_current%` | 当前在线会话（以秒为单位） |
---
## 🧪 未来计划
- 🎨 格式化文本的渐变色彩支持
- 🌟 奖励认领的粒子效果
- 🐛 调试模式以方便故障排除
- ➕ 更多功能即将推出
---
## 📁 配置
- `config.yml`: 定义游戏时间里程碑、奖励（命令）、要求、奖励图标/lore 和音效。
- 每个奖励在认领时可以使用 `claimSound` 参数自定义音效
- 从超过 400 种 Minecraft 音效中选择（例如，`entity.player.levelup`，`block.note_block.pling`）
- 所有音效以标准音量 (1.0) 和音调 (1.0) 播放
- 可以使用 `headId` 并带有 Base64 纹理值添加自定义头颅
- 使用 `page` 参数指定奖励应出现在哪个页面上（从 0 开始）
- 导航按钮可以使用 `headId` 参数使用自定义玩家头颅
- 可配置 GUI 插槽和每页插槽
- 空闲保护设置：
- `interaction-threshold`: 在时间窗口中所需的最小交互次数
- `time-window-minutes`: 用于检查交互的时间窗口（分钟）
---
## 📥 安装
1. 下载最新版本
2. 将 `.jar` 文件放入您的 `/plugins` 文件夹
3. 重启服务器
4. 配置 `config.yml` 以定义奖励/要求。
5. (可选) 安装 [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) 以使用占位符
---
## ✅ 要求
- Minecraft: `1.21 up to 1.21.8`
- Java: `21+`
- 服务器: Paper / Pufferfish / Purpur (其他需要测试)
- (可选) PlaceholderAPI
---
## 📊 统计数据
PlayTimePulse 通过 bStats 收集匿名使用统计数据。 这有助于我们了解插件的使用情况，并指导未来的开发。
您可以在 [bStats](https://bstats.org/plugin/bukkit/PlayTimePulse/26638) 上查看插件统计数据。
要选择退出统计数据收集，请在 `/plugins/bStats/config.yml` 文件中将 `enabled` 设置为 `false`。
---
## 💬 支持
- 📬 [打开一个问题](https://github.com/Souldevhub/PlayTimePulse/issues)
- 💻 [Discord](https://discord.gg/6SCAZfENjw)