mtgodot-poc/audit/contracts/combat.affect-status.md

combat.affect_status —— 受击、眩晕、击倒、状态旗标和状态图标

状态：PARTIAL

本合同对照 40250 Windows 客户端的两条相关但不能合并的链路：

1. Actor 的 AffectFlagContainer 变化如何驱动附着效果、眩晕/睡眠显示和石头烟雾。
2. 服务端 GC_DAMAGE_INFO、GC_STUN、GC_AFFECT_ADD/REMOVE 和角色更新如何进入实体、动作、状态图标与清理流程。

注意：40250 Windows 客户端不在本地决定普攻中毒率、眩晕率、减速率或持续伤害；这些结果由服务端计算，客户端消费状态包和伤害包。当前端的 combat_status_effect_system.gd 是本地/server-like 模拟器，因此即使其单元测试通过，也不能作为客户端等价实现的证据。

40250 参考调用链

Actor affect flags

• UserInterface/AffectFlagContainer.cpp
  • Clear、CopyInstance、CopyData 按位复制固定字节数据。
  • Set/IsSet 对每个 affect bit 做边界检查。
• UserInterface/InstanceBaseEffect.cpp
  • SetAffectFlagContainer：建筑直接忽略；石头走 __SetStoneSmokeFlagContainer；普通 Actor 走 __SetNormalAffectFlagContainer。
  • 普通 Actor 逐 bit 比较旧/新值，只对变化位调用 __SetAffect、GraphicThingInstance.__OnSetAffect 或 __OnResetAffect，最后复制新容器。
  • __ClearAffects 在删除、重建和重置时销毁附着效果并清空容器；石头按烟雾等级重建烟雾。
  • AFFECT_INVISIBILITY 会清附着特效和文字尾；AFFECT_STUN 调用 SetSleep。
• UserInterface/NetworkActorManager.cpp / InstanceBase.cpp
  • 角色创建和更新顺序包含 SetAffectFlagContainer，随后才刷新速度、攻击速度、阵营、PK 和 state flags。
  • SetStateFlags 仅负责 killer/party 等展示与目标相关状态，不等同于 affect bitset。

受击、眩晕和伤害

• UserInterface/PythonNetworkStreamPhaseGame.cpp
  • RecvDamageInfoPacket 找到 VID 后调用 AddDamageEffect(damage, flag, bSelf, bTarget)；负伤害只记录错误，不由客户端扣血。
  • RecvAffectAddPacket 处理能量状态时间，并调用 BINARY_NEW_AddAffect(type, point, value, duration)。
  • RecvAffectRemovePacket 调用 BINARY_NEW_RemoveAffect(type, point)。
• InstanceBase/ActorInstanceBattle
  • __HitGood、__HitGreate、__HitStone 只负责表现层受击动作、震屏、击倒/起身队列；服务器伤害和状态仍是权威来源。
  • __CanProcessNetworkStatePacket 在死亡、击倒或不能取消的技能动作中拒绝网络状态输入。
• PythonNetworkStreamPhaseGameActor.cpp
  • CharacterAdd2/CharacterUpdate 搬运两个 32-bit affect words 和 state flag；更新进入 Actor manager 后再刷新 Actor 表现。

当前端实现映射

• extension/src/net/classic/classic_parser.cpp、extension/src/net/entity_store.cpp
  • 已解析角色创建/更新的两个 affect words、GC_STUN、GC_AFFECT_ADD/REMOVE 和 GC_DAMAGE_INFO。
  • Entity.affect_flags 使用 64-bit 保存 bitset，Affect/AffectChange 保存本地玩家的状态图标数据。
  • m2_client.cpp 已把 affect change 转为 affect_added/affect_removed 信号。
• project/net_world.gd、project/ui/player_view.gd、project/ui/mob_view.gd
  • 远端节点会收到 set_affect_flags，并有附着特效映射；hit_reaction.gd 实现 damage/knockdown/standup 队列和 shake/InsertDelay 近似。
  • game_scene.gd/hud.gd/quickbar.gd 已消费一般 affect 数据，但图标目前是通用色块，未逐 affect 对照 40250 的 icon/附着资源。
• project/net_play.gd
  • 本地主角消费 damage、stunned、knock_down 门控，并在攻击成功时驱动目标受击表现。
• project/combat_status_effect_system.gd
  • 另有客户端本地中毒、眩晕、减速、灼烧/流血施加、计时和直接改 HP 的模拟链；它不是 40250 Windows 客户端的协议消费链。

分支等价矩阵

参考判据/副作用	当前实现	结论
AffectFlagContainer 按位复制、边界检查和旧/新差分	native 64-bit 字段 + mut_affect_flags；视图用 AFFECT_EFFECT_MAP 遍历	基本等价；未覆盖完整 bit 宽度和所有 effect resource
普通 Actor affect 变化触发设置/重置附着效果	NetWorld._apply_field_updates → set_affect_flags	部分等价；当前按映射表重扫，未证明逐 bit 的旧/新回调和失败清理顺序
石头烟雾按 0/1/2/3 等级销毁并重建	当前通用 affect 映射，没有对应 stone smoke 分支证据	缺失/不等价
建筑忽略 affect flag	当前 _apply_field_updates 依赖节点是否有 setter，没有显式建筑 no-op 规则	未证明等价
AFFECT_INVISIBILITY 清附着效果、文字尾和可见性	当前有 affect effect 映射，但目标选择/文字尾的隐身门控分散在其它脚本	不完整
AFFECT_STUN 驱动睡眠/眩晕表现	当前 mut_stun 仅置 Entity.stunned；本地门控可阻止行动，远端主要靠命中回调	不完整；没有完整远端 SetSleep/清除链
GC_DAMAGE_INFO 只产生 DamageEffect/飘字，不在客户端扣血	net_world._on_damage 产生飘字；基础 damage_effect_test 通过	基本等价；本地主角 _on_damage 额外使用通用 damage/击退锁，flag 细分未完整
GC_AFFECT_ADD/REMOVE → UI 状态图标和能量时间	native signal → game_scene/HUD/quickbar，基础协议测试通过	基本等价；图标资源、重复/乱序/过期 duration 未证明
客户端不本地结算 poison/stun/slow/fire 结果	combat_status_effect_system.gd 本地 roll、tick 并直接改 HP	明确不等价；数据权威错误
死亡、击倒、技能不可取消时拒收网络状态	EntityStore::can_process_network_state 和 NetPlay._can_process_network_state 有 dead/knockdown/stun 门	部分等价；native 门不含 stunned，远端动作消费也未统一
受击动作 HitGood/Great/Stone 的资源选择和队列	hit_reaction.gd/PlayerView/MobView 有近似队列	部分等价；hit_view_test.gd 当前有 1 项失败，前向 damage 仍停留在 combo 资源

已执行测试

• project/test_combat_status_effect_parity.gd：24/24 PASS；只能证明当前本地模拟器自身行为，不证明客户端权威模型正确。
• project/damage_effect_test.gd：PASS；覆盖伤害飘字分类和显示门。
• project/combat_fx_test.gd：PASS；覆盖命中、连击、shake、affect 和死亡主链。
• project/test_mob_combat_reaction_parity.gd：17/17 PASS；覆盖怪物受击和击倒 helper。
• project/test_combat_death_pickup_entry_parity.gd：PASS；覆盖死亡/动作锁相关入口。
• build/extension/net_entity_test：PASS；覆盖 native stun/affect add/remove 等状态存储。
• build/extension/net_classic_session_test：PASS；覆盖 classic session 状态包入口。
• project/hit_view_test.gd：FAIL，1 项：fScalar < 0 的前向受击期望 damage/damage_1.msa，实际仍为 onehand_sword/combo_01.msa。

已确认差异和未验证项

1. combat_status_effect_system.gd 把服务端战斗状态结算复制到客户端，包含随机 roll、持续时间、毒/火跳伤害和直接改 HP；必须与协议消费链分离，否则会造成双重结算或离线假状态。
2. native GC_STUN 目前只置 stunned=true，没有专门的解除包/清除路径；当前依赖后续实体更新/重建恢复，未证明与 40250 Actor affect 清除顺序一致。
3. NetWorld._apply_field_updates 没有 40250 __SetNormalAffectFlagContainer 的逐 bit 差分回调，也没有 stone smoke/building/no-op 的显式分支。
4. 远端 stunned/knock_down 没有统一进入 SetSleep、击倒动作和网络状态拒收链；本地 NetPlay 与远端 NetWorld 的门控职责不一致。
5. hit_view_test.gd 的失败说明受击动作资源/动作锁时序仍有真实差异，当前不能将受击合同标记为通过。
6. 需要补齐 affect bit→effect/icon 资源索引、重复/乱序 add/remove、duration 过期、死亡/切图/重连清理、隐身文字尾、stone smoke 和建筑 no-op 测试。

下一轮验证入口

• 先移除或隔离本地状态结算器的权威写入，只保留服务端 affect/damage 包驱动的视图与 UI。
• 为每个 affect bit 建立 40250 资源、附着骨骼、开关、清理和石头烟雾矩阵。
• 增加 GC_AFFECT_ADD → duration → GC_AFFECT_REMOVE、重复/乱序/重连/换图的 native→HUD 端到端测试。
• 增加远端 Actor 的 stunned/knockdown/skill-cancel 状态机测试，并修复 hit_view_test.gd 的前向 damage 资源选择后再提升合同状态。