mtgodot-poc/audit/contracts/network.reconnect-warp.md

network.reconnect_warp

Scope

核对游戏中 GC_WARP 换图、断线重连、保留角色槽位/direct-enter、旧 socket/实体/特效清理和重试策略。换图和断线重连虽然都要重新建立 TCP，但必须分别对照 40250 的调用链，不能只因为最终进入同一张地图就判定等价。

Reference call chain

• UserInterface/PythonNetworkStreamPhaseGame.cpp::GamePhase
• UserInterface/PythonNetworkStreamPhaseGame.cpp::RecvWarpPacket
• UserInterface/PythonNetworkStream.cpp::ConnectGameServer
• UserInterface/PythonNetworkStream.cpp::SetLoadingPhase
• UserInterface/PythonNetworkStreamPhaseLoading.cpp::SetLoadingPhase
• UserInterface/PythonNetworkStreamPhaseGame.cpp::SetGamePhase
• UserInterface/NetworkActorManager.cpp
• EterLib/NetStream.cpp::Connect
• EterLib/NetStream.cpp::Clear

Current call chain

• extension/src/net/classic/classic_session.cpp::connect_direct_enter
• extension/src/net/classic/classic_session.cpp::connect_warp
• extension/src/net/classic/classic_session.cpp::pump
• extension/src/net/m2_client.cpp::pump_classic
• extension/src/net/m2_client.cpp::warp_to_game_server
• extension/src/net/m2_client.cpp::reconnect
• extension/src/net/entity_store.cpp::reset_for_map_change
• project/game_scene.gd::_on_world_reset
• project/net_play.gd::clear_for_map_change
• project/net_world.gd::clear_for_map_change
• project/app_flow.gd::_on_disconnected, _on_char_list, _enter_character
• project/ui/reconnect_ui.gd::_retry_now

Reference branch matrix

场景	40250 实现	当前端实现	结论
普通选人进入	ConnectGameServer(slot) 在同一个 CPythonNetworkStream 保存 m_dwSelectedCharacterIndex 并设置 DirectEnter，再连接角色地址	ClassicSession::connect_direct_enter 保存 m_selected_slot/m_direct_enter_slot，发送登录 key 后在 SELECT 进入 Loading 并发送 select	MAPPED：已覆盖主要状态和包序，但仍需真实服务端断点证据
GC_WARP	RecvWarpPacket 消费完整 warp；设置当前 selected slot 的 DirectEnter；在同一个 CNetworkStream 上 Connect(lAddr,wPort)；Connect 先清旧 socket/缓冲/加密/sequence	pump_classic 每次只取一个 warp cue，先 EntityStore::reset_for_map_change 和 world_reset，再在同一 ClassicSession 调 connect_warp；ClassicStream::disconnect/connect 清 socket/缓冲/加密/sequence，后续 warp 保留在队列	PARTIAL：单次消费和保留状态方向已对齐，但清理 owner/真实包序仍不同
warp 地址	40250 对 lAddr,wPort 直接 Connect，即使回到当前 channel 也按重连处理	classic warp 同样格式化 addr/port 后连接；Godot/旧 backend 仍有 same_server 分支	PARTIAL：classic 主链接近，双 backend 的 same-server 语义仍未统一
Loading 进入	SetLoadingPhase 设置 Loading process/leave、CPythonPlayer::Clear、删除全部飞行物和全部效果、清空 DirectEnter mode	classic warp 路径在收到 warp 时提前清 EntityStore/Godot actor/fly/effect/UI，再由 SetLoading 等价状态继续；connect_warp 将 DirectEnter 重新设置为 true	PARTIAL：当前在旧连接仍可能处理剩余 queue 前先清理；DirectEnter 清除/重设顺序与参考不同
Game phase 离开	__LeaveGamePhase 清 PVP key、NetworkActorManager、combo、character/item manager；随后 Loading 再清 player/fly/effect	_on_world_reset、net_play.clear_for_map_change、net_world.clear_for_map_change、EntityStore.reset_for_map_change 分散清理	PARTIAL：覆盖面较全，但没有一份可证明顺序与重复调用幂等的单一 owner
warp 后角色槽位	同一 CPythonNetworkStream 保留 m_dwSelectedCharacterIndex 与 DirectEnter；新 Select/Loading 流程不回普通选人	classic connect_warp 和有 selected slot/login key 的 M2Client::warp_to_game_server 均保留同一 ClassicSession；无票据/无槽位时仍有 fallback	PARTIAL：主链已对齐，fallback 和真实服务端包序仍待证
远端断线	CNetworkStream::Clear 清 transport；Python phase/应用层按已有网络状态处理，不自动模拟角色列表 UI 回放	ClassicSession 进入 Failed 并发 disconnected；GameScene 保留；ReconnectUI 每 5 秒最多重试 5 次	PARTIAL：当前增加了 UI 自动重试和角色列表回放，未证明与参考的 phase/owner 行为一致
generic reconnect	40250 没有 M2Client::reconnect 这条新 session + Godot slot 回放调用链；已有网络对象和选中状态是参考依据	有 login key 且已有 selected slot 时，M2Client::reconnect 调用同一 ClassicSession::connect_warp；仅无票据/无槽位时才走新 session fallback	PARTIAL：主 classic 重连方向一致，fallback 和真实服务端包序仍待证
重连失败	由 Connect/phase process 的结果进入已有 network phase/error 路径；只有 PHASE_GAME 后才属于远端游戏断线	classic Failed 按 was_online_lost 转 disconnected，AppFlow 保留 GameScene；PHASE_GAME 前连接失败走 login_failed	PARTIAL：事件分类已修正，但 timeout、重复回调和最终停止条件未与参考建立对应
重试并发	参考没有独立 5 秒 UI timer；连接对象本身负责一次 Connect 和 limitSec	M2Client::reconnect 对 Auth/GameConnect/GameLogin 做幂等 in-flight guard；ReconnectUI 的 5 秒 timer 仍是平台适配	PARTIAL：guard 已有 native 实现，尚缺真实重复点击/旧 socket 竞态证据
超时	Win32 Connect 记录 m_connectLimitTime，OnProcess 检查连接时限并清理	ClassicStream::connect 使用 nonblocking connect，并默认记录 3000ms monotonic deadline；process 超时清理并进入失败状态	MAPPED：连接 deadline 算法已对齐，仍需实际阻塞连接测试

Cleanup order matrix

顺序点	40250	当前端	结论
1	RecvWarpPacket 先读完 warp，再调用 Connect；Connect::Clear 丢弃旧 socket 中 warp 后的尾包	parser 产生 warp cue 后，ClassicStream 在当前帧结束时清空剩余接收缓冲，M2Client 再 drain cue、reset world 并 connect	MAPPED：classic 旧连接尾包不会跨越 GC_WARP 边界
2	Connect::Clear 清 socket、cipher、recv/send buffer、sequence	ClassicStream::disconnect 清 socket、buffer、sequence、cipher、phase	MAPPED
3	进入 Loading 后 CPythonPlayer::Clear、Flying、Effect、DirectEnter initialize	_on_world_reset 清 NetPlay/NetWorld/Ground/UI/audio，EntityStore 清实体/状态/效果/fly/队伍局部状态	PARTIAL：数据集合基本覆盖，owner 和时序不同
4	Game leave 清 NetworkActor/character/item manager	GameScene/NetPlay/NetWorld 节点可能继续存活，靠 reset 方法清状态；节点本身不重建	PARTIAL
5	新 MainCharacter/Loading 数据重新建立 actor/main VID	当前收到新包后由 EntityStore signal/catch-up/scene model 重建	PARTIAL：需真实 warp burst 和重复 warp 测试

Equivalence matrix

项目	状态	证据
Preconditions	PARTIAL	classic connect_warp 检查 selected slot/login key；generic reconnect 增加连接中幂等 guard，但 fallback 仍需真实失败矩阵
Branch structure	PARTIAL	GC_WARP 和有槽位的 generic reconnect 均走保留 session 分支；无槽位/无 ticket 仍走销毁/新建 session
Algorithms/formulas	MAPPED	warp 地址、端口、坐标单位和 IPv4 字节序已有明确映射
State transition order	PARTIAL	40250 是同一 stream 的 Connect→Loading；当前包含 external world_reset、Godot 场景清理和新 session 补偿路径
Constants/units	MAPPED	lAddr/wPort、角色槽位和 server coordinate 转换均已定位
Timing/event sources	PARTIAL	参考由 GC_WARP/phase/Connect limit 驱动；当前另加 ReconnectUI 5 秒 timer 和 Loading enter delay
Resource/data sources	PARTIAL	GC_WARP 和 classic fast reconnect 使用当前 parser session；fallback 仍使用 cfg/login key 并重新取 char list
Protocol side effects	PARTIAL	主 classic 重连保持 login key/direct-enter；fallback 仍可能先回角色列表再选人，包序不同
Interruption/failure/cleanup	PARTIAL	旧 transport 和多数世界状态可清理，但 timeout、重复 reconnect、重复 warp、旧 queue 和 UI retry 终止未闭环

Required parity tests

• 真实 GC_WARP：记录旧 socket close、新 socket endpoint、login key、selected slot、DirectEnter 和 PHASE_SELECT→CG_PLAYER_SELECT→PHASE_LOADING 包序。
• 同服地址与跨服地址分别测试；确认两者都遵循 40250 的 Connect(lAddr,wPort)，且不会遗漏 world reset。
• warp burst 前后验证 EntityStore、NetWorld、NetPlay、GroundItems、Flying/Effect、PVP/duel、shop/exchange/safebox、quickslot/skill/points 的清理和重建顺序。
• 远端断线后验证：旧连接只产生一次 disconnected，重连期间不重复创建 session，不短暂切到 Login/Select，成功后回到原 slot。
• 对 reconnect() 加 in-flight、连接失败、连接超时、5 次上限、手动立即重试、再次断线和停止自动重试矩阵。
• 连续两个 GC_WARP、warp 后立刻断线、旧连接尾包与新连接首包交错等竞态测试。

本轮新增的包级边界回归：GC_WARP + GC_CHARACTER_ADD 同一读缓冲中到达时，旧尾包 不会在 host 调用 connect_warp() 前写入 EntityStore；warp cue 仍按 FIFO 保留给外层 重连 owner。classic session 与 legacy GameClient 都在当前 warp 帧后丢弃旧缓冲； 该测试仍不替代真实旧/新 socket 交错、重复 warp 和 datagram 注销验证。

同时新增真实 loopback 断开回归：TCP 已建立但尚未收到 PHASE_GAME 时 peer close， 不会设置 was_online_lost，从而不会把角色选择/DirectEnter 失败误导向局内重连。

Evidence run

• build/extension/net_classic_session_test 已覆盖 direct-enter 的 slot endpoint、GC_WARP 的目标 endpoint、selected slot/login key 保留和 warp cue。
• build/extension/net_entity_test 额外覆盖多个 warp cue 的 FIFO 取出：第一个重连被消费后，第二个仍保留，不会因 owner return 丢失。
• project/app_flow_lifecycle_test.gd 已覆盖游戏态断线遮罩、角色列表回放和原 slot 选择的 UI 级行为。
• project/gamescene_test.gd、project/p9_test.gd 通过，证明世界重置/地图换图的局部装配和 warp 辅助状态没有断言失败。
• project/p10_test.gd 当前已通过；此前失败的 Loading 遮罩和无 SceneTree timer 问题已在前一轮修复。
• 静态逐行核对确认：classic generic reconnect 现在保留同一 session 的 selected slot/login key/DirectEnter；ClassicStream::connect 已有 3000ms deadline；M2Client::reconnect 对连接中状态做幂等保护。
• project/disconnect_world_reset_test.gd 已验证显式 M2Client.disconnect_from_server() 在 transport teardown 前发出一次 world_reset，重复调用仍按每个离线边界通知一次，避免保留的 GameScene 依赖 session 析构清理旧 presentation state。
• 现有测试仍没有证明真实 M2Client 重复点击、deadline 触发、旧/新 socket 交错和同服/跨服包序，因此合同保持 PARTIAL。

Deep audit round 2026-09-20（历史快照，部分结论由后续修复轮覆盖）

本轮按 40250 的实际调用顺序重新核对了以下不可合并的差异：

1. RecvWarpPacket 在 40250 中读完完整 TPacketGCWarp 后，直接在原 CNetworkStream 上 Connect(lAddr,wPort)；当前 classic 专用分支先在 M2Client::pump_classic 外部发出 world_reset，再调用同一 ClassicSession 的 connect_warp。传输清理方向一致，但清理 owner/时序不是 1:1，仍需真实旧 socket 尾包和新 socket 首包测试。
2. 当时 generic reconnect 与 GC_WARP 不能视为同一实现：reconnect() → warp_to_game_server() 会 disconnect()、销毁 ClassicSession；该差异已由 2026-09-21 修复轮收敛，当前主 classic 分支保留原 session。
3. 40250 的 SetLoadingPhase() 明确执行 CPythonPlayer::Clear()、删除全部 Flying/Effect 并 __DirectEnterMode_Initialize()；当前 _on_world_reset() 将清理分散到 EntityStore、NetPlay、NetWorld、GroundItems、UI 和 scene 状态，随后 connect_warp() 又把 DirectEnter 设回 true。覆盖面存在，但顺序和单一属主未对齐。
4. 40250 的非阻塞 Connect 在 OnProcess() 以 m_connectLimitTime 超时后清理并触发失败；该 deadline 已由 2026-09-21 修复轮加入 ClassicStream，仍需实际阻塞连接测试。
5. 当时 p10_test 失败的 Loading/SceneTree 问题已修复；当前 p10_test、app_flow_lifecycle_test、gamescene_test、p9_test 均通过。

Active UserInterface datagram/stream reconnect review

• PythonNetworkDatagram* 的状态 sender 表和 PythonNetworkStream.h 的 phase/请求 API 共同决定 warp、observer、角色和 UI 请求在何时仍可发送；PythonNetworkStreamPhaseOffline.cpp 明确切离 offline 时不能保留旧 phase 的 packet 状态。
• 本轮静态核对确认当前端虽然有 connect_warp/world reset，但仍需补 datagram sender 注销、offline 旧包丢弃、warp 前后 selected/direct-enter 状态和新旧 socket 尾包隔离的逐分支证据；合同保持 PARTIAL。

Implementation fix round 2026-09-21

按 40250 CNetworkStream::Connect(limitSec=3) 和同一 stream Clear()->Connect() 语义修复 classic 重连：ClassicStream 为非阻塞 TCP 连接记录 3000ms 单调时钟 deadline，超时清理 socket/buffer/cipher/sequence 并进入失败；M2Client::reconnect 在已有 login key 和 selected slot 时不再销毁 ClassicSession，而是清理 world 后调用同一 session 的 connect_warp，保留角色槽位、login key 和 DirectEnter。连接中的重复重试改为幂等返回，不创建第二个 session。

回归：net_classic_session_test、net_classic_stream_test、完整 ctest（23/23）、p10_test、app_flow_lifecycle_test、gamescene_test、p9_test 和 git diff --check 均通过。真实阻塞连接 deadline、重复点击/旧 socket 竞态、同服/跨服 burst 包序及 datagram 注销仍保持 PARTIAL。

Audit/fix round 2026-09-20 — warp queue ownership

继续核对 PythonNetworkStreamPhaseGame.cpp::RecvWarpPacket 的“消费一个完整 warp 后立即替换同一连接”语义与当前 M2Client::pump_classic/pump_game：当前实现原先对 drain_warps() 返回的整个 vector 遍历，但在第一个跨服 warp 后立即 return，导致同一帧已进入队列的后续 warp 被一起清空；这与参考端后续 phase tick 保留后续包不一致。

修复内容：

• EntityStore::take_next_warp() 改为 FIFO 一次取一个 cue，未处理 cue 保留在队列中。
• classic 和 legacy game 两条 M2Client warp 分支都改为每次 pump 只消费一个 warp；跨服重连 return 后，下一次 pump 仍能看到后续 cue。
• 新增 net_entity_test 的双 warp 顺序/队列耗尽断言。

回归：net_entity_test、net_classic_session_test、net_loopback_test、p9_test.gd、gamescene_test.gd、p10_test.gd、app_flow_lifecycle_test.gd 和 git diff --check 均通过；完整 ctest 在前一轮已为 23/23。

仍为 PARTIAL：真实旧/新 socket 交错、同服/跨服 live 包序、连接 deadline 实际超时、重复 reconnect/warp、datagram 注销和清理 owner 的时序仍需继续取证。

Implementation fix round 2026-09-22T08:20Z

复核 40250 SetOffLinePhase/__LeaveGamePhase 后发现，当前显式 M2Client.disconnect_from_server() 只销毁 auth/game/classic session；如果 AppFlow 保留 GameScene 进入断线重连或用户主动离线，场景侧不会收到 world_reset，旧 Actor、飞行、目标、UI 和 BGM 状态只能等待节点销毁。按参考端“先清 phase owner，再清 transport”的顺序，当前实现先对活动 EntityStore 调用 reset_for_map_change()，发出 world_reset，再断开各 transport 并回到 Idle。

修复前新增 disconnect_world_reset_test.gd 稳定复现两项失败；修复后通过，且 app_flow_lifecycle_test.gd、netbridge_test.gd 通过。该修复只闭合显式 disconnect 的清理通知，不代表真实 GC_WARP/重连包序、统一 generation、旧新 socket 竞态和通用 EffectManager 已等价，合同仍保持 PARTIAL。

Status

PARTIAL。