Files
AVA2/docs/MOBILE-ARCHITECTURE.md
T
shenleiandClaude Opus 5.5 260d421bde Wire attack and combo execution (mobile step 3b)
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>
2026-10-12 20:30:57 +09:00

11 KiB
Raw Blame History

移动端架构(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 上开发(鼠标模拟单指,触控板测双指);多指同时操作和性能需要真机验证。