mtgodot-poc/audit/contracts/item.drop-pickup.md

item.drop_pickup

Scope

审计地面掉落物从 GC_ITEM_GROUND_ADD、所有权更新、模型/特效/名条创建，到鼠标点选、走近、500ms 拾取节流、权限拒绝、CG_ITEM_PICKUP、GC_ITEM_GROUND_DEL 和拾取后物品回包的完整链路。

Reference call chain

• PythonNetworkStreamPhaseGameItem.cpp
  • RecvItemGroundAddPacket 读取坐标、VID、vnum，转换全局/本地坐标后调用 CPythonItem::CreateItem。
  • RecvItemOwnership 调用 CPythonItem::SetOwnership；RecvItemGroundDelPacket 调用 CPythonItem::DeleteItem。
• PythonItem.cpp / ItemData.cpp / ItemManager.cpp
  • CreateItem 先通过 CItemManager::GetItemDataPointer 验证 vnum，使用 CItemData::GetDropModelThing 创建实际掉落模型，按地形高度/法线处理位置，并挂接 drop effect、掉落声音和掉落动画状态；名条使用 item data 名称。
  • SetOwnership 只更新已有 VID 的 ground instance 和名条；未知 VID 不创建对象。
  • DeleteItem 同时删除模型实例和 CPythonTextTail 名条；DeleteAllItems 用于清理整张地图。
• PythonPlayer.cpp / PythonPlayerInputMouse.cpp
  • SendClickItemPacket 在观战模式直接拒绝，500ms 节流；读取地面物品 owner、vnum 和 ItemManager anti-flag，非本人且不满足组队/可掉落可赠送条件时触发 OnCannotPickItem，否则发送 SendItemPickUpPacket。
  • __OnPressItem 清理旧预约和自动攻击；距离足够时发送 WAIT 状态和拾取请求，否则建立 MODE_CLICK_ITEM 预约并持续走近。
  • __ProcessClickItem 到达约 20 像素内时发送 WAIT、SendClickItemPacket、停止并清理预约；物品消失则清理预约。
• PythonTextTail.cpp / CPythonItem::__Pick
  • 鼠标拾取先测试实际掉落模型的相交，再回退到文本尾标拾取；owner 名条独立显示并参加尾标排布。

Current call chain

• extension/src/net/classic/classic_parser.cpp / EntityStore
  • 解析 GC_ITEM_GROUND_ADD、GC_ITEM_GROUND_DEL、GC_ITEM_OWNERSHIP，写入 GroundItem{vid,vnum,x,y,z,owner} 并通过 M2Client 信号同步。
  • 当前 parser/store 不查询 ItemManager 以拒绝未知 vnum；未知掉落仍可进入当前状态。
• project/ui/ground_items.gd
  • _on_added 生成通用 item_bag.gr2 或 BoxMesh，占位模型；按 MapCoord 和地形采样设置位置，创建名字/owner Label3D、稀有光柱和名条防重叠。
  • _on_removed/clear_for_map_change 删除 Godot 节点；_process 旋转占位网格、按距离改名字颜色并重新排布尾标。
  • try_pickup/try_pickup_vid 有 3m 步行、5m 骑马、最近优先、500ms 节流和 owner 名字拦截；然后直接调用 client.pickup_item(vid)。
  • pick_at 用投影后的模型点、名字标签和 owner 标签的 64px 最近点选择，不是参考端的实际模型相交 + TextTail Pick。
• project/net_play.gd / player_controller.gd
  • pick_ground_item 在约 20m?（代码使用 CLICK_ITEM_PICKUP_CM 换算）内立即发 WAIT 并尝试拾取，否则建立走近预约；有观战拦截和自动攻击清理。
• extension/src/net/m2_client.cpp / classic_session.cpp
  • pickup_item 只检查 is_in_game、正 VID 和 u32 范围，再发送 CG_ITEM_PICKUP；没有参考端的 observer、item proto、owner/party、anti-flag 或 action gate。
  • ground_item_added/ground_item_removed/item_picked_up 信号存在，但未证明 GC_ITEM_GROUND_DEL 后 inventory item set/update 的严格反馈顺序。

Branch matrix

场景	40250	当前端	结论
掉落创建	ItemManager 验证 vnum，按 item proto 的 drop model、地形/法线、drop effect、声音和动画创建	parser/store 建立记录；UI 通用 bag/BoxMesh，无实际 item drop model、effect、sound、drop animation	GAP
坐标/地形	全局坐标转换后按 Background height/normal 设置模型位置	MapCoord 转换并 sample_height + 0.1，没有法线、模型包围盒和掉落动画落点	PARTIAL
所有权更新	只更新已存在 VID；owner 进入独立 TextTail owner 实例	mut_ground_owner 更新并重新发 ground added；UI 重建/更新 owner tag	MAPPED + tests
名称与颜色	名称取 CItemData::GetName，颜色/尾标来自 item data 和 TextTail	名称优先 proto/item_list；grade/color 有适配，但 _process 近距离颜色会覆盖原品阶色	PARTIAL
名条点击	实际模型 Intersect，再 TextTail Pick	64px 投影点近邻，可能选中不可见/非相交对象或错误标签	PARTIAL
近距离拾取	距离约 20 像素内发送 WAIT+pickup；远距离建立 MODE_CLICK_ITEM 走近	pick_ground_item 有走近预约和 WAIT；GroundItems 又有 3m/5m 阈值，两个距离层未统一证明	PARTIAL
最近拾取/按键	GetCloseItem/预留动作按参考距离和对象选择	最近优先、3m/5m 和 500ms 已有本地测试	MAPPED + tests
所有权拒绝	owner 不同且非 party/anti-flag 允许时本地拒绝并回调	只比较 owner 字符串与本地名字；没有 ItemManager anti-flag 和 party member 分支	PARTIAL
观战/行动门	IsObserverMode 和主角行动状态阻止拾取	NetPlay 有 observer；native pickup_item 未有统一行动门	PARTIAL
拾取协议	SendItemPickUpPacket 写包并 SendSequence	ClassicSession 构造 VID 包，但没有序列/副作用等价保证	PARTIAL
拾取成功/失败清理	server GC ground del 删除模型和名条；后续 item get/set/update 刷新背包	ground del 删除 Node，item event/物品信号存在；失败、超时、重复回包和预约清理缺少包级测试	PARTIAL
换图/断线	DeleteAllItems 和阶段清理释放全部 ground instance/text tail	clear_for_map_change queue_free；延迟释放/generation/断线顺序未完全证明	PARTIAL

Implementation-equivalence matrix

项目	状态	证据/限制
Preconditions	PARTIAL	stage/VID、距离、owner 名和 observer 有部分检查；ItemManager vnum/anti-flag/party/action gate 缺失
Branch structure	PARTIAL	add/owner/del、最近拾取、走近预约和移动端入口存在；实际模型拾取、权限分支和 drop animation 分支不等价
Algorithms/formulas	PARTIAL	坐标转换、距离、500ms、尾标布局已覆盖；模型包围盒/法线/近似拾取和颜色更新不同
State transition order	PARTIAL	reference 是 add→model/text tail→ownership→pickup→server del→inventory feedback；当前 signal→Node 与延迟 queue_free/双距离层顺序未端到端证明
Constants/units	PARTIAL	3m/5m/500ms 有测试；参考 20 像素、真实 item model 尺寸和服务端 cm/m 换算还需统一 fixture
Timing/event sources	PARTIAL	当前依赖 Godot _process、signals、预约；参考由网络收包、输入状态机、Item/Actor/TextTail 事件驱动
Resource/data sources	GAP	当前 ground model 使用通用 item bag/BoxMesh，没有使用 CItemData::GetDropModelThing、drop effect、drop sound、法线等资源链
Protocol side effects	PARTIAL	add/del/ownership/pickup packet 基础结构已解析；SendSequence、OnCannotPickItem 全分支和拾取后回包顺序未闭合
Interruption/failure/cleanup	PARTIAL	map change 清理有实现；server 拒绝、重复 ownership、延迟删除、断线和旧 VID generation 尚未完整覆盖

Regression evidence

• project/test_ground_pickup_parity.gd：拾取距离、骑马距离、最近优先、500ms、owner 名拦截、稀有光柱和基础名条通过。
• project/mob_death_drop_test.gd：掉落坐标/地形高度、Yang 名称、拾取调用和死亡清理通过。
• project/p2b_test.gd：掉落节点、proto 名称、多条名条去重、owner 独立名条和颜色通过，但退出仍有 2 个 ObjectDB 泄漏。
• project/text_tail_arrange_test.gd：尾标 AABB 和 owner 排布通过。
• extension/tests/net_entity_test.cpp、extension/tests/net_classic_session_test.cpp：ground add/del/owner 与经典物品包基础布局通过。
• 未覆盖：未知 vnum、真实 drop model/effect/sound、模型相交拾取、party + anti-flag 权限矩阵、observer/native action gate、CG_ITEM_PICKUP 后 GC_DEL→ITEM_GET/ITEM_SET 顺序、失败/重复/断线/换图竞态。

Deep audit round 2026-09-20

Fresh regression results

• godot --headless --path project --script test_ground_pickup_parity.gd：退出码 0；距离、骑马距离、最近优先、500ms、owner 拦截和基础名条通过。
• godot --headless --path project --script mob_death_drop_test.gd：退出码 0；死亡脱离、地面坐标/高度、Yang 命名和拾取调用通过。
• godot --headless --path project --script p2b_test.gd：退出码 0；地面掉落、名称、名条去重、owner 名条和颜色通过，但退出仍有 2 个 ObjectDB 实例泄漏。
• godot --headless --path project --script text_tail_arrange_test.gd：退出码 0；尾标 AABB 与 owner 排布通过。
• godot --headless --path project --script test_drop_and_cursor_parity.gd：退出码 0；MapCoord heading、cursor 注册、占位模型创建和点选通过。
• ./build/extension/net_entity_test 与 ./build/extension/net_classic_session_test：均退出码 0；只证明 ground add/del/owner 和 pickup 包的基础 native 处理。

Static parity findings

• 40250 CPythonItem::CreateItem 先用 ItemManager 校验 vnum，再加载 GetDropModelThing，创建 drop effect、drop sound、drop animation，并按地形法线调整实例；当前 parser/store 接受未知 vnum，GroundItems 使用通用 item_bag.gr2 或 BoxMesh，未接 item-specific model/effect/sound/animation。
• 40250 的 SetOwnership 只更新已存在 VID，DeleteItem 同时回收 ground instance 与 TextTail；当前 owner 更新通过 ground_item_added 信号重建/更新 Godot 节点，仍没有未知 vnum/未知 VID 的严格资源语义和 generation 保护。
• 40250 鼠标拾取优先测试真实掉落模型相交，再回退到 TextTail；当前 pick_at 只比较模型/名条/owner 标签的屏幕投影点距离 64px，可能选中不可见或非实际相交对象。
• 40250 SendClickItemPacket 有 observer、owner、party/anti-flag 和 action gate；当前 GroundItems 只比较 owner 字符串，M2Client::pickup_item 只检查游戏阶段、VID 和整数范围，缺少 ItemManager anti-flag、party 分支、native action gate 与 SendSequence 等价语义。
• 当前 NetPlay 的 20m 走近/等待路径与 GroundItems 的 3m/5m 拾取路径同时存在；它们都能发 CG_ITEM_PICKUP，但距离、预约清理、拒绝和重复/延迟回包尚未由同一状态机统一证明。
• 现有 ground_item_removed 和 item_picked_up 信号存在，但没有包级 fixture 证明 CG_ITEM_PICKUP → GC_ITEM_GROUND_DEL → GC_ITEM_GET/SET/UPDATE 的成功、失败、重复、断线和换图时序。

Round conclusion

本轮仍为 PARTIAL：基础 ground add/del/owner/pickup 协议和局部 UI 回归通过，但真实掉落资源链、模型相交点选、权限矩阵、native action gate 与拾取后的权威回包链仍未与 40250 统一；本轮未修改实现代码。

Status

PARTIAL。当前端已具备掉落状态、坐标、owner 名条、最近拾取和基础协议骨架，但通用占位模型替代了 40250 的 item proto drop model/effect/sound/animation，拾取权限和模型点选分支也不完整；现有本地回归不能标记为完整 1:1，本轮未修改实现代码。