Files
AVA2/docs/MOBILE-ARCHITECTURE.md

16 KiB
Raw Permalink Blame History

移动端架构(2026-10-12)

2026-10-13 交互更新:摇杆闲置隐藏、真实落点与显示中心分离;技能独立多指、拖动瞄准与冷却重试,物品图标抬高、快捷按钮完整热区,以及 NPC/物品接近交互。实现文件、测试和限制见 移动交互调整。

本文是引入移动端(Android 优先,iOS 其后)后的目标结构和实施顺序。游戏逻辑、网络、渲染、资源各层保持现状;变化集中在平台打包、主程序的平台适配与触屏输入、以及 Python 界面的手机 HUD 叠加层。标为"新增"或"拆分"的部分尚未实现。

现状

  • android/build.sh 可以编出 arm64 调试 APK(SDL3 + FreeType 自动编译,16 KB 页对齐),连接手机时自动安装启动;真机运行尚未验证。
  • android/push_assets.py 把资源(assets/loose,其上叠加按打包清单生成的 build/dev/test-rundir,同名文件以 pack 版本为准;再叠加 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() 内缩。低内存事件目前只记日志;均未真机验证。
  • 触摸分流已实现(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 布局已实现(PORT-PLAN「Mobile step 4」):左上头像圆框 + 等级名字 + HP/SP/体力条,buff 图标在其下;顶部居中沿用原版目标栏;右上一排圆形入口(好友、角色、背包、菜单)+ 原版小地图 + 活动图标;左侧竖排按钮(任务、技能、表情、聊天)和原版提示按钮;右下攻击键 + 两圈 8 个快捷格(当前快捷页,可切第 1-3 页)+ 换页、上下马、拾取;底部药水栏(第 4 快捷页,全局格 24-31)和经验细条。移动模式下 PC 任务栏隐藏。圆框由原生 CDisc(wndMgr.RegisterDisc)几何绘制,图标只用 AVA2 自己的贴图,不用其他服的美术。小地图仍是原版圆形、按钮文字为英文、未真机验证。
  • 软键盘已改为仅在输入框获得焦点(ime.EnableCaptureInput)或聊天打开时弹出。
  • src/app/main.cpp 共 2418 行,启动、主循环、登录和调试参数都在其中。
  • Android 默认渲染缩放 0.75。
  • 界面缩放已实现(PORT-PLAN「Mobile step 5」):手机/平板按屏幕宽高比和像素密度自动选逻辑分辨率(高 600–768,宽随比例,至少 1024),不再给 1024×768 加黑边,也不改写 metin2.cfg;--ui-height / AVA2_UI_HEIGHT 可改高度;桌面可用 --phone 2400x1080@2.75 --safe-insets 50,0,0,24 模拟。安全区变化(如旋转 180 度刘海换边)时 HUD 实时重建并重新摆放原版窗口。运行中窗口尺寸变化(分屏、折叠屏)仍沿用启动时的逻辑分辨率;尚无游戏内界面大小选项;未真机验证。

分层结构

┌──────────────────────────────────────────────────────────────┐
│ 平台打包     android/ (Gradle + SDLActivity + build.sh)      │  新增
│              ios/ (build.sh)      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 时再拆。(已完成:src/app/app_loop.{h,cpp},主体为每帧挂起一次的协程;main.cpp 只选择 SDL 回调或经典循环。)

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(ios/build.sh,资源用 ios/push_assets.py 小写拷入 Documents) 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++ 手势识别
技能圈旁 自动狩猎(AUTO 键) 原版没有 客户端新功能:轻点开关、长按设置;已完成(第 6 步)

注意事项:

  • 原版窗口按 800×600 设计;移动端逻辑分辨率取高 600~720 再整体放大,按钮点击范围不小于手指大小。
  • 20:9 等宽屏需按安全区域布局。
  • 不使用其他服务器的界面美术;图标用 AVA2 自带技能/道具图标,按钮底框和摇杆另制。

物品与窗口手势

原版窗口不改,触摸由 src/app/input/touch_router 翻译成原版鼠标事件,经窗口管理器和移植的 CSlotWindow 鼠标处理进入 uiinventory.py 等原版脚本:

手势 翻译成 原版效果
手指按住不动 鼠标移到该处 物品格显示原版物品提示
点按 在按下点依次发移动、左键按下、左键抬起 拿起物品(图标跟随);再点空格/装备格/其他窗口即放下、穿戴、交易放入
拖动(超过 tap_slop) 在起点按下左键,随后跟随移动,抬起即松开 原版拖拽:换格、拖到装备栏、拖出窗口丢弃、拖到商店出售
双击(300 ms、40 px 内) 原版左键双击 OnUseSlot:使用药水、穿戴/卸下装备
长按物品格(450 ms) touch.SetLongPressEvent 回调 提示保持显示,弹出 ui_mobile_actions.ItemActionSheet:使用、拆分、加入快捷栏、关闭
长按背包空格子(450 ms) 同一回调,isEmpty=1 面板只有“整理”和“关闭”;整理调用原版整理按钮 separateButton 的事件(确认框 → /click_sort_items)
  • 长按面板的按钮调用原版槽位事件。“使用”调用 OnUseSlot;“拆分”和“加入快捷栏”通过 touch.SetVirtualKey 临时按住 Shift / Ctrl,再调用 OnSelectItemSlot,走原版的修饰键分支。
  • 点面板外任意处关闭面板。长按其他窗口的空格子、或被大件物品占住的格子,仍按普通按下处理。
  • 手指抬起后指针移到屏幕外(拿着物品时除外),以免提示一直停留。被取消的触摸、点地面(世界点击)结束后也一样。
  • 快捷栏和药水栏:每次点按的左键按下都会触发一次使用;第二下被识别成双击时只多发一个双击,快捷格没有双击事件,所以连点 N 次就是用 N 次。

系统边缘与取消

以下交互思路参考 jhaizhou-ops/d2r-mobile(MIT),只借鉴想法,没有拷贝代码:

  • 底部安全区(手势导航条)里落下的世界手指不拖镜头,也不算点地面。
  • 系统取消某一根手指(SDL_EVENT_FINGER_CANCELED,例如边缘手势从它下面开始)时只释放这一根,其他手指不受影响。摇杆手指被取消后,摇杆保持原方向 joy_reacquire_ms(300 ms);这段时间内在原基点 1.5 倍半径内落下的手指接管摇杆,基点不变。
  • 攻击键点得比一帧还快时,松开推迟到下一帧,保证原版 player 模块至少看到一次按下。
  • 没有采用的:技能拖动瞄准(Metin2 技能按目标/朝向释放)、点面板外关闭所有窗口(点世界要移动角色)、手柄自动切换(以后再说)。
  • 技能:技能圈和底部栏是原版快捷栏格,点按即使用(第 4 步)。从技能窗口把技能拖到快捷栏用的是同一套槽位拖拽,但还没有单独测试。

目录变化

  • 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. 自动战斗等新增功能(自动狩猎已完成,见 PORT-PLAN);iOS 打包与 app_loop 拆分(均已完成,模拟器验证到游戏场景;真机签名安装未测)。

第 3、4 步大部分可在 macOS 上开发(鼠标模拟单指,触控板测双指);多指同时操作和性能需要真机验证。