11 KiB
ItxiaohuiServerAdvancements
ItxiaohuiServerAdvancements 是一款面向 Paper 1.21.8 的 Minecraft 服务端成就插件。通过原版进度界面展示独立的服务器成就树,默认启用 129 个自动成就,涵盖探索、战斗、种田、烹饪、驯养与收藏。无需客户端模组、AI 接口或管理员逐项审核。
当前版本为 1.2.0,构建需要 Java 21。默认包含 129 个自动普通成就 + 根进度,另保留 22 个默认关闭的可选人工项目。见完整目录与管理说明。
安装
- 使用 Java 21 启动 Paper 1.21.8。
- 将
build/libs/ItxiaohuiServerAdvancements.jar放入服务端plugins/。 - 正常启动服务端。插件会自动创建:
plugins/ItxiaohuiServerAdvancements/config.ymlplugins/ItxiaohuiServerAdvancements/advancements.ymlplugins/ItxiaohuiServerAdvancements/messages.ymlplugins/ItxiaohuiServerAdvancements/data/advancements.db
- 玩家加入后约 1 秒自动获得无弹窗、无广播、无奖励的根进度;按
L打开原版进度界面。
1.2.0 首次启动会先备份原 advancements.yml,安装/升级自动优先目录:与旧模板完全一致的定义自动更新,自定义条目、管理员禁用状态和已删除旧项保留。后续启动不会反复安装,不清库。少量主观或服务器专属项目默认关闭,不影响自动路线。模板不生成世界建筑,也不虚构地点坐标。
不要使用 Bukkit /reload。修改 Advancement 的 ID、父级、图标、标题、描述、显示选项或增删节点后,请用 stop 正常关闭服务器再启动。Paper 1.21.8 的动态移除接口不会在当前进程中立即清除注册表,因此插件故意拒绝危险的热替换。
构建
.\gradlew.bat clean test shadowJar
产物固定为 build/libs/ItxiaohuiServerAdvancements.jar。SQLite JDBC 3.50.3.0 已打包并通过隔离类加载器加载,避免选中 Paper 内置的其他版本;JNI 包名保持原样。不需要另装数据库或驱动。
Linux/macOS 可执行 ./gradlew clean test shadowJar。
配置
全局选项位于 config.yml。root 控制独立页签的根节点,根 ID 不能作为普通成就删除;statistics.flush-interval-seconds 控制内存统计批量写入周期。全局配置或节点定义修改后需要正常重启,消息文件可用 /isa reload 重载。
普通成就位于 advancements.yml:
achievements:
first_diamond:
name: "钻石收藏家"
description: "累计从地面拾取 64 个钻石"
icon: "minecraft:diamond"
frame: goal # task / goal / challenge
parent: root
display: { x: 2, y: 0 } # 排序提示;原版客户端负责最终坐标
hidden: false
show-toast: true
announce-chat: false
enabled: true
conditions:
- { type: collect_item, item: "minecraft:diamond", amount: 64 }
rewards:
experience: 100
allow-reclaim: false
items:
- { item: "minecraft:emerald", amount: 3 }
commands:
- "say {player} 完成了钻石收藏家"
一个成就的多个条件采用 AND 关系。配置加载时会检查非法 ID、图标、材料、未知条件、缺失父级、依赖缺失和父级循环。单个坏定义会被隔离并写入明确日志;/isa validate 可提前检查。
条件类型与统计口径
| 类型 | 必要参数 | 统计口径 |
|---|---|---|
first_join |
无 | Bukkit 判定的首次加入 |
online_time |
amount, unit |
登录会话累计;单位为 seconds/minutes/hours |
mine_block |
block, amount |
未取消的方块破坏事件 |
collect_item |
item, amount |
从世界物品实体拾取的数量;不含交易、容器转移、管理员命令等来源 |
obtain_item |
item, amount |
插件能确认的新获得数量:当前包括地面拾取和玩家合成产出;不含交易、容器转移或命令来源 |
kill_mob |
entity, amount |
玩家作为直接 Bukkit killer 的击杀;entity: "*" 表示任意实体 |
visit_dimension |
dimension |
加入时所在维度或切换后进入的维度 |
move_distance |
amount |
同一世界内实际移动距离;单次大于等于 100 格的跳变不计,避免传送灌水 |
reach_location |
world, x, y, z, radius, 可选 id |
进入指定球形区域 |
craft_item |
item, amount |
原版 CRAFT_ITEM 成功统计的增量;包括普通和 Shift 合成,不统计无产出点击 |
breed_mob |
entity, amount |
玩家作为繁殖者的成功繁殖;支持 * |
experience_level |
amount |
历史达到的最高经验等级 |
complete_achievement |
achievement |
指定服务器成就的原版完成状态 |
manual |
无 | 只能由管理员授予 |
player_statistic |
statistic, amount,按统计类型可需 materials 或 entity |
读取原版累计统计;距离单位为厘米,可能包含安装前历史 |
vanilla_advancement |
advancement |
指定 minecraft 原版进度已完成 |
inventory_set |
items, amount,可选 each |
随身物品中至少指定数量的不同种类,每种满足数量要求 |
visit_biome |
biome |
周期采样记录到达该生物群系 |
visit_structure |
structures, amount |
周期记录进入不同的天然结构位置,重复进入同一处不累加 |
altitude |
amount |
环境采样记录历史到达的最高正 Y 坐标 |
event_count |
event, amount,可选 subjects |
新版安装后的进食、取出烹饪食物、驯服、成功钓获或放置方块数量 |
event_distinct |
同上 | 对上述事件记录的不同对象种类计数,不把重复吃同一种食物当新品种 |
统计值是历史累计值,不会因物品被丢弃、存箱或成就被撤销而清零。节点 x/y 不是原版 Advancement JSON 字段;插件将其用于稳定排序,最终位置由原版客户端按父子树自动布局。
奖励
experience:经验点(不是经验等级)。items:原版物品 ID 与数量;背包放不下时掉落在玩家位置。commands:由控制台执行,支持受控占位符{player}和{uuid}。allow-reclaim:撤销后再次完成是否允许再次发奖,默认false。completion-message:可选的个人完成消息。
后台队列先将奖励预约为 RESERVED,再持久化 PENDING 执行意图,之后才在主线程授予原版进度、发经验/物品和执行命令。成功落库为 CLAIMED;部分失败为 FAILED。
RESERVED 表示尚未执行,可以安全恢复;PENDING 与 FAILED 都不自动重放,即使 allow-reclaim=true 也一样。管理员应先备份数据库,查询 reward_claims 中的 status、attempts、detail 与日志,核查实际经验/物品/命令是否已执行,再人工补发欠缺部分。不要直接删除未决记录后重跑整份奖励。数据库事务不能与外部游戏命令形成绝对原子事务。
若数据库预约失败,玩家的原版节点不会提前完成,可以在数据库恢复后重试。管理命令异步返回实际完成结果。
命令与权限
主命令为 /isa,别名 /itxiaohuiadvancements。
| 命令 | 用途 |
|---|---|
/isa help |
帮助 |
/isa list / /isa info <id> |
查看定义 |
/isa editor |
打开管理容器 GUI |
/isa give <在线玩家> <id> |
手动完成并发奖 |
/isa revoke <在线玩家> <id> |
撤销原版完成状态,不清统计 |
/isa progress <在线玩家> |
查看完成数和内存统计 |
/isa create <id> |
创建一个默认禁用的 YAML 骨架 |
/isa delete <id> confirm |
检查子节点后删除定义;不清历史数据 |
/isa validate |
校验磁盘配置 |
/isa reload |
重载消息并校验;定义有变化时要求正常重启 |
/isa backup |
刷盘、WAL checkpoint 并备份数据库 |
权限:
itxiaohui.serveradvancements.admin:默认 OP,包含全部子权限。itxiaohui.serveradvancements.giveitxiaohui.serveradvancements.revokeitxiaohui.serveradvancements.view
管理 GUI 的点击事件会再次执行服务端权限检查。复杂条件和奖励仍以 YAML 为准,GUI 提供浏览、详情、启停、给自己授予/撤销、重载和操作提示。
SQLite 备份与恢复
数据库启用 WAL、FULL 同步、外键、busy timeout 和结构版本迁移。运行时 JDBC 操作统一走后台单线程队列。高频统计使用版本快照批量 UPSERT,读取失败时不以空缓存覆盖历史数据;未保存的重登缓存会被保留。离线且已保存的缓存会被淘汰。
退出、备份和正常停服会主动刷盘。进程在最近一次批量保存后被强杀,仍可能丢失尚在内存中的统计;周期可调低到 5 秒,但不能宣称任何崩溃都不丢数据。
备份:执行 /isa backup,后台先刷盘,再使用 SQLite VACUUM INTO 制作包含已提交 WAL 页的一致快照。每次创建独立目录,包含 advancements.db 以及三份 YAML;连续同秒请求不会覆盖或冲突。刷盘失败不会报备份成功。
恢复:
- 使用
stop正常关闭服务端。 - 额外复制保存当前
data/advancements.db及同目录的-wal/-shm(若存在)。 - 将选定备份复制为
data/advancements.db。 - 确保没有遗留的旧
advancements.db-wal、advancements.db-shm与新主库混用。 - 启动服务端并检查完整性与插件日志。
不要在服务器运行时直接覆盖数据库。
架构
advancement:不稳定动态注册 API 的唯一隔离层、原版进度授予/撤销。config/model:YAML 解析、校验、成就模型。condition/listener:行为统计和 AND 条件求值。statistics/database:内存缓存、异步批量持久化、迁移、奖励状态和审计。reward:防重复奖励执行。command/gui:权限受控的管理入口。
已知限制
UnsafeValues.loadAdvancement/removeAdvancement在 Paper 1.21.8 已标记为不稳定/弃用;相关代码已集中隔离。定义更新采用正常重启流程。- 原版客户端决定节点坐标与未解锁深层节点的可见范围,插件不能通过标准 Advancement JSON 强制绝对
x/y。 collect_item只统计地面拾取;不会虚假宣称覆盖交易、箱子、漏斗或命令来源。- 当前管理命令修改原版玩家进度只支持在线玩家;离线玩家统计仍保存在 SQLite,玩家下次进入后继续累计。
/isa revoke不清累计统计;若玩家条件仍满足,后续求值会再次完成该成就。默认奖励防重仍会阻止重复发奖。- 条件依赖和父级关系一起做迭代环检测,树深度上限为 256;每个节点最多 64 条条件,物品奖励单项 1–4096 个、经验奖励 0–1000000,避免误配置耗尽资源。
从 1.0.0 升级:备份数据目录,使用 stop 正常关闭后替换 JAR 并启动;无需清空 SQLite 或玩家原版进度文件。旧的 PENDING/FAILED 记录会继续保留,按上面的核查流程处理,不会自动重复发放。
测试
使用 ./gradlew test securityAudit(Windows 使用 .\gradlew.bat test securityAudit)运行单元和审计测试,报告位于 build/reports/tests/。
许可证
本项目按 GNU GPL v3 发布。随 JAR 分发的 SQLite JDBC 仍按其原有许可证发布,许可证声明位于 JAR 内的 META-INF/maven/org.xerial/sqlite-jdbc/。