mtgodot-poc/audit/contracts/movement.click-collision.md

movement.click_collision

Scope

审计鼠标点地、点实体、掉落物优先级、预约移动、地形 ATTRIBUTE_BLOCK、Actor 碰撞、滑动/停止和输入门控。

Reference call chain

• CPythonPlayer::NEW_SetMouseState
  • 按绑定分派 MOVE、SMART、CAMERA、AUTO、ATTACK、SKILL。
• __OnPressSmart / __OnClickSmart
  • 优先级为 item -> actor -> ground -> screen；按住和点击分别进入移动/攻击/交互分支。
• __OnPressGround / __OnClickGround
  • 清预约和自动攻击，取消钓鱼，检查 MOVABLE_GROUND_DISTANCE，调用 NEW_MoveToDestPixelPositionDirection；被 gate 拒绝时使用 __ReserveClickGround 延迟重试。
• CInstanceBase::NEW_Goto / NEW_Stop
  • 检查 syncing、moving skill、lock；设置 Src/Dst/rotation/m_isGoing，到达或停止时结束 walking。
• CInstanceBase::CheckAdvancing
  • Actor collision 使用真实 collision sphere；逐个 TestActorCollision 并 AdjustDynamicCollisionMovement，第二个碰撞或调整后仍相交时 BlockMovement。
  • 对移动段和下一位置检查 ATTRIBUTE_BLOCK。

Current call chain

• PlayerController._on_click
  • ground_items.pick_at 优先，其次对 pickables 做射线/AABB 点选，最后做地面射线求交。
• PlayerController._goto / _process
  • 检查 active/frozen/locked/moving_skill 和近距离门；被 gate 拒绝时保存目标并在 0.1 秒后重试。
  • 点地使用 Src/Dst；WASD/移动端输入取消点地目标。
• PlayerController._get_blocking_actor / _actor_blocked
  • 使用固定 ACTOR_BODY_RADIUS_M、距离门和趋近条件；静态 Actor 阻挡，其他 Actor 尝试切线滑移。
• PlayerController._blocked
  • 通过 Metin2World.is_blocked 查询地形/静态阻挡；阻挡时尝试 x/z 分轴推进。
• GameScene._on_ground_clicked
  • 生成 40250 EFFECT_PICK / click.mse 地面点击特效。

Field-level findings

• 40250 的 NEW_SetMouseState 区分 MBS_PRESS 和 MBS_CLICK：Smart 按住会持续执行 __OnPressSmart，可持续预约地面/Actor/物品；松开才执行 __OnClickSmart。当前 PlayerController._unhandled_input 只处理左键按下，未实现同一条鼠标 Smart press/hold 状态机，因此按住鼠标连续移动、按住点 Actor/物品和 screen-direction 分支不能证明与参考一致。
• 40250 的 Smart 优先级是 item -> actor -> ground -> screen，并且 actor/item 在按住与点击时走不同的预约/攻击/拾取逻辑。当前单击优先级已映射，但 actor 分支直接 target_selected，item 通过 signal 进入 NetPlay；没有统一记录 press/click/auto 三种组合的发送包序列。
• 40250 NEW_CanMoveToDestPixelPosition 只拒绝当前坐标相同；当前 _goto 以固定 1m 门提前成功返回，门值来自近似常量，不是从 CPythonPlayer::SetMovableGroundDistance 的运行时状态读取。
• 40250 Actor 碰撞使用当前运动模式选择 body/defending sphere，并在每个真实碰撞球对之间做距离门、趋近判定；当前 _get_blocking_actor 固定 0.55m 半径，且 _actor_blocked 只把部分 meta kind 当作静态阻挡，远端骨骼/坐骑/多个 collision sphere 的分支未复刻。
• 40250 的物体碰撞在 __TestObjectCollision 命中后走 AvoidObject/AdjustCollisionMovement，若仍阻挡则 BlockMovement 清除运动；当前对 terrain/Actor 采用一次 frame 的 direct、切线和 x/z 分轴推进，可能留下 _is_going 或继续发移动状态，需单独验证被阻挡终止时序。
• 当前 _ray_ground 以每 1m 射线采样、最多 80m，再二分地表；40250 GetPickingPointWithRay 先对象 picking，再 terrain/object height，且射线范围由相机 ray 配置，采样边界和桥/台阶优先级不同。

Branch matrix

场景	40250	当前端	结论
点选优先级	item -> actor -> ground；点击和按住路径不同	item -> actor -> ground；左键 click 已接入	MAPPED，按住/自动模式仍需完整 fixture
近距离点地	小于 MOVABLE_GROUND_DISTANCE 直接不动	固定 1m MOVABLE_GROUND_DISTANCE_M	PARTIAL：默认值/运行时设置未完全证明
lock/sync/moving skill	拒绝平移；moving skill 可转向；失败点地预约 0.1s	三门和预约重试已实现	MAPPED + tests
地形阻挡	对 movement segment 分段检查 ATTRIBUTE_BLOCK，下一位置命中则 BlockMovement	is_blocked + direct/分轴推进	PARTIAL：采样步长和 BlockMovement 时序不同
Actor 碰撞	使用每个 MSM 的真实 collision sphere；动态调整；第二次碰撞直接停	固定 body 半径近似，按 static/动态尝试滑移	GAP：碰撞几何和多碰撞分支不 1:1
点地特效	成功 NEW_Goto 后显示 EFFECT_PICK	ground_clicked 连接 click.mse	MAPPED
空白点击停止	无 item/actor/ground 时 __OnClickSmart -> NEW_Stop	_ray_ground 未命中时 _on_click -> stop()	MAPPED + regression
输入中断	失焦/停止/攻击/技能清除预约或按键状态	_notification、stop、NetPlay 入口已接入	PARTIAL：窗口/网络中断组合待测

Equivalence matrix

项目	状态	证据
Preconditions	MAPPED	active、player、camera、world 和三道移动 gate 已定位
Branch structure	PARTIAL	Smart/Auto/Camera/Attack/Skill 绑定和两种鼠标状态尚未全部覆盖
Algorithms/formulas	PARTIAL	转向/距离/到达算法已映射；collision sphere 与 segment sampling 是近似
State transition order	PARTIAL	预约、输入、碰撞、动画和网络状态的交错顺序需真实包/场景 fixture
Constants/units	PARTIAL	1m 近距离门、固定 0.55m body 半径、8m distance gate 未完全由资源证明
Timing/event sources	PARTIAL	参考端 frame collision/update 与当前 Godot _process 同步点不同
Resource/data sources	PARTIAL	参考端 .msm sphere/bone collision，当前移动层没有直接消费全部骨骼碰撞数据
Protocol side effects	MAPPED	ground/actor/item/skill 入口已接入 NetPlay；完整发送包序列仍需 fixture
Interruption/failure/cleanup	PARTIAL	点地被阻挡、实体删除、失焦、死亡、换图中断和连续点击待测

Regression evidence

• project/player_move_test.gd：Src/Dst、三道 gate、预约、Actor 阻挡/死亡/skip collision、坐骑转向、空白点击停止旧目标。
• project/movement_parity_test.gd：转向阻尼、到达精度和切线碰撞入口。
• project/netplay_test.gd：CLICK_ACTOR、CLICK_ITEM、CLICK_POSITION、USE_SKILL 预约分支。
• project/test_click_target_effect_parity.gd：点地、目标光圈和飞行物静态障碍测试。
• 本轮四项回归均退出码通过；其中 click/target/fly 测试仍报告 3 个 ObjectDB 泄漏和 1 个资源退出时仍在使用，说明效果节点的清理虽满足断言，但退出生命周期尚不干净。

Deep audit round 2026-09-20

本轮按 40250 鼠标输入、移动门、碰撞和地面 picking 的真实调用链复核：

1. 40250 NEW_SetMouseState 读取鼠标绑定后，对 Smart 分支在 MBS_PRESS 和 MBS_CLICK 分别调用 __OnPressSmart/__OnClickSmart；按住期间每帧可持续执行 item/actor/ground/screen 分支，并维护 m_isSmtMov。当前 PlayerController::_unhandled_input 只处理 InputEventMouseButton.pressed，没有左键 release、hold tick 或 MBS_PRESS 状态，因此“按住点地持续走”“按住实体持续攻击/交互”“Smart release 停止”不能视为已实现。
2. 参考 __OnClickSmart 在没有拾取对象/地面时明确 NEW_Stop()；当前 _on_click 已在 _ray_ground 未命中时调用 stop()，清除旧的 _is_going、预约目标和按键状态，避免 click miss 后继续移动。player_move_test.gd 已增加回归。
3. 40250 NEW_CanMoveToDestPixelPosition/CheckAdvancing 使用当前 Actor motion 的真实 collision sphere、对象碰撞 AvoidObject/AdjustCollisionMovement，第二次碰撞或调整后仍相交时 BlockMovement；当前只用固定 ACTOR_BODY_RADIUS_M、静态 kind 判断、一次切线再 x/z 分轴推进，没有第二碰撞停止状态，也没有从 MSM 读取每个骨骼碰撞球。
4. 当前 _ray_ground 以每 1m、最多 800m 的高度采样后二分；参考 GetPickingPointWithRay 由 terrain/object picking 和相机 ray 边界决定，桥、台阶和对象 height 的优先级不是同一算法。现有测试只用假 world 高度和静态 obstacle，未覆盖真实 bridge/object/attribute 边界。
5. 四组回归均通过：player_move_test.gd、movement_parity_test.gd、netplay_test.gd、test_click_target_effect_parity.gd；最后一项退出时仍有 3 个 ObjectDB 泄漏和 1 个资源使用警告，说明效果断言通过不等价于退出/中断生命周期已清理。

Active EterLib picking-core review

• EterLib/GrpCollisionObject.cpp 支持 bound box、cube、indexed mesh、mesh triangle、sphere 和 cylinder 的 ray intersection；Ray.h 固定 start/direction/range/end 的单位与边界，lineintersect_utils.cpp 还提供线段/平行线最近点和调整算法。
• 当前端点击/弹道分别使用 Godot ray/AABB/胶囊和简化地面采样；虽然 test_click_target_effect_parity 断言通过，但没有复用参考端同一 mesh-triangle/球柱体/线段最近点优先级，不能标记 picking 一致。
• 本轮完成 GrpCollisionObject/Ray/line intersection 静态核对，点击碰撞合同继续为 PARTIAL。

Status

PARTIAL。当前实现的输入/预约主链已建立，但碰撞几何、逐 Actor 调整和多碰撞停止条件与 40250 仍有结构差异；本轮不做无证据的算法替换。

Audit round 2026-09-21T04:35Z — collision geometry boundary

本轮重新沿 CActorInstance::CheckAdvancing、TestActorCollision、 AvoidObject/BlockMovement、CMapOutdoor::GetPickingPointWithRay 对照 PlayerController::_process、_get_blocking_actor、_blocked 和 _ray_ground：

• 40250 的阻挡判定来自 .msm 每个 Actor 的真实 collision sphere，并且在移动段/下一位置分别检查，动态调整后再次相交会进入 BlockMovement；当前端仍是固定 0.55m body 半径、单次切线和 x/z 分轴近似。
• 40250 的点地射线由 terrain/object picking 和相机 ray range 决定；当前端仍是最多 800m、每 1m 高度采样后二分，桥/台阶/object height 的优先级没有 1:1 数据来源。
• 现有 player_move_test.gd、movement_parity_test.gd、netplay_test.gd、test_click_target_effect_parity.gd 全部通过；最后一项仍有 3 个 ObjectDB 泄漏和 1 个资源退出警告，因此只证明当前 fixture 的行为，不证明真实碰撞资源和退出清理等价。

结论：本轮没有实施替换；合同继续 PARTIAL。下一轮应优先建立真实 .msm sphere/object picking fixture，再决定是否下沉共享碰撞几何，而不是继续调固定半径。