概览
Pickup 拾取模块功能概览
Pickup 拾取模块
模块简介
Pickup 是 Suite 的物品拾取增强模块，通过 ArcartX UI 提供两种工作模式：通知模式（拾取时弹出 HUD 提示）与扫描模式（禁用自动拾取，面板展示附近掉落物，按键交互拾取）。所有界面均基于 ArcartX 客户端 MOD 渲染，服务端通过 PacketBridge 与客户端通信。
通知模式下，玩家正常拾取地面掉落物，HUD 以滚动队列展示最近 N 条拾取记录，每条包含物品图标、名称与数量，超时后自动消失。扫描模式下，模块周期性扫描玩家周围掉落物，经五维过滤筛选后推送到客户端 HUD 面板，玩家通过按键打开透明交互菜单，使用鼠标点击或滚轮切换选中并拾取目标物品，可选联动 Warehouse 模块将拾取物自动存入仓库。
| 属性 | 值 |
|---|---|
| 模块 ID | pickup |
| 版本 | 1.4.4 |
| 配置版本 | 3（当前 schema） |
| 配置文件 | config.yml、messages.yml |
| 命令入口 | 玩家 /pickup（无模块管理命令） |
| 外部依赖 | 无 |
| 模块依赖 | 无（Warehouse 自动入库可选联动） |
| 对外能力 | PickupNotifiable（拾取通知）、PickupInterceptor（拾取拦截） |
功能特性
| 功能 | 说明 |
|---|---|
| 拾取通知 HUD | 通知模式下，玩家拾取物品时在屏幕右下角弹出提示，包含物品图标、名称与数量，支持多条堆叠与自动消失 |
| 掉落物扫描面板 | 扫描模式下，周期性扫描玩家附近掉落物，以半透明面板竖向展示，每项包含图标、名称与数量 |
| 选中高亮 | 扫描面板当前选中项以蓝色高亮，支持滚轮循环切换 |
| 鼠标点击拾取 | 直接点击面板上的物品条目即可拾取对应物品 |
| 交互菜单 | 按自定义交互键打开透明菜单捕获鼠标光标，用于精确操作 |
| 五维过滤 | 材质黑/白名单、物品名称正则、Lore 正则、NBT 键匹配、最小堆叠数量 |
| 合并显示 | 同名同类物品合并为一条，显示总数量 |
| 拾取延迟 | 掉落物落地一定时间后才开始显示，防止刚扔出的物品立即出现 |
| 仓库联动 | 扫描模式拾取后可选自动存入 Warehouse 仓库模块 |
| 玩家开关 | 玩家可通过 /pickup 命令随时开关个人拾取功能 |
依赖表
| 依赖 | 类型 | 说明 |
|---|---|---|
| ArcartX 客户端 MOD | 硬依赖 | 提供 UI 渲染、PacketBridge 通信、客户端包处理与按键事件 |
| Warehouse 模块 | 可选 | 扫描模式拾取后自动存入仓库（WarehouseAutoDepositable Capability） |
| NeigeItems / MythicMobs / MMOItems | 可选 | 识别对应物品来源的显示名与序列化数据 |
Pickup 模块在
module.yml中声明depends: []，不强制依赖其他模块。运行时依赖 ArcartX 客户端 MOD 提供 UI 渲染能力，客户端未安装时 HUD 无法显示。
模式对比
| 特性 | 通知模式（notification） | 扫描模式（scanner） |
|---|---|---|
| 拾取行为 | 正常自动拾取 | 禁用自动拾取，改为按键/点击拾取 |
| HUD 功能 | 显示拾取通知（滚动队列） | 实时展示附近掉落物列表 |
| 交互方式 | 无交互 | 按键拾取 / 鼠标点击 / 滚轮切换 |
| 过滤系统 | 无 | 材质 + 名称 + Lore + NBT + 数量五维过滤 |
| 仓库联动 | 无（仅补发 HUD 提示） | 可选自动存入仓库 |
| UI 界面 | AXS:pickup_hud（1 套） | AXS:loot_panel + AXS:loot_interact（2 套） |
拾取机制
通知模式流程
- 玩家拾取地面掉落物，HUD 弹出拾取提示（图标 + 名称 + 数量）
- 新提示插入队列首位，旧条目依次下移
- 每条提示超过
entry-ttl-ms后自动隐藏 - 拾取事件同时发布
axs.pickup.item_pickupEventBus 事件，供其他模块订阅
通知模式下，若 Warehouse 模块开启自动入库先行拦截了拾取，Warehouse 会主动补发 HUD 提示，玩家仍能看到拾取通知。
扫描模式流程
disable-auto-pickup启用时，玩家的自动拾取被禁用- 周期扫描任务（
scan-interval-ticks间隔）扫描玩家scan-radius半径内的掉落物 - 掉落物经五维过滤，并通过
pickup-delay-ticks落地延迟检查后加入可见列表 merge-same-items启用时，相同材质+名称的条目合并数量- 列表推送到
loot_panelHUD 展示 - 玩家按交互键打开
loot_interact透明菜单，点击物品条目或滚轮切换选中 - 确认拾取后物品进入背包；
warehouse-auto-deposit启用时优先存入仓库 - 背包满时物品保留在地面并提示玩家；周围无掉落物时自动关闭交互菜单
五维过滤
按以下顺序依次检查每个掉落物，任一维度不通过则不显示：
| 顺序 | 维度 | 规则 |
|---|---|---|
| 1 | 最小数量 | 堆叠数低于 min-amount 则过滤 |
| 2 | 材质过滤 | blacklist 模式：命中黑名单则过滤；whitelist 模式：白名单非空时未命中则过滤 |
| 3 | 名称正则 | 命中 name-blacklist 正则则过滤 |
| 4 | Lore 正则 | 命中 lore-blacklist 正则则过滤；lore-whitelist 非空时未命中则过滤 |
| 5 | NBT 键 | 命中 nbt-blacklist 键则过滤；nbt-whitelist 非空时未命中则过滤 |
过滤配置基于
ItemMatcher体系，材质匹配使用material-ids，名称/Lore 使用正则表达式，NBT 使用键路径匹配。详见 物品匹配条件 与 物品来源。
UI 界面
Pickup 模块根据工作模式注册不同的 ArcartX UI 界面：
| 界面 | UI ID | 模式 | 配置路径 | 说明 |
|---|---|---|---|---|
| 拾取通知 HUD | AXS:pickup_hud | 通知模式 | ui.notification-ui-id | 滚动队列展示最近拾取记录，根据 max-visible 与 entry-ttl-ms 动态生成 |
| 掉落物面板 HUD | AXS:loot_panel | 扫描模式 | ui.scanner-ui-id | 常驻 HUD，展示附近掉落物列表，捕获滚轮与点击 |
| 交互菜单 | AXS:loot_interact | 扫描模式 | ui.interact-ui-id | 透明菜单，按键打开后捕获鼠标光标，ESC 关闭 |
通知模式的
pickup_hud.yml在启动时根据配置参数动态生成到ui/pickup_hud.yml，修改max-visible或entry-ttl-ms后需开启ui.overwrite-ui-files或手动删除旧文件以重新生成。扫描模式的loot_panel.yml与loot_interact.yml为固定导出文件。UI 图标渲染使用 Slot 组件，详见 UI 图标。
配置版本与迁移
当前配置版本为 3。模块包含两份迁移文件：
| 迁移 | 说明 |
|---|---|
| 1 → 2 | 移除已废弃的 scanner.keybind.default-key 字段（从未被代码使用） |
| 2 → 3 | 将分散在 notification / scanner 嵌套节中的 UI 配置抽离到统一 ui 顶层节 |
配置版本低于 3 时，模块启动时自动按顺序应用迁移。详见 配置管理。