PlaytimeRewards - PlaytimeRewards

欢迎回来！这里是 PlaytimeRewards 的全新版本。本插件完全重写，旨在更简洁、更易维护，它能够追踪每位玩家的在线时长，并按照你的配置给予他们奖励。

💡功能特性

• 追踪玩家的总游戏时长与单次会话时长。
• 可自定义奖励触发方式：按固定时长奖励，或按每日周期奖励。
• 奖励内容支持执行控制台命令、播放粒子效果与声音。
• 未来计划支持直接给予物品等更多奖励形式。
• 完全支持 PlaceholderAPI，可在其他插件中显示时长信息。
• 数据使用 UUID 保存，兼容玩家改名。

🎮前置需求

• 服务器需运行 Java 17 或更高版本。
• 如需使用变量功能，需安装 PlaceholderAPI。

🔧使用方法

基本配置

在配置文件中，你可以

• 设置奖励触发的时长条件（例如每在线1小时）。
• 定义奖励内容，如执行的命令、播放的粒子或声音。
• 配置时长显示的文本格式。

玩家命令

• /ptr：查看自己的在线时长与可领取的奖励。
• /ptr help：查看帮助信息。

管理员命令

• /ptr reload：重载插件配置与语言文件。
• /ptr reset <玩家名>：重置指定玩家的在线时长数据。

✨PlaceholderAPI 变量

本插件提供以下变量，可用于计分板、聊天栏等

格式化时长

• %ptr_playtime%：玩家的总游戏时长（格式在 lang.yml 中定义）。
• %ptr_sessiontime%：玩家本次会话的时长。

累计时长（单位）

• %ptr_playtime_days%：总游戏时长（天）。
• %ptr_playtime_hours%：总游戏时长（小时）。
• %ptr_playtime_minutes%：总游戏时长（分钟）。
• %ptr_playtime_seconds%：总游戏时长（秒）。
• %ptr_sessiontime_days%：会话时长（天）。
• %ptr_sessiontime_hours%：会话时长（小时）。
• %ptr_sessiontime_minutes%：会话时长（分钟）。
• %ptr_sessiontime_seconds%：会话时长（秒）。

分解时长（Trimmed）

这些变量仅返回时长中特定单位的部分。

• 例如：若总时长为 12d3h50m23s，则：

- `%ptr_playtime_hours%` 返回 `291h`（总小时数）。

- `%ptr_playtime_hours_trimmed%` 返回 `3h`（仅“小时”部分）。

• 可用变量包括：

- `%ptr_playtime_days_trimmed%`

- `%ptr_playtime_hours_trimmed%`

- `%ptr_playtime_minutes_trimmed%`

- `%ptr_playtime_seconds_trimmed%`

- `%ptr_sessiontime_days_trimmed%`

- `%ptr_sessiontime_hours_trimmed%`

- `%ptr_sessiontime_minutes_trimmed%`

- `%ptr_sessiontime_seconds_trimmed%`

❓常见问题与计划

常见问题

• 问：我能从旧版 PlaytimeRewards 迁移数据吗？
• 不能。这是完全重写的插件，两者仅名称相同，数据格式不兼容。

• 问：插件支持 1.17.1 以下的版本吗？
• 理论上可以，但插件使用 Java 17 编译，因此服务器必须运行 Java 17 或更高版本。对于使用旧版 Java 的服务器，目前视为不支持。

• 问：插件如何保存数据？
• 数据保存在 playerData.yml 文件中，使用 UUID 而非玩家名记录，以节省空间并兼容改名。

• 问：插件支持 /reload 吗？
• 代码设计时考虑了重载支持，但未经过充分测试，建议优先使用重启来确保稳定性。

未来开发计划

• 支持自定义进度（Advancements）作为奖励。
• 添加游戏内 GUI 奖励编辑器。
• 添加离线时间计算（上次退出到本次登录的时间）。
• 添加 AFK（挂机）检测与时间排除功能。

⭐注意事项

• 请勿在评论中报告错误或提出建议，请使用插件页面的“讨论”板块，以便更好地交流与处理。
• 本插件使用 bStats 收集匿名使用数据以帮助改进。
• 感谢 ViscousHurricane 创作的优秀艺术作品！
• 更多详细配置信息，请查看插件文件内的 config.yml 与 lang.yml，或访问文档页面。

PlaytimeRewards 是一款用于追踪玩家游戏时长并发放奖励的 Minecraft 插件。它提供了查看游戏时长、时长排行榜以及根据累计或会话时长自动发放奖励的功能，并支持高度自定义的奖励配置和消息文本。

💡命令与权限

/playtime 或 /pt

查看游戏时长。

• /pt - 查看自己的游戏时长和本次会话时长。
• /pt [玩家名] - 查看指定在线玩家的游戏时长。
• /pt [离线玩家名] - 查看指定离线玩家的总游戏时长。

权限节点：

• playtimerewards.cmd.playtime.own - 查看自己的游戏时长。
• playtimerewards.cmd.playtime.others - 查看其他在线玩家的游戏时长。
• playtimerewards.cmd.playtime.others.offline - 查看离线玩家的游戏时长。

相关消息：

• CMD_SUC_PT_OWN: 显示自己的游戏时长。
• 参数 0-3: 总游戏时长（天、时、分、秒）。
• 参数 4-7: 本次会话时长（天、时、分、秒）。
• CMD_SUC_PT_OTHER: 显示指定在线玩家的游戏时长。
• 参数 0 & 5: 玩家名。
• 参数 1-4: 总游戏时长。
• 参数 6-9: 本次会话时长。
• CMD_SUC_PT_OTHER_OFFLINE: 显示指定离线玩家的游戏时长。
• 参数 0: 玩家名。
• 参数 1-4: 总游戏时长。
• CMD_ERR_NO_PERMISSION: 无权限提示。
• CMD_ERR_PLAYER_NOT_FOUND: 未找到玩家错误提示。
• 参数 0: 输入的玩家名。
• CMD_ERR_TOO_MANY_REQUESTS: 请求过于频繁错误提示（限制为每 10 秒 1 次请求）。

/playtimetop 或 /pttop

显示游戏时长排行榜。

权限节点：

• playtimerewards.cmd.playtimetop - 使用此命令。

配置项：

• PlaytimeTopAmount: (默认 10) 设置排行榜显示的玩家数量。

相关消息：

• CMD_SUC_PTTOP_HEADER: 排行榜标题行。
• 参数 0: 显示的玩家数量。
• CMD_SUC_PTTOP_ENTRY: 每个排行榜条目的显示格式。
• 参数 0: 排名。
• 参数 1: 玩家名。
• 参数 2-5: 游戏时长（天、时、分、秒）。

/playtimerewards 或 /ptr

插件管理命令。

• /ptr list - 列出所有已注册的奖励。
• /ptr reload - 重载所有插件数据（config.yml, lang.yml, rewards.yml）。
• /ptr info - 显示插件相关信息。

权限节点：

• playtimerewards.cmd.playtimerewards.list - 使用 list 子命令。
• playtimerewards.cmd.playtimerewards.reload - 使用 reload 子命令。
• playtimerewards.cmd.playtimerewards.info - 使用 info 子命令。

相关消息：

• CMD_SUC_PTR_LIST_HEADER: 奖励列表标题。
• 参数 0: 列出的奖励数量。
• CMD_SUC_PTR_LIST_ENTRY: 每个奖励条目的显示格式。
• 参数 0: 奖励的内部名称。
• 参数 1: 奖励的显示名称。
• 参数 2: 奖励的计数类型（CountType）。
• CMD_SUC_PTR_RELOAD_SUCCESS: 重载成功提示。

🎮配置文件

插件包含三个主要的配置文件：config.yml、rewards.yml 和 lang.yml。首次启动插件时会自动生成。

config.yml

包含插件的主要配置。

主要选项：

• EnableUpdateCheck: (默认 true) 是否检查新版本。
• AllowAutoUpdate: (默认 false) 是否允许在服务器重启时自动下载并安装最新版本。
• PlaytimeTopAmount: (默认 10) /pttop 命令显示的玩家数量。
• DataSaveInterval: (默认 '1h30m') 数据自动保存间隔。设置为 '-1' 可禁用。
• ColorCode: (默认 '§') 插件使用的颜色代码。此为隐藏选项，需手动添加。

AFK 系统配置：

• AFK.Enable: (默认 false) 是否启用 AFK 检测系统。
• AFK.Time: (默认 '10m') 玩家无操作后被标记为 AFK 的时间。
• AFK.CancelOnMove: (默认 true) 移动是否重置 AFK 状态。
• AFK.CancelOnLook: (默认 true) 环视是否重置 AFK 状态。
• AFK.CancelOnInteract: (默认 true) 交互（点击）是否重置 AFK 状态。
• AFK.CancelOnChat: (默认 true) 聊天是否重置 AFK 状态。
• AFK.CancelOnCommand: (默认 true) 执行命令是否重置 AFK 状态。

rewards.yml

定义所有基于时长的奖励。

奖励结构示例：

SampleReward1:
  DisplayName: '§3I´m a cool §4Reward§3!' # 游戏中显示的奖励名称
  CountType: 'PLAYTIME' # 计数类型：PLAYTIME（总时长）, SESSION_TIME（会话时长）, GLOBAL_TIME（全局时长）
  Time: '1m30s' # 触发奖励所需的时间，支持 d（天）、h（时）、m（分）、s（秒）的组合，如 '3d15m'
  Repeating: true # 是否可重复获取（例如每 5 秒一次）
  GrantFirst: false # 是否在首次满足条件时立即授予（对非重复奖励无意义）
  PermissionNeeded: 'cool.long.time.player.rank' # 获取此奖励所需的权限（可选）
  ConsoleCommands: # 从控制台执行的命令（可选）
    - 'say <PLAYER> is a cool Person!'
  Display:
    PlayerMessages: # 发送给获得奖励的玩家的消息（可选）
      - 'Congrats <PLAYER> upon Earning <REWARD>'
    GlobalMessages: # 发送给全服玩家的消息（可选）
      - '<PLAYER> earned the Achievement <REWARD>'
    ActionbarMessage: '§1Hello §4<PLAYER>§1!' # 动作栏消息（可选）
    Particles: # 粒子效果（可选）。格式：'粒子名称, 数量, offsetX, offsetY, offsetZ, extra'
      - 'FLAME, 10, 0.2, 0.2, 0.2, 1'
    Sounds: # 音效（可选）。格式：'音效名称, 音效类别, 音量, 音高'
      - 'BLOCK_BELL_USE, PLAYERS, 1.0, 1.0'

重要说明：

• 每个奖励的名称（如 SampleReward1）必须是唯一的。
• 标记为“可选”的部分可以完全删除，以保持文件简洁。
• 可用的计数类型（CountType）为 PLAYTIME、SESSION_TIME 和 GLOBAL_TIME。

lang.yml

自定义插件发送给玩家的所有消息。

消息变量：

• 每条消息中的 %[x] 代表一个将由插件填充的参数，请确保按正确顺序使用它们。
• 自插件 v0.1.5 起，支持在消息中使用十六进制颜色代码。

十六进制颜色使用语法：

• 简单颜色：§([HexColor])

  CMD_SUC_PT_OWN: |-
    §(fc03ad)Your Playtime is %[0]d %[1]h %[2]m %[3]s

• 颜色渐变：§([HexRangeBeginning]-) [文本] §(-[HexRangeEnding])

  CMD_SUC_PT_OWN: |-
    §(031cfc-)Your Playtime is %[0]d %[1]h %[2]m %[3]s§(-fc03ad)

默认包含的消息：

• 所有命令的成功与错误返回消息。
• AFK 状态变更通知 (NOTIF_AFK_USER_WENT_AFK, NOTIF_AFK_USER_CAME_BACK)。
• 更新可用通知 (NOTIF_UPDATE_AVAILABLE)。
• PlaceholderAPI 时间格式 (EXT_PAPI_TIME_FORMAT)。

扩展资源：

• 你可以在 GitHub 上找到公开的语言文件。
• 音效列表：https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html
• 音效类别列表：https://hub.spigotmc.org/javadocs/spigot/org/bukkit/SoundCategory.html
• 粒子效果列表：https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html