# ItxiaohuiServerAdvancements ItxiaohuiServerAdvancements 是一款面向 Paper 1.21.8 的 Minecraft 服务端成就插件。通过原版进度界面展示独立的服务器成就树,默认启用 129 个自动成就,涵盖探索、战斗、种田、烹饪、驯养与收藏。无需客户端模组、AI 接口或管理员逐项审核。 当前版本为 **1.2.0**,构建需要 Java 21。默认包含 **129 个自动普通成就 + 根进度**,另保留 22 个默认关闭的可选人工项目。见[完整目录与管理说明](FUN_ACHIEVEMENTS.md)。 ## 安装 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 的动态移除接口不会在当前进程中立即清除注册表,因此插件故意拒绝危险的热替换。 ## 构建 ```powershell .\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`: ```yaml 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 ` | 查看定义 | | `/isa editor` | 打开管理容器 GUI | | `/isa give <在线玩家> ` | 手动完成并发奖 | | `/isa revoke <在线玩家> ` | 撤销原版完成状态,不清统计 | | `/isa progress <在线玩家>` | 查看完成数和内存统计 | | `/isa create ` | 创建一个默认禁用的 YAML 骨架 | | `/isa delete 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](LICENSE) 发布。随 JAR 分发的 SQLite JDBC 仍按其原有许可证发布,许可证声明位于 JAR 内的 `META-INF/maven/org.xerial/sqlite-jdbc/`。