Move the macOS/Android data and config directory code out of main.cpp into src/app/platform. Handle background/foreground: save config and interface status, pause audio, cancel touch input and skip rendering while keeping the network pumped. Map the window safe area through the letterboxed presentation into TouchLayout and expose touch.GetSafeArea() so the mobile HUD stays clear of notches and gesture bars. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
11 KiB
移动端架构(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 内置资源。 - 平台层已实现(
src/app/platform/):资源根目录与配置目录;前后台切换(进后台时保存配置、暂停声音、取消输入、停止渲染,网络照常收发;Android 设SDL_ANDROID_BLOCK_ON_PAUSE=0);安全区域按逻辑分辨率换算后放进触摸布局,HUD 用touch.GetSafeArea()内缩。低内存事件目前只记日志;HUD 只在创建时读安全区;均未真机验证。 - 触摸分流已实现(
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,失焦时关闭。
- 资源根目录与配置目录(Android 配置已写入
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。
实施顺序
- APK 打包补全,资源
adb push到设备,真机进入登录界面;同时用--perf-log实测之前的性能优化。 platform/:资源根目录、前后台切换、软键盘按需打开。input/:触摸分流、虚拟摇杆、攻击键、镜头手势——可在手机上移动和战斗。mobile/:手机 HUD(状态面板、技能圈和快捷栏、右上角入口、小地图、左侧按钮)。- 界面缩放和安全区域收尾。
- 自动战斗等新增功能;iOS 打包与
app_loop拆分。
第 3、4 步大部分可在 macOS 上开发(鼠标模拟单指,触控板测双指);多指同时操作和性能需要真机验证。