安装与环境
1. 环境要求
| 项 | 要求 | 说明 |
|---|---|---|
| 服务端 | Paper / Purpur / Spigot 1.21.11+ | plugin.yml 声明 api-version: '1.21' |
| Java | 25+ | 编译目标 Java 25，低版本 JVM 无法加载 |
| 硬依赖 | QinhCoreLib | 必须先于 QI 装好，否则 QI 拒绝启动 |
⚠️ QI 在
onEnable时会检查 QinhCoreLib 是否已加载并启用，以及服务端兼容性（ServerCompat.validateServer()）。任一不满足，QI 会中止启动并在控制台报错。
2. 可选软依赖
这些插件装了就启用对应功能，没装就自动降级，不影响 QI 主体运行：
| 软依赖 | 启用的功能 |
|---|---|
| AttributePlus | 物品战斗属性真正作用到玩家（数值后端）。详见 属性与数值 |
| QinhSkills | 物品动作 qinhskills:cast 释放技能。详见 集成 |
| PlaceholderAPI | %qinhitems_...% 占位符。详见 占位符 |
| Legendinlay | 宝石孔后端 A。详见 宝石孔 |
| MagicGem | 宝石孔后端 B |
| LegendCore | 把 QI 物品注册进 LegendCore 的 ItemManagerAPI（qi- 前缀） |
| MythicMobs | 怪物 / 掉落集成 |
| CraftEngine / ItemsAdder / Nexo | 自定义模型 / 材质提供者 |
3. 安装步骤
- 关闭服务器。
- 把 QinhCoreLib 的 jar 放进
plugins/。 - 把 QinhItems 的 jar 放进
plugins/。 - （可选）放入你想用的软依赖插件。
- 启动服务器。
首次启动时，QI 会通过 BundledContentBootstrap 把内置示例内容解压到磁盘（见下文），并打印启动摘要日志。
4. 首次启动会生成什么
QI 第一次启动会在 plugins/QinhItems/ 下释放一批文件，并写一个标记文件 .bundled_initialized_v3 表示「已初始化」。
始终会释放的核心文件：
plugins/QinhItems/
├── config.yml # 主配置（见 参考/配置文件）
├── item_types.yml # 物品类型定义
├── item_tiers.yml # 品质 / Tier 定义
├── enchant_limits.yml # 附魔上限
├── items/ # 物品定义（按类型分文件）
│ ├── weapon.yml armor.yml ring.yml gem.yml consumable.yml … （40+ 个）
├── fragments/
│ └── weapon_base.yml # 碎片示例
├── sections/
│ └── example_sections.yml # 段 / 词缀 / 池 示例
├── sets/
│ └── sets.yml # 套装示例
├── integrations/
│ ├── action_handlers.yml
│ ├── gem_socket_types.yml
│ ├── legendinlay_sockets.yml legendinlay_guide.yml
│ ├── magicgem_sockets.yml magicgem_guide.yml
│ ├── bridges.yml
│ └── resource_models.yml
└── legendcore/
├── QinhItemsModule.groovy # LegendCore 兜底脚本
└── README.txt📌 示例物品只在首次启动释放一次。如果你删了服务器里
items/下的某个内置示例又想找回来，需要手动删除.bundled_initialized_v3标记或单独从 jar 里取，否则不会自动重新释放。
5. 验证安装
进服后执行：
/qi status你会看到载入的物品数量、ActionTable 数量、是否有问题。再执行：
/qi diagnose查看完整诊断（属性后端是否接入、宝石后端、桥接 / 层 / 处理器数量等）。
也可以直接领一个内置示例物品试试（ID 见 items/weapon.yml，例如雷霆之刃）：
/qi give demo_thunder_edge🖼️ [图片占位]
/qi diagnose的控制台 / 聊天输出截图 · 建议assets/diagnose-output.png
6. 启动日志读什么
启动摘要（QinhItemsStartupLog）大致长这样，关键看几项：
物品定义: 123 · ActionTable 45
Bridge: 3 · Layer: 4 · Handler: 12
Combat: 启用 · 属性后端: attributeplus (已接入)
宝石: LI(LC✔·8孔) · MG(2孔)
诊断: 30/30 项可用- 属性后端 显示
attributeplus (已接入)说明 AP 正常；显示noop说明没检测到 AP，进入纯物品库模式。 - Combat: 关闭(纯物品库) 说明你在
config.yml里把combat.enabled关了。
下一步 → 5 分钟快速上手