feat(items): 角色背包与储藏箱物品及金币丢弃至地面实体系统 (Item & Gold Dropping to Ground) #388

New Issue

troytt · 2026-09-23T01:56:54Z

troytt commented

2026-09-23 01:56:54 +00:00

问题背景与现状分析

目前在客户端中，当玩家在背包（Inventory）或储藏箱（Stash）中拾起物品（cursorItem）并点击面板外部地面时，仅在状态栏提示「已将某物品丢弃在地面」，并未在世界场景中生成实际的地面物品实体，物品直接从内存中丢失。此外，金币系统缺乏丢弃通道，无法将金币从背包或储藏箱中取出散落在地面。

原版 Diablo II v1.13c 核心机制规范（Ground Truth）

1. 物品存储状态机 (ItemMode) 转换

物品从 ItemMode.STORED (0) 被鼠标拾起变为 ItemMode.CURSOR (4)。
丢弃至地面时，转换为 ItemMode.DROPPING (5) 并最终落定为 ItemMode.GROUND (3)。

2. 地面物品实体数据结构 (GroundItem)

唯一标识：全局递增或 UUID 实体 ID。
世界坐标：基于当前地图坐标系的世界像素与网格坐标 (x, y)。
物品元数据：完整的 UiInventoryItem / ItemBase 数据（含品质、代码、属性、尺寸、金币数量等）。
金币掉落实体：当丢弃金币时，生成特殊的 code: "gld" 实体，记录金币数量 amount。

3. 散落坐标与碰撞规避 (Drop Placement & Collision Validation)

严格参照 D2Common.dll 中的 ITEM_Drop 算法，在玩家站立坐标周围放射状搜索最近的非阻挡、合法可行走地面网格（blocked !== 1）。
严禁将物品生成在虚空或不可通达的墙体内。

4. 真实掉落音效 (Authentic Drop SFX)

丢弃装备时，根据 Weapons.txt / Armor.txt / Misc.txt 中的 dropsound 字段播放对应的原版音效（金属、皮革、药水破空、金币落地等）。

改造与验收标准

玩家可在背包和储藏箱中拿起任意装备/道具，点击场景地面将其丢弃并生成可交互实体。
支持背包金币丢弃交互，扣减角色金币并在地面生成对应数额的金币堆实体。
掉落位置经过合法行走网格校验，绝不穿透至阻挡区或虚空。
丢弃时正确播放对应的原版落地音效。
自动化构建与单测（npm run typecheck, npm test）100% 通过。

## 问题背景与现状分析目前在客户端中，当玩家在背包（Inventory）或储藏箱（Stash）中拾起物品（cursorItem）并点击面板外部地面时，仅在状态栏提示「已将某物品丢弃在地面」，并未在世界场景中生成实际的地面物品实体，物品直接从内存中丢失。此外，金币系统缺乏丢弃通道，无法将金币从背包或储藏箱中取出散落在地面。 --- ## 原版 Diablo II v1.13c 核心机制规范（Ground Truth） ### 1. 物品存储状态机 (ItemMode) 转换 - 物品从 `ItemMode.STORED` (0) 被鼠标拾起变为 `ItemMode.CURSOR` (4)。 - 丢弃至地面时，转换为 `ItemMode.DROPPING` (5) 并最终落定为 `ItemMode.GROUND` (3)。 ### 2. 地面物品实体数据结构 (GroundItem) - **唯一标识**：全局递增或 UUID 实体 ID。 - **世界坐标**：基于当前地图坐标系的世界像素与网格坐标 `(x, y)`。 - **物品元数据**：完整的 `UiInventoryItem` / `ItemBase` 数据（含品质、代码、属性、尺寸、金币数量等）。 - **金币掉落实体**：当丢弃金币时，生成特殊的 `code: "gld"` 实体，记录金币数量 `amount`。 ### 3. 散落坐标与碰撞规避 (Drop Placement & Collision Validation) - 严格参照 `D2Common.dll` 中的 `ITEM_Drop` 算法，在玩家站立坐标周围放射状搜索最近的非阻挡、合法可行走地面网格（`blocked !== 1`）。 - 严禁将物品生成在虚空或不可通达的墙体内。 ### 4. 真实掉落音效 (Authentic Drop SFX) - 丢弃装备时，根据 `Weapons.txt` / `Armor.txt` / `Misc.txt` 中的 `dropsound` 字段播放对应的原版音效（金属、皮革、药水破空、金币落地等）。 --- ## 改造与验收标准 1. 玩家可在背包和储藏箱中拿起任意装备/道具，点击场景地面将其丢弃并生成可交互实体。 2. 支持背包金币丢弃交互，扣减角色金币并在地面生成对应数额的金币堆实体。 3. 掉落位置经过合法行走网格校验，绝不穿透至阻挡区或虚空。 4. 丢弃时正确播放对应的原版落地音效。 5. 自动化构建与单测（npm run typecheck, npm test）100% 通过。

troytt added this to the 复刻捡起/丢弃物品 milestone 2026-09-23 01:56:54 +00:00

troytt referenced this issue from a commit

2026-09-23 02:19:33 +00:00

feat(items): authentic 1.13c ground items entity, safe drop radial search and item/gold dropping (Fixes #388)

troytt closed this issue

2026-09-23 02:19:33 +00:00

troytt referenced this issue from a commit

2026-09-23 02:19:33 +00:00

Merge branch 'issue-388' into main (Fixes #388)

Sign in to join this conversation.