godot-platform-mobile

平台：移动端

触控优先的输入、安全区域处理和电池优化是移动端开发的关键。

切勿这样做（移动端专家规则）

输入与显示

• 切勿使用鼠标事件处理触控交互 — 在移动设备上依赖 InputEventMouseButton 并不可靠。始终使用 InputEventScreenTouch 和 InputEventScreenDrag，以实现高保真的多点触控支持。
• 切勿忽略显示安全区域（刘海／开孔） — 放置在摄像头刘海后方的 UI 无法使用。查询 DisplayServer.get_display_safe_area()，并相应调整关键 UI 的位置。
• 切勿假设屏幕方向固定 — 锁定横屏游戏却不处理 size_changed 信号，会导致可折叠设备或平板方向切换时布局错乱。

电池与性能

• 切勿在应用进入后台时维持高帧率 — 应用在后台仍以 60 FPS 运行会消耗电池。使用 NOTIFICATION_APPLICATION_PAUSED 将 Engine.max_fps 降至 1。
• 切勿在移动端使用 Forward+ 渲染器 — 大多数移动 GPU 并未针对 Forward+ 优化。使用专用的 Mobile 或 Compatibility 渲染器，以获得最佳填充率。
• 切勿停用“ETC2/ASTC”纹理压缩 — 未压缩的桌面纹理会因显存耗尽而导致移动设备崩溃。

权限与操作系统集成

• 切勿假设 Android 权限会自动授予 — 你必须显式调用 OS.request_permission()，并使用 OS.get_granted_permissions() 验证权限。
• 切勿在没有权限的情况下调用手持设备振动 — 在 Android 上，除非在导出预设中启用了 VIBRATE 权限，否则振动调用会被忽略。
• 切勿在主线程上执行阻塞式 I/O — 在移动设备上保存大型文件可能触发 ANR（应用无响应）错误。请使用后台线程。

---

可用脚本

必须遵循：选择黄金路径分支，然后仅加载匹配的脚本。

黄金路径

1. 运行下方的决策树（控制方式 × 方向 × 渲染器）。
2. 触控／摇杆 → mobile_gesture_recognizer.gd（+ 输入技能，用于操作映射）。内置虚拟摇杆足够时可直接使用。
3. 布局／刘海 → adaptive_safe_area_inset.gd + orientation_layout_adaptor.gd。
4. 生命周期／热管理 → thermal_throttle_monitor.gd（暂停时降低 FPS + 管理发热）。
5. 权限／分享／IAP → 根据需要使用 android_runtime_permissions.gd、native_share_invoker.gd、mobile_iap_flow_boilerplate.gd。
6. 显存／压缩 → mobile_vram_optimizer.gd。

脚本索引

mobile_gesture_recognizer.gd

用于缩放手势和双指旋转的专家级多点触控逻辑。

adaptive_safe_area_inset.gd

使用 DisplayServer 内边距动态处理安全区域（刘海）。

thermal_throttle_monitor.gd

通过 NOTIFICATION_APPLICATION_PAUSED 管理电池与发热。

mobile_iap_flow_boilerplate.gd

适用于 Android/iOS 应用内购买（IAP）的统一样板代码。

haptic_pattern_generator.gd

用于移动端触觉反馈的高级振动模式。

android_runtime_permissions.gd

Android 权限请求与验证专家逻辑。

mobile_sensor_fusion.gd

使用加速度计与重力融合实现稳定的动作控制。

orientation_layout_adaptor.gd

在横屏／竖屏切换时自适应调整 UI。

mobile_vram_optimizer.gd

显存监控与纹理压缩强制规则。

native_share_invoker.gd

用于社交功能的操作系统级原生分享面板集成。

platform_mobile_patterns.gd / mobile_safe_area_handler.gd

其他模式 / 旧版安全区域辅助工具——仅在黄金路径脚本不足以满足需求时加载。

---

实现前的决策树

维度	选择	意味着
控制方案	点击/手势、虚拟摇杆或倾斜	手势 → mobile_gesture_recognizer.gd；摇杆 → 内置摇杆 / Control 摇杆；倾斜 → mobile_sensor_fusion.gd
方向	锁定横屏 / 竖屏 / 自适应	自适应 → 必须使用 orientation_layout_adaptor.gd + size_changed
渲染器	Mobile 或 Compatibility	手机 GPU 上绝不使用 Forward+；启用 ETC2/ASTC；在加载画面预编译着色器

触摸输入使用 InputEventScreenTouch / InputEventScreenDrag，而非鼠标模拟。

项目设置（移动端）

[rendering]
renderer/rendering_method="mobile"
textures/vram_compression/import_etc2_astc=true

[display]
window/handheld/orientation="landscape"

应用商店元数据

• 图标：512×512（Android）、1024×1024（iOS）；多分辨率截图；隐私政策；年龄分级。

发布门槛检查（原因）

1. ANR I/O — 在主线程执行大量存档/加载操作会触发 Android ANR。原因：操作系统会终止无响应的应用。门槛：使用后台线程 / WorkerThreadPool 处理磁盘 I/O。
2. 暂停时的 FPS — 应用进入后台后仍保持 60 FPS 会消耗电量并使 SoC 发热。原因：NOTIFICATION_APPLICATION_PAUSED 必须降低 Engine.max_fps（参见 thermal_throttle_monitor.gd）。
3. 权限请求时机 — 在功能实际需要时请求 Android 权限（麦克风、照片），不要在冷启动时请求。原因：Play 政策 + 用户信任；通过 android_runtime_permissions.gd 中的 OS.get_granted_permissions() 验证。

专家提示（以脚本为先）

• Android 返回键：禁用 quit_on_go_back，在 mobile_navigation_manager.gd 中处理 NOTIFICATION_WM_GO_BACK_REQUEST。
• 触觉反馈：haptic_pattern_generator.gd / mobile_haptics.gd + 导出时添加 VIBRATE 权限。
• 着色器卡顿：mobile_shader_precompiler.gd；深入了解预编译方案，优先参考 godot-shaders-basics。

深入了解（按需）

• 触摸/摇杆、安全区域、Android 返回键、触觉反馈、着色器预编译 → mobile-touch-and-expert.md

参考

渐进式展开：仅在研究特定 API 时打开官方文档链接； 将工作分配给相关领域时加载相关技能——不要预加载整个技能网络。

官方文档

• 使用 InputEvent — 事件管线说明了为何移动端应使用 InputEventScreenTouch / InputEventScreenDrag，而非模拟鼠标按键。
• 输入示例 — 多点触控、拖动和手势模式，是虚拟摇杆、缩放／旋转和滑动 HUD 的实现基础。
• 处理退出请求 — NOTIFICATION_APPLICATION_PAUSED / 恢复以及 Android 返回键（WM_GO_BACK_REQUEST）的生命周期处理，取代了桌面端的退出假设。
• DisplayServer — get_display_safe_area()、方向和虚拟键盘 API，可用于处理刘海屏、折叠屏和屏幕键盘遮挡。
• OS — request_permission() / get_granted_permissions()、功能标签和内存查询，可用于 Android 运行时门控和 VRAM 监控。
• Input — vibrate_handheld()、加速度计／重力／陀螺仪融合，以及触控↔鼠标模拟开关。
• 为 Android 导出 — 平台代码就绪后所需的权限（包括 VIBRATE）、APK/AAB 和商店打包限制。
• 为 iOS 导出 — Xcode 导出、功能以及 App Store 审核要求，可在后期发现遗漏的隐私／插件设置。
• Android 应用内购买 — 官方 Play Billing 流程；IAP 样板脚本会将其与 iOS 商店插件抽象整合。
• 3 种渲染方法简介 — 说明移动端构建为何应优先选择 Mobile 或 Compatibility，而非 Forward+，以适应填充率和功能集需求。
• 多种分辨率 — 拉伸模式、内容缩放，以及适用于手机／平板宽高比变化的方向安全布局。
• 功能标签 — 使用 mobile / android / ios 分支处理权限、分享面板和仅限平台的单例。

相关技能

前置条件

• godot-input-handling — 在发布手势识别器或虚拟摇杆前，了解共享的 InputEvent 缓冲、多点触控索引和死区。
• godot-ui-containers — 了解锚点、Margin/Box 容器和最小尺寸，确保安全区域内边距和 44–48px 触控目标的布局正确。
• godot-project-foundations — 了解 Android/iOS 导出分支所依赖的功能标签、显示拉伸和渲染器默认设置。

补充技能

• godot-adapt-desktop-to-mobile — 桌面端→触控控制映射、摇杆生成器和 UI 缩放，可与此技能深入讲解的 OS／权限 API 配合使用。
• godot-performance-optimization — 当热降频 FPS 上限和 ETC2／ASTC 仍无法满足中端设备的预算时，用于分析性能并降低 CPU／GPU 开销。
• godot-save-load-systems — 将可靠的存档管理与暂停／恢复流程挂钩，而非仅依赖桌面端退出通知。
• godot-autoload-architecture — 用于管理权限、触觉反馈、热状态监控器和常驻暂停处理程序的单例。
• godot-audio-systems — 在 APPLICATION_PAUSED 时静音／降低总线音量，避免后台音频让设备持续发热。
• godot-shaders-basics — 更高效的 CanvasItem／Spatial 着色器路径和预编译策略，可避免移动端卡顿峰值。
• godot-tweening — 在移动端输入文本时，当 OS 虚拟键盘遮挡 LineEdit，可用于平滑抬高 UI。
• godot-platform-desktop — 当同一项目在支持移动端功能标签的同时仍兼容双输入时，确保鼠标／键盘操作路径正确。

下游／使用方

• godot-export-builds — 在设备上通过触控／安全区域／权限检查后，用于签名、CI 预设和商店打包。
• godot-genre-puzzle — 使用移动端手势和安全区域 HUD 模式的点击／滑动／捏合控制方案。
• godot-economy-system — 接入 Play Billing／App Store 插件后使用的软／硬通货和经收据验证的 IAP 商品。

主技能

• godot-master — 用于发现此平台技能及同级领域技能的库路由器和镜像模块入口。