mtgodot-poc/audit/contracts/combat.flying-projectile.md

# combat.flying_projectile —— 飞行物、目标、地形碰撞、命中和回收

状态：`PARTIAL`

本合同覆盖 40250 客户端的两条飞行物来源：

- 普攻/弓箭的 `.msa FLY` 事件 → `OnSetFlyTarget` / `OnShoot` → `CG_FLY_TARGETING`、`CG_SHOOT`。
- 服务端 `GC_CREATE_FLY`、`GC_FLY_TARGETING`、`GC_ADD_FLY_TARGETING` → 客户端 `CFlyingManager` 弹道、目标追踪、背景/Actor 碰撞和爆炸回调。

## 40250 参考调用链

### 客户端发射事件

- `GameLib/ActorInstanceFly.cpp` `OnGetFlyTargetPosition`
  - 从目标 Actor 的飞行目标包围球读取位置。
- `UserInterface/PythonPlayerEventHandler.cpp:232` `CNormalBowAttack_FlyEventHandler_AutoClear::OnSetFlyTarget`
  - 读取主角位置/朝向并发送 `SendFlyTargetingPacket(target VID, target position)`。
- `UserInterface/PythonPlayerEventHandler.cpp:241` `OnShoot`
  - 在动作资源的 FLY 事件帧发送 `SendShootPacket(skill)`。
- `UserInterface/PythonPlayerEventHandler.cpp:259` `OnExplodingAtAnotherTarget`
  - 若启用对应处理，向另一 Actor 发送攻击包并调用目标 `OnShootDamage`；当前参考实现该函数主体被直接 `return`，必须保留这个可达性事实，不能凭注释臆造伤害链。

### 飞行数据和弹道

- `GameLib/FlyingData.cpp` `CFlyingData::LoadScriptFile`
  - `.fly` 资源读取 initial velocity、cone/roll、angular velocity、gravity、range、acceleration、homing、bomb effect、hit-on-background、hit-on-another-monster、pierce count、bomb range 和 attach data。
- `GameLib/FlyingInstance.cpp` `CFlyingInstance::Create`
  - 绑定 `CFlyTarget`、`canAttack`、起点、旋转方向、局部初速/加速度和剩余射程。
- `GameLib/FlyingInstance.cpp:347` `CFlyingInstance::Update`
  - homing → 速度/加速度推进 → 维护 attach effect → 超程 → 目标线段命中 → 穿透/爆炸 → 其它 Actor 动态碰撞 → 地形高度/静态背景碰撞。
- `GameLib/FlyTarget.cpp` `CFlyTarget`
  - 目标可以是对象或坐标；对象被删除时转为最后目标位置，避免悬空指针。
- `GameLib/FlyingObjectManager.cpp`
  - Update 返回 false 后从实例表删除；地图/场景销毁时删除全部实例和挂接特效。

### 网络收包

- `UserInterface/PythonNetworkStreamPhaseGame.cpp:2559` `RecvAddFlyTargetingPacket`
  - 找不到射手时只记录并返回；存在目标 VID 时绑定对象，否则通过地图高度构造坐标目标。
- `:2599` `RecvFlyTargetingPacket`
  - 与上面相同，但替换当前目标而不是追加。
- `:2697` `RecvCreateFlyPacket`
  - 起点或终点实例不存在时不创建；否则 `CreateIndexedFly(type, start, end)`。
- `:2637-2695` `SendShootPacket`、`SendAddFlyTargetingPacket`、`SendFlyTargetingPacket`
  - 每个发送操作后都发送 sequence。

## 当前端实现映射

- `project/fly_object.gd`
  - `FlyData`、`FlyInstance`、`FlyManager` 对应 `CFlyingData/CFlyingInstance/CFlyingManager`。
  - 已实现 `.msf` 的 `CFlyingData::LoadScriptFile` 字段解析和 cm→m 单位适配，并保留目标对象/坐标、homing、线段到点命中、超程、地形高度/静态 Physics layer 2 碰撞、穿透计数、爆点和地图清理。
- `project/net_world.gd`
  - `_on_fly` 按 `playersettingmodule.py` 的索引表加载 `.msf` 并消费服务端飞行 cue；`_on_fly_targeting` 暂存 shooter 的目标队列；`clear_for_map_change` 清理飞行物和爆点。
  - 服务端索引经验球通过 `FLY_EXP` 加载 `ga_piece_yellow_small2.msf`；离线 `spawn_exp_fly` 仍是独立的多球测试/表现辅助入口。
- `project/net_play.gd`
  - `_emit_swing` 在弓箭起手时调用 `_send_fly_target`，并由 `bow_shot_fired` 进入发射链。
  - `send_fly_targeting` 处理扇形/圆形目标追加。
- `project/world_shot.gd`、`project/fx/skill_fx.gd`
  - 提供世界投射物/技能表现层。
- `extension/src/net/*`
  - 当前 classic parser/store/client 提供飞行事件和目标坐标的网络入口。

## 分支等价矩阵

| 参考判据/副作用 | 当前实现 | 结论 |
|---|---|---|
| `.fly`/`.msf` 资源读取飞行参数和 attach data | `FlyData.load_msf` 解析参考字段、相对/绝对资源路径和 cm→m 单位；`FlyInstance` 已创建 AttachFile/FlyTrace，`NetWorld._indexed_fly_data` 绑定 40250 注册资源；远端 Actor 的 MSA FLY 也进入同一实例入口 | 部分等价；精确远端 skill 上下文、相机尾迹几何和所有资源矩阵仍缺 |
| 起点/终点实例缺失则不创建飞行物 | `_on_fly` 用 `Vector3.INF`/节点存在门控后返回 | 基本等价；完整 packet handler/sequence 仍未 live 验证 |
| 对象目标随 Actor 移动，目标删除后转位置 | `FlyTargetAnchor.fly_target_position` 使用包围球中心；`notify_target_despawn` 在渐隐/替换前立即转为位置目标 | 基本等价；迟到目标包和 VID 重用的包级矩阵仍未完成 |
| homing、速度/加速度、射程和线段到点命中 | `FlyInstance._adjust_homing`/`update` | 基本等价；坐标轴和单位转换需真实资源验证 |
| `m_fCollisionSphereRadius = max(move distance*2, configured radius)` | `FlyInstance.update` 在同一顺序计算膨胀半径，并通过 `actor_provider` 查询当前可见 Actor | 基本等价；Actor 碰撞球半径的真实模型标定仍未完全证明 |
| `hitonanothermonster` + 已命中对象集合 + `OnExplodingAtAnotherTarget` | `FlyInstance._find_another_actor`、`hitted_objects`、`at_another` 回调和穿透分支已接入；射手被排除 | 部分等价；EffectManager/真实动态 culling 仍未完全复现 |
| hit-on-background 先地形高度后静态背景碰撞 | 当前动态 Actor 分支后仍是 `sample_height` 后 Physics layer 2 ray | 基本等价的 Godot 平台适配；真实 culling 半径/查询范围未证明相同 |
| pierce count：命中后 bomb，减计数，耗尽才 explode | `FlyInstance.pierce`/`target_hitted` 与动态 `at_another` 分支均执行相同的 bomb/继续/爆炸顺序 | 基本等价；多种真实资源与同帧背景竞争仍未完整验证 |
| `OnShootDamage` 仅在 `canAttack` 对象目标命中时触发 | 当前 `shoot_damage` signal 有入口，但服务端 GC 弹道使用 `can_attack=false` | 基本等价；真实本地弓箭事件到服务端回包链未完整证明 |
| 超程 `OnExplodingOutOfRange`、背景/目标回调和删除 | `exploded` signal + manager 删除；BombEffect 优先走 EffectRegistry，资源不可用才 fallback flash | 基本等价；EffectManager 真实生命周期和全部回调包序仍未完整验证 |
| Add/Set FlyTargeting 追加与替换 | 入站通过 shooter meta `fly_target_queue`、`append`；出站普通弓箭走独立 `fly_targeting`/`CG_FLY_TARGETING`，附加目标走 `add_fly_targeting`/`CG_ADD_FLY_TARGETING` | 基本等价；shooter 不可见/本地主角/VID 重用分支待验证 |
| `GC_CREATE_FLY` indexed normal/firecracker/auto-fire 类型 | `INDEXED_FLY_TYPES` 与 40250 注册表一致；`_on_fly` 已分别复刻普通、随机位置烟花和 +100cm AUTO_FIRE 起点，AttachFile 优先作为实际视觉 | 基本等价；资源缺失 fallback、真实模型半径和包序仍未完全证明 |
| 每个 outbound 飞行目标/射击包后发送 sequence | ClassicSession 字节级验证 `CG_FLY_TARGETING`、`CG_ADD_FLY_TARGETING`、`CG_SHOOT` 均追加正确 sequence；完整动作队列与真实 socket 包序仍未 live 验证 | 部分等价 |

## 已执行测试

- `project/fly_test.gd`：PASS；覆盖 `CFlyingManager/CFlyingInstance` 基础弹道、命中、超程和 `__CanShot`。
- `project/fly_reset_test.gd`：PASS；覆盖地图切换时飞行物和爆点清理。
- `project/test_exp_fly_parity.gd`：6/6 PASS；覆盖经验光球飞行和吸收。
- `project/fly_target_bounds_test.gd`：0 failures；覆盖模型目标包围球中心和 CPU/GPU 一致性，但有 ObjectDB leak warning。
- `project/test_click_target_effect_parity.gd`：0 failures；覆盖静态障碍碰撞和目标效果清理，但有 ObjectDB/RID 清理警告。
- `project/combat_fx_test.gd`：PASS；覆盖命中/连击/效果主链。
- `project/fly_data_msf_test.gd`：PASS；覆盖 `geompung.msf`、经验球和 `arrow_01.msf` 的字段、相对资源路径、attach data、枚举及 cm→m 转换。
- `project/indexed_fly_type_test.gd`：PASS；覆盖 40250 NORMAL/FIRE_CRACKER/AUTO_FIRE 的索引类型、起点高度、对象/位置目标和随机距离范围。
- `project/fly_dynamic_collision_test.gd`：PASS；覆盖动态 Actor 双目标穿透和同一 Actor 的 `HittedObjectSet` 去重。
- `project/fly_target_lifecycle_test.gd`：PASS；覆盖包围球目标中心和 Actor 销毁时立即转位置目标。
- `project/fly_attachment_effect_test.gd`：PASS；覆盖绝对 AttachFile 解析、EffectRegistry 实例、FlyTrace 轨迹、BombEffect 和资源视觉不重复绘制。
- `project/remote_motion_fly_test.gd`：PASS；覆盖远端 Actor `GC_FLY_TARGETING` 队列、MSA FLY 事件、owner VID/skill 和资源飞行实例创建。

## Implementation fix round 2026-09-21T06:34Z

按 `FlyingObjectManager::CreateIndexedFly` 接入 `INDEXED_FLY_TYPES`：NORMAL 保持射手根位置和对象目标，FIRE_CRACKER 使用 +200cm 起点、-90° 基准方向与 20..50m/10..25m 随机位置目标，AUTO_FIRE 使用 +100cm 起点并保留对象目标。新增 `indexed_fly_type_test.gd`，修复前 FIRE_CRACKER/AUTO_FIRE 断言失败，修复后通过。

按 `FlyingInstance::Update` 接入动态 Actor 碰撞：每帧使用 `max(move_distance * 2, collision_sphere_radius)`，排除 owner，按节点实例身份维护 `hitted_objects`，触发 `at_another` 并复刻 pierce/bomb/explode 分支。按 `FlyTarget`/`ActorInstanceFly` 接入 `FlyTargetAnchor` 包围球中心，并在 NetWorld 的 despawn、同 VID 替换前调用 `notify_target_despawn`，保证渐隐节点不再继续移动飞行目标。新增 `fly_dynamic_collision_test.gd` 和 `fly_target_lifecycle_test.gd`，均通过。

修复后 `fly_test`、`fly_reset_test`、`fly_data_msf_test`、`motion_event_fly_test`、`test_exp_fly_parity`、`netbridge_test`、`combat_fx_test`、`netplay_test` 和静态建筑碰撞回归通过。真实 `EffectManager`/`FlyTrace` 资源表现、真实模型动态半径、包序和不可见 Actor 生命周期仍使合同保持 `PARTIAL`。

## Implementation fix round 2026-09-22T07:55Z

复核 `CFlyingManager::DeleteAllInstances` 的销毁边界时发现，当前 `FlyInstance.handler` 闭包捕获实例自身，而实例又持有该 Callable；地图清理只清数组会留下 `RefCounted` 环。现新增 `_release_instance()`，在地图清理和自然过期两个删除路径中同步解除 handler、target、world、data 引用，再移除实例；地图清理的 visual/flash 节点也按 Loading 的同步删除边界直接释放。

修复前 `fly_reset_test.gd` 虽 PASS 但退出报告 5 个 ObjectDB 泄漏；修复后退出无 ObjectDB 泄漏。`test_exp_fly_parity.gd` 行为断言仍为 6/6 PASS，但其旧式单函数 fixture 仍报告 3 个 ObjectDB/不在 SceneTree 的路径警告，属于测试 harness 生命周期待清理，不将其伪装成完全干净证据。动作事件 FLY 的 owner/skill/包序、真实模型半径、远端不可见 Actor 和 EffectManager 全量生命周期仍保持 `PARTIAL`。

## Implementation fix round 2026-09-21T06:46Z

继续按 40250 `FlyingData::LoadScriptFile`、`FlyTrace` 和 `FlyingObjectManager` 的资源链修复飞行特效：`TailLength` 按参考保持秒单位，`TailSize` 只做 cm→m 转换；`AttachData` 现在会实例化 `AttachFile`，并维护 line/multi-line/sine/exp 四类尾迹历史和按时间衰减的轨迹几何。`BombEffect` 优先通过 `EffectRegistry` 资源实例化，只有资源不存在时才使用兼容性 flash，避免资源特效和通用球体重复绘制。

同时修复 `EffectRegistry` 对 `.msf` 内绝对资源路径的解析：存在的绝对路径不再被重复拼接到资源根目录。新增 `fly_attachment_effect_test.gd` 覆盖 AttachFile 实例、FlyTrace 历史、BombEffect、资源视觉去重和地图清理；`fly_data_msf_test.gd` 增加 `TailLength` 单位回归。资源特效链已进入正式运行路径，但精确相机朝向、所有远端 FLY/SHOOT owner-skill 组合、EffectManager 的每种资源生命周期和真实包序仍未完成，因此合同继续保持 `PARTIAL`。

## Implementation fix round 2026-09-21T06:54Z

按 40250 `CActorInstance::ProcessMotionEventFly` 补齐远端 Actor 的动作事件飞行链：`NetWorld` 现在从 `GC_FLY_TARGETING/GC_ADD_FLY_TARGETING` 保存的当前目标队列取目标，在远端 MSA 的 type 6 事件帧创建同一个 `.msf` 飞行实例，使用 Actor 动作位置/挂骨骼位置作为起点，并传递 owner VID 与 skill index；对象目标、坐标目标和目标队列消费均保持分支语义。`GC_CREATE_FLY` 的服务端索引飞行仍与动作事件路径分离。

新增 `remote_motion_fly_test.gd` 覆盖远端目标队列、资源实例、owner/skill 和单次消费，修复后的测试无 ObjectDB 泄漏。远端动作事件没有原生 `m_kCurMotNode.uSkill` 的完整网络字段时仍只能使用事件字段或当前动作参数回退，精确 skill 上下文、包序、不可见 Actor 和全量资源矩阵继续保持 `PARTIAL`。

## Implementation fix round 2026-09-21T06:59Z

按 40250 `CNormalBowAttack_FlyEventHandler_AutoClear::OnSetFlyTarget` 与 `CPythonNetworkStream::SendFlyTargetingPacket` 修正出站主目标链：新增 `M2Client.fly_targeting`、`ClassicSession::send_fly_targeting` 和 Godot 绑定，普通弓箭不再误发 `CG_ADD_FLY_TARGETING`；扇形/圆形技能的附加目标继续使用独立的 `add_fly_targeting`。ClassicSession 回归逐字节验证两种 header 和 sequence，战斗回归验证弓起手优先调用主目标 API。

该修复只闭合了主/附加目标包类型和局部 sequence 证据；不可见 shooter、VID 重用、真实 socket 中乱序/重连和完整 MSA→CG_SHOOT 时序仍保持 `PARTIAL`。

## Implementation fix round 2026-09-21T07:03Z

继续核对 `FlyingInstance::UpdateAttachInstance` 后修正尾迹几何：40250 的
`MULTI_LINE`、`SINE`、`EXP` 分支使用 `(-sin(roll) * offset, 0,
-cos(roll) * offset)`，当前端原先把局部 Z 号写反，导致资源飞行物的尾迹/AttachFile
偏到相反一侧；现已改为同号。`LINE` 的 effect 朝向按参考只使用基础飞行旋转，其他三种
偏移类型才叠加 `m_qAttachRotation`。新增直接检查 `MULTI_LINE` 局部 Z 偏移的回归断言。

`fly_attachment_effect_test`、`fly_data_msf_test`、`fly_test`、`fly_dynamic_collision_test`、
`fly_target_lifecycle_test`、`fly_reset_test` 均通过。`coneangle/rollangle` 初始旋转、
相机相关 FlyTrace 顶点生成、完整资源矩阵和远端原生 skill 上下文仍未闭合，合同保持 `PARTIAL`。

### Active GameLib flying-core review

- `GameLib/FlyingData.h` 定义 `.fly` 的初速、cone/roll、角速度、重力、加速度、homing、range、bomb effect、background/another-monster 命中、pierce、collision sphere 和 attach tail；`FlyingInstance.h` 保存速度/旋转/剩余射程、目标、已命中集合和 attach effect 生命周期。
- `FlyingObjectManager.h` 按 index/type 注册飞行资源，创建/更新/渲染/删除实例；`FlyTrace.cpp` 则用动态池记录位置时间 deque，按 tail length 衰减并生成相机相关的飞行尾迹。当前 `fly_object.gd` 已按索引读取 `.msf`，接入动态 Actor 碰撞/已命中集合、AttachFile/FlyTrace、BombEffect 资源清理和远端 MSA FLY 创建；精确相机朝向、模型半径标定、全部资源组合和远端原生 skill 上下文仍缺证据。
- 本轮完成 `FlyTarget`/`FlyingData`/`FlyingInstance`/`FlyingObjectManager`/`FlyTrace` 的活跃源码静态核对；测试通过只证明基础 Godot 弹道，不提升合同状态。

## 已确认差异和未验证项

1. 普通 GC 飞行物已从 40250 索引注册表加载 `.msf` 建立 `FlyData`，本地主角和远端 Actor 的动作事件 type 6 都进入同一实例入口；远端原生 `m_kCurMotNode.uSkill` 上下文、动作/网络包序仍未闭合。
2. `hitonanothermonster` 已接入动态 Actor 碰撞、按节点身份的 `HittedObjectSet` 去重、穿透后继续飞行和另一目标回调；真实客户端的 culling 范围、模型动态半径和背景/Actor 同帧竞争仍未证明一致。
3. 正式目标命中已经使用 `FlyTargetAnchor` 包围球中心，目标销毁也会转为最后坐标；`.fly` 的 bomb range/collision sphere 与真实模型资源组合仍没有逐类标定矩阵。
4. `_on_fly_targeting` 只把目标队列挂在可见 shooter 节点；40250 的 `CPythonCharacterManager` 实例表与当前 `NetWorld` 可见节点表不是同一生命周期，远端暂不可见、主角本地节点、VID 重用和迟到 `GC_CREATE_FLY` 尚未证明一致。
5. `bombeffect` 已优先走 `EffectRegistry`，AttachFile/FlyTrace 也已进入飞行实例生命周期；精确相机尾迹、颜色/材质、所有资源组合和 EffectManager 的逐资源回收仍未证明一致。
6. 已有测试覆盖 `.msf` 字段、索引类型、动态 Actor 双目标穿透/去重、目标删除、AttachFile/FlyTrace/BombEffect、主/附加目标 header+sequence 和地图清理；仍缺 Add/Set 乱序、真实服务端包序、完整资源矩阵和背景/Actor 同帧竞争。

## Audit round 2026-09-21T06:24Z

本轮沿 `FlyingObjectManager::CreateIndexedFly`、`FlyingInstance::Update`、`FlyTarget::NotifyTargetClear` 和 `CActorInstance::OnGetFlyTargetPosition` 做了源码级闭环核对，并验证了当前资源目录包含 40250 注册的 7 个 FIRE_CRACKER `.msf`、1 个 AUTO_FIRE `.msf` 以及普通索引 `.msf`。

- `playersettingmodule.py` 的 16 个索引资源路径已在当前 `INDEXED_FLY_FILES` 中出现，但类型元数据没有进入当前表；`NetWorld._on_fly` 所有索引都统一创建普通对象目标，未复刻 FIRE_CRACKER 的 `+200cm` 起点/随机位置目标和 AUTO_FIRE 的 `+100cm` 起点。
- 40250 每帧按 `max(move_distance * 2, collision_sphere_radius)` 扫描动态 Actor，并用 `HittedObjectSet` 去重；当前已按同一顺序实现 provider 查询、owner 排除、去重和 `at_another` 分支，但 provider 的可见性边界与真实模型半径仍是适配层差异。
- 40250 目标 Actor 销毁时立即 `ClearFlyTargeter()`，飞行物切换为最后目标坐标；当前 `_on_despawn` 先走渐隐/延迟释放，`FlyInstance` 仍持有旧 Node3D，目标删除、同 VID 重建和迟到 `GC_CREATE_FLY` 尚未达到同一时序。
- 40250 对象目标位置来自 `CActorInstance::OnGetFlyTargetPosition` 的包围球中心；当前 `FlyInstance.target_position()` 读取 Node3D 根位置，`fly_target_bounds_test` 的包围球 helper 尚未接入正式飞行命中链。
- 40250 的 `bombeffect`、attach/tail 和 FIRE_CRACKER/AUTO_FIRE 的资源表现由 `EffectManager`/`FlyTrace` 管理；当前只生成通用 SphereMesh/flash，资源路径虽能解析但尚未真正消费。

因此本轮没有提升合同状态；当前结论仍为 `PARTIAL`。资源消费、动态碰撞和目标生命周期已从“缺失”推进到“有运行证据的部分等价”，后续应优先补远端动作事件 FLY、包序/乱序、不可见 Actor 与完整资源生命周期矩阵。

## 下一轮验证入口

- 为动作事件 FLY 增加远端 Actor 的原生 skill 上下文和 `CG_FLY_TARGETING → CG_SHOOT → sequence` 真实状态机/包序测试。
- 增加背景与 Actor 同帧竞争、三 Actor/多种 collision sphere 的真实可见性与半径矩阵。
- 增加 `GC_FLY_TARGETING → GC_ADD_FLY_TARGETING → GC_CREATE_FLY` 乱序、不可见 shooter、目标删除/VID 重用和 map reset 测试。
- 对照每个 `INDEX_FLY_TYPE` 的 AttachFile、BombEffect、尾迹材质、颜色和回收时序，补齐资源矩阵后再决定是否提升合同状态。