ExtraBackpack 额外背包

模块简介

ExtraBackpack 是 Suite 的随身扩容背包模块，通过 ArcartX UI 替换原版物品栏界面。它不再持有独立存储——所有物品直接读写玩家个人仓库（WarehouseAccess capability），背包 UI 与仓库 UI 是同一存储的两个入口：背包里存的、取的，仓库里立即可见，反之亦然。

分类页（装备/材料/杂物等）是仓库内容的过滤器而非独立存储：每页显示匹配该页规则的仓库槽位 + 剩余空格；空格写入经仓库自动分配。携物点击空格时执行严格分类匹配——命中规则的物品只能进对应页签，无命中的只能进兜底页签。

容量 = 个人仓库已解锁格数（base-slots + 逐格购买的 extra_slots），槽位价格与上限统一由仓库配置（ArcartXWarehouse.yml 的 warehouses.personal）。销毁光标物品需二级密码验证，由核心统一管理。

功能特性

依赖表

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

背包机制详解

UI 界面替换

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

UI 界面结构：

分类匹配规则

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

1. 遍历所有分类（按 priority 升序），跳过兜底分类与无匹配规则的分类
2. 对每个分类，根据 nbt.path 读取物品对应值，检查是否在 nbt.values 列表中
3. 首个匹配成功的分类即为物品归属页签（该物品只在该页签的过滤视图中显示，且只能放入该页签）
4. 若无匹配，物品归入兜底页签——存储层面不分家，所有物品都在同一个人仓库里

支持的 NBT 路径类型：

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

存储模型

额外背包不持有独立存储：所有槽位操作经 WarehouseAccess 直写玩家个人仓库（warehouse_slots 表，owner_type=personal），持久化、并发锁与崩溃恢复全部由仓库模块负责。本模块仅维护打开 UI 期间的过滤视图：

网格视图（每页签）
├── gridItems[]:  格子 → ItemStack（匹配该页签的仓库槽位 + 尾部空格）
└── gridMapping[]: 格子 → 仓库槽位索引（-1 = 空格，写入时经仓库自动分配）

存入流程（UI 拖动）：

1. 玩家把物品放入某格子，ArcartX 原生完成放置并触发槽位更新事件
2. 已占用格（映射 ≥0）→ setSlot(仓库索引, 物品) 覆写仓库记录
3. 空格（映射 -1）→ deposit() 由仓库合并同类/分配空位
4. 写库完成后重建过滤视图并回推槽位

存入流程（API / 拾取兜底）：直接 warehouse.deposit()，仓库先合并同类堆叠再填空格。

取出流程：取出即 setSlot(索引, null) 删除仓库记录；API 取出按「页签过滤序号 → 仓库索引」映射后调用 withdraw()。

容量与扩容

容量 = 个人仓库已解锁格数，与仓库完全共通：

• 初始 base-slots（默认 32），上限 max-slots（默认 999）
• 玩家在背包设置面板或仓库 UI 左栏点击「+1 格」按钮逐格购买，价格由仓库 slot-price 决定
• 每次购买 extra_slots + 1，立即生效并刷新两边视图

分类页配置中的 slots.initial / price 字段已弃用（保留解析以兼容旧配置，不再生效）；slots.max 语义变为「该页网格显示上限」，应 ≥ 仓库 max-slots。

操作令牌机制

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

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