feat: 修正使用说明md文件

2026-06-02 16:39:36 +08:00
parent 3dd0e0a27d
commit 161fc0d0ed
2 changed files with 0 additions and 459 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,604 @@
+# 1.AuOnlineReward 是什么？
+
+AuOnlineReward 是一个 Minecraft 1.12.2 Bukkit / Spigot 在线奖励插件。
+
+它用于根据玩家在线时间发放阶段奖励，并根据阶段奖励领取次数解锁累积奖励。
+
+核心功能：
+
+- 玩家通过 GUI 查看在线信息和奖励状态
+- 支持每日在线阶段奖励
+- 支持累积领取次数奖励
+- 支持每日在线数据刷新
+- 支持月度在线数据刷新
+- 支持配置奖励物品和奖励命令
+- 支持通过 API 获取玩家在线时间
+- 支持奖励领取事件，方便其他插件监听
+
+简单理解：
+
+```yml
+AuOnlineReward = 在线时长统计 + 在线奖励 GUI + 奖励命令执行
+玩家 = 在线积累时间并领取奖励
+管理员 = 配置奖励物品、奖励条件和发奖命令
+```
+
+------
+
+# 2.运行环境
+
+## 服务端版本
+
+```yml
+Minecraft: 1.12.2
+服务端: Bukkit / Spigot / Paper
+Java: 8
+```
+
+## 前置插件
+
+AuOnlineReward 依赖 DemonAPI。
+
+`plugin.yml` 中已经声明：
+
+```yml
+depend:
+  - DemonAPI
+```
+
+服务器启动前必须确保 DemonAPI 已放入插件目录。
+
+------
+
+# 3.安装方式
+
+## 第一步：放入插件
+
+将插件 jar 放入服务器插件目录：
+
+```yml
+plugins/AuOnlineReward.jar
+```
+
+同时放入前置插件：
+
+```yml
+plugins/DemonAPI.jar
+```
+
+## 第二步：启动服务器
+
+首次启动后会生成插件配置文件。
+
+## 第三步：检查加载
+
+控制台应能看到插件正常启用，没有缺少 DemonAPI 的报错。
+
+------
+
+# 4.目录结构
+
+## 插件配置目录
+
+默认配置和语言文件位于：
+
+```yml
+plugins/AuOnlineReward/config.yml
+plugins/AuOnlineReward/language.yml
+```
+
+## 玩家数据目录
+
+玩家在线数据会保存到：
+
+```yml
+plugins/AuData/AuOnlineReward/玩家名.yml
+```
+
+玩家数据示例：
+
+```yml
+OnlineData:
+  todayOnline: 0
+  totalOnline: 0
+  monthOnline: 0
+  totalSign: 0
+  signAmount: 0
+  currentReward: MinuteReward_30
+  collectionTime: 1717200000000
+  offlineTime: 1717200000000
+  receivedList: []
+  permanentReceived: []
+```
+
+字段说明：
+
+```yml
+todayOnline: 今日在线秒数
+totalOnline: 累积在线秒数
+monthOnline: 本月在线秒数
+totalSign: 总计领取阶段奖励次数
+signAmount: 当前轮累积领取阶段奖励次数
+currentReward: 当前可领取的阶段奖励
+collectionTime: 上次阶段奖励领取时间
+offlineTime: 上次离线时间
+receivedList: 今日已领取阶段奖励
+permanentReceived: 当前轮已领取累积奖励
+```
+
+------
+
+# 5.玩家命令
+
+## 打开在线奖励界面
+
+```yml
+/auonline open
+```
+
+玩家执行后会打开在线福利 GUI。
+
+GUI 中会显示：
+
+- 累积在线时间
+- 本月在线时间
+- 今日在线时间
+- 总计领取奖励次数
+- 阶段奖励状态
+- 累积奖励状态
+
+注意：
+
+```yml
+每日 00:10 前无法打开 GUI
+这是为了避免跨日数据刷新期间领取状态异常
+```
+
+------
+
+# 6.管理员命令
+
+管理员命令需要 OP 权限。
+
+## 查看命令帮助
+
+```yml
+/auonline
+```
+
+## 重载配置
+
+```yml
+/auonline reload
+```
+
+重载内容：
+
+- 奖励配置
+- 语言配置
+- GUI 标题
+- 奖励显示文本
+
+## 刷新所有玩家每日数据
+
+```yml
+/auonline dayrefresh
+```
+
+作用：
+
+- 清空今日在线时间
+- 重置当前阶段奖励
+- 重置今日阶段奖励领取记录
+- 重新载入在线玩家数据
+
+## 刷新指定玩家每日数据
+
+```yml
+/auonline dayrefresh 玩家名
+```
+
+只刷新指定玩家的每日在线奖励数据。
+
+## 查看玩家数据
+
+```yml
+/auonline info 玩家名
+/auonline look 玩家名
+```
+
+不填写玩家名时，默认查看执行者自己的数据。
+
+## 查看今日在线排行
+
+```yml
+/auonline topDay
+/auonline top
+```
+
+显示当前已缓存玩家的今日在线排行。
+
+------
+
+# 7.奖励类型
+
+AuOnlineReward 当前包含两类奖励。
+
+## 阶段奖励
+
+配置节点通常以 `MinuteReward_` 开头。
+
+示例：
+
+```yml
+RewardData:
+  MinuteReward_30:
+    slot: 10
+    needOnline: 1800
+    needOnlineTime: 1800
+    itemStack:
+      ==: org.bukkit.inventory.ItemStack
+      type: IRON_INGOT
+    commands:
+      - eco give %player% 500
+```
+
+字段说明：
+
+```yml
+slot: GUI 中的格子位置
+needOnline: 距离上次阶段奖励领取需要等待的秒数
+needOnlineTime: 今日在线秒数要求
+itemStack: GUI 中展示的奖励物品
+commands: 领取后执行的命令
+```
+
+阶段奖励领取成功后：
+
+- 增加当前轮阶段领取次数
+- 增加总计阶段领取次数
+- 写入今日已领取记录
+- 切换到下一个阶段奖励
+- 执行奖励命令
+- 保存玩家数据
+
+## 累积奖励
+
+配置节点通常以 `SignReward_` 开头。
+
+示例：
+
+```yml
+RewardData:
+  SignReward_15:
+    slot: 29
+    needOnline: 25
+    itemStack:
+      ==: org.bukkit.inventory.ItemStack
+      type: CHEST
+    commands:
+      - eco give %player% 10000
+```
+
+字段说明：
+
+```yml
+slot: GUI 中的格子位置
+needOnline: 需要累计领取多少次阶段奖励
+itemStack: GUI 中展示的奖励物品
+commands: 领取后执行的命令
+```
+
+累积奖励领取成功后会写入 `permanentReceived`。
+
+当领取 `SignReward_Max` 后：
+
+```yml
+signAmount 会重置为 0
+permanentReceived 会清空
+进入下一轮累积奖励
+```
+
+------
+
+# 8.奖励命令怎么写？
+
+奖励命令写在 `commands` 列表中。
+
+示例：
+
+```yml
+commands:
+  - eco give %player% 500
+  - points give %player% 10
+  - bcm &a玩家 &e%player% &a领取了在线奖励
+```
+
+支持占位符：
+
+```yml
+%player%   玩家名
+%itemName% 奖励物品显示名
+```
+
+如果命令包含 `msg:`，会向玩家发送消息，而不是由控制台执行命令。
+
+示例：
+
+```yml
+commands:
+  - "msg:&a你领取了在线奖励"
+```
+
+颜色代码支持：
+
+```yml
+&a &b &c &e &f
+```
+
+插件执行时会转换为 Minecraft 颜色符号。
+
+------
+
+# 9.语言文件怎么写？
+
+语言文件为：
+
+```yml
+plugins/AuOnlineReward/language.yml
+```
+
+主要节点：
+
+```yml
+Online-Gui:
+  Title: "§r日常福利 - 累积在线豪礼相赠"
+  Received: "§a§l★ §7领取状态: §a已领取"
+  Not-Started: "§c§l★ §7领取状态: §c未开始"
+  Pending: "§b§l★ §7领取状态: §b待领取"
+  Total-Online: "§7累积在线: §a%time%"
+  Monthly-Online: "§7本月在线: §a%time%"
+  Daily-Online: "§7今日在线: §a%time%"
+  Total-Rewards: "§7总计领取奖励: §a%amount%次"
+Message:
+  Reward-Progress: "你还需要获取§e[%amount%次]§a阶段奖励才能领取奖励。"
+  Wait-Time: "您还需要等待§e[%time%秒]§a才能领取该奖励。"
+  Daily-Requirement: "你需要今日在线§e[%time%秒]§a才能领取该奖励。"
+  Already-Claimed: "你已经领取过这个累积奖励。"
+  Not-Available: "这个阶段奖励尚未开启,暂时无法领取。"
+```
+
+修改语言文件后执行：
+
+```yml
+/auonline reload
+```
+
+------
+
+# 10.在线时间刷新机制
+
+## 在线计时
+
+插件会定时统计在线玩家的在线时长。
+
+统计字段：
+
+```yml
+todayOnline: 今日在线
+monthOnline: 本月在线
+totalOnline: 累积在线
+```
+
+玩家退出时会补算最后一段在线时间，并保存玩家数据。
+
+## 每日刷新
+
+每日刷新会处理：
+
+```yml
+todayOnline = 0
+currentReward = MinuteReward_30
+receivedList = []
+collectionTime = 当前时间
+```
+
+## 月度刷新
+
+月度刷新会处理：
+
+```yml
+monthOnline = 0
+```
+
+## 刷新性能说明
+
+批量刷新玩家文件时，插件会将 YAML 文件读写放到异步任务中执行。
+
+刷新完成后，再回到主线程重新载入在线玩家。
+
+这样可以降低大量玩家数据文件刷新时对主线程的影响。
+
+------
+
+# 11.API 调用
+
+其他插件可以通过 `OnlineAPI` 获取玩家在线时间。
+
+## 获取今日在线分钟数
+
+```java
+int minutes = OnlineAPI.getTime(playerName);
+```
+
+## 获取本月在线分钟数
+
+```java
+int minutes = OnlineAPI.getTimeMonth(playerName);
+```
+
+## 获取累积在线分钟数
+
+```java
+int minutes = OnlineAPI.getTimeTotal(playerName);
+```
+
+注意：
+
+```yml
+API 返回单位是分钟
+底层玩家数据保存单位是秒
+```
+
+------
+
+# 12.事件监听
+
+玩家成功领取奖励后会触发：
+
+```java
+OnlineRewardEvent
+```
+
+监听示例：
+
+```java
+@EventHandler
+public void onOnlineReward(OnlineRewardEvent event) {
+    Player player = event.getPlayer();
+    String playerName = event.getPlayerName();
+    String rewardKey = event.getOnlineData().getRewardKey();
+}
+```
+
+事件可用于：
+
+- 记录领奖日志
+- 触发额外奖励
+- 接入活动系统
+- 接入统计系统
+
+------
+
+# 13.配置示例
+
+## 阶段奖励示例
+
+```yml
+RewardData:
+  MinuteReward_30:
+    slot: 10
+    needOnline: 1800
+    needOnlineTime: 1800
+    itemStack:
+      ==: org.bukkit.inventory.ItemStack
+      type: IRON_INGOT
+      meta:
+        ==: ItemMeta
+        meta-type: UNSPECIFIC
+        display-name: §6§l阶段奖励 I
+        lore:
+          - §7还差 §c%time% §7才能领取
+          - §e金币 §e*500
+    commands:
+      - eco give %player% 500
+```
+
+## 累积奖励示例
+
+```yml
+RewardData:
+  SignReward_15:
+    slot: 29
+    needOnline: 25
+    itemStack:
+      ==: org.bukkit.inventory.ItemStack
+      type: CHEST
+      meta:
+        ==: ItemMeta
+        meta-type: TILE_ENTITY
+        display-name: §6§l累积打卡奖励 I
+        lore:
+          - §7还需领取 §c%amounut% §7阶段奖励
+          - §e金币 §e*10000
+    commands:
+      - eco give %player% 10000
+```
+
+注意：
+
+```yml
+阶段奖励 lore 中需要包含 %time%
+累积奖励 lore 中需要包含 %amounut%
+```
+
+------
+
+# 14.常见问题
+
+## 执行 /auonline open 没反应
+
+检查：
+
+```yml
+是否在每日 00:10 之前
+DemonAPI 是否正常加载
+language.yml 中 Title 是否存在
+config.yml 中 RewardData 是否存在
+```
+
+## 奖励无法领取
+
+检查：
+
+```yml
+今日在线秒数是否达到 needOnlineTime
+距离上次领取是否达到 needOnline
+currentReward 是否等于当前点击的阶段奖励
+该奖励是否已经在 receivedList 中
+```
+
+## 累积奖励无法领取
+
+检查：
+
+```yml
+signAmount 是否达到 needOnline
+该奖励是否已经在 permanentReceived 中
+```
+
+## 修改配置后没有变化
+
+执行：
+
+```yml
+/auonline reload
+```
+
+如果删除了奖励节点，重载后旧奖励缓存会被清理。
+
+## 玩家数据异常
+
+可以刷新指定玩家每日数据：
+
+```yml
+/auonline dayrefresh 玩家名
+```
+
+也可以检查玩家数据文件：
+
+```yml
+plugins/AuData/AuOnlineReward/玩家名.yml
+```
+
+------
+
+# 15.维护建议
+
+- 修改奖励配置前，先备份 `config.yml`。
+- 大量玩家数据刷新建议避开服务器高峰期。
+- 奖励命令应先在测试服验证，避免命令拼写错误导致奖励无法发放。
+- 不建议把高耗时命令放入奖励命令列表。
+- 修改语言或奖励配置后，使用 `/auonline reload` 重载。
+- 发布新版本时，应同步检查 `plugin.yml` 的版本号。
+- 每次更新后建议至少完成一次登录、打开 GUI、领取奖励、退出保存的冒烟测试。