InfStarMC/MagicGem-Reforged

Fork 0

Files

T

Coldsmiles d87fc866ab Improve integration and migration logging

2026-10-05 02:08:18 +08:00

7.1 KiB

Raw Blame History

MagicGem → MagicGem Reforged 升级指南

本文只描述从原版 MagicGem 升级到 MagicGem Reforged 的流程。当前版本只扫描并导入 plugins/MagicGem，不执行多个目录之间的合并。

MagicGem Reforged 面向 Minecraft/Paper 1.21.x（包括 1.21.11），使用 Java 21。它保留原插件的非授权功能，不实现网络授权或机器绑定。

升级前的状态

原版服务器通常是：

plugins/
├─ MagicGem-旧版本.jar
└─ MagicGem/
   ├─ config.yml
   ├─ gems/
   ├─ skills/
   ├─ gui/
   └─ languages/

升级后的结构是：

plugins/
├─ MagicGem-Reforged-1.0.0.jar
├─ MagicGem/
└─ MagicGem-Reforged/

MagicGem 是迁移来源，MagicGem-Reforged 是当前有效数据目录。

正式升级步骤

停止服务器，不能在运行中替换插件 JAR 或修改插件数据。
备份整个服务器，至少包括：
```
plugins/MagicGem/
world/
world_nether/
world_the_end/
```
玩家背包、末影箱、容器和世界区块中的物品数据不在插件目录中，只备份 plugins/MagicGem 不足以完整回滚。
移除旧版 MagicGem JAR。不要同时加载旧版和重制版。
将 MagicGem-Reforged JAR 放入 plugins/。
保留 plugins/MagicGem，不要提前重命名、删除或清空它。
使用 Java 21 启动 Paper 1.21.x。
等待迁移完成后检查控制台日志，再执行游戏内验证。

插件身份和命令

重制版的 plugin.yml 使用：

name: MagicGem-Reforged
main: cn.infstar.magicgem.MagicGem

主命令仍然是 /mgem。命令兼容不代表旧 JAR 可以同时运行；服务器中只能安装当前 JAR。

Java 主类已经是独立的新入口 cn.infstar.magicgem.MagicGem。旧入口 pku.yim.magicgem.MagicGem 作为兼容父类保留，供依赖原版公开 API 的其他插件继续解析；它不会作为 Paper 的实际入口加载。

第一次启动时的目录迁移

启动时，迁移器只检查：

plugins/MagicGem/

目标是当前插件的数据目录：

plugins/MagicGem-Reforged/

会迁移以下内容：

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/。其他原版目录不会自动复制，遇到自定义数据时应在备份后手动检查。

迁移完成标记

成功完成一次迁移后，目标目录会创建：

plugins/MagicGem-Reforged/.migration-magicgem-reforged-v1.complete

再次启动时发现该标记，迁移器会跳过重复复制。

如果迁移过程中出现文件权限或 IO 错误：

不会删除原版目录；
会记录错误日志；
不会把本次启动标记为已完成；
下一次启动会再次尝试。

如果确实需要重新扫描原版目录，应停止服务器，先备份当前 MagicGem-Reforged，再删除完成标记并重新启动。不要在没有备份的情况下删除标记。

配置和资源加载顺序

迁移发生在插件默认资源写入和注册表加载之前：

复制原版文件到 MagicGem-Reforged；
只为缺失文件写入当前版本默认资源；
读取 MagicGem-Reforged/config.yml；
加载 gems/、skills/、gui/ 和 languages/；
注册命令与事件。

因此原版自定义配置会优先存在，当前版本新增的默认文件也会补齐。原版配置中的 lang 和当前配置中的 language 都可以识别。

玩家物品兼容

目录迁移不会遍历所有玩家物品。物品采用兼容读取和按需写回，玩家拿到物品、使用宝石、镶嵌、拆卸或触发技能时才会逐步写入当前格式。

宝石身份

原版宝石物品中的：

MAGICGEM_NAME

仍然可以被识别。识别成功后，重制版会写入自己的当前数据，同时保留原版名称字段。

镶嵌内容

原版镶嵌数据：

MAGICGEM_EMBED

仍然可以读取。执行镶嵌、拆卸或相关物品操作时，重制版会更新当前数据并继续写入兼容的原版 NBT 字段。

技能列表

原版技能列表：

MAGICGEM_SKILL

仍然可以读取。技能能否执行取决于对应的 skills/*.yml 是否成功迁移并加载。

启动后验证

应在控制台确认：

Imported original plugins/MagicGem into MagicGem-Reforged: X files copied, Y conflicts.
MagicGem Reforged 已启用，命令 /mgem，加载 N 颗宝石。

插件还会逐项记录可选挂钩插件的状态，例如：

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、已完成标记跳过和迁移失败等状态。

然后执行：

/mgem view
/mgem get
/mgem embed
/mgem reload

至少验证：

旧宝石可以识别和使用；
已镶嵌装备的宝石数量正确；
拆卸和重新镶嵌正常；
原有技能可以触发；
GUI 和语言设置正确；
Vault、PlayerPoints、PlaceholderAPI、MythicMobs 等软依赖状态正常；
重启服务器后数据仍然存在。

如果重制版加载的宝石数量异常，先检查 plugins/MagicGem-Reforged/gems/ 是否完整，再查看 YAML 解析错误。

回滚

发生问题时：

停止服务器。
保存当前日志和 plugins/MagicGem-Reforged，用于排查。
移除重制版 JAR。
恢复原版 MagicGem JAR。
使用备份恢复 plugins/MagicGem、世界和玩家数据。
启动旧版服务器验证。

迁移器不会删除 plugins/MagicGem，所以仅目录迁移失败时原版数据仍然存在。但如果重制版运行期间已经改变了玩家物品或世界数据，建议恢复完整服务器备份。

升级检查清单

已停止服务器并备份插件、世界和玩家数据。
已移除旧版 MagicGem JAR。
已放入 MagicGem-Reforged JAR。
plugins/MagicGem 原版目录仍然保留。
plugins/MagicGem-Reforged 中已生成迁移后的配置和资源。
控制台没有迁移或 YAML 解析错误。
宝石数量与原版预期一致。
旧宝石、镶嵌装备和技能已实际测试。
GUI、语言和软依赖已测试。
已保留冲突备份和原始服务器备份。
已重启服务器验证持久化结果。

7.1 KiB Raw Blame History Unescape Escape