Files

179 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <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](LICENSE) 发布。随 JAR 分发的 SQLite JDBC 仍按其原有许可证发布,许可证声明位于 JAR 内的 `META-INF/maven/org.xerial/sqlite-jdbc/`。