ItxiaohuiServerAdvancements

ItxiaohuiServerAdvancements 是一款面向 Paper 1.21.8 的 Minecraft 服务端成就插件。通过原版进度界面展示独立的服务器成就树,默认启用 129 个自动成就,涵盖探索、战斗、种田、烹饪、驯养与收藏。无需客户端模组、AI 接口或管理员逐项审核。

当前版本为 1.2.0,构建需要 Java 21。默认包含 129 个自动普通成就 + 根进度,另保留 22 个默认关闭的可选人工项目。见完整目录与管理说明。

安装

  1. 使用 Java 21 启动 Paper 1.21.8。
  2. 将 build/libs/ItxiaohuiServerAdvancements.jar 放入服务端 plugins/。
  3. 正常启动服务端。插件会自动创建:
    • plugins/ItxiaohuiServerAdvancements/config.yml
    • plugins/ItxiaohuiServerAdvancements/advancements.yml
    • plugins/ItxiaohuiServerAdvancements/messages.yml
    • plugins/ItxiaohuiServerAdvancements/data/advancements.db
  4. 玩家加入后约 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.give
  • itxiaohui.serveradvancements.revoke
  • itxiaohui.serveradvancements.view

管理 GUI 的点击事件会再次执行服务端权限检查。复杂条件和奖励仍以 YAML 为准,GUI 提供浏览、详情、启停、给自己授予/撤销、重载和操作提示。

SQLite 备份与恢复

数据库启用 WAL、FULL 同步、外键、busy timeout 和结构版本迁移。运行时 JDBC 操作统一走后台单线程队列。高频统计使用版本快照批量 UPSERT,读取失败时不以空缓存覆盖历史数据;未保存的重登缓存会被保留。离线且已保存的缓存会被淘汰。

退出、备份和正常停服会主动刷盘。进程在最近一次批量保存后被强杀,仍可能丢失尚在内存中的统计;周期可调低到 5 秒,但不能宣称任何崩溃都不丢数据。

备份:执行 /isa backup,后台先刷盘,再使用 SQLite VACUUM INTO 制作包含已提交 WAL 页的一致快照。每次创建独立目录,包含 advancements.db 以及三份 YAML;连续同秒请求不会覆盖或冲突。刷盘失败不会报备份成功。

恢复:

  1. 使用 stop 正常关闭服务端。
  2. 额外复制保存当前 data/advancements.db 及同目录的 -wal/-shm(若存在)。
  3. 将选定备份复制为 data/advancements.db。
  4. 确保没有遗留的旧 advancements.db-wal、advancements.db-shm 与新主库混用。
  5. 启动服务端并检查完整性与插件日志。

不要在服务器运行时直接覆盖数据库。

架构

  • advancement:不稳定动态注册 API 的唯一隔离层、原版进度授予/撤销。
  • config / model:YAML 解析、校验、成就模型。
  • condition / listener:行为统计和 AND 条件求值。
  • statistics / database:内存缓存、异步批量持久化、迁移、奖励状态和审计。
  • reward:防重复奖励执行。
  • command / gui:权限受控的管理入口。

已知限制

  1. UnsafeValues.loadAdvancement/removeAdvancement 在 Paper 1.21.8 已标记为不稳定/弃用;相关代码已集中隔离。定义更新采用正常重启流程。
  2. 原版客户端决定节点坐标与未解锁深层节点的可见范围,插件不能通过标准 Advancement JSON 强制绝对 x/y。
  3. collect_item 只统计地面拾取;不会虚假宣称覆盖交易、箱子、漏斗或命令来源。
  4. 当前管理命令修改原版玩家进度只支持在线玩家;离线玩家统计仍保存在 SQLite,玩家下次进入后继续累计。
  5. /isa revoke 不清累计统计;若玩家条件仍满足,后续求值会再次完成该成就。默认奖励防重仍会阻止重复发奖。
  6. 条件依赖和父级关系一起做迭代环检测,树深度上限为 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/。

S
Description
ItxiaohuiServerAdvancements 是一款面向 Paper 1.21.8 的 Minecraft 服务端成就插件。通过原版进度界面展示独立的服务器成就树,默认启用 129 个自动成就,涵盖探索、战斗、种田、烹饪、驯养与收藏。无需客户端模组、AI 接口或管理员逐项审核。
Readme GPL-3.0
179 KiB
1 Stars 1 Watchers 0 Forks
1.2.0
Latest
2026-11-13 21:13:02 +08:00
Generate repository badges
Languages
Java 100%