godot-adapt-desktop-to-mobile

改造：桌面端转移动端

将桌面游戏移植到移动平台的专家指南。

切勿

• 切勿直接使用鼠标位置 — 触摸没有“悬停”状态。将 mouse_motion 替换为 screen_drag，并检查 InputEventScreenTouch.pressed。
• 切勿保留过小的 UI 元素 — Apple HIG 要求触控目标至少为 44pt。Android Material 要求至少为 48dp。将按钮放大 2-3 倍。
• 切勿忽略手指遮挡 — 用户的手指会遮挡半径为 50-100px 的区域。将关键信息放在触控控件上方，而不是下方。
• 切勿在应用进入后台时仍以全性能运行 — 会耗尽电量的应用可能被移动操作系统终止。应用失去焦点时，暂停物理模拟，并将 FPS 降至 1-5。
• 切勿使用仅限桌面端的功能 — 移动端没有鼠标悬停、右键、键盘快捷键和滚轮。请提供触控替代方案。

---

可用脚本

必须：在实现相应模式之前，先阅读对应脚本。不要在正文中粘贴摇杆/手势/UI 教程。

dynamic_joystick_spawner.gd

移动摇杆必用 — 摇杆会出现在用户触摸屏幕左半侧的位置（优先于固定位置方案）。

virtual_joystick.gd

固定底座摇杆 Control — UI 美术需要静态摇杆底座时使用；否则优先使用 dynamic_joystick_spawner。

gesture_combo_system.gd

滑动/捏合必用 — 将持续时间/距离/多点触控比例转换为信号。

mobile_ui_adapter.gd

Control 重映射必用 — 调整桌面 HUD 的大小和锚点，以适配拇指触及范围和屏幕密度。

resolution_scaler.gd

自适应调整 scaling_3d_scale，在保持 2D UI 清晰的同时维持 60FPS。

battery_saver_mode.gd

必用 — NOTIFICATION_APPLICATION_PAUSED → Engine.max_fps = 1 并暂停物理模拟。

ui_safe_area_margins.gd

使用 DisplayServer.get_display_safe_area() 为刘海/挖孔屏添加边距。

touch_camera_pan_zoom.gd

单指平移 + 双指捏合缩放 Camera2D。

haptic_feedback_manager.gd

Input.vibrate_handheld + iOS 插件钩子模式。

mobile_shader_fallback.gd

在性能较弱的移动端渲染器上移除 SSS/clearcoat/重型着色效果。

on_screen_keyboard_handler.gd

虚拟键盘遮挡时 → 使用补间动画将 UI 上移。用于 LineEdit/TextEdit 获得焦点时 — 不能替代 HUD 缩放。

mobile_ui_adapter.gd 与 on_screen_keyboard_handler 的区别

需求	脚本
调整 HUD 大小和锚点、生成虚拟摇杆、适配拇指触及范围和屏幕密度	mobile_ui_adapter
操作系统虚拟键盘遮挡获得焦点的文本字段	on_screen_keyboard_handler（通常两者都会用：adapter 负责布局，OSK handler 负责文本字段）

offline_save_sync.gd

必用 — 在应用暂停时持久化数据（在移动端，WM_CLOSE 不可靠）。

---

触控控制方案

决策矩阵

类型	推荐控制方式	脚本
平台跳跃游戏	虚拟摇杆（左侧）+ 跳跃按钮（右侧）	dynamic_joystick_spawner / virtual_joystick
俯视角射击游戏	双摇杆（左侧移动，右侧瞄准）	dynamic_joystick_spawner ×2
回合制游戏	直接点击单位/格子	gesture_combo_system（点击）
益智游戏	点击、滑动、捏合	gesture_combo_system
卡牌游戏	拖放	mobile_ui_adapter + drag Controls
赛车游戏	倾斜或点击左/右侧	platform-mobile / Input sensors

移植流程（按顺序）

1. MANDATORY mobile-port-checklist.md — 在重新映射控件前，确认移植前的清单和关卡项。
2. 将悬停／右键／滚动替换为对应的触控操作（决策矩阵）。
3. MANDATORY 为 44–48dp 触控目标配置安全区域和 mobile_ui_adapter；确保关键 HUD 位于手指上方。
4. 在暂停／恢复时接入 battery_saver_mode + offline_save_sync。
5. 启用 resolution_scaler + mobile_shader_fallback，直到设备 FPS 稳定。
6. 深入处理 Android/iOS 内购／权限 → godot-platform-mobile（控件／UI／性能关卡通过前，Do NOT Load 完整平台技能）。

边缘情况（检查清单）

• 双摇杆上的多点触控索引冲突 — 按摇杆分别跟踪 event.index
• 屏幕键盘遮挡 LineEdit → on_screen_keyboard_handler.gd
• 后台终止且未保存 → offline_save_sync.gd（WM_CLOSE 在移动设备上不可靠）
• 刘海区域裁切 → ui_safe_area_margins.gd
• 手掌触碰屏幕边缘 — 忽略边缘约 50px 范围内的点击
• 桌面测试构建：同时处理 InputEventMouseButton 和 InputEventScreenTouch

设备测试（发布前）

• 在实际设备上测试 44–48dp 触控目标
• HUD 位于手指上方（遮挡范围 50–100px）
• 暂停时降低 FPS，并在进入后台时保存
• 启用 resolution_scaler.gd + mobile_shader_fallback.gd 后 FPS 稳定
• 竖屏和横屏安全区域

完整移植方案 → mobile-port-deep.md。

深度方案

移植超出决策矩阵范围时，MANDATORY 阅读 mobile-port-deep.md。首次重新映射控件时，Do NOT Load 此文档。

专家技巧（简要）

• 通过 await RenderingServer.frame_post_draw + 视口图像截取商店截图。
• 调试叠加层：OS.get_memory_info() — 监控期间不要频繁执行开销大的内存分配。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作路由到对口领域时再加载相关技能 — 不要预加载整个技能网络。

官方文档

• 使用 InputEvent — 事件管线，以及为什么在移动设备上，InputEventScreenTouch / InputEventScreenDrag 会取代对悬停和鼠标移动的假设。
• 鼠标和输入坐标 — 视口与画布变换，确保触摸位置和桌面鼠标测试落在相同的 UI/游戏空间中。
• 输入示例 — 可用于虚拟摇杆、滑动和捏合手势的实用多点触控与拖动模式。
• 多种分辨率 — 拉伸模式、宽高比和内容缩放，让手机/平板布局中的触控目标保持清晰易读。
• 分辨率缩放 — 自适应画质在移动 GPU 无法满足帧预算时使用的 scaling_3d_scale / FSR 权衡。
• 3 种渲染方法简介 — 为什么移植项目应优先选择 Mobile 或 Compatibility，而非 Forward+，以满足填充率和功能集方面的需求。
• 处理退出请求 — 移动操作系统使用的 NOTIFICATION_APPLICATION_PAUSED / 恢复生命周期机制，而不是依赖可靠的窗口关闭保存。
• DisplayServer — get_display_safe_area()、虚拟键盘 API，以及刘海屏和屏幕键盘遮挡背后的屏幕指标。
• 使用容器 — Margin/Box/Grid 容器约定，用于安全区域内边距和大型触控目标。
• TouchScreenButton — 内置屏幕按钮，无需自定义命中测试即可触发 Input 操作。
• 导出到 Android — 控件/UI 移植就绪后所需的权限、APK/AAB 和设备测试关卡。
• 导出到 iOS — Xcode 导出、功能配置和 App Store 限制，这些要求可能会在后期发现桌面端遗留问题。

相关技能

前置要求

• godot-input-handling — 构建虚拟摇杆或滑动连招前，共享 InputEvent 缓冲、死区和多点触控手势的基础。
• godot-ui-containers — 锚点、容器和最小尺寸，确保 44–48px 的触控目标和安全区域边距符合布局要求。
• godot-project-foundations — 每个移植分支所依赖的功能标签（mobile/android/ios）、显示拉伸和渲染器默认设置。

补充内容

• godot-platform-mobile — 完成桌面端到触控操作的映射后，深入了解 Android/iOS 平台 API（权限、IAP、热管理）。
• godot-performance-optimization — 当自适应 scaling_3d_scale 和材质回退方案仍不够时，进行性能分析并降低 CPU/GPU 开销。
• godot-save-load-systems — 构建持久化存档管理机制，使其响应暂停/恢复，而非仅依赖桌面端退出通知。
• godot-camera-systems — 用于单指平移和双指捏合控制器的 Camera2D/3D 跟随与缩放约定。
• godot-shaders-basics — 为移动 GPU 移除仅限桌面端的视觉功能时，采用开销更低的 CanvasItem/Spatial 着色器方案。
• godot-3d-materials — StandardMaterial3D 功能标志（SSS、clearcoat）；mobile_shader_fallback 会在性能较弱的渲染器上禁用这些功能。
• godot-tweening — 当操作系统虚拟键盘遮挡 LineEdits/TextEdits 时，平滑抬升 UI。
• godot-autoload-architecture — 为触觉反馈、省电模式和离线存档同步管理器设置单例。

下游 / 使用方

• godot-export-builds — 在设备上通过触控/UI/性能门槛后，进行打包、签名并配置 CI 导出预设。
• godot-platform-desktop — 当同一项目在移动端适配后仍支持双输入时，确保桌面端鼠标/键盘操作路径正常运行。
• godot-genre-puzzle — 使用此技能中的手势和 UI 缩放模式的点击/滑动/捏合控制方案。

主索引

• godot-master — 知识库路由器和镜像模块入口，用于在相邻领域中查找此适配技能。