232 lines
7.1 KiB
Markdown
232 lines
7.1 KiB
Markdown
# MagicGem → MagicGem Reforged 升级指南
|
||
|
||
本文只描述从原版 MagicGem 升级到 MagicGem Reforged 的流程。当前版本只扫描并导入 `plugins/MagicGem`，不执行多个目录之间的合并。
|
||
|
||
MagicGem Reforged 面向 Minecraft/Paper 1.21.x（包括 1.21.11），使用 Java 21。它保留原插件的非授权功能，不实现网络授权或机器绑定。
|
||
|
||
## 升级前的状态
|
||
|
||
原版服务器通常是：
|
||
|
||
```text
|
||
plugins/
|
||
├─ MagicGem-旧版本.jar
|
||
└─ MagicGem/
|
||
├─ config.yml
|
||
├─ gems/
|
||
├─ skills/
|
||
├─ gui/
|
||
└─ languages/
|
||
```
|
||
|
||
升级后的结构是：
|
||
|
||
```text
|
||
plugins/
|
||
├─ MagicGem-Reforged-1.0.0.jar
|
||
├─ MagicGem/
|
||
└─ MagicGem-Reforged/
|
||
```
|
||
|
||
`MagicGem` 是迁移来源，`MagicGem-Reforged` 是当前有效数据目录。
|
||
|
||
## 正式升级步骤
|
||
|
||
1. 停止服务器，不能在运行中替换插件 JAR 或修改插件数据。
|
||
2. 备份整个服务器，至少包括：
|
||
|
||
```text
|
||
plugins/MagicGem/
|
||
world/
|
||
world_nether/
|
||
world_the_end/
|
||
```
|
||
|
||
玩家背包、末影箱、容器和世界区块中的物品数据不在插件目录中，只备份 `plugins/MagicGem` 不足以完整回滚。
|
||
3. 移除旧版 MagicGem JAR。不要同时加载旧版和重制版。
|
||
4. 将 `MagicGem-Reforged` JAR 放入 `plugins/`。
|
||
5. 保留 `plugins/MagicGem`，不要提前重命名、删除或清空它。
|
||
6. 使用 Java 21 启动 Paper 1.21.x。
|
||
7. 等待迁移完成后检查控制台日志，再执行游戏内验证。
|
||
|
||
## 插件身份和命令
|
||
|
||
重制版的 `plugin.yml` 使用：
|
||
|
||
```yaml
|
||
name: MagicGem-Reforged
|
||
main: cn.infstar.magicgem.MagicGem
|
||
```
|
||
|
||
主命令仍然是 `/mgem`。命令兼容不代表旧 JAR 可以同时运行；服务器中只能安装当前 JAR。
|
||
|
||
Java 主类已经是独立的新入口 `cn.infstar.magicgem.MagicGem`。旧入口 `pku.yim.magicgem.MagicGem` 作为兼容父类保留，供依赖原版公开 API 的其他插件继续解析；它不会作为 Paper 的实际入口加载。
|
||
|
||
## 第一次启动时的目录迁移
|
||
|
||
启动时，迁移器只检查：
|
||
|
||
```text
|
||
plugins/MagicGem/
|
||
```
|
||
|
||
目标是当前插件的数据目录：
|
||
|
||
```text
|
||
plugins/MagicGem-Reforged/
|
||
```
|
||
|
||
会迁移以下内容：
|
||
|
||
```text
|
||
MagicGem/config.yml → MagicGem-Reforged/config.yml
|
||
MagicGem/gems/ → MagicGem-Reforged/gems/
|
||
MagicGem/skills/ → MagicGem-Reforged/skills/
|
||
MagicGem/gui/ → MagicGem-Reforged/gui/
|
||
MagicGem/languages/ → MagicGem-Reforged/languages/
|
||
```
|
||
|
||
迁移器只复制目标中不存在的文件，因此原版文件内容会完整保留。它不会删除、改写或移动 `plugins/MagicGem`。
|
||
|
||
如果 `MagicGem-Reforged` 已经存在，例如上一次迁移中断后重新启动：
|
||
|
||
- 目标中不存在的文件继续复制；
|
||
- 目标中内容相同的文件跳过；
|
||
- 目标中内容不同的文件保留目标版本；
|
||
- 冲突的原版文件会保存到 `migration-backup/MagicGem/`；
|
||
- 原版源目录始终保留。
|
||
|
||
迁移器只处理 `config.yml`、`gems/`、`skills/`、`gui/` 和 `languages/`。其他原版目录不会自动复制，遇到自定义数据时应在备份后手动检查。
|
||
|
||
## 迁移完成标记
|
||
|
||
成功完成一次迁移后，目标目录会创建：
|
||
|
||
```text
|
||
plugins/MagicGem-Reforged/.migration-magicgem-reforged-v1.complete
|
||
```
|
||
|
||
再次启动时发现该标记，迁移器会跳过重复复制。
|
||
|
||
如果迁移过程中出现文件权限或 IO 错误：
|
||
|
||
- 不会删除原版目录；
|
||
- 会记录错误日志；
|
||
- 不会把本次启动标记为已完成；
|
||
- 下一次启动会再次尝试。
|
||
|
||
如果确实需要重新扫描原版目录，应停止服务器，先备份当前 `MagicGem-Reforged`，再删除完成标记并重新启动。不要在没有备份的情况下删除标记。
|
||
|
||
## 配置和资源加载顺序
|
||
|
||
迁移发生在插件默认资源写入和注册表加载之前：
|
||
|
||
1. 复制原版文件到 `MagicGem-Reforged`；
|
||
2. 只为缺失文件写入当前版本默认资源；
|
||
3. 读取 `MagicGem-Reforged/config.yml`；
|
||
4. 加载 `gems/`、`skills/`、`gui/` 和 `languages/`；
|
||
5. 注册命令与事件。
|
||
|
||
因此原版自定义配置会优先存在，当前版本新增的默认文件也会补齐。原版配置中的 `lang` 和当前配置中的 `language` 都可以识别。
|
||
|
||
## 玩家物品兼容
|
||
|
||
目录迁移不会遍历所有玩家物品。物品采用兼容读取和按需写回，玩家拿到物品、使用宝石、镶嵌、拆卸或触发技能时才会逐步写入当前格式。
|
||
|
||
### 宝石身份
|
||
|
||
原版宝石物品中的：
|
||
|
||
```text
|
||
MAGICGEM_NAME
|
||
```
|
||
|
||
仍然可以被识别。识别成功后，重制版会写入自己的当前数据，同时保留原版名称字段。
|
||
|
||
### 镶嵌内容
|
||
|
||
原版镶嵌数据：
|
||
|
||
```text
|
||
MAGICGEM_EMBED
|
||
```
|
||
|
||
仍然可以读取。执行镶嵌、拆卸或相关物品操作时，重制版会更新当前数据并继续写入兼容的原版 NBT 字段。
|
||
|
||
### 技能列表
|
||
|
||
原版技能列表：
|
||
|
||
```text
|
||
MAGICGEM_SKILL
|
||
```
|
||
|
||
仍然可以读取。技能能否执行取决于对应的 `skills/*.yml` 是否成功迁移并加载。
|
||
|
||
## 启动后验证
|
||
|
||
应在控制台确认：
|
||
|
||
```text
|
||
Imported original plugins/MagicGem into MagicGem-Reforged: X files copied, Y conflicts.
|
||
MagicGem Reforged 已启用，命令 /mgem，加载 N 颗宝石。
|
||
```
|
||
|
||
插件还会逐项记录可选挂钩插件的状态，例如：
|
||
|
||
```text
|
||
Optional integration PlaceholderAPI: enabled (version 2.x, api=available)
|
||
Optional integration MMOItems: absent
|
||
Optional integration MythicMobs: enabled (version 5.x, adapter=items=..., skillApi=true)
|
||
```
|
||
|
||
迁移器也会记录开始、未找到 `plugins/MagicGem`、已完成标记跳过和迁移失败等状态。
|
||
|
||
然后执行：
|
||
|
||
```text
|
||
/mgem view
|
||
/mgem get
|
||
/mgem embed
|
||
/mgem reload
|
||
```
|
||
|
||
至少验证：
|
||
|
||
- 旧宝石可以识别和使用；
|
||
- 已镶嵌装备的宝石数量正确；
|
||
- 拆卸和重新镶嵌正常；
|
||
- 原有技能可以触发；
|
||
- GUI 和语言设置正确；
|
||
- Vault、PlayerPoints、PlaceholderAPI、MythicMobs 等软依赖状态正常；
|
||
- 重启服务器后数据仍然存在。
|
||
|
||
如果重制版加载的宝石数量异常，先检查 `plugins/MagicGem-Reforged/gems/` 是否完整，再查看 YAML 解析错误。
|
||
|
||
## 回滚
|
||
|
||
发生问题时：
|
||
|
||
1. 停止服务器。
|
||
2. 保存当前日志和 `plugins/MagicGem-Reforged`，用于排查。
|
||
3. 移除重制版 JAR。
|
||
4. 恢复原版 MagicGem JAR。
|
||
5. 使用备份恢复 `plugins/MagicGem`、世界和玩家数据。
|
||
6. 启动旧版服务器验证。
|
||
|
||
迁移器不会删除 `plugins/MagicGem`，所以仅目录迁移失败时原版数据仍然存在。但如果重制版运行期间已经改变了玩家物品或世界数据，建议恢复完整服务器备份。
|
||
|
||
## 升级检查清单
|
||
|
||
- [ ] 已停止服务器并备份插件、世界和玩家数据。
|
||
- [ ] 已移除旧版 MagicGem JAR。
|
||
- [ ] 已放入 MagicGem-Reforged JAR。
|
||
- [ ] `plugins/MagicGem` 原版目录仍然保留。
|
||
- [ ] `plugins/MagicGem-Reforged` 中已生成迁移后的配置和资源。
|
||
- [ ] 控制台没有迁移或 YAML 解析错误。
|
||
- [ ] 宝石数量与原版预期一致。
|
||
- [ ] 旧宝石、镶嵌装备和技能已实际测试。
|
||
- [ ] GUI、语言和软依赖已测试。
|
||
- [ ] 已保留冲突备份和原始服务器备份。
|
||
- [ ] 已重启服务器验证持久化结果。
|