Pickup 拾取模块

模块简介

Pickup 是 Suite 的物品拾取增强模块，通过 ArcartX UI 提供两种工作模式：通知模式（拾取时弹出 HUD 提示）与扫描模式（禁用自动拾取，面板展示附近掉落物，按键交互拾取）。所有界面均基于 ArcartX 客户端 MOD 渲染，服务端通过 PacketBridge 与客户端通信。

通知模式下，玩家正常拾取地面掉落物，HUD 以滚动队列展示最近 N 条拾取记录，每条包含物品图标、名称与数量，超时后自动消失。扫描模式下，模块周期性扫描玩家周围掉落物实体，经五维过滤引擎筛选后推送到客户端 HUD 面板，玩家通过按键打开透明交互菜单，使用鼠标点击或滚轮切换选中并拾取目标物品，可选联动 Warehouse 模块将拾取物自动存入仓库。

• 模块 ID：pickup
• 版本：1.4.4
• 配置版本：3（当前 schema）
• 源码主类：xuanmo.arcartxsuite.pickup.PickupModule
• 配置文件：config.yml
• 消息文件：messages.yml

功能特性

依赖表

Pickup 模块在 module.yml 中声明 depends: []，不强制依赖其他模块。运行时依赖 ArcartX 客户端 MOD 提供 UI 渲染能力，客户端未安装时 HUD 无法显示。

模式对比

拾取机制

通知模式流程

1. 玩家拾取地面掉落物，触发 EntityPickupItemEvent（HIGHEST 优先级，ignoreCancelled = true）
2. PickupService 监听事件，将物品序列化为 JSON 并构造 payload（itemJson + amount）
3. 若玩家 HUD 已打开，延迟 1 tick 发送 pick 包到客户端；否则先调用 openUi 打开 HUD，将 payload 排入待发队列，HUD 打开确认后 flush
4. 客户端 pickup_hud.yml 的 packetHandler.pick 接收包，将新条目插入队列首位，旧条目依次下移
5. HUD tick 动作每帧检查各条目是否超过 entry-ttl-ms，超时则隐藏
6. 拾取事件同时通过 EventBus 发布 axs.pickup.item_pickup 事件，供其他模块订阅

通知模式下，若 Warehouse 模块以 LOWEST 优先级取消了 EntityPickupItemEvent（自动入库），本模块监听器因 ignoreCancelled = true 不会触发。Warehouse 通过 PickupNotifiable.notifyPickup 主动补发 HUD 提示。

扫描模式流程

1. 服务启动时注册 EntityPickupItemEvent 监听器（LOW 优先级），当 disable-auto-pickup 启用时取消所有玩家的自动拾取
2. 周期扫描任务（scan-interval-ticks 间隔）遍历在线玩家，扫描其 scan-radius 半径内的 Item 实体
3. 每个掉落物经 LootFilterEngine 五维过滤，通过 pickup-delay-ticks 延迟检查后加入可见列表
4. 若 merge-same-items 启用，相同材质+名称的条目合并数量
5. 列表变化时发送 update 包到客户端 loot_panel HUD，包含各槽位的可见状态、数量与物品 JSON
6. 玩家按交互键，宿主按键系统回调 LootScannerService.handleInteractKeyFromHost，服务端校验后发送 open_interact 包，客户端打开 loot_interact 透明菜单
7. 玩家在菜单中点击物品条目（pick_0 ~ pick_7）或滚轮切换选中（scroll_up / scroll_down），客户端回包通知服务端
8. 服务端 handlePick 将选中物品放入玩家背包，若 warehouse-auto-deposit 启用则优先存入仓库
9. 背包满时物品保留在地面并提示玩家；周围无掉落物时自动关闭交互菜单

五维过滤引擎

LootFilterEngine 按以下顺序依次检查每个掉落物，任一维度不通过则不显示：

过滤配置基于 ItemMatcher 体系，材质匹配使用 material-ids，名称/Lore 使用正则表达式，NBT 使用键路径匹配。详见 物品匹配条件 与 物品来源。

UI 界面

Pickup 模块根据工作模式注册不同的 ArcartX UI 界面：

通知模式的 pickup_hud.yml 由 PickupHudTemplateWriter 在启动时根据配置参数动态生成到 ui/pickup_hud.yml，修改 max-visible 或 entry-ttl-ms 后需开启 ui.overwrite-ui-files 或手动删除旧文件以重新生成。扫描模式的 loot_panel.yml 与 loot_interact.yml 从 jar 资源导出。UI 图标渲染使用 Slot 组件，详见 UI 图标。

配置版本与迁移

当前配置版本为 3。模块包含两份迁移文件：

配置版本低于 3 时，模块启动时自动按顺序应用迁移。详见 配置管理。