605 lines
11 KiB
Markdown
605 lines
11 KiB
Markdown
# 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、领取奖励、退出保存的冒烟测试。
|