秦淮系列文档

English

简体中文

English

简体中文

Appearance

Overview: What is QI ​

Previous: Home　·　Next: Installation & Environment

In one sentence ​

QinhItems (QI) is a data-driven custom item engine. Server owners describe — in YAML (or an in-game GUI) — what an item looks like, what attributes it has, and what effects fire on which key press. QI compiles that description into a real Minecraft ItemStack and, at runtime, maintains its display, attributes, actions, and binding state.

If you've used MMOItems, here's the analogy:

MMOItems conceptQI equivalentNote
Item TypesItem TypesQI types carry a "capability matrix"
StatsAttributes providers.ap / VariablesNumbers handled by AttributePlus
AbilitiesAction systemTriggers + handlers
TiersTier / QualityWeighted roll + capacity
Gem StonesGem socketsDual backend
SetsSetsActivated by piece count
/mi command/qi command
Editor GUIEditor GUI

But QI is not a clone of MMOItems. It has a few fundamental design differences — understanding them saves you headaches.

QI's three design principles ​

1) QI doesn't decide "how numbers are computed", only "numbers are attached to the item" ​

QI itself does not calculate combat damage. It attaches attributes as a JSON blob (providers.ap.value) onto the item, and when equipped hands them to AttributePlus (AP) to actually apply to the player. This means:

  • The meaning of "attack = 22" is decided by AP (you define what "physical damage" means in AP).
  • QI only: reads attributes off the item → formats them → hands them to AP, and displays them in the item lore.
  • No AP installed? QI enters "pure item-library mode": items can still be created, trigger actions, and render — only the numbers don't apply.

See Attributes & Numbers.

2) Item = Definition + Instance + Layers ​

A QI item in memory is the sum of three parts:

  • Definition: the "blueprint" written in YAML, shared by all items of the same ID.
  • Instance: per-item state stored in this one ItemStack's NBT — e.g. rolled numbers, owner, seed.
  • Layer: "patches" appended after creation — e.g. punching sockets, inlaying, reinforcing, extra affixes. Layers have an owner domain and priority, protected by policy.

What the player finally sees is these three composed through the Assembly Pipeline. When developers modify an item, they must know which layer they're touching — see Layers & Assembly.

3) The config layer (YAML) only describes "what it is"; logic goes to handlers ​

QI's action system deliberately does not support if / else / switch / conditional branches in YAML. A trigger is just "run a sequence of handler references in order". Need complex logic? A developer implements an action handler (QinhActionHandler) in Kotlin/Java; YAML only references it and passes a payload.

This boundary keeps config simple and fully GUI-editable while pushing complexity into code. See Action System Overview and Action Handler Development.

What it can do — typical scenarios ​

  • A sword that summons thunder on left-click, 3s cooldown, costs 1 redstone, epic quality.
  • A warrior set that triggers berserk and adds +15 physical damage and Haste II when 4 pieces are worn.
  • A soulbound weapon that can't be traded and isn't dropped on death.
  • A weapon with 2 gem sockets that players inlay via Legendinlay.
  • A random drop table: roll rarity by quality weight, then roll affixes by capacity, generating endlessly varied gear.
  • Bulk import from an old MMOItems config into QI.

Its place in the Qinh ecosystem ​

QI is the "item base" of the Qinh series. Its sibling modules:

  • QinhCoreLib (QCL) — the unified low-level library (item-source management, attribute pipeline, action contracts). QI hard-depends on it.
  • QinhSkills (QS) — the skill engine. qinhskills:cast in item actions hands skill casting to QS.
  • AttributePlus (AP) — a third-party attribute plugin, QI's numbers backend.

🖼️ [Image placeholder] Qinh ecosystem module diagram (QCL base, QI items, QS skills, AP numbers) · suggested assets/ecosystem-diagram.png

Keep reading ​