mtgodot-poc/audit/contracts/movement.remote-sync-state.md

movement.remote-sync-state

Scope

比较远端角色 GC_MOVE/状态命令的接收、服务器时钟校正、TCP 状态队列释放、动作前移动、到达后的动作、速度/走跑模式、位置纠偏、死亡/击倒/表情锁、中断和换图清理。

Reference call chain

• UserInterface/PythonNetworkStreamPhaseGameActor.cpp::RecvCharacterMovePacket
  • 解码 bRot * 5、bFunc、bArg、dwTime、目标坐标和 dwDuration。
  • CNetworkActorManager::MoveActor 查找已有 VID，同时更新 SNetworkActorData 的展示目标。
• UserInterface/InstanceBase.cpp::PushTCPState
  • 用 ELTimer_GetServerFrameMSec() - dwCmdTime 更新 70/30 EMA。
  • 以 dwCmdTime + m_nAverageNetworkGap 入队。
• UserInterface/InstanceBase.cpp::StateProcess
  • 服务器帧未到时保留队首。
  • __CanProcessNetworkStatePacket 拒绝死亡、击倒和不可取消技能。
  • __IsEnableTCPProcess 在表情或 TCP 状态禁用期间暂停释放。
  • 按 FUNC_WAIT、FUNC_MOVE、FUNC_COMBO、FUNC_ATTACK、FUNC_MOB_SKILL、FUNC_EMOTION 和 FUNC_SKILL 分支建立 Src/Dst、m_kMovAfterFunc 和动作。
• UserInterface/InstanceBase.cpp::MovementProcess
  • 由 CActorInstance::AccumulationMovement 的动作根运动推进。
  • 到达后按 m_kMovAfterFunc 执行 combo/attack/skill/emotion，远端过冲超过 100 像素时重新取 Src，并把普通移动降为等待。
• UserInterface/PythonNetworkStreamPhaseGameActor.cpp::RecvSyncPositionPacket
  • 每个纠偏元素调用 CNetworkActorManager::SyncActor。
  • CActorInstance::TEMP_Push 做 100 段物理碰撞探测、BlendingPosition 和大位移受击动作。
• UserInterface/PythonNetworkStreamPhaseHandShake.cpp
  • 握手 dwTime + lDelta 与本地毫秒时钟建立服务器帧时基。

Current call chain

• extension/src/net/classic/classic_parser.cpp::HDR_GC_MOVE
• extension/src/net/entity_store.cpp::mut_move
  • 远端 VID 入 std::deque<StateCmd>，用 average_network_gap 做 70/30 EMA。
  • drain_state_queue 按 server_frame_ms、死亡/击倒门释放。
• extension/src/net/entity_store.cpp::apply_state_cmd
  • 已覆盖 WAIT/MOVE/COMBO/ATTACK/MOB_SKILL/FUNC_EMOTION/技能位掩码，并保存 mov_after_func。
• extension/src/net/entity_store.cpp::tick
  • 先释放命令，再以 .msa 提取的 WALK/RUN 根运动速度推进；无资源时按 dwDuration 线性插值。
• extension/src/net/entity_store.cpp::mut_snap_position
  • GC_SYNC_POSITION 直接把当前位置和 Src/Dst 设置为纠偏坐标并停止移动。
• project/net_world.gd::_update_visibility
  • 节点位置直接读取 C++ 实体坐标；按 func、moving、walk_mode、dead 更新远端动作。
• extension/src/net/classic/classic_session.cpp
  • 将 classic 握手推导出的 server_frame_ms() 每帧喂给 EntityStore。
• extension/tests/net_state_queue_test.cpp
  • 覆盖帧门、阈值、技能位、死亡/击倒挂起、顺序、时钟防呆、根运动和 duration fallback。

Audit findings (2026-09-20)

已确认当前端的远端移动不再是收到 GC_MOVE 就直接改坐标，核心队列、70/30 网络延迟 EMA、服务器帧释放、1/50 像素阈值、到达后动作和根运动推进都已有对应实现；因此这一项不能继续保持“未审计的 MAPPED”。

仍有材料差异，状态定为 PARTIAL：

• 40250 的 FUNC_EMOTION 在目标距离大于 100 像素时先走到目标再执行情绪；当前端已补齐 100 像素阈值、到达后的 mov_after_func 和远程表情不启用 skip-collision 的分支。由于 TPacketGCMove 本身不携带 uTargetVID，双人表情目标解析仍无法在网络层 1:1 复刻。
• 40250 __CanProcessNetworkStatePacket 还检查不可取消技能，__IsEnableTCPProcess 还检查 IsActEmotion 和 m_bEnableTCPState；当前已新增 presentation-owned skill_active/skill_can_cancel/acting_emotion/tcp_state_enabled 门，并由远端一次性技能/表情的 motion_bound("wait") 尾事件释放。技能可取消性仍缺少 40250 动作数据的权威来源，未知资源和无模型节点保留回退路径。
• 40250 的远端移动权威推进来自动作 .msa 的 AccumulationMovement；当前有真实 WALK/RUN 根运动读取，但无模型时使用 dwDuration fallback，且坐骑直接 fallback，速度/到达时间不完全一致。
• 40250 FUNC_COMBO/FUNC_SKILL 到达后使用 uArg 选择具体动作；当前队列保存了 mov_after_arg，且 net_world 已把 FUNC_ATTACK 映射为 NAME_NORMAL_ATTACK、把 FUNC_COMBO 的 func_arg 原样传给 play_attack_motion，把 FUNC_SKILL 的循环/移动位传给 play_skill_motion。FUNC_EMOTION 现在也按 uArg 尝试 set_motion_id，动作完成后释放 TCP 门；远端 combo/skill/emotion 资源缺失时仍按视图实现回退，怪物 motlist 的逐段资源覆盖和技能 grade 权威来源仍未完全闭合。
• 40250 TEMP_Push 对 GC_SYNC_POSITION 做 100 段物理碰撞探测、BlendingPosition，并在位移超过 150 像素时触发 DAMAGE_FLYING/STAND_UP；当前端已由 mut_snap_position 记录源点/序号/150cm 与技能判定，NetWorld 执行 100 段 is_blocked 探测、1 秒倒数偏移和击倒动作链。无模型/无地形 world 时仍保留可验证的权威坐标回退，因此资源和真实场景碰撞结果仍为 PARTIAL。
• 40250 对命令队列的未来时间不设置 1000ms 防呆阀；当前 STATE_QUEUE_MAX_WAIT_MS 超过阈值立即释放，是为未完成的真实服务器时基校准保留的有意偏离。
• 换图清理已清除实体和队列，但“远端动作正在播出时收到死亡、击倒、传送和重新 Add”的完整资源/动作事件顺序仍缺端到端证据。

Deep audit round 2026-09-20

本轮重新对照 InstanceBase::StateProcess、TEMP_Push 和 NetworkActorManager::MoveActor/SyncActor 的实际分支，并重跑当前端队列、实体和移动回归：

• 40250 在释放队首命令前同时检查死亡、击倒、不可取消技能、表情和 m_bEnableTCPState；当前队列虽然有死亡/击倒门，且已补 FUNC_EMOTION 的距离/到达分支，但没有不可取消技能、表情活动和 TCP 状态开关的等价状态源，双人表情目标也无法从 TPacketGCMove 还原。
• 40250 的 FUNC_COMBO、FUNC_ATTACK、FUNC_MOB_SKILL 和 FUNC_SKILL 在到达后继续使用命令参数选择动作；当前 mov_after_arg 能保存参数，但远端视图侧没有完整的 arg→动作资源路由，当前回归只验证 func/队列状态，不验证具体 .msa 播放结果。
• GC_SYNC_POSITION 在 40250 进入 TEMP_Push，当前端已补 100 段碰撞探测、BlendingPosition 偏移和大位移击倒动作门；真实模型动作、地图碰撞资源和无模型 fallback 仍不能证明完全一致。
• 本轮 net_state_queue_test、net_entity_test、net_world_vis_test、netplay_test、movement_parity_test 和 net_world_remote_action_test 均退出码 0；这些测试证明队列门、EMA、根运动 fallback、可见性、上行移动和 TEMP_Push 纠偏事件/击倒门没有回归，但没有覆盖真实模型动作资源、表情锁、不可取消技能权威数据、实服乱序/跨图/死亡重建和地图碰撞资源。

本轮没有把已有 PASS 测试误升为等价完成；核心队列链保持可用，但上述状态门、动作参数和纠偏物理仍使合同保持 PARTIAL。

Equivalence matrix

项目	状态	备注
Preconditions	PARTIAL	VID、主角过滤、服务器帧门、死亡/击倒、不可取消技能和表情/TCP 门已有实现；技能可取消性权威来源和双人表情目标未闭合
Branch structure	PARTIAL	WAIT/MOVE/COMBO/ATTACK/MOB_SKILL/EMOTION/SKILL 距离分支已对齐；完整禁止门仍缺失
Algorithms/formulas	PARTIAL	70/30 EMA、1/50 阈值、100 像素过冲、100 点纠偏探测、150cm 击倒阈值和 1 秒 BlendingPosition 已对齐；无模型/无 world fallback 不等价
State transition order	PARTIAL	队列→动作前移动→到达动作→动作尾释放，以及 sync serial→碰撞→缓动→击倒/起身→释放门顺序已对齐；双人表情目标和真实资源尾时序未闭合
Constants/units	PARTIAL	角度、cm、阈值和 70/30 已记录；1000ms 防呆阀与坐骑/fallback 是偏离
Timing/event sources	PARTIAL	classic server frame 已接入；真实握手时基、动作事件与状态动作的端到端联机证据不足
Resource/data sources	PARTIAL	WALK/RUN .msa 根运动、PC combo .msa 模式目录、PC emotion action 和 damage_flying/standup 入口已接入；技能可取消/grade、怪物逐段 combo、emotion 目标、真实击倒资源覆盖仍不完整
Protocol side effects	PARTIAL	GC_MOVE、GC_SYNC_POSITION、CHANGE_SPEED、WALK_MODE 已解析；纠偏动作已桥接，双人情绪目标和服务器时基副作用未等价
Interruption/failure/cleanup	PARTIAL	死亡/击倒挂队、换图清理已有单测；技能/表情/传送/重建完整矩阵未完成

Regression evidence

• extension/tests/net_state_queue_test.cpp：服务器帧释放、WAIT 1.0、攻击/技能 50.0、FUNC_EMOTION 100.0、死亡/击倒挂队、FIFO、时钟防呆、根运动和 duration fallback。
• extension/tests/net_entity_test.cpp：远端移动命令的 near/far 行为、到达后动作和未知 VID 忽略。
• project/netplay_test.gd、project/movement_parity_test.gd：上行状态节流和移动预测不回归。
• project/net_world_remote_action_test.gd：远端 FUNC_ATTACK 使用普通攻击索引 13，FUNC_COMBO 保留 bArg 连击段，并传递武器动作模式与攻速比例。
• extension/tests/net_state_queue_test.cpp：不可取消技能、活动表情、TCP 状态禁用和恢复后的队列释放边界。
• extension/tests/net_entity_test.cpp：GC_SYNC_POSITION 记录源点、单调 serial、150cm 大位移和技能抑制状态。
• project/net_world_remote_action_test.gd：TEMP_Push 大位移动作、击倒网络门、旧位置起始偏移和动作尾释放。

Implementation fix round 2026-09-20

按 40250 InstanceBase::StateProcess 到 RunNormalAttack / RunComboAttack 的动作选择 补齐远端攻击状态的参数桥：普通攻击使用 CRaceMotionData::NAME_NORMAL_ATTACK（13），连击 使用 TPacketGCMove.bArg 原值，二者都从远端视图读取当前武器动作模式，并把 bAttackSpeed / 100 传给动作播放层。此前两种状态都会降级成通用 set_anim_state("attack")，导致远端角色看不到 对应的 combo 段；资源解析失败时仍保留通用状态回退。

回归：godot --headless --path project --script net_world_remote_action_test.gd 通过。 死亡/击倒门、FUNC_EMOTION 目标、技能 grade、坐骑根运动和 TEMP_Push 纠偏物理仍保持 PARTIAL，本轮没有把动作索引测试误当成完整资源/联机等价。

Implementation fix round 2026-09-20 — state gates and emotion action

按 40250 __CanProcessNetworkStatePacket 与 __IsEnableTCPProcess 增加 EntityStore 的 四个 presentation-owned 状态门：不可取消技能阻止后续状态出队，活动表情阻止 TCP 状态， m_bEnableTCPState=false 时只允许当前 FUNC_EMOTION，死亡/击倒门保持原有优先级。NetWorld 在远端技能/表情动作开始时设置门，在 motion_bound("wait") 动作尾清除；节点剔除和换图也会 清除门，避免模型被释放后队列永久冻结。

同时把 FUNC_EMOTION 的 func_arg 接入 40250 动作 ID（单人表情使用 target_race=-1， 双人 GC_MOTION 仍走原有目标 VID 路径），并让出生时已经带有 FUNC_* 的实体在字段刷新后 立即绑定初始动作，而不是等待下一次状态变化。

回归：net_state_queue_test、net_world_remote_action_test、net_world_vis_test、 netplay_test、player_motion_test、test_skill_state_arg_parity 和完整 ctest（23/23） 均通过。技能可取消性的动作数据来源、真实远端模型动作尾时序、双人表情目标和 TEMP_Push 仍保持 PARTIAL。

Status

PARTIAL。远端 TCP 状态队列主链已经有较充分实现和单元测试；FUNC_EMOTION 的距离/到达顺序已补齐，但 40250 的不可取消技能门、双人表情目标、纠偏物理动作、远端动作参数和真实服务器时基仍未完全等价。

Implementation fix round 2026-09-21 — TEMP_Push correction path

按 40250 NetworkActorManager::SyncActor → CInstanceBase::NEW_SyncPixelPosition → CActorInstance::TEMP_Push 补齐 GC_SYNC_POSITION 的表现层纠偏：EntityStore::mut_snap_position 现在保留同步前坐标、单调 correction serial、150cm 大位移判定及 IsUsingSkill 抑制位； M2Client::entity_dict 将这些字段交给 NetWorld。节点收到新 serial 后，NetWorld 按 TEMP_Push 的 100 个采样点调用地图 is_blocked，无碰撞时用 PhysicsPush 的 1 秒 倒数偏移保持旧位置起步并回到权威目标；大位移且非技能时启动 DAMAGE_FLYING -> STAND_UP，并通过 set_entity_knockdown 复刻 IsKnockDown 网络状态门。 动作尾、节点剔除和换图会释放该门；没有可用模型/地形时保留权威坐标回退，不伪造资源动作。

回归：net_entity_test、net_world_remote_action_test、net_world_vis_test、 netplay_test、player_motion_test、movement_parity_test 和完整 ctest（23/23）通过。 真实 IPhysicsWorld 地形数据、动作资源覆盖、技能可取消权威来源、双人表情目标和真实服 乱序/跨图/死亡重建仍保持 PARTIAL。

Implementation fix round 2026-09-21 — unified remote FUNC_MOVE arrival branch

复核 40250 CInstanceBase::MovementProcess 的远端 actor 分支后确认， m_kMovAfterFunc == FUNC_MOVE 穿过 Dst 时没有 PC/NPC/monster 的 ch_type 分叉： FUNC_MOVE 的到达 switch case 继续沿当前根运动推进，只有后续状态命令或超过 100cm 的 overshoot 防呆分支才会改回 WAIT。当前端此前只让 PC 继续，NPC/MOB 在第一次越过 Dst 时提前停止并清除 skip_collision，导致远端怪物的连续 GC_MOVE 表现和 40250 不一致。

现已将 EntityStore::advance_walk_by_motion 的远端到达逻辑统一为参考分支： 死亡/击倒仍立即停止；FUNC_MOVE 保留 moving、mov_after_func 和根运动推进； 普通攻击、连击、技能、表情等到达动作继续走原有 finish_walk。新增 NPC/MOB 回归用例先证明修复前会失败，修复后 net_state_queue_test、net_entity_test、 net_classic_session_test 和 git diff --check 均通过。

本合同仍为 PARTIAL：真实 WALK/RUN 根运动资源、技能可取消/grade 权威数据、双人 表情目标、TEMP_Push 地图碰撞和真实服务器时序尚未达到同一实现证据。