179 lines
11 KiB
Markdown
179 lines
11 KiB
Markdown
# 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/`。
|