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