这页用于说明 HNWarehouse 当前版本的依赖、目录结构、首启生成内容与首次排查重点。

---

依赖关系

硬依赖

• HNCore

HNWarehouse 当前会直接复用 HNCore 的公共日志、数据库与运行时能力，因此 HNCore 未加载时，HNWarehouse 不应被视为可正常运行。

可选联动

• HNEconomy：用于 economy 条件
• PlaceholderAPI：用于 placeholder 条件

即使不安装这两个可选插件，HNWarehouse 也能启动；只是相关条件类型在运行时不可用或会直接失败。

---

建议环境

• Paper 1.20.1
• Java 17

---

安装步骤

1. 先安装并确认 HNCore 正常启动
2. 放入 HNWarehouse 插件本体
3. 如需经济或占位符条件，再额外放入 HNEconomy / PlaceholderAPI
4. 启动服务器，等待默认配置生成与存储后端初始化

---

首次启动后应生成的内容

默认情况下，插件会生成：

plugins/HNWarehouse/
├─ config.yml
├─ warehouses/
│  ├─ main.yml
│  ├─ reward.yml
│  └─ overflow.yml
└─ data/
   ├─ players/                # 仅旧 YAML 迁移来源可能存在
   └─ .migration-complete     # 完成旧 YAML 自动迁移后写入

说明：

• config.yml：全局 capture 与 storage 配置
• warehouses/*.yml：仓库定义模板，每个文件一个仓库
• data/players/：旧版玩家 YAML 迁移来源目录，不再是正式主持久化路径
• .migration-complete：旧 YAML 自动迁移完成后的标记文件

如果 warehouses/ 下没有任何 .yml 仓库文件，插件会自动写出默认模板。

---

当前正式主存储

当前正式主存储已经切到 HNCore DatabaseManager 驱动的数据库后端。

这意味着：

• 新版本运行时应优先以数据库状态为准
• 旧 data/players/*.yml 主要是升级时的历史导入来源
• 首启检查重点也应该放在数据库初始化、状态输出与迁移结果上，而不是只盯着 YAML 目录

---

plugin.yml 当前依赖声明

当前插件声明的是：

• depend: HNCore
• softdepend: HNEconomy, PlaceholderAPI

也就是说：

• HNCore 缺失时不应继续视为正常环境
• HNEconomy / PlaceholderAPI 缺失时，只影响对应条件能力

---

首启后建议立刻执行的命令

/hnwarehouse status

当前建议重点确认：

• 插件版本
• Debug 模式
• 存储后端
• 统一存储系统是否已初始化
• 自动保存间隔
• 离线摘要缓存秒数
• capture 三种来源的默认目标仓库
• HNEconomy Hook 是否可用
• HNCore 共享物品库 是否可用
• 仓库定义数量是否正确

---

如果你是从旧版本升级

建议额外确认：

• plugins/HNWarehouse/data/players/ 下的旧 YAML 是否被扫描
• 数据库中原本不存在的玩家档案是否已被成功导入
• plugins/HNWarehouse/data/.migration-complete 是否已生成
• 原始 YAML 是否仍被保留用于人工核对

当前语义是：

• 启动时会扫描旧 YAML
• 仅在数据库中不存在该玩家档案时才导入
• 成功后写 .migration-complete
• 原始 YAML 不会自动删除

---

首启常见检查项

1. 仓库定义是否加载成功

如果 warehouses/*.yml 配置结构错误，通常会直接影响：

• 仓库定义数量
• 页面数量
• 访问条件统计
• open / purchase / unlock / expand 等命令行为

2. 默认 capture 路由是否合理

建议先核对：

• manual-default-warehouse
• reward-default-warehouse
• auto-collect-default-warehouse

如果默认目标仓库不存在，运行时会尝试回退到可用仓库，但这通常意味着你的配置还没整理好。

3. 可选联动是否符合预期

如果你已经配置了：

• economy 条件
• placeholder 条件
• core-item 条件

那就应在首启阶段一并确认依赖可用，而不是等上线后再排查“为什么解锁条件一直失败”。

4. 存储与迁移是否符合预期

建议确认：

• status 显示的存储后端是否正确
• 自动保存间隔与摘要缓存是否符合预期
• 如果是旧版本升级，自动迁移是否已经完成

---

目前首启后不会自动接入的能力

当前版本还没有完整接入以下运行时链路：

• 掉落拾取接管监听器
• 死亡掉落改写
• 原版背包热栏投影
• 更完整的 InventoryClick / InventoryDrag 接管策略

所以现阶段更适合作为：

• 统一仓库领域骨架
• 投递 / 提取 / 查询 / 权限限制基础能力
• 下游业务插件的仓库 API 与数据承载层

---

下一步看什么

• 想直接跑通一次存取链路：看 快速开始
• 想细看配置项：看 配置说明
• 想看数据库、迁移与 Session 行为：看 数据存储与运维