# 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-0.1.0-SNAPSHOT.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
/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、语言和软依赖已测试。
- [ ] 已保留冲突备份和原始服务器备份。
- [ ] 已重启服务器验证持久化结果。