QinhItems（QI）官方文档
秦淮原生物品库 — 为 Paper / Purpur / Spigot 1.21.11+、Java 25+ 打造的下一代自定义物品引擎。
当前版本：1.1.0 · API 版本：1 · 硬依赖：QinhCoreLib
QinhItems（下称 QI）是秦淮 RPG 生态的核心物品模块。它让你不写一行代码就能创造带属性、技能动作、套装、宝石孔、品质词缀、灵魂绑定的复杂自定义物品，同时为开发者提供一套干净、稳定、分层的 API 去读取、生成、改造物品。
🖼️ [图片占位] 一张展示 QI 物品（带结构化 Lore、套装、宝石孔、品质前缀）的游戏内截图 · 建议文件名
assets/hero-item-showcase.png
📖 这份文档怎么读
文档按读者角色分区。先确认你是谁，再从对应入口进入：
| 我是… | 从这里开始 | 你会学到 |
|---|---|---|
| 🆕 第一次接触 QI | 入门 → 概览 → 安装 → 5 分钟上手 | QI 是什么、怎么装、怎么造第一个物品 |
| 🛠️ 服主 / 配置者 | 服主指南 | YAML 物品配置、类型、品质、属性、动作、套装、宝石、绑定… |
| 📦 想要现成配方照抄 | 物品示例库 Cookbook | ~140 件内置示例物品逐类注解 + 即用配方 |
| 🩺 保存 / 重载报错了 | 校验报错速查 · 诊断排错 | 每条报错原文 + 原因 + 修法 |
| ❓ 快速找答案 | FAQ 常见问题集 | 易错点问答速查 |
| 🎮 想用 GUI 而不是手写 YAML | 编辑器 GUI | 游戏内可视化编辑物品、动作、套装 |
| 💻 插件开发者 | 开发者文档 | QinhItemsAPI、事件、动作处理器、Provider 桥、装配管线 |
| 📚 查命令 / 配置项 / 占位符 | 参考手册 | 命令树、权限、config.yml、PlaceholderAPI |
如果你不确定某个术语（如「层 Layer」「Provider」「Section」「ICVM」），随时翻 术语表。
✨ 核心特性一览
- 类型化物品系统 — 40+ 内置物品类型（weapon / armor / ring / gem / consumable…），每种类型声明自己支持的能力（属性、技能、宝石孔、套装、渲染）。详见 物品类型。
- 结构化 Lore 渲染 — 品质名 → 类型 → 属性 → 词缀段 → 宝石孔 → 技能 → 套装 → 描述 → 需求 → 绑定 → 耐久，自动按统一顺序排版。详见 显示与 Lore。
- 属性系统 — 通过
providers.ap或基础值（base values）给物品加战斗属性，桥接 AttributePlus；无 AP 时降级为纯物品库。详见 属性与数值。 - 物品动作 / 技能触发 — 100+ 触发原子（左右键、潜行双击、命中、击杀、序列连招…）+ 内置动作处理器（消息、音效、标题、命令、给物、技能释放…）+ 冷却 / 消耗 / 条件。详见 动作系统。
- 变量引擎 — 物品级动态值（随机数值、品质词、星级），
{变量名}占位符渲染，多源冲突解析与溯源。详见 变量。 - 品质 / 词缀 / 随机生成 — 类似 MMOItems 的随机物品生成：按品质权重抽 tier、按容量抽词缀池。详见 品质与词缀 与 随机生成。
- 套装系统 — 按穿戴件数激活的套装加成（属性 / 药水效果 / 主动技能）。详见 套装。
- 宝石孔 — Legendinlay / MagicGem 双后端的镶嵌孔。详见 宝石孔。
- 灵魂绑定 — 绑定后只有归属者可用、不可丢弃 / 交易 / 死亡掉落，连潜影盒里的绑定物都保护。详见 灵魂绑定。
- 游戏内可视化编辑器 — 一整套 GUI，从浏览到逐字段编辑、动作绑定、套装编排，全程无需碰 YAML。详见 编辑器 GUI。
- 导入 / 导出 — 从 MMOItems / NeigeItems 导入；
.qipack内容包导出导入。详见 导入导出。 - 稳定 API + 事件 — 分层门面（assembly / variables / actions / layers / bridge）、完整生命周期事件。详见 API 概览。
🗺️ 完整目录
完整章节导航见 SUMMARY.md（目录树）。
⚠️ 运行环境要求
| 项 | 要求 |
|---|---|
| 服务端 | Paper / Purpur / Spigot 1.21.11+ |
| Java | 25+ |
| 硬依赖 | QinhCoreLib（必须先装） |
| 可选软依赖 | AttributePlus、QinhSkills、PlaceholderAPI、CraftEngine、MythicMobs、LegendCore、Legendinlay、MagicGem、ItemsAdder、Nexo |
没装 AttributePlus 也能跑：QI 会进入「纯物品库模式」，物品照常渲染、动作照常触发，只是不往玩家身上加数值属性。详见 属性与数值。
📌 文档约定
- 形如
qi:title、QinhItemsAPI、providers.ap.value的是代码标识符 / 配置键，请原样照抄，大小写敏感。 - 形如
🖼️ [图片占位]的段落是留给你后续补图的位置，已标注建议文件名（放到assets/目录）。 - 代码块里的中文是注释 / 说明，真正写进 YAML 的请保留键名英文。
- 所有 YAML 路径默认相对于
plugins/QinhItems/。