HN 系列 Wiki

主题

这页汇总当前版本的两类配置：

  • 全局配置：plugins/HNWarehouse/config.yml
  • 仓库定义：plugins/HNWarehouse/warehouses/*.yml

一、全局配置：config.yml ​

当前默认结构：

yml
debug: false

capture:
  manual-enabled: true
  reward-enabled: true
  auto-collect-enabled: false
  manual-default-warehouse: main
  reward-default-warehouse: reward
  auto-collect-default-warehouse: main

storage:
  autosave-interval-seconds: 60
  summary-cache-ttl-seconds: 3
  project-hotbar: false
  allow-vanilla-main-inventory-edit: false

gui:
  access-display:
    accessible:
      label: "可访问"
      color: "green"
      info-material: "CHEST"
      action-material: "CHEST"
      placeholder-material: "GRAY_STAINED_GLASS_PANE"
      locked-title: "%subject%可访问"
      locked-prompt: "当前可正常访问"
      action-button-title: "当前可访问"
      action-button-hint: "当前仓库可直接访问"
      action-badge: "[可直接访问]"
      info-action-hint: "当前仓库可直接访问"
      visual-hint: "当前状态正常"

debug ​

  • 是否开启调试输出
  • 默认：false

capture.manual-enabled ​

  • 是否启用普通投递来源
  • 典型场景：API 主动投递、管理流程投递

capture.reward-enabled ​

  • 是否启用奖励投递来源
  • 典型场景：任务、签到、补偿等业务奖励投递

capture.auto-collect-enabled ​

  • 是否启用自动收纳来源骨架
  • 当前阶段主要是预留路由位与配置位

capture.*-default-warehouse ​

  • 三种来源的默认目标仓库 ID
  • 要求该仓库在 warehouses/*.yml 中真实存在

当前默认：

  • manual -> main
  • reward -> reward
  • auto-collect -> main

storage.autosave-interval-seconds ​

  • 在线 session 自动保存间隔，单位秒
  • 设为 0 表示关闭自动保存
  • 当前 autosave 由异步任务触发
  • 间隔过低虽然不会直接等价于“主线程卡顿”，但仍可能增加数据库压力

storage.summary-cache-ttl-seconds ​

  • 离线仓库摘要短缓存时间，单位秒
  • 默认：3
  • 设为 0 可理解为关闭这类缓存
  • 仅影响离线玩家摘要查询
  • 写入后会主动失效缓存，不会长期保留旧摘要

storage.project-hotbar ​

  • 预留配置，后续用于热栏投影策略
  • 当前不建议把它理解为“已经完整实现”

storage.allow-vanilla-main-inventory-edit ​

  • 预留配置，后续用于原版主背包编辑策略
  • 当前同样属于预留位

gui.access-display ​

  • 用于统一定义“仓库可访问 / 未购买 / 未解锁 / 受限”四类状态的展示主题
  • 主要影响仓库访问相关 GUI 的标题、按钮、提示文案、材质与视觉提示
  • 如果你希望玩家在锁定视图里看到更明确的购买/解锁引导，这一块就是核心配置入口

当前每个状态节点通常都支持：

  • label：状态短标签
  • color：状态主色
  • info-material：信息展示位材质
  • action-material：操作按钮材质
  • placeholder-material：占位背景材质
  • locked-title：锁定标题，可使用 %subject%
  • locked-prompt：锁定提示语
  • action-button-title：操作按钮标题
  • action-button-hint：操作按钮提示
  • action-badge：附加状态徽标
  • info-action-hint：信息区补充提示
  • visual-hint：视觉引导说明

这块最常见的用途：

  • 把“未购买”和“未解锁”做成明显不同的材质与颜色
  • 给玩家更清晰的按钮提示，例如“点击购买 / 点击解锁”
  • 统一不同仓库锁定视图的视觉风格，避免提示不一致

二、仓库定义：warehouses/*.yml ​

每个文件只定义一个仓库，并保留 id: 字段。

例如默认 main.yml 会包含：

  • access
  • pages

而 reward.yml 额外展示了：

  • item-admission

三、access：仓库访问控制 ​

示例：

yml
access:
  bypass-permission: hnwarehouse.access.bypass
  visible-when-locked: true
  purchase:
    enabled: true
    requirements: []
  use-requirements: []
  unlock:
    enabled: true
    requirements: []

bypass-permission ​

  • 拥有该权限时，可无视当前仓库的 use-requirements 与 unlock 限制

visible-when-locked ​

  • 仓库锁定时，是否仍允许玩家看到锁定视图
  • 适合需要展示“可解锁仓库”的场景

purchase ​

  • 一次性购买条件
  • 成功后会写入玩家档案中的购买状态

use-requirements ​

  • 每次访问都要检查的条件
  • 适合 VIP、动态货币余额、临时活动门槛等

unlock ​

  • 一次性解锁条件
  • 成功后会写入玩家档案中的解锁状态

purchase、unlock 与 use-requirements 是三层不同概念，不要把它们当成同一个开关。

四、pages：仓库页面定义 ​

示例：

yml
pages:
  page-1:
    capacity: 36
    auto-collect: true
    priority: 200
    allowed-sources:
      - manual
      - auto-collect

capacity ​

  • 页面容量
  • 当前主要体现为该页可容纳的条目槽位数

auto-collect ​

  • 是否允许自动收纳来源进入该页
  • 即使全局启用了 auto-collect，页面侧也仍要允许才会生效

priority ​

  • 同一仓库内的页面投递优先级
  • 数值越高，越先尝试投递

allowed-sources ​

  • 当前页允许接收的来源
  • 当前支持：
    • manual
    • reward
    • auto-collect

expansion ​

  • 页扩容开关与条件
  • 成功后会写入玩家档案中的页扩容状态

示例：

yml
expansion:
  enabled: true
  requirements:
    - type: placeholder
      placeholder: "%player_level%"
      operator: ">="
      value: "40"
      as: number
      message: "需要等级达到 40 级"

五、item-admission：仓库级物品准入规则 ​

示例：

yml
item-admission:
  whitelist:
    - material: DIAMOND
    - identity:
        item-type: warehouse_token
        origin: hnwarehouse
        token-id: open_remote
  blacklist:
    - name-contains: 测试禁用
    - pdc:
        "hnwarehouse:forbidden": "true"

规则顺序：

  1. blacklist 优先判定
  2. 若命中 blacklist，直接拒绝
  3. 若 whitelist 非空，则必须至少命中一条 whitelist
  4. 若 whitelist 为空，则默认允许未被 blacklist 命中的物品

当前支持的匹配字段包括：

  • material
  • name-contains
  • lore-contains
  • identity.item-type
  • identity.origin
  • identity.token-id
  • identity.serial
  • pdc.<namespaced-key>

其中：

  • identity.*
  • pdc.*

更适合配合 HNCore 物品身份协议与 PDC 标记做精细隔离。

六、requirements：条件类型说明 ​

当前 purchase / use-requirements / unlock / expansion 共用统一条件模型。

economy ​

  • 依赖 HNEconomy
  • 常见字段：currency、amount

vanilla-item ​

  • 检查玩家背包里的原版物品条件
  • 常见字段：material、amount

core-item ​

  • 使用 HNCore 共享物品库物品作为条件
  • 常见字段：source、item-id、amount

permission ​

  • 纯权限节点判断
  • 常见字段：permission

placeholder ​

  • 依赖 PlaceholderAPI
  • 常见字段：
    • placeholder
    • operator
    • value
    • as
    • message

当前支持比较符：

  • ==
  • !=
  • >
  • >=
  • <
  • <=
  • contains
  • matches

当前支持值类型：

  • number
  • string
  • boolean

七、默认仓库模板的角色建议 ​

main ​

  • 主仓库
  • 适合作为普通投递主入口
  • 默认示例里展示了访问限制、解锁条件与页扩容结构

reward ​

  • 奖励仓库
  • 适合只接收 reward 来源的物品
  • 默认示例里重点展示了 item-admission

overflow ​

  • 兜底仓库
  • 适合作为测试期或过渡期的统一收纳仓库
  • 也适合给未来复杂路由保留 fallback

八、推荐搭配阅读 ​

HN 系列插件文档

Copyright © 2024