@@ -0,0 +1,132 @@
# 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 | UI 参考源是 40250 的 `Client/Eternexus/root` ， `assets/root` （m2dev 版本） | 两者有实质差异 |
| 2026-09-22 | 现有 `project/ui/*.gd` （60 个文件，依据的是错误版本的脚本）不再维护，由 Python 层取代 | — |
## 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 的（`TPixelPosition` 用 cm，时间是 `ELTimer_GetMSec` 的毫秒，角度用度），只在适配层换算。
- `net_play.gd` 、`net_world.gd` 、`game_scene.gd` 、`player_controller.gd` 、`entity_store.cpp` 是迁移来源：移植某个单元的那次提交，同时删掉它们里面被取代的逻辑，只留胶水（建节点、转发输入、读状态摆节点）。
- 迁移结束后 Godot 这边只剩：场景节点、渲染适配、一个把输入转发给 `CPythonWindowManager` 并每帧调用 Update/Render 的宿主 Control。
## 4. 路线
| 批次 | 内容 | 状态 |
| --- | --- | --- |
| 0 | 工具：参考根解析、`port_map.py` 、构建/测试入口 | 完成（55f733fd、5afd5a4f）
| 1 | 删除运行时不加载的 106 个 `*_system.gd` 及其测试 | 完成（a989b8f1）
| — | 定下目录结构，评估内嵌 Python | 完成（9d0e50de）
| — | 内嵌 Python Android 真机验证 | 完成（b02c49bb）
| 2 | P0 角色/移动单元照抄到镜像文件；第一个单元负责建立 `port/` 、`platform/` 和 CMake 目标 | **下一步，未开始 ** |
| 2P | CPython 2.7.18 编进 libmtgodot： **下一步，未开始 ** ，可与 2 并行 |
| 3 | P1 战斗/技能 → P2 游戏阶段封包 → P3 物品；Python 层（`PythonLauncher` → 窗口系统 → `*Module.cpp` ）
| 4 | `NEEDS_LIVE` 真服验证 | 未开始 |
### 批次 2：P0 单元（每个单元一个 worktree，互不共享实现文件的可并行）
1. `UserInterface/PythonPlayerEventHandler.cpp` ： `net_play.gd` 对齐，需迁到镜像文件；OnWaiting 标为 DIVERGENT
2. `UserInterface/InstanceBaseMovement.cpp` + `InstanceBase.cpp` （串行）
3. `UserInterface/PythonPlayerInput*.cpp` （排在第 2 项之后）
4. `GameLib/ActorInstanceMotion.cpp` + `ActorInstanceEvent.cpp`
5. `GameLib/ActorInstance.cpp` + `Position` /`Rotation` /`CollisionDetection`
6. `UserInterface/PythonCharacterManager.cpp`
7. `UserInterface/PythonPlayer.cpp`
每轮的步骤（详见 SKILL.md）：`port_map.py init/show` → 通读参考文件 → 照抄到镜像文件，逐函数与旧实现对比、
记录差异 → 删旧逻辑、改调用方 → 只为改动的公式/分支写测试 → 更新 port-map 和 history → 一个单元一次提交。
### 批次 2P：内嵌 Python 集成
1. 把 CPython 2.7.18 源码放进 `extension/third_party/cpython-2.7.18/` ，用我们自己的 CMake 编译。macOS/Android/iOS
共用一份源码清单和 `pyconfig.h` （ `HAVE_LANGINFO_H` ），C 模块清单见 `tools/py_embed_android/build-and-run.sh`
2. 静态链接进 `libmtgodot` ，照抄 `ScriptLib/PythonLauncher.cpp`
3. `pack` 模块通过 `asset_io` 读取，标准库的纯 Python 文件放进资源包，由 `system.py` 自带的导入钩子加载
4. 先用桩 C++ 模块在 APK 进程里跑通 `system.py` → `prototype.RunApp()` （对照结果：74 个模块中 66 个加载成功，引导期调用 33 个 C++ 函数）
5. 同样的流程在 iOS 上跑一遍
## 5. 当前进度
实时数字用 `port_map.py status` 查看。2026-09-22 的状态：
| 层 | 函数数 | 已完成 |
| --- | --- | --- |
| logic | 3285 | 6 |
| python | 4890 | 0（其中 `Client/root` 的 3350 个在 2P 完成后记为 `N_A` ，属于原样运行） |
| platform | 2229 | 0 |
## 6. 换机器后的环境准备
目录布局（路径都相对 `~/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： （ `ANDROID_NDK_HOME` 指向它；未设置时脚本选版本号最低的 NDK）、openjdk@21 、Godot 导出模板；
`adb` 用 `/opt/homebrew/bin/adb` 。APK 导出用 `./export-android.sh` 。
- 真服账号、密码不写进仓库或 audit 账本。
新会话恢复工作：
``` bash
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、5 节更新状态并提交。
shenlei