ExtraBackpack 额外背包

模块简介

ExtraBackpack 是 Suite 的额外槽位背包模块，通过 ArcartX UI 替换原版物品栏界面，为玩家提供多分类额外背包空间。模块默认关闭，启用后与玩家原版背包共存——原版背包作为首个标签页保留，额外分类页（装备/材料/杂物等）作为后续标签页展示，每页独立配置槽位数量、上限与付费扩容价格。

物品分类基于 NBT/PDC 路径匹配规则，由模块自行判断。玩家拾取物品时可自动归类存入对应分类页，也可在 UI 中手动存取。扩容通过货币付费实现，支持多货币类型。销毁原版背包物品需二级密码验证，由核心统一管理。

模块 ID：extrabackpack
版本：1.4.4
配置版本：2（当前 schema）
源码主类：xuanmo.arcartxsuite.extrabackpack.ExtraBackpackModule
配置文件：config.yml
消息文件：messages.yml
UI 文件：ui/extrabackpack.yml
通信包 ID：AXS_BACKPACK

功能特性

功能	说明
多分类额外背包	支持装备/材料/杂物等多个分类页，每页独立配置初始槽位、最大槽位与扩容价格
原版背包共存	UI 替换原版物品栏界面，原版背包作为首个标签页保留，额外分类页作为后续标签页
NBT 自动归类	根据物品 NBT/PDC 路径匹配规则自动归类到对应分类，支持 `pdc:`、`material`、`display-name`、`lore` 等多种路径
兜底分类	未匹配任何分类规则的物品自动归入标记为 `default` 的兜底分类页
拾取自动存入	玩家拾取物品时自动按分类规则存入额外背包，放不下的部分保留在原版背包
付费扩容	每个分类可配置独立的扩容货币与单价，玩家在 UI 中输入数量购买槽位
快捷栏交互	UI 底部展示原版快捷栏 9 格，点击可将快捷栏物品存入额外背包
原版物品管理	原版标签页支持查看物品信息、存入额外背包、销毁物品（需二级密码验证）
二级密码保护	销毁原版背包物品需通过核心二级密码验证，支持设置/解锁/清除密码
操作令牌防重放	UI 操作携带 action token，防止重放攻击与并发冲突
持久化存储	支持 SQLite/MySQL 双方言，共享存储模式与自建存储模式
数据迁移	支持 `/axs migrate` 跨数据库源迁移，支持 `/axs purge` 按玩家/全量清除数据

依赖表

依赖	类型	说明
ArcartX 客户端 MOD	硬依赖	提供 UI 渲染与 PacketBridge，背包界面通过 ArcartX UI 呈现
ArcartXSuite 核心	硬依赖	提供 PacketBridge、ItemBridge、CurrencyBridge、PacketGuard、VanillaItemNameBridge 等桥接服务

可选依赖	类型	说明
Warehouse	softdepend	`module.yml` 声明 `softdepends: [warehouse]`（加载顺序在 Warehouse 之后）；同时本模块注册 `ExtraBackpackAccess` Capability 供 Warehouse 消费，用于仓库与额外背包间的物品交互

ExtraBackpack 模块本身不依赖任何外部插件（无 external-depends），货币系统通过核心 CurrencyBridgeAPI 统一桥接（支持 Vault/PlayerPoints/XConomy 等）。

背包机制详解

UI 界面替换

ExtraBackpack 模块注册一套 ArcartX UI 界面（UI ID AXS:extrabackpack），通过 match: [物品栏界面] 替换原版物品栏界面。玩家打开原版背包时自动呈现额外背包 UI，无需额外命令触发。

UI 界面结构：

区域	说明
标题栏	显示"额外背包"标题与容量状态文本（如 `9/27`）
刷新按钮	手动刷新 UI 数据
分类标签行	横向排列的分类标签（含原版背包标签 + 各分类页标签），点击切换
背包网格	12 列网格，动态创建槽位控件，展示当前分类页物品
购买卡片	显示扩容提示文本、数量输入框与购买按钮
快捷栏卡片	展示原版快捷栏 9 格，点击存入额外背包
物品信息面板	原版标签页中点击物品时显示物品信息
物品操作面板	原版标签页中右键物品时显示存入/销毁选项
销毁确认框	销毁物品前的二次确认弹窗
二级密码面板	设置/解锁/清除二级密码的弹窗面板

分类匹配规则

物品分类依据 ExtraBackpackCategory 的 NBT 匹配规则，由模块自行判断。匹配流程：

遍历所有分类（按 priority 升序），跳过兜底分类与无匹配规则的分类
对每个分类，根据 nbt.path 读取物品对应值，检查是否在 nbt.values 列表中
首个匹配成功的分类即为物品归属分类
若无匹配，物品不自动归类（拾取时不存入额外背包）

支持的 NBT 路径类型：

路径	说明	示例
`pdc:<namespace>:<key>`	读取 PersistentDataContainer 字符串值	`pdc:arcartx:item_category`
`pdc:<key>`	读取 PDC 值，namespace 默认为插件名	`pdc:category`
`material`	读取物品材质 ID（经 VanillaItemNameBridge 翻译为中文名）	`material`
`display-name` / `name`	读取物品显示名称	`display-name`
`custom-model-data`	读取 CustomModelData 整数值	`custom-model-data`
`lore`	遍历物品 Lore 行，检查是否包含匹配值	`lore`

匹配值与路径值均做 trim().toLowerCase() 归一化处理。lore 路径使用 contains 匹配，其余路径使用精确匹配。

存储模型

额外背包采用分类分页存储模型，核心数据结构为 ExtraBackpackSlotRecord：

extra_backpack_slots 表
├── player_uuid: 玩家 UUID
├── category_id: 分类标识
├── slot: 槽位序号（从 0 开始）
├── item_data: Base64 序列化物品数据
├── updated_at: 更新时间戳（毫秒）

extra_backpack_capacity 表
├── player_uuid: 玩家 UUID
├── category_id: 分类标识
├── capacity: 当前容量（槽位数）
├── updated_at: 更新时间戳（毫秒）

内存模型：每位玩家在内存中维护 Map<String, ItemStack[]>（分类 ID → 槽位物品数组），数组长度即当前容量。玩家上线时从数据库加载，退出时持久化。

存入流程：

根据 NBT 匹配规则确定物品分类
在对应分类页中先尝试合并到相同物品的槽位（受 maxStackSize 限制）
剩余物品写入空闲槽位
放不下的部分返回原版背包或掉落

取出流程：

物品优先放入快捷栏 0-8 格
快捷栏放不下的部分掉落在玩家脚下

容量与扩容

每个分类定义包含初始槽位与最大槽位：

categories:
  equipment:
    slots:
      initial: 9    # 初始槽位数
      max: 27       # 最大槽位上限
    price:
      currency: "points"  # 扩容货币
      per-slot: 100       # 每个槽位价格

玩家在 UI 中输入购买数量，系统计算总价并扣费。扩容后按新容量重建该页数组，保留已有物品。容量始终限制在 [initialSlots, maxSlots] 范围内。

若分类未配置 price 或 per-slot <= 0，该分类不可扩容。

操作令牌机制

UI 打开时签发唯一的 action token，客户端在执行购买槽位、销毁物品、设置/清除二级密码等敏感操作时需携带有效 token。操作完成后自动轮换 token，防止重放攻击。UI 关闭时清除 token 并持久化数据。

关于 UI 条件匹配与图标渲染的通用知识，参考条件系统与图标系统。

概览