停止服务器并备份整个服务器目录，尤其是 plugins/MagicGem、plugins/CMagicGem 和玩家数据。
使用 Java 21 启动 Paper 1.21.x，将新 JAR 放入 plugins，移除旧 MagicGem JAR。不要同时加载新旧 JAR。
如果有 plugins/MagicGem，新版本会沿用它作为主数据目录，宝石、技能、GUI、语言、配置和已有物品按原路径继续读取。
如果还保留先前重实现的 plugins/CMagicGem，新版本会将其中的 gems、skills、gui、languages 和 config.yml 导入 plugins/MagicGem。缺失文件和 YAML 配置项会自动补入。
两个目录有同名冲突时，plugins/MagicGem 的值优先；冲突的 CMagicGem 原文件副本会写入 plugins/MagicGem/migration-backup/CMagicGem。源 plugins/CMagicGem 保持不变，迁移完成后会写入 .migration-cmagicgem-v1.complete 标记，避免每次启动重复导入。
启动后检查控制台的导入数量、冲突提示和配置加载结果。确认一切正常前，请保留备份和旧数据目录。

原版 MagicGem 数据已经在 plugins/MagicGem 时无需复制或重命名目录。物品读取兼容原版 MAGICGEM_* NBT 和先前 CMagicGem 的 PDC 数据，并继续写入原版 NBT 字段以兼容升级过程。

完整迁移步骤、目录合并规则、冲突备份、物品兼容和回滚流程见 MIGRATION.md。

主命令是 /mgem，并提供 /cmgem 和 /cmg 别名。

命令

/mgem reload [gem|skill]
/mgem give <玩家> <宝石> [数量]
/mgem apply <玩家> <宝石> [槽位]
/mgem remove <玩家> <宝石> [槽位]
/mgem get、/mgem view、/mgem embed [界面]
/mgem signal <玩家|@all> <信号>
/mgem material|lore|enchant|nbt

可选兼容

按需安装 PlaceholderAPI、Vault、PlayerPoints、MythicMobs 4/5、MMOItems、MythicArtifacts/MythicCrucible、Residence、PvPManager、EcoEnchants 或 GoldenEnchants。所有集成都采用软依赖；缺少对应插件时，只有相关条件或奖励不可用。

构建

mvn clean package

产物位于 target/cmagicgem-0.1.0-SNAPSHOT.jar。