yhy/AuPet

Fork 0

Files

yhy 293a160856 初始化项目

2026-06-03 06:25:44 +08:00

11 KiB

Raw Blame History

1.AuOnlineReward 是什么？

AuOnlineReward 是一个 Minecraft 1.12.2 Bukkit / Spigot 在线奖励插件。

它用于根据玩家在线时间发放阶段奖励，并根据阶段奖励领取次数解锁累积奖励。

核心功能：

玩家通过 GUI 查看在线信息和奖励状态
支持每日在线阶段奖励
支持累积领取次数奖励
支持每日在线数据刷新
支持月度在线数据刷新
支持配置奖励物品和奖励命令
支持通过 API 获取玩家在线时间
支持奖励领取事件，方便其他插件监听

简单理解：

AuOnlineReward = 在线时长统计 + 在线奖励 GUI + 奖励命令执行
玩家 = 在线积累时间并领取奖励
管理员 = 配置奖励物品、奖励条件和发奖命令

2.运行环境

服务端版本

Minecraft: 1.12.2
服务端: Bukkit / Spigot / Paper
Java: 8

前置插件

AuOnlineReward 依赖 DemonAPI。

plugin.yml 中已经声明：

depend:
  - DemonAPI

服务器启动前必须确保 DemonAPI 已放入插件目录。

3.安装方式

第一步：放入插件

将插件 jar 放入服务器插件目录：

plugins/AuOnlineReward.jar

同时放入前置插件：

plugins/DemonAPI.jar

第二步：启动服务器

首次启动后会生成插件配置文件。

第三步：检查加载

控制台应能看到插件正常启用，没有缺少 DemonAPI 的报错。

4.目录结构

插件配置目录

默认配置和语言文件位于：

plugins/AuOnlineReward/config.yml
plugins/AuOnlineReward/language.yml

玩家数据目录

玩家在线数据会保存到：

plugins/AuData/AuOnlineReward/玩家名.yml

玩家数据示例：

OnlineData:
  todayOnline: 0
  totalOnline: 0
  monthOnline: 0
  totalSign: 0
  signAmount: 0
  currentReward: MinuteReward_30
  collectionTime: 1717200000000
  offlineTime: 1717200000000
  receivedList: []
  permanentReceived: []

字段说明：

todayOnline: 今日在线秒数
totalOnline: 累积在线秒数
monthOnline: 本月在线秒数
totalSign: 总计领取阶段奖励次数
signAmount: 当前轮累积领取阶段奖励次数
currentReward: 当前可领取的阶段奖励
collectionTime: 上次阶段奖励领取时间
offlineTime: 上次离线时间
receivedList: 今日已领取阶段奖励
permanentReceived: 当前轮已领取累积奖励

5.玩家命令

打开在线奖励界面

/auonline open

玩家执行后会打开在线福利 GUI。

GUI 中会显示：

累积在线时间
本月在线时间
今日在线时间
总计领取奖励次数
阶段奖励状态
累积奖励状态

注意：

每日 00:10 前无法打开 GUI
这是为了避免跨日数据刷新期间领取状态异常

6.管理员命令

管理员命令需要 OP 权限。

查看命令帮助

/auonline

重载配置

/auonline reload

重载内容：

奖励配置
语言配置
GUI 标题
奖励显示文本

刷新所有玩家每日数据

/auonline dayrefresh

作用：

清空今日在线时间
重置当前阶段奖励
重置今日阶段奖励领取记录
重新载入在线玩家数据

刷新指定玩家每日数据

/auonline dayrefresh 玩家名

只刷新指定玩家的每日在线奖励数据。

查看玩家数据

/auonline info 玩家名
/auonline look 玩家名

不填写玩家名时，默认查看执行者自己的数据。

查看今日在线排行

/auonline topDay
/auonline top

显示当前已缓存玩家的今日在线排行。

7.奖励类型

AuOnlineReward 当前包含两类奖励。

阶段奖励

配置节点通常以 MinuteReward_ 开头。

示例：

RewardData:
  MinuteReward_30:
    slot: 10
    needOnline: 1800
    needOnlineTime: 1800
    itemStack:
      ==: org.bukkit.inventory.ItemStack
      type: IRON_INGOT
    commands:
      - eco give %player% 500

字段说明：

slot: GUI 中的格子位置
needOnline: 距离上次阶段奖励领取需要等待的秒数
needOnlineTime: 今日在线秒数要求
itemStack: GUI 中展示的奖励物品
commands: 领取后执行的命令

阶段奖励领取成功后：

增加当前轮阶段领取次数
增加总计阶段领取次数
写入今日已领取记录
切换到下一个阶段奖励
执行奖励命令
保存玩家数据

累积奖励

配置节点通常以 SignReward_ 开头。

示例：

RewardData:
  SignReward_15:
    slot: 29
    needOnline: 25
    itemStack:
      ==: org.bukkit.inventory.ItemStack
      type: CHEST
    commands:
      - eco give %player% 10000

字段说明：

slot: GUI 中的格子位置
needOnline: 需要累计领取多少次阶段奖励
itemStack: GUI 中展示的奖励物品
commands: 领取后执行的命令

累积奖励领取成功后会写入 permanentReceived。

当领取 SignReward_Max 后：

signAmount 会重置为 0
permanentReceived 会清空
进入下一轮累积奖励

8.奖励命令怎么写？

奖励命令写在 commands 列表中。

示例：

commands:
  - eco give %player% 500
  - points give %player% 10
  - bcm &a玩家 &e%player% &a领取了在线奖励

支持占位符：

%player%   玩家名
%itemName% 奖励物品显示名

如果命令包含 msg:，会向玩家发送消息，而不是由控制台执行命令。

示例：

commands:
  - "msg:&a你领取了在线奖励"

颜色代码支持：

&a &b &c &e &f

插件执行时会转换为 Minecraft 颜色符号。

9.语言文件怎么写？

语言文件为：

plugins/AuOnlineReward/language.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: "这个阶段奖励尚未开启,暂时无法领取。"

修改语言文件后执行：

/auonline reload

10.在线时间刷新机制

在线计时

插件会定时统计在线玩家的在线时长。

统计字段：

todayOnline: 今日在线
monthOnline: 本月在线
totalOnline: 累积在线

玩家退出时会补算最后一段在线时间，并保存玩家数据。

每日刷新

每日刷新会处理：

todayOnline = 0
currentReward = MinuteReward_30
receivedList = []
collectionTime = 当前时间

月度刷新

月度刷新会处理：

monthOnline = 0

刷新性能说明

批量刷新玩家文件时，插件会将 YAML 文件读写放到异步任务中执行。

刷新完成后，再回到主线程重新载入在线玩家。

这样可以降低大量玩家数据文件刷新时对主线程的影响。

11.API 调用

其他插件可以通过 OnlineAPI 获取玩家在线时间。

获取今日在线分钟数

int minutes = OnlineAPI.getTime(playerName);

获取本月在线分钟数

int minutes = OnlineAPI.getTimeMonth(playerName);

获取累积在线分钟数

int minutes = OnlineAPI.getTimeTotal(playerName);

注意：

API 返回单位是分钟
底层玩家数据保存单位是秒

12.事件监听

玩家成功领取奖励后会触发：

OnlineRewardEvent

监听示例：

@EventHandler
public void onOnlineReward(OnlineRewardEvent event) {
    Player player = event.getPlayer();
    String playerName = event.getPlayerName();
    String rewardKey = event.getOnlineData().getRewardKey();
}

事件可用于：

记录领奖日志
触发额外奖励
接入活动系统
接入统计系统

13.配置示例

阶段奖励示例

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

累积奖励示例

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

注意：

阶段奖励 lore 中需要包含 %time%
累积奖励 lore 中需要包含 %amounut%

14.常见问题

执行 /auonline open 没反应

检查：

是否在每日 00:10 之前
DemonAPI 是否正常加载
language.yml 中 Title 是否存在
config.yml 中 RewardData 是否存在

奖励无法领取

检查：

今日在线秒数是否达到 needOnlineTime
距离上次领取是否达到 needOnline
currentReward 是否等于当前点击的阶段奖励
该奖励是否已经在 receivedList 中

累积奖励无法领取

检查：

signAmount 是否达到 needOnline
该奖励是否已经在 permanentReceived 中

修改配置后没有变化

执行：

/auonline reload

如果删除了奖励节点，重载后旧奖励缓存会被清理。

玩家数据异常

可以刷新指定玩家每日数据：

/auonline dayrefresh 玩家名

也可以检查玩家数据文件：

plugins/AuData/AuOnlineReward/玩家名.yml

15.维护建议

修改奖励配置前，先备份 config.yml。
大量玩家数据刷新建议避开服务器高峰期。
奖励命令应先在测试服验证，避免命令拼写错误导致奖励无法发放。
不建议把高耗时命令放入奖励命令列表。
修改语言或奖励配置后，使用 /auonline reload 重载。
发布新版本时，应同步检查 plugin.yml 的版本号。
每次更新后建议至少完成一次登录、打开 GUI、领取奖励、退出保存的冒烟测试。

11 KiB Raw Blame History

1.AuOnlineReward 是什么？

2.运行环境

服务端版本

前置插件

3.安装方式

第一步：放入插件

第二步：启动服务器

第三步：检查加载

4.目录结构

插件配置目录

玩家数据目录

5.玩家命令

打开在线奖励界面

6.管理员命令

查看命令帮助

重载配置

刷新所有玩家每日数据

刷新指定玩家每日数据

查看玩家数据

查看今日在线排行

7.奖励类型

阶段奖励

累积奖励

8.奖励命令怎么写？

9.语言文件怎么写？

10.在线时间刷新机制

在线计时

每日刷新

月度刷新

刷新性能说明

11.API 调用

获取今日在线分钟数

获取本月在线分钟数

获取累积在线分钟数

12.事件监听

13.配置示例

阶段奖励示例

累积奖励示例

14.常见问题

执行 /auonline open 没反应

奖励无法领取

累积奖励无法领取

修改配置后没有变化

玩家数据异常

15.维护建议

11 KiB

Raw Blame History