导入 / 导出实操手册

所属：开发者　·　相关：导入导出（API） · 命令

导入导出讲 API 与格式，本页讲从 MMOItems / NeigeItems 迁移到 QI 的完整步骤、字段映射对照、dry-run 解读。

一、从 MMOItems 迁移

步骤

1. 把 MMOItems 的物品配置文件放进
   plugins/QinhItems/imports/

2. 先预览（不写入）：
   /qi imports dry-run
   → 看报告：将导入哪些 ID、各属性怎么映射、有无警告

3. 确认无误后正式导入：
   /qi imports run
   → 物品写入 items/，词缀 / 段写入对应注册表

4. /qi reload 重载，/qi give <id> 验证

属性映射对照

MMOItems 属性	QI 目标	说明
`attack-damage`	`base_attack_damage`（基础值）	核心属性
`max-health`	`base_health`	核心属性
`defense`	`base_defense`	核心属性
`attack-speed`	普通属性 attack_speed
`magic-damage`	magic_damage
`armor-penetration`	armor_penetration
`max-mana`	max_mana
`mana-regeneration`	mana_regen
`critical-strike-chance`	`critical_rate`（÷100）	比率类除以 100
`dodge-rating`	dodge（÷100）
`block-rating`	block_rate（÷100）
`lifesteal`	lifesteal（÷100）

核心三项进 base_values（受 base 编辑器管理），其余进 providers.ap。比率类自动 ÷100。最终都交 AttributePlus，记得配好 attribute-mapping。

技能（ability）映射

MMOItems ability	QI 触发器
attack / on_hit	`on_damage`
damaged / when_hit	`on_hit`
right_click / left_click	同名
shift_right_click / shift_left_click	同名
sneak	`shift_toggle`
kill_entity	`on_kill`
shoot_bow	`bow_shoot`
shoot_trident	`trident_throw`
death / login	`death` / `join`

限制映射

MMOItems	QI
`required-level: N`	`level:N`
`required-class: A,B`	`class:A,B`（委托 `QinhItemUseCheckEvent`）
`permission: X`	`permission:X`

level / permission / world 由 QI 原生判；class / 阵营等委托给 QinhItemUseCheckEvent，需你实现职业判断。

二、从 NeigeItems 迁移

放进 imports/ 后同样 dry-run → run。NeigeItems 格式导入：sections、FancyDrop、actions、actions_file、data 等字段。未知字段走 generic 兜底格式。

三、迁移旧物品源

/qi migrate dry-run      # 预览迁移
/qi migrate              # 执行（带校验）

用于把旧版 QI 物品源结构迁到当前结构。

四、dry-run 报告怎么读

ImportReport 输出含：

字段	含义
扫描文件数	imports/ 里被扫的文件
导入数 / 导入 ID	将创建的物品
各格式计数	mmoitems / neigeitems / generic 各多少
映射字段	每个属性 / 字段怎么转的（排查映射用）
生成的段 / 词缀	顺带产出的 Section / Affix
警告	不阻止导入但需注意（如未识别属性）
错误	阻止该项导入

强烈建议先 dry-run 看映射字段，确认属性都映射对了再 run。

五、内容包（.qipack）跨服分发

把当前 QI 内容打包成单文件分发到别的服。

导出

/qi packs export
→ 生成 qinhitems-pack.yml（默认名），含 metadata + sections + affixes + layerSnapshots + 每物品的引用

导入

1. 把 .qipack（或 pack yml）放进 packs 目录
2. /qi packs list          # 确认看到
3. /qi packs import        # = apply / sync

同步

/qi packs sync             # 刷新 + 导出
/qi packs gui              # 图形化管理（仅玩家）

导入时会校验声明数 vs 实际加载数，不一致会报 structureMismatch，并给 mismatchSummary。

六、API 调用

kotlin

QinhItemImportService.importAll(dryRun = false): ImportReport
QinhItemImportService.migrateLegacySources(dryRun): ImportReport
QinhItemPackExportService.exportAll("qinhitems-pack.yml"): PackExportReport
QinhItemPackImportService.importFile(file): PackImportReport

字段细节见导入导出（API）。

迁移检查清单

[ ] 配好 attribute-mapping（AP 属性名一致）
[ ] dry-run 看映射字段无误
[ ] class 等限制有对应 QinhItemUseCheckEvent 实现
[ ] 导入后 /qi reload + /qi give 抽查几件
[ ] /qi diagnose 确认无新增问题

导入 / 导出实操手册 ​

一、从 MMOItems 迁移 ​

步骤 ​

属性映射对照 ​

技能（ability）映射 ​

限制映射 ​

二、从 NeigeItems 迁移 ​

三、迁移旧物品源 ​

四、dry-run 报告怎么读 ​

五、内容包（.qipack）跨服分发 ​

导出 ​

导入 ​

同步 ​

六、API 调用 ​

迁移检查清单 ​

下一步 ​