Document MagicGem migration workflow

README.md

@@ -1,25 +1,31 @@
-# CMagicGem
+# MagicGem
 
-CMagicGem 是 MagicGem 的 Paper 1.21.x 重实现，目标运行范围为 Minecraft/Paper 1.21–1.21.11。项目使用 Java 21 和 Paper API，不包含原插件的网络授权逻辑。
+MagicGem 是面向 Minecraft/Paper 1.21.x（包括 1.21.11）的插件重实现，使用 Java 21 和 Paper API。它保留原插件的非授权功能，不实现网络授权或机器绑定。
 
-## 安装
+## 安装与迁移
 
-1. 使用 Java 21 启动 Paper 1.21.x。
-2. 将 `CMagicGem-*.jar` 放入服务器的 `plugins` 目录。
-3. 保留旧插件数据时，不要删除 `plugins/MagicGem`。CMagicGem 首次启动会把尚不存在的配置安全复制到 `plugins/CMagicGem`，不会修改旧目录。
-4. 移除旧 MagicGem JAR 后启动服务器，并检查控制台中的配置加载结果。
+1. 停止服务器并备份整个服务器目录，尤其是 `plugins/MagicGem`、`plugins/CMagicGem` 和玩家数据。
+2. 使用 Java 21 启动 Paper 1.21.x，将新 JAR 放入 `plugins`，移除旧 MagicGem JAR。不要同时加载新旧 JAR。
+3. 如果有 `plugins/MagicGem`，新版本会沿用它作为主数据目录，宝石、技能、GUI、语言、配置和已有物品按原路径继续读取。
+4. 如果还保留先前重实现的 `plugins/CMagicGem`，新版本会将其中的 `gems`、`skills`、`gui`、`languages` 和 `config.yml` 导入 `plugins/MagicGem`。缺失文件和 YAML 配置项会自动补入。
+5. 两个目录有同名冲突时，`plugins/MagicGem` 的值优先；冲突的 `CMagicGem` 原文件副本会写入 `plugins/MagicGem/migration-backup/CMagicGem`。源 `plugins/CMagicGem` 保持不变，迁移完成后会写入 `.migration-cmagicgem-v1.complete` 标记，避免每次启动重复导入。
+6. 启动后检查控制台的导入数量、冲突提示和配置加载结果。确认一切正常前，请保留备份和旧数据目录。
 
-主命令是 `/cmgem`，别名是 `/cmg`。插件不会注册 `/mgem`，因此可与旧插件并存进行迁移核验。
+原版 `MagicGem` 数据已经在 `plugins/MagicGem` 时无需复制或重命名目录。物品读取兼容原版 `MAGICGEM_*` NBT 和先前 `CMagicGem` 的 PDC 数据，并继续写入原版 NBT 字段以兼容升级过程。
+
+完整迁移步骤、目录合并规则、冲突备份、物品兼容和回滚流程见 [MIGRATION.md](MIGRATION.md)。
+
+主命令是 `/mgem`，并提供 `/cmgem` 和 `/cmg` 别名。
 
 ## 命令
 
-- `/cmgem reload [gem|skill]`
-- `/cmgem give <玩家> <宝石> [数量]`
-- `/cmgem apply <玩家> <宝石> [槽位]`
-- `/cmgem remove <玩家> <宝石> [槽位]`
-- `/cmgem get`、`/cmgem view`、`/cmgem embed [界面]`
-- `/cmgem signal <玩家|@all> <信号>`
-- `/cmgem material|lore|enchant|nbt`
+- `/mgem reload [gem|skill]`
+- `/mgem give <玩家> <宝石> [数量]`
+- `/mgem apply <玩家> <宝石> [槽位]`
+- `/mgem remove <玩家> <宝石> [槽位]`
+- `/mgem get`、`/mgem view`、`/mgem embed [界面]`
+- `/mgem signal <玩家|@all> <信号>`
+- `/mgem material|lore|enchant|nbt`
 
 ## 可选兼容