mtgodot-poc/audit/contracts/network.character-select.md

network.character_select.create_delete

Scope

对比 40250 角色列表、固定槽位、帝国选择、角色选择、创建、删除、强制改名和 DirectEnter 的完整网络调用链、固定字段、阶段副作用、回调顺序和失败清理。

本轮是静态审计、阶段副作用核对和现有测试复核；角色选择主路径已有多轮实现修复，合同仍为 PARTIAL。

Reference call chain

普通登录到角色列表

1. CPythonNetworkStream::SetLoginPhase() 在 UserInterface/PythonNetworkStreamPhaseLogin.cpp 发送 CG_LOGIN/CG_LOGIN2，随后 ClearLoginInfo() 清除密码。
2. CPythonNetworkStream::LoginPhase() 接收 HEADER_GC_LOGIN_SUCCESS3/4、HEADER_GC_EMPIRE、创建/删除/改名结果。
3. __RecvLoginSuccessPacket3/4() 把数据写入固定的 m_akSimplePlayerInfo[PLAYER_PER_ACCOUNT4] 和对应 guild 数组；3 槽报文只覆盖前 3 个槽，未覆盖的第 4 槽仍是已清零的空槽。
4. RecvPhasePacket() -> SetSelectPhase()；普通路径根据 IsSelectedEmpire() 进入选人或选帝国窗口。
5. SelectPhase() 分派创建、删除、改名和再次登录成功包；UI 回调读取同一份固定槽位数据。

普通选人/创建/删除/改名

• SendSelectEmpirePacket() 写入 CG_EMPIRE，发送成功后立即 SetEmpireID(dwEmpireID)，再 SendSequence()。
• SendSelectCharacterPacket() 写入 CG_PLAYER_SELECT，再 SendSequence()。
• SendCreateCharacterPacket() 写入 slot/name/job/shape/CON/INT/STR/DEX 固定字段，再 SendSequence()。
• SendDestroyCharacterPacket() 用 strncpy(..., PRIVATE_CODE_LENGTH-1) 写入删除码，再 SendSequence()。
• SendChangeNamePacket() 写入 slot/name，再 SendSequence()。
• __RecvPlayerCreateSuccessPacket() 在 < PLAYER_PER_ACCOUNT4 时更新固定槽位并调用 OnCreateSuccess()；越界只记录错误并返回，不产生成功回调。
• __RecvPlayerCreateFailurePacket() 同时通知创建窗口和选人窗口。
• __RecvPlayerDestroySuccessPacket() 清零整个槽位，并独立清零 guild id/name，然后调用 OnDeleteSuccess(index)。
• __RecvPlayerDestroyFailurePacket() 消费空包并调用 OnDeleteFailure()。
• __RecvChangeName() 只在 PID 命中固定槽位时清除 bChangeName、更新名称并调用 OnChangeName(index,name)；PID 不命中时调用创建失败码 100。

DirectEnter

1. Python net.DirectEnter(slot) -> CPythonNetworkStream::ConnectGameServer(slot)。
2. ConnectGameServer() 校验 < PLAYER_PER_ACCOUNT4，保存所选槽位，设置 __DirectEnterMode，按该槽的 lAddr:wPort 建立新的 game 连接。
3. 新连接握手和 SetLoginPhase() 仍发送带 login key 的 CG_LOGIN2，不是普通选人窗口路径；登录信息随后被清除。
4. SetSelectPhase() 在 DirectEnter 模式只切换到 Loading UI，不调用普通 SendSelectCharacterPacket()；DirectEnter 标记在 SetLoadingPhase() 中初始化清除。
5. GC_WARP 也通过 __DirectEnterMode_Set(m_dwSelectedCharacterIndex) 后连接目标 lAddr:wPort 复用这条路径。

Current call chain

• extension/src/net/classic/classic_session.cpp::on_phase()、select_char()、create_character()、delete_character()、change_name()、send_empire()、connect_direct_enter()。
• extension/src/net/classic/classic_parser.cpp::parse_login_success()、on_gc()。
• extension/src/net/classic/wire_classic.h 的固定包结构和 is_sequence_cg()。
• extension/src/net/m2_client.cpp::select_character()、enter_game()、CRUD 转发、pump_classic() 事件分派和 build_char_list()。
• project/app_flow.gd::_on_char_list()、_build_char_list()、_enter_character()、_forward_char_evt()。
• project/ui/char_select_screen.gd::_pad_slots()、_do_start()、创建/删除/改名回调。

Branch-by-branch comparison

场景	40250 参考行为	当前实现	结论
4 槽登录成功	写入 4 个固定槽位，空槽仍有 index 2/3 和全字段零值	parse_login_success(..., n=4) 重建 4 个 CharSlot；主路径等价	MAPPED
3 槽登录成功	写入固定 4 槽数组的前 3 项，第 4 项保持清零空槽	parse_login_success(..., PLAYER_PER_ACCOUNT3) 仍分配 4 个零初始化槽，slot_count()/build_char_list() 暴露 4 槽	MAPPED
空槽建号	固定槽位 UI 允许空槽，创建成功写回该槽	4 槽数组和 UI 补槽均保留空槽 index，创建回包按 slot 写回	MAPPED；真实服务端异常仍缺包序证据
帝国选择	CG_EMPIRE 发送成功后立即本地写入 empire，再发 sequence	send_empire() 只发包；当前 m_empire 只有收到 GC_EMPIRE 后才改变	GAP：本地状态写入时点不同
普通选人	UI 调用 SendSelectCharacterPacket，包后有 sequence	select_char() 在 CharSelect 且 slot 在当前 vector 范围内时发送固定包；stream 自动追加 sequence	MAPPED，重复触发/空槽语义缺少测试
创建请求	固定 name/job/shape/四维字段，发 sequence；参考发送函数本身不做 slot 空闲判定；中文名称按 GB2312 字节字段发送	当前做 stage、slot、name 和整数范围校验，先将 UTF-8 名称转成 GB2312/GBK，再按 24 字节 wire cap 填包	MAPPED：中文 40250 字节容量已对齐，前置校验/真实包序仍需继续证明
创建成功	<4 才更新固定槽并回调；越界只消费包，不产生成功回调	account_slot >= m_slots.size() 只消费包并返回；有效槽才更新并排入 CreateOk	MAPPED
创建失败	同时通知创建窗口和选人窗口	一个 char_create_failed 信号由当前选人页转发	PARTIAL：单窗口适配存在，但缺少双接收者/顺序证明
删除请求	删除码最多复制 7 个字节，固定包后发 sequence	strncpy(..., PRIVATE_CODE_LENGTH-1)，零初始化尾部后发送	MAPPED：删除码边界已对齐
删除成功	清零槽位和 guild id/name 后回调 slot	CharSlot{} 清空所有字段后排入 DeleteOk；有效 4 槽时等价	MAPPED，3 槽第 4 槽和异常 slot 未覆盖
删除失败	消费空包并回调 OnDeleteFailure()	解析为 DeleteFail，由 UI 清空输入框	MAPPED，需补固定包/连续包测试
改名成功	按 PID 命中槽位后清除强制改名并回调 index/name	按 PID 更新槽位并排入 name event；UI 再发整表和 PID/name	PARTIAL：event 适配存在，index 语义和顺序未完全保持
改名 PID 不命中	调用创建失败码 100	未命中时排入 CreateFail(100)，不产生 name event	MAPPED
DirectEnter 目标连接	设置 DirectEnter，连接角色槽 lAddr:wPort，重新走 CG_LOGIN2；DirectEnter 的 select 阶段不发普通选择包	连接槽地址并保留 login key；在 PHASE_SELECT 中只切 Loading，不发送 CG_PLAYER_SELECT	MAPPED 主分支；真实服务器时序仍未证明
DirectEnter 重复进入	参考 API 通过单一网络流状态和 UI phase 控制	当前 enter_game()/connect_direct_enter() 没有 native epoch/重复请求保护	PARTIAL
旧数据清理	登录阶段先清固定角色/guild 数组；离线/Loading 也清 DirectEnter 标记	新的 ClassicSession 通常从空 parser 开始；复用/失败/断线时没有同等固定槽和事件队列清理合同	PARTIAL

Equivalence matrix

项目	状态	证据
Preconditions	PARTIAL	当前有 stage/slot/name/range 校验，但 40250 的固定 4 槽、空槽、DirectEnter 和重复调用边界未完全一致
Branch structure	PARTIAL	CRUD 主分支存在；3 槽固定数组、未命中改名、DirectEnter select 分支不同
Algorithms/formulas	PARTIAL	包字段和 sequence 基本一致；classic 固定名称现在按 UTF-8 -> GB2312/GBK 转换后的字节截断，非中文 locale 和完整异常矩阵仍未闭合
State transition order	PARTIAL	帝国本地写入时点、创建/删除/改名事件和 DirectEnter 选择包顺序不同
Constants/units	PARTIAL	私码 8 字节、角色名 24 GB2312 字节 cap、3/4 槽暴露规则已定位；其它 locale 和异常边界仍未完全证明
Timing/event sources	PARTIAL	参考 phase/window callback；当前为 parser queue -> M2Client signal -> Godot UI，未证明所有成功/失败顺序等价
Resource/data sources	MAPPED	角色槽、guild、login key、角色 game 地址均已定位到对应报文/状态来源
Protocol side effects	PARTIAL	普通 CRUD 包和 sequence 有；帝国本地副作用、越界响应和 DirectEnter 额外 CG_PLAYER_SELECT 不同
Interruption/failure/cleanup	PARTIAL	创建/删除/改名异常、连接中断、重复进入和角色实例管理器生命周期缺少完整自动测试

Existing test evidence

通过的现有回归：

• extension/tests/net_classic_session_test.cpp / build/extension/net_classic_session_test：4 槽成功列表、强制改名成功、创建失败包兼容、删除码 7 字节边界、普通选人、槽地址连接。
• 同一测试还覆盖 legacy 3 槽保持第 4 个空槽、DirectEnter SelectPhase 不发送普通选择包、未知改名 PID 的 CreateFail(100)，以及 Select phase 外角色回包被拒绝。
• extension/tests/net_loopback_test.cpp / build/extension/net_loopback_test：创建/删除/改名的经典 loopback 主路径。
• project/char_create_delete_test.gd：Godot 选人页 UI 创建、删除、改名和帝国按钮流程。
• project/test_intro_select_parity.gd：选人页及删除码 UI 的既有测试。

这些测试没有覆盖：3 槽登录后的固定第 4 槽、空槽 slot 3 的创建/删除结果、非中文 locale codepage、未命中 PID 的改名错误码、DirectEnter 在 PHASE_SELECT 的包序列、重复进入和中断清理。因此通过结果不能提升合同状态。

Deep audit round 2026-09-20

本轮重跑角色选择/CRUD/loopback 回归，并把 native 代码中的 DirectEnter 与固定槽位行为重新对照：

• char_create_delete_test.gd、test_intro_select_parity.gd、net_classic_session_test 和 net_loopback_test 均退出码 0；它们证明当前 4 槽主路径、UI 创建/删除/改名、普通选人和 loopback CRUD 没有回归。
• ClassicParser::parse_login_success() 仍按报文 n 清空并创建 vector；legacy 3 槽报文因此不会保留 reference 固定 4 槽数组中的 slot 3 空项。当前 UI 测试使用的是补齐后的 4 槽 fixture，不能覆盖真实 3 槽包。
• ClassicSession::on_phase(PHASE_SELECT) 在 m_direct_enter 时先切 Loading，但仍调用 send_select_char(m_direct_enter_slot)；参考 DirectEnter 的 Select phase 只切 Loading，不发送普通 CG_PLAYER_SELECT，所以当前多发包差异仍存在。
• 创建成功即使 account_slot >= m_slots.size() 也会排入 CreateOk；改名 PID 未命中时当前只排入 name event，不生成参考创建失败码 100。帝国选择也没有参考端“发送成功后立即写本地 empire”的时点。
• 当前角色名、改名和创建字段仍经 UTF-8 to_wire，本轮安全编码审计已确认与 Windows locale codepage 不是同一语义；重复 enter_game/DirectEnter 失败和中断清理仍没有独立状态 epoch。

结论：4 槽/legacy 3 槽固定槽、DirectEnter 不重复选人、越界创建和未命中改名回调、帝国写入时点已按 40250 对齐；locale 字节、双窗口回调/连续异常包、重复进入/中断清理、角色实例管理器生命周期和真实服务端包序仍与 40250 不一致，合同保持 PARTIAL。

Required tests before verification

• 3 槽/4 槽登录成功后都暴露固定 4 个槽位，空槽 index、guild 和角色字段全部清零。
• 在 3 槽协议下创建/删除 slot 3，证明参考行为与当前行为的边界；若协议确实禁止，记录服务器分支证据而不是用 vector 长度推断。
• 创建/改名名称在 0、最大字节、最大字节+1、非 ASCII、locale codepage 不可逆字符下的实际 wire bytes 与参考比较。
• 创建成功越界、创建失败双窗口、删除成功/失败连续包的状态和事件顺序。
• 改名 PID 命中和未命中（错误码 100）以及强制改名状态清理。
• DirectEnter 从初始 game 连接到槽地址的完整阶段和 wire 序列，确认 PHASE_SELECT 是否可达以及是否应发送 CG_PLAYER_SELECT；增加重复 enter_game、连接失败和中断后的清理断言。

Active UserInterface character-manager review

• AbstractCharacterManager.h/PythonCharacterManager.h 把 VID→CInstanceBase 实例表、主实例、选中实例、fade/dead list、设备对象、point effect、transform update 和销毁顺序作为角色管理器职责；PythonCharacterManagerModule.cpp 还注册 RaceData 的 motion mode、weighted motion、normal/combo attack、attach bone、shape 和 motion resource。
• PythonCharacterModule.cpp 的创建/注册/删除/淡出/选择、装备/发型/武器、位置/方向/动作、render mode、affect、bound box 和 faint 起身队列构成角色选择后到游戏内的统一实例入口。当前端角色选择和 NetWorld entity view 能显示/删除角色，但没有同一 manager 的 dead/fade/device/motion registration 生命周期。
• 本轮完成活跃角色管理源码静态核对；现有 character select 测试和网络包测试不能替代参考端实例表、重复 VID、fade 删除、主实例切换和进入游戏清理语义，合同保持 PARTIAL。

Implementation fix round 2026-09-21

按 40250 的固定数组和 phase 分支修复当前 classic 客户端：legacy GC_LOGIN_SUCCESS3 现在只填充前 3 项但始终保留 4 个零初始化槽位；创建成功的越界槽不再产生成功事件；未知 PID 的改名回包改为创建失败码 100；SendSelectEmpirePacket 对齐为写包成功后立即更新本地 empire；DirectEnter 的 PHASE_SELECT 只切换 Loading，不再额外发送普通 CG_PLAYER_SELECT。

新增/更新 native 边界回归覆盖 legacy 三槽固定槽、帝国本地状态时点、未知改名 PID 和 DirectEnter 包序。cmake --build build -j2、ctest --test-dir build --output-on-failure（23/23）、char_create_delete_test.gd、test_intro_select_parity.gd、p10_test.gd、app_flow_lifecycle_test.gd 和 git diff --check 均通过。

剩余 locale codepage 字节语义、创建/删除异常和双窗口回调、DirectEnter 重复进入/中断清理、角色实例管理器生命周期以及真实服务端包序仍未达到 40250 统一语义，合同保持 PARTIAL。

Audit round 2026-09-20 — Select-phase side-effect gate

继续核对 PythonNetworkStreamPhaseLogin.cpp::LoginPhase、 PythonNetworkStreamPhaseSelect.cpp::SelectPhase 与当前 ClassicSession::on_packet：40250 的角色创建、删除、强制改名回包只在 SelectPhase 的分支中消费；错误阶段不会进入固定槽位和 UI 回调。当前端此前由 phase-neutral parser 直接接收这些 header，延迟的创建/改名包可能在 Login/Loading 阶段改写角色列表。

本轮修复 ClassicSession::on_packet 的阶段门禁：

• GC_PLAYER_CREATE_SUCCESS、GC_PLAYER_CREATE_FAILURE、GC_PLAYER_DELETE_SUCCESS、GC_PLAYER_DELETE_WRONG_SOCIAL_ID、GC_CHANGE_NAME 只有 CharSelect 或 DirectEnter 尚处协议 SelectPhase 时才进入 parser。
• 错误阶段返回明确错误并断开当前 phase owner，避免角色槽、改名状态和 UI 事件产生错误副作用。
• DirectEnter 的 UI stage 已是 Loading，但 m_direct_enter 仍作为协议 SelectPhase 标志保留，确保其合法的阶段边界不被误拒绝。

回归：net_classic_session_test、net_classic_stream_test、net_classic_wire_test、net_loopback_test、char_create_delete_test.gd、test_intro_select_parity.gd、p10_test.gd 和 git diff --check 均通过。

这只闭合了角色 CRUD 回包的阶段副作用；Login/Select/Loading/Game 的完整 117-header allowlist、burst tick 消费顺序、locale codepage、双窗口回调和真实服务端包序继续由 network.packet_dispatch_protocol/本合同跟踪，状态保持 PARTIAL。

Implementation fix round 2026-09-21 — 40250 Chinese name bytes

角色创建和改名入口保持 UTF-8 业务字符串，但实际 CG_PLAYER_CREATE/CG_CHANGE_NAME 固定字段改由 mtnet::to_wire() 写入 GB2312/GBK bytes。wire_text_fits() 在编码后按 CHARACTER_NAME_MAX_LEN=24 校验：12 个中文字符可发送，13 个中文字符在客户端被拒绝；结构体零初始化保证第 25 个字节为 NUL。net_text_codec_test 覆盖独立转换，net_classic_session_test 直接检查创建/改名 packet bytes，避免只测试 helper 而漏掉真实发送入口。

Status

PARTIAL。