Import / Export Hands-On Manual

Belongs to: Developer　·　Related: Import/Export (API) · Commands

Import/Export covers the API and formats; this page covers the complete steps for migrating from MMOItems / NeigeItems to QI, field mapping references, and how to read dry-run reports.

---

1. Migrating from MMOItems

Steps

1. Put MMOItems' item config files into
   plugins/QinhItems/imports/

2. Preview first (no write):
   /qi imports dry-run
   → Read the report: which IDs will be imported, how each attribute maps, any warnings

3. Once confirmed, run the actual import:
   /qi imports run
   → Items written to items/, affixes / sections written to the corresponding registries

4. /qi reload to reload, /qi give <id> to verify

Attribute mapping reference

MMOItems attribute	QI target	Notes
attack-damage	base_attack_damage (base value)	Core attribute
max-health	base_health	Core attribute
defense	base_defense	Core attribute
attack-speed	normal attribute attack_speed
magic-damage	magic_damage
armor-penetration	armor_penetration
max-mana	max_mana
mana-regeneration	mana_regen
critical-strike-chance	critical_rate (÷100)	Ratio types divided by 100
dodge-rating	dodge (÷100)
block-rating	block_rate (÷100)
lifesteal	lifesteal (÷100)

The three core items go into base_values (managed by the base editor); the rest go into providers.ap. Ratio types are automatically ÷100. Everything is ultimately handed to AttributePlus, so remember to configure attribute-mapping properly.

Ability mapping

MMOItems ability	QI trigger
attack / on_hit	on_damage
damaged / when_hit	on_hit
right_click / left_click	same name
shift_right_click / shift_left_click	same name
sneak	shift_toggle
kill_entity	on_kill
shoot_bow	bow_shoot
shoot_trident	trident_throw
death / login	death / join

Restriction mapping

MMOItems	QI
required-level: N	level:N
required-class: A,B	class:A,B (delegated to QinhItemUseCheckEvent)
permission: X	permission:X

level / permission / world are judged natively by QI; class / faction etc. are delegated to QinhItemUseCheckEvent, where you need to implement the class check.

---

2. Migrating from NeigeItems

After placing files into imports/, do dry-run → run the same way. NeigeItems format import: sections, FancyDrop, actions, actions_file, data and other fields. Unknown fields fall back to the generic format.

---

3. Migrating Legacy Item Sources

/qi migrate dry-run      # Preview migration
/qi migrate              # Execute (with validation)

Used to migrate legacy QI item source structures to the current structure.

---

4. How to Read the dry-run Report

The ImportReport output includes:

Field	Meaning
Scanned file count	Files scanned in imports/
Import count / Import IDs	Items that will be created
Per-format counts	How many of mmoitems / neigeitems / generic each
Mapped fields	How each attribute / field was converted (for troubleshooting mapping)
Generated sections / affixes	Sections / Affixes produced as a side effect
Warnings	Don't block import but need attention (e.g. unrecognized attributes)
Errors	Block that item from importing

It is strongly recommended to dry-run first and check the mapped fields, confirming all attributes mapped correctly before running.

---

5. Content Pack (.qipack) Cross-Server Distribution

Package the current QI content into a single file for distribution to other servers.

Export

/qi packs export
→ Generates qinhitems-pack.yml (default name), containing metadata + sections + affixes + layerSnapshots + a reference for each item

Import

1. Put the .qipack (or pack yml) into the packs directory
2. /qi packs list          # Confirm it shows up
3. /qi packs import        # = apply / sync

Sync

/qi packs sync             # Refresh + export
/qi packs gui              # Graphical management (players only)

On import, it validates the declared count vs actual loaded count; a mismatch reports structureMismatch and provides a mismatchSummary.

---

6. API Calls

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

For field details see Import/Export (API).

---

Migration Checklist

• [ ] attribute-mapping configured (AP attribute names consistent)
• [ ] dry-run mapped fields verified correct
• [ ] Restrictions like class have a corresponding QinhItemUseCheckEvent implementation
• [ ] After import, /qi reload + /qi give to spot-check a few items
• [ ] /qi diagnose to confirm no new issues

---

Next Steps

• Import/Export (API)
• Diagnostics & Troubleshooting Compendium
• Events: QinhItemUseCheckEvent