mtgodot-poc/docs/PORT-PLAN.md

40250 1:1 移植：路线与方案

本文是移植工作的总入口，换一台电脑继续开发时先读这份。更新日期：2026-09-22。

• 方法细则：.agents/skills/metin2-40250-parity-audit/SKILL.md（每轮的做法、状态定义、工具）
• 批次队列：audit/remediation-roadmap.md
• 逐函数进度：audit/port-map/**；每轮一行记录：audit/history.jsonl
• Python UI 评估：docs/PYTHON-EMBED-EVAL.md
• 旧方案 docs/CLIENT-REFACTOR-40250-PLAN.md（"形式上不照搬类文件"）已被本文取代

1. 目标与原则

metin2-client 是 40250 Windows 客户端的跨平台版本（macOS / Windows / Linux / Android / iOS）。 除渲染和平台 API 外，所有玩法算法、分支、常量、状态顺序、计时来源、数据来源、封包副作用和清理路径都以 40250 为准。40250 源码就是规格，不设计行为，只照抄。

• 工作单位是 40250 的一个源文件（或超大文件里的一组函数），不是某个行为分支。
• 当前代码里没有 40250 对应物的逻辑是缺陷，要删掉。
• 运行时不会加载的代码不算实现，它的测试也不算证据。

2. 已定的决定

日期	决定	依据
2026-09-22	逻辑层按 40250 结构移植：C++ → C++，文件名、类名、方法名、成员名、语句顺序都保持一致	能逐文件机械核对，不再"找差异"
2026-09-22	UI 走内嵌 CPython 2.7.18（方案 A），原样运行 40250 的 root/*.py 和 uiscript/，只移植 C++ 模块	脚本无需改动；macOS 和 Android 真机均已验证，见 docs/PYTHON-EMBED-EVAL.md
2026-09-22	数据源统一改为 40250（Client/Eternexus 的 root/uiscript/locale，以及 Client/pack 的资源），不再用仓库里 m2dev 版本的 assets/root、assets/uiscript、assets/locale	两者有实质差异，见第 5 节
2026-09-22	现有 project/ui/*.gd（60 个文件，依据的是错误版本的脚本）不再维护，由 Python 层取代	—
2026-09-22	照抄时保持 40250 的宽度和溢出语义（Win32 下 long 为 32 位），序列化结构用定宽类型并 static_assert 大小	64 位平台 long 是 8 字节，机械照抄会破坏 proto/封包/EPK 布局和 TEA
2026-09-22	迁移期新旧路径共存，新路径接通运行后才在同一提交删除旧逻辑；先做最小纵向切片 2V	main 始终可玩；运行时不可达的新代码不算实现

3. 三个层和代码位置

层	40250 单元	做法	位置
logic	UserInterface/、GameLib/、EterLib 的网络/计时/文本解析、EterPack、EterLocale	逐文件照抄 C++	extension/src/port/<Lib>/<File>.{h,cpp}
python	root/*.py、uiscript/、UserInterface/*Module.cpp、EterPythonLib/、ScriptLib/	脚本原样运行；*Module.cpp、窗口系统、CPythonLauncher 照抄	extension/src/port/<Lib>/ + extension/third_party/cpython-2.7.18/
platform	Direct3D/Grp*、Granny、Miles、SpeedTree、特效/地形渲染、Win32 窗口/输入/IME、线程、反作弊	适配层，接口与 40250 调用方看到的一致，按可观察输出核对	extension/src/platform/ + 现有渲染代码

extension/src/port/UserInterface/InstanceBase.cpp      # 40250 同名文件的照抄
extension/src/port/GameLib/ActorInstance.cpp
extension/src/port/ScriptLib/PythonLauncher.cpp
extension/src/port/EterPythonLib/PythonWindow*.cpp
extension/src/port/UserInterface/*Module.cpp           # app/net/player/chr/... Python 模块
extension/src/platform/                                # CGraphicThingInstance、CSoundManager 等同名适配接口
extension/third_party/cpython-2.7.18/                  # 静态库（2P 批次加入）

逻辑层规则：

• 40250 调用平台类的地方，调用 extension/src/platform/ 下同名的适配接口，ported 代码里不直接写 Godot 调用。
• 40250 的单例（CPythonPlayer、CPythonCharacterManager、CPythonNetworkStream）归扩展所有，GDScript 不持有玩法状态。
• 保持 40250 的宽度和溢出语义，不是机械保留 C++ 类型名。 40250 是 Win32（ILP32/LLP64）：long/unsigned long 是 32 位，指针是 32 位。64 位的 macOS/Linux/Android/iOS 上 long 是 64 位，照抄会改变结构大小、TEA 的读取宽度和 溢出行为。统一由 port/common/Win32Types.h（批次 2A）把 LONG/DWORD/long 等映射到 int32_t/uint32_t：
  • 凡是参与序列化的结构（proto 记录、封包、EPK 索引、msa/msm 二进制）一律用定宽类型，#pragma pack 与 40250 相同， 并对 40250 已知大小加 static_assert(sizeof(...) == N)（如 TItemTable == 156）；
  • 纯计算里的 long 如依赖 32 位回绕，也换成 int32_t；
  • 指针存进 DWORD 的写法（句柄、SetUserData 等）改成 uintptr_t，并在 port-map 的 note 里记下。
• 单位保持 40250 的（TPixelPosition 用 cm，时间是 ELTimer_GetMSec 的毫秒，角度用度），只在适配层换算。
• 迁移来源：net_play.gd、net_world.gd、game_scene.gd、player_controller.gd、entity_store.cpp。旧逻辑只在新路径 已接通运行时之后才删除（见第 4 节"迁移方式"），删除与接通在同一次提交完成。
• 迁移结束后 Godot 这边只剩：场景节点、渲染适配、一个把输入转发给 CPythonWindowManager 并每帧调用 Update/Render 的宿主 Control。

4. 路线

批次	内容	状态
0	工具：参考根解析、port_map.py、构建/测试入口	完成（55f733fd、5afd5a4f）
1	删除运行时不加载的 106 个 *_system.gd 及其测试	完成（a989b8f1）
—	定下目录结构，评估内嵌 Python；Android 独立程序验证	完成（9d0e50de、b02c49bb）
2A	基础：Win32 类型层、参考公共头的最小闭包、port_logic CMake 目标、platform 接口骨架、头文件可编译门禁、port-map 重新基线	下一步
2R	资源包能力盘点：EPK 类型/密钥/覆盖顺序/路径大小写/移动端交付	下一步，可与 2A 并行（只读分析 + 独立工具）
2P	CPython 2.7.18 编进 libmtgodot，五个平台分别配置和验证	2A 之后
2D	数据源切到 40250（msm 路径、proto、资源根、严格资源测试）	proto 部分在 2A 之后；资源根在 2R 之后
2V	最小纵向切片：CPythonLauncher → system.py → wndMgr → 登录/选角 → GamePhase → 本地角色移动	需要 2A、2P、2D；这是第一个可运行的新架构里程碑
2	其余 P0 角色/移动单元，按依赖拓扑移植	2V 之后
3	P1 战斗/技能 → P2 游戏阶段封包 → P3 物品；Python 层（窗口系统 → *Module.cpp）	未开始
4	NEEDS_LIVE 真服验证	未开始

迁移方式：始终保持可玩

旧 GDScript 路径和新的 ported 路径在切片接通前共存，由构建/运行开关选择（例如 MT_PORT_PATH=legacy|port，默认 legacy）。规则：

• 新单元先编译进 port_logic，但只有被新路径的运行时调用到，才算实现（"运行时不可达不算实现"同样适用于新代码）； 没有接通前，port-map 状态保持 TODO，note 写"已照抄，未接通"。
• 每个接通步骤的提交同时：切换调用方到新路径、删除被取代的旧逻辑、跑一遍能覆盖该路径的运行测试（离线 FakeClient 或真服 e2e）。
• main 在任意提交上都能进游戏走动；legacy 路径在 2V 完成、默认值切到 port 并稳定后整体删除。

批次 2A：基础

1. extension/src/port/common/：Win32Types.h（BYTE/WORD/DWORD/LONG/BOOL/UINT/HANDLE 等的定宽映射）、 40250 用到的 Win32/CRT 宏和函数（ZeroMemory、_snprintf、stricmp、timeGetTime 等）的最小实现、 StdAfx.h 等价物。
2. 参考公共头的最小闭包：从第一批要移植的单元出发（PythonPlayerEventHandler.h 依赖 ActorInstance.h、FlyHandler.h、 PythonNetworkStream.h、InstanceBase.h），用脚本列出 #include 闭包，把闭包里的头文件先照抄为可编译的声明。
3. port_logic 静态库 CMake 目标，链接进 libmtgodot；在 macOS 和 Android 两个工具链上编译。
4. extension/src/platform/ 接口骨架：闭包里出现的平台类（CGraphicThingInstance、CSoundManager 等）只声明 40250 调用方用到的方法，先给空实现。
5. 门禁：port/** 下每个头文件单独编译通过（header self-containment），序列化结构的 static_assert 全部通过。
6. port-map 重新基线（见第 6 节）。
7. 用 #include 依赖图生成批次 2 的移植顺序（拓扑序），替换原来"互不共享实现文件即可并行"的假设：共享头文件的单元， 头文件由先做的那个单元负责，后面的单元只能在它合入后开始。

批次 2R：资源包能力盘点

40250 的读取链不只是 EterPack.cpp，还有 EterPackManager.cpp（多包覆盖顺序、路径归一化）、 EterPackPolicy_CSHybridCrypt.cpp（HybridCrypt，密钥可能来自登录/握手阶段的服务器下发）、CMappedFile、CLZO， 以及 TEA/Panama/Camellia/Twofish/XTEA。压缩类型有六种：NONE、COMPRESS、SECURITY、PANAMA、 HYBRIDCRYPT、HYBRIDCRYPT_WITHSDB。Client/pack 有 217 个文件、约 1.3 GB。

1. 写一个只读的扫描工具（Python，放在 tools/），解析所有 .eix，统计每个包、每种 compressed_type 的文件数和字节数。
2. 按统计结果决定：
   • 只有 NONE/COMPRESS/SECURITY 的包可以离线解出；
   • PANAMA/HYBRIDCRYPT* 如存在，确认密钥来源：本地的 Index/配置，还是服务器 GC_HYBRIDCRYPT_KEYS/SDB 下发。需要服务器密钥的包，要么移植密钥链，要么在开发期用一次真服登录抓取密钥后离线解包（密钥不进仓库）。
3. 验证 Index 文件列出的包顺序和同名文件的覆盖优先级，与 CEterPackManager 一致。
4. 路径归一化：40250 在 Windows 上大小写不敏感，并把 d:/ymir work/ 等前缀映射到包内路径。确定统一的小写化规则，扫描大小写冲突。
5. 移动端交付：决定最终形式（例如解包后重新打成我们自己的 mtpack，或直接在设备上读 EPK），给出 Android/iOS 的包体积、首包与按需下载的划分，以及更新方式。MT_ASSETS 只是开发期覆盖。
6. 输出写进本文第 5 节，再决定 2D 的资源根切换方式。

批次 2P：内嵌 Python 集成

1. CPython 2.7.18 源码放进 extension/third_party/cpython-2.7.18/。共用源码清单和静态模块清单（Modules/Setup 中启用的 C 模块，见 tools/py_embed_android/build-and-run.sh）；每个平台各自一份 pyconfig.h（由该平台的 configure 生成后提交，或 Windows 用 PC/pyconfig.h），因为它是对目标平台类型大小和系统 API 的探测结果，不能共用。已知平台差异：Android API 24 需关掉 HAVE_LANGINFO_H。
2. 静态链接进 libmtgodot，照抄 ScriptLib/PythonLauncher.cpp。
3. pack 模块通过 asset_io 读取，标准库的纯 Python 文件放进资源包，由 system.py 自带的导入钩子加载。
4. 五个平台分别验证：编译、链接无未定义符号、Py_Initialize、静态 C 模块逐个 import、在 app 进程里跑 system.py → prototype.RunApp()（对照结果：74 个模块中 66 个加载成功，引导期调用 33 个 C++ 函数）。

   平台	状态
   macOS arm64	系统 Python 2.7.18 跑通 spike；静态嵌入未做
   Android arm64	独立可执行文件在真机跑通（b02c49bb）；APK 进程内未做
   iOS arm64	未做
   Linux x86_64	未做
   Windows x64	未做（用 PCbuild 的源码清单和 PC/pyconfig.h，不走 configure）

5. 数据源切换：m2dev assets → 40250

现在的渲染和逻辑读的是 assets/，这是从 m2dev 的包解出来的。2026-09-22 与 40250 Client/Eternexus 逐项对比的结果：

数据	读取方	与 40250 的差异	处理
root/npclist.txt	mob_view.gd、m2_client.cpp	相同	无
8 个 *.msm（种族模型、挂点、染色）	equip_model.gd、player_view.gd	内容相同，位置不同：m2dev 在 root/msm/<cls>_<m/w>.msm，40250 在 root/<cls>_<m/w>.msm（LoadLocalRaceData("warrior_m.msm")）	查找列表加上 40250 的位置
playersettingmodule.py 的动作注册（SetGeneralMotions、__LoadGame*Ex）和连击表	motion_registry.gd、net_play.gd	相同	40250 的文件是 CP949 + CRLF，切换后跑一遍解析测试
playersettingmodule.py 的特效注册	暂无	40250 多了 EFFECT_LEVELUP_*_FOR_GERMANY、EFFECT_EMPIRE+1..3，少了 EFFECT_AGGREGATE_MONSTER	移植特效时按 40250
atlasinfo.txt、grpblk.txt	—	相同	无
uiscript/uiscript	现有 project/ui/*.gd	40250 有 94 个，m2dev 有 80 个；共有的 71 个中，去掉空白差异后有 11 个不同（建角/选角/密码/信使/公会等）	由 2P 直接运行 40250 的 uiscript，不单独处理
item_proto	proto.cpp	读不了：40250 每条 156 字节（TItemTable，含 long 字段，需按 32 位布局），m2dev 236 字节；40250 用经典 TEA（32 轮，0x9E3779B9，按 32 位字处理），m2dev 用 XChaCha20	按 40250 移植（需 2A 的类型层）
mob_proto	proto.cpp	读不了：每条 255 字节 vs 335 字节，加密同上	同上
item_list.txt	item_list.gd	177 行不同（m2dev 有 dummy 条目等）；40250 放在 locale/en/，m2dev 在 locale/common/	按 40250 路径读取
locale_interface.txt、itemdesc.txt、skilldesc.txt、skilltable.txt	UI、技能表	20 行 / 2 行 / 2 行 / 位置不同	按 40250 路径读取
模型、贴图、地图（PC、Monster、Outdoor 等）	渲染	未核对：40250 是经典 .eix/.epk 包	由 2R 决定

切换步骤（批次 2D）：

1. msm 查找路径加上 root/<cls>_<m/w>.msm。
2. proto 读取按 40250 移植：EterBase/tea.cpp、GameLib/ItemData.h 的 TItemTable、CPythonNonPlayer 的 mob 表，放进镜像文件（使用 2A 的定宽类型和 static_assert），替换 extension/src/proto/proto.cpp 里的 m2dev 格式。
3. 资源测试严格模式：
   • 统一资源环境变量：C++ 测试（extension/CMakeLists.txt 目前只透传 M2_ASSETS）和 GDScript（MT_ASSETS）统一读 MT_ASSETS，过渡期两者都透传；
   • 新增 MT_ASSETS_STRICT=1：指定了 40250 资源时，缺文件必须失败，不能跳过；
   • 为 40250 的 root、locale、proto 和关键包生成来源清单（路径 + sha256），提交到 audit/，测试开始时核对。
4. 资源根切换方式按 2R 的结论执行，跑渲染和解析测试，更新本节状态。

6. 进度与 port-map 基线

实时数字用 port_map.py status 查看。

2A 时做一次重新基线，之后的数字才代表新架构的进度：

• 之前"完成"的 6 个函数（PythonPlayerEventHandler.cpp）作废：OnMove/OnMoving/OnStop 的实现在 net_play.gd，属于迁移来源； 3 个 N_A（单例、构造、析构，理由是"由 NetPlay 场景节点持有"）与"单例归扩展所有"冲突。全部回退为 TODO。
• 原样运行的 Python 脚本函数不标 N_A（N_A 只用于没有玩法语义的平台胶水）。新增状态 RUN_AS_IS： impl 指向随包运行的原脚本，evidence 要求该函数所在模块在目标平台的运行证据（导入成功且被运行路径调用到）。 需要同步修改 port_map.py 和 references/audit-schema.md。

2026-09-22 基线前的数字（仅供参考）：logic 3285 个函数、python 4890、platform 2229，完成数视为 0。

7. 换机器后的环境准备

目录布局（路径都相对 ~/Work/mt/，工具按相对路径查找）：

~/Work/mt/metin2-client/                     # 本仓库（git remote origin）
~/Work/mt/40250/Server Client TMP4/          # 40250 参考（不在 git 里，需自行复制）
    ClientVS22/source/                       # C++ 参考根（audit/manifest.json 的 reference_root）
    Client/Eternexus/root, uiscript, locale  # Python 参考
~/Work/mt/metin2-client/assets/, bgm/        # 游戏资源（gitignored，需自行复制；或用 MT_ASSETS 指到别处）

• 参考源放在其他位置时，设置 MT_40250_SOURCE=<.../ClientVS22/source>。
• Python 2.7.18：用于运行 py_embed_spike.py。macOS 安装 python.org 的 2.7.18 包，确认 python2.7 --version。
• Python 3：用于 port_map.py 和其他审计脚本。
• Android：NDK 27.2（ANDROID_NDK_HOME 指向它；未设置时脚本选版本号最低的 NDK）、openjdk@21、Godot 导出模板； adb 用 /opt/homebrew/bin/adb。APK 导出用 ./export-android.sh。
• 真服账号、密码不写进仓库或 audit 账本。

新会话恢复工作：

cd ~/Work/mt/metin2-client
git pull
python3 .agents/skills/metin2-40250-parity-audit/scripts/port_map.py status
python3 .agents/skills/metin2-40250-parity-audit/scripts/port_map.py queue --limit 20
python3 .agents/skills/metin2-40250-parity-audit/scripts/port_map.py check
python2.7 .agents/skills/metin2-40250-parity-audit/scripts/py_embed_spike.py --out /tmp/py_embed_spike.txt   # 可选：复核 Python 原型
tools/py_embed_android/build-and-run.sh                                                         # 可选：连接 Android 真机复核

然后按第 4 节标为"下一步"的批次继续，每完成一步在第 4 节（及 2P 平台表、第 5 节）更新状态并提交。