Port the ActorInstanceBattle combo state machine, CRaceMotionData attack data, player motion/combo tables, NEW_Attack + OnAttack/OnHit packets and remote FUNC_ATTACK/FUNC_COMBO playback so keyboard and touch attacks swing and hit on the real-server path. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
149 lines
11 KiB
Markdown
149 lines
11 KiB
Markdown
# 移动端架构(2026-10-12)
|
||
|
||
本文是引入移动端(Android 优先,iOS 其后)后的目标结构和实施顺序。游戏逻辑、网络、渲染、资源各层保持现状;变化集中在平台打包、主程序的平台适配与触屏输入、以及 Python 界面的手机 HUD 叠加层。标为"新增"或"拆分"的部分尚未实现。
|
||
|
||
## 现状
|
||
|
||
- `android/build.sh` 可以编出 arm64 调试 APK(SDL3 + FreeType 自动编译,16 KB 页对齐),连接手机时自动安装启动;真机运行尚未验证。
|
||
- `android/push_assets.py` 把资源(`assets/loose` + python-root + `python27.zip`)推送到应用外部存储目录,客户端启动时切换到该目录。
|
||
- 游戏资源为 2.8 GB、约 5 万个散文件(`assets/loose`),17 个源文件中 120 多处通过 `std::filesystem` / `ifstream` 直接读文件,无法读取 APK 内置资源。
|
||
- 没有处理前后台切换(`SDL_EVENT_WILL_ENTER_BACKGROUND` / `DID_ENTER_FOREGROUND`)和低内存事件。
|
||
- 触摸分流已实现(`src/app/input/touch_router.*`,见下文 `input/`):移动端或 `--touch` / `AVA2_TOUCH=1` 时关闭 SDL 触摸转鼠标,每个手指分到界面、攻击键、左下浮动摇杆或镜头(单指拖动转向、双指缩放、轻点=点地移动)。Python 模块 `touch` 供 HUD 设置攻击键位置并读取摇杆状态;`ui_mobile_joystick` / `ui_mobile_combat` 改为只做显示(`not_pick`)。多指同时操作尚未在真机验证。
|
||
- 出招已接通(PORT-PLAN「Mobile step 3b」):触摸攻击键和键盘共用 `ProcessPlayerAttack`,按原版连招时序出招,发送 FUNC_COMBO 移动包,命中检测后发 `CG_ATTACK`;尚未在真服验证,弓箭飞行、技能、PvP 规则等仍缺。
|
||
- 原型 HUD 用到的 `taskbar/attack_button_0x.sub`、`quickslot_0x.sub` 不在资源包里:攻击键暂用色块,技能圈槽位不可见。
|
||
- 软键盘已改为仅在输入框获得焦点(`ime.EnableCaptureInput`)或聊天打开时弹出。
|
||
- `src/app/main.cpp` 共 2418 行,启动、主循环、登录和调试参数都在其中。
|
||
- Android 默认渲染缩放 0.75。
|
||
|
||
## 分层结构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 平台打包 android/ (Gradle + SDLActivity + build.sh) │ 新增
|
||
│ ios/ (以后) macOS .app (已有脚本) │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ 主程序 src/app/ │
|
||
│ main.cpp 入口、命令行参数 │ 拆分
|
||
│ app_loop 每帧:事件 → Python → 网络 → 渲染 │ 从 main.cpp 抽出
|
||
│ platform/ 数据目录、前后台切换、安全区域、软键盘 │ 新增
|
||
│ input/ 触摸分流、虚拟摇杆、攻击键、镜头手势 │ 新增
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ Python 2 界面层(原版行为) │
|
||
│ upstream/python-root AVA2 原版脚本(不修改) │
|
||
│ mobile/ 手机 HUD 叠加层(仅移动端加载) │ 新增
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ 原生模块 src/scripting/python_*.cpp │ 不变
|
||
│ player / net / chr / app / wndmgr / grp ... │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ 游戏逻辑与网络 src/eter_net, src/network, src/game │ 不变
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ 渲染 src/eter_render, eter_effect, eter_image │ 不变
|
||
│ HardwareScene: SDL_GPU → Metal (macOS/iOS) │
|
||
│ → Vulkan (Android) │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ 资源 CResourceManager + std::filesystem │ 基本不变
|
||
│ 根目录由 platform/ 决定 │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ SDK ../sdk (libgr2, speedtree) 第三方: SDL3, CPython │ 不变
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 平台打包层
|
||
|
||
- Android APK 只包含 `libmain.so`、`python27.zip` 和 python-root 脚本。
|
||
- 游戏资源不进 APK,放在应用外部存储目录(`SDL_GetAndroidExternalStoragePath()`):开发期用 `adb push`,正式版首次启动下载。启动时把工作目录切到该目录,现有文件读取代码无需修改。
|
||
- 以后可把散文件合成大包,减少移动端打开大量小文件的开销。
|
||
- `support/android` 挪到顶层 `android/` 并补全 Gradle wrapper、SDL3 Java 部分、图标和一键编译安装脚本。
|
||
- `AVA2_SDK_ROOT` 沿用默认的 `../sdk`。
|
||
|
||
### 主程序层
|
||
|
||
- `platform/` 集中平台差异,替代散落在 `main.cpp` 中的 `#ifdef`:
|
||
- 资源根目录与配置目录(Android 配置已写入 `SDL_GetAndroidInternalStoragePath()`);
|
||
- 前后台切换:暂停渲染和声音、保存配置、保持网络连接,回到前台后恢复;
|
||
- 屏幕安全区域(`SDL_GetWindowSafeArea`),避开刘海和圆角;
|
||
- 软键盘:仅在输入框获得焦点时 `SDL_StartTextInput`,失焦时关闭。
|
||
- `input/` 是统一输入入口。桌面键盘鼠标路径不变;移动端关闭 SDL 触摸转鼠标,每个手指按顺序判断归属:
|
||
|
||
```
|
||
手指按下 → 落在 HUD 按钮? → 转成点击,交给 Python 界面
|
||
→ 落在原版弹出窗口上? → 转成鼠标事件,交给 wndmgr
|
||
→ 落在左下摇杆区? → 摇杆 → player.SetSingleDIKKeyState
|
||
→ 落在攻击键? → player.SetAttackKeyState
|
||
→ 其他区域 → 单指转镜头 (app.RotateCamera) / 双指缩放
|
||
```
|
||
|
||
最终都调用原版已有的移动和攻击接口,游戏逻辑不感知输入设备差异。多指同时操作(摇杆 + 攻击 + 镜头)由此支持。
|
||
- `app_loop` 从 `main.cpp` 抽出,便于 iOS 改用 SDL 回调式主循环;可在做 iOS 时再拆。
|
||
|
||
### Python 界面层
|
||
|
||
- `upstream/python-root` 原版脚本不修改(AGENTS.md)。
|
||
- 移动端启动时额外加载 `mobile/`:隐藏 PC 任务栏(`uitaskbar`),挂上手机 HUD。背包、商店、任务等窗口仍用原版,整体放大显示。
|
||
- 桌面版默认不加载 `mobile/`,现有测试和原版对照检查不受影响;可用开关在 macOS 上打开 HUD 以鼠标调试。
|
||
|
||
### 不变的层
|
||
|
||
原生模块、游戏逻辑与网络、渲染、SDK 桌面与移动端共用,已有性能优化同样生效。渲染只有图形后端不同(macOS/iOS Metal,Android Vulkan,均经 SDL_GPU)。
|
||
|
||
## 每帧数据流
|
||
|
||
```
|
||
SDL 事件 ─→ platform/(前后台、窗口尺寸)
|
||
└→ input/(键鼠或触摸分流)─→ Python 界面 / player.* 接口
|
||
Python 更新(原版脚本 + mobile HUD)
|
||
网络收发(PythonNetworkStream)
|
||
游戏对象更新(角色、特效、低模、动画时钟)
|
||
渲染(3D 场景 → UI → 合成到屏幕)
|
||
```
|
||
|
||
## 构建矩阵
|
||
|
||
| 平台 | 产物 | 图形后端 | 界面 | 输入 |
|
||
|---|---|---|---|---|
|
||
| macOS(开发和测试) | `ava2_client`、.app | Metal | 原版 PC 界面(可开关手机 HUD) | 键盘鼠标 |
|
||
| Android(主目标) | APK(`libmain.so`) | Vulkan | 原版界面 + 手机 HUD | 触屏 |
|
||
| iOS(以后) | .app | Metal | 同 Android | 触屏 |
|
||
|
||
## 手机 HUD 布局
|
||
|
||
参考常见的 Metin2 手游布局。每个元素都对应现有数据或接口,不需要改游戏逻辑:
|
||
|
||
| 位置 | 元素 | 现有基础 | 工作 |
|
||
|---|---|---|---|
|
||
| 左上 | 头像、HP/SP/经验、buff 图标 | `player.GetStatus`、affect 数据 | 新做紧凑状态面板 |
|
||
| 顶部中间 | 目标名称、等级、血条 | `uitarget.py` | 改位置、放大字号 |
|
||
| 右上 | 通知、邮件、角色、背包、菜单 | 原版窗口 | 入口按钮,点开弹出原版窗口 |
|
||
| 右侧 | 小地图、+/- 缩放、地图名 | `uiminimap.py` | 重新摆放 |
|
||
| 左侧竖排 | 任务、组队、表情、聊天等 | 原版功能 | 图标按钮 |
|
||
| 左下 | 浮动摇杆 | `player.SetSingleDIKKeyState` | C++ 虚拟摇杆,方向换算为移动方向 |
|
||
| 右下 | 大攻击键 | `player.SetAttackKeyState` | 按住持续攻击 |
|
||
| 攻击键外圈 / 底部 | 技能圈、药水栏、翻页 | 原版快捷栏(4 页) | 技能圈对应技能格,底部栏对应道具格 |
|
||
| 攻击键附近 | 骑乘、拾取、锁定目标 | `player.PickCloseItem`;骑乘/锁定接口待核对 | 小按钮 |
|
||
| 屏幕空白处 | 转镜头、双指缩放 | `app.RotateCamera`;镜头距离接口待核对 | C++ 手势识别 |
|
||
| 可选 | 自动战斗 | 原版没有 | 客户端新功能,最后做 |
|
||
|
||
注意事项:
|
||
|
||
- 原版窗口按 800×600 设计;移动端逻辑分辨率取高 600~720 再整体放大,按钮点击范围不小于手指大小。
|
||
- 20:9 等宽屏需按安全区域布局。
|
||
- 不使用其他服务器的界面美术;图标用 AVA2 自带技能/道具图标,按钮底框和摇杆另制。
|
||
|
||
## 目录变化
|
||
|
||
- `support/android` → 顶层 `android/`(补全)。
|
||
- `src/app/` 拆出 `platform/` 和 `input/`(以及以后的 `app_loop`)。
|
||
- 新增 `mobile/`(Python HUD)。
|
||
- 其他目录不变;资源不进 APK。
|
||
|
||
## 实施顺序
|
||
|
||
1. APK 打包补全,资源 `adb push` 到设备,真机进入登录界面;同时用 `--perf-log` 实测之前的性能优化。
|
||
2. `platform/`:资源根目录、前后台切换、软键盘按需打开。
|
||
3. `input/`:触摸分流、虚拟摇杆、攻击键、镜头手势——可在手机上移动和战斗。
|
||
4. `mobile/`:手机 HUD(状态面板、技能圈和快捷栏、右上角入口、小地图、左侧按钮)。
|
||
5. 界面缩放和安全区域收尾。
|
||
6. 自动战斗等新增功能;iOS 打包与 `app_loop` 拆分。
|
||
|
||
第 3、4 步大部分可在 macOS 上开发(鼠标模拟单指,触控板测双指);多指同时操作和性能需要真机验证。
|