godot-platform-mobile

name	godot-platform-mobile
description	Expert blueprint for mobile platforms (Android/iOS) covering touch controls, virtual joysticks, responsive UI, safe areas (notches), battery optimization, and app store guidelines. Use when targeting mobile releases or implementing touch input. Keywords mobile, Android, iOS, touch, InputEventScreenTouch, virtual joystick, safe area, battery, app store, orientation.

Platform: Mobile

Touch-first input, safe area handling, and battery optimization define mobile development.

NEVER Do (Expert Mobile Rules)

Input & Display

• NEVER use mouse events for touch interaction — Relying on InputEventMouseButton on mobile is unreliable. Always use InputEventScreenTouch and InputEventScreenDrag for high-fidelity multi-touch support.
• NEVER ignore display safe areas (notches/cutouts) — UI placed behind a camera notch is unusable. Query DisplayServer.get_display_safe_area() and offset critical UI accordingly.
• NEVER assume fixed orientation — Locking a landscape game without handling the size_changed signal leads to broken layouts on foldable devices or tablet orientation shifts.

Battery & Performance

• NEVER maintain high framerate when backgrounded — Keeping an app at 60 FPS in the background drains battery. Use NOTIFICATION_APPLICATION_PAUSED to drop Engine.max_fps to 1.
• NEVER use the Forward+ renderer for mobile — Most mobile GPUs are not optimized for Forward+. Use the dedicated Mobile or Compatibility renderers for optimal fill-rate.
• NEVER leave 'ETC2/ASTC' texture compression disabled — Uncompressed desktop textures will crash mobile devices due to VRAM exhaustion.

Permissions & OS Integration

• NEVER assume Android permissions are automatically granted — You MUST explicitly call OS.request_permission() and verify with OS.get_granted_permissions().
• NEVER call handheld vibration without permission — On Android, vibration calls are ignored unless the VIBRATE permission is enabled in the export preset.
• NEVER block the main thread for I/O — Large file saves on mobile can trigger ANR (Application Not Responding) errors. Use background threads.

---

Available Scripts

MANDATORY: Pick the golden-path branch, then load only the matching scripts.

Golden path

1. Run the decision tree below (control × orientation × renderer).
2. Touch / stick → mobile_gesture_recognizer.gd (+ input skill for action maps). Built-in virtual joystick when sufficient.
3. Layout / notches → adaptive_safe_area_inset.gd + orientation_layout_adaptor.gd.
4. Lifecycle / thermal → thermal_throttle_monitor.gd (pause FPS + heat).
5. Permissions / share / IAP → android_runtime_permissions.gd, native_share_invoker.gd, mobile_iap_flow_boilerplate.gd as needed.
6. VRAM / compression → mobile_vram_optimizer.gd.

Script index

mobile_gesture_recognizer.gd

Expert multi-touch logic for pinch-to-zoom and two-finger rotation.

adaptive_safe_area_inset.gd

Dynamic safe-area (notch) handling using DisplayServer insets.

thermal_throttle_monitor.gd

Battery and heat management via NOTIFICATION_APPLICATION_PAUSED.

mobile_iap_flow_boilerplate.gd

Unified boilerplate for Android/iOS In-App Purchases (IAP).

haptic_pattern_generator.gd

Advanced vibration patterns for mobile haptic feedback.

android_runtime_permissions.gd

Expert Android permission requesting and verification logic.

mobile_sensor_fusion.gd

Stable motion controls using Accelerometer and Gravity fusion.

orientation_layout_adaptor.gd

Adaptive UI swapping for Landscape/Portrait transitions.

mobile_vram_optimizer.gd

VRAM monitoring and texture compression enforcement rules.

native_share_invoker.gd

OS-level native share sheet integration for social features.

platform_mobile_patterns.gd / mobile_safe_area_handler.gd

Additional patterns / legacy safe-area helper — load only if golden-path scripts insufficient.

---

Decision tree (before implementation)

Axis	Choose	Implies
Control scheme	Tap/gesture vs virtual stick vs tilt	Gestures → mobile_gesture_recognizer.gd; stick → built-in joystick / Control stick; tilt → mobile_sensor_fusion.gd
Orientation	Locked landscape / portrait / adaptive	Adaptive → MANDATORY orientation_layout_adaptor.gd + size_changed
Renderer	Mobile vs Compatibility	Never Forward+ on phone GPUs; ETC2/ASTC on; precompile shaders on load screens

Touch input uses InputEventScreenTouch / InputEventScreenDrag — not mouse emulation.

Project settings (mobile)

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

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

App Store Metadata

• Icons: 512×512 (Android), 1024×1024 (iOS); multi-res screenshots; privacy policy; age rating.

Ship-gate checks (WHY)

1. ANR I/O — Large saves/loads on the main thread trip Android ANR. WHY: OS kills unresponsive apps. Gate: background threads / WorkerThreadPool for disk I/O.
2. Pause FPS — Backgrounded apps left at 60 FPS drain battery and heat the SoC. WHY: NOTIFICATION_APPLICATION_PAUSED must drop Engine.max_fps (see thermal_throttle_monitor.gd).
3. Permission timing — Request Android permissions at the feature moment (mic, photos), not on cold boot. WHY: Play policy + user trust; verify with OS.get_granted_permissions() via android_runtime_permissions.gd.

Expert notes (script-first)

• Android Back: disable quit_on_go_back, handle NOTIFICATION_WM_GO_BACK_REQUEST in mobile_navigation_manager.gd.
• Haptics: haptic_pattern_generator.gd / mobile_haptics.gd + export VIBRATE permission.
• Shader hitch: mobile_shader_precompiler.gd; prefer godot-shaders-basics for deep precompile recipes.

Deep dives (on demand)

• Touch/joystick, safe area, Android back, haptics, shader precompile → mobile-touch-and-expert.md

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing work to a peer domain — do not preload the whole lattice.

Official Documentation

• Using InputEvent — Event pipeline that makes InputEventScreenTouch / InputEventScreenDrag the correct mobile path instead of mouse-button emulation.
• Input examples — Multi-touch, drag, and gesture patterns behind virtual joysticks, pinch/rotate, and swipe HUDs.
• Handling quit requests — NOTIFICATION_APPLICATION_PAUSED / resume and Android back (WM_GO_BACK_REQUEST) lifecycle that replaces desktop quit assumptions.
• DisplayServer — get_display_safe_area(), orientation, and virtual keyboard APIs for notches, foldables, and OSK occlusion.
• OS — request_permission() / get_granted_permissions(), feature tags, and memory queries used by Android runtime gates and VRAM watchdogs.
• Input — vibrate_handheld(), accelerometer/gravity/gyroscope fusion, and touch↔mouse emulation toggles.
• Exporting for Android — Permissions (including VIBRATE), APK/AAB, and store packaging constraints after platform code is ready.
• Exporting for iOS — Xcode export, capabilities, and App Store gates that catch missing privacy/plugin setup late.
• Android in-app purchases — Official Play Billing flow that the IAP boilerplate script abstracts with iOS store plugins.
• Introduction to the 3 rendering methods — Why mobile builds should prefer Mobile or Compatibility over Forward+ for fill-rate and feature set.
• Multiple resolutions — Stretch modes, content scale, and orientation-safe layouts for phone/tablet aspect changes.
• Feature tags — / / branching for permissions, share sheets, and platform-only singletons.

Related Skills

Prerequisites

• godot-input-handling — Shared InputEvent buffering, multi-touch indices, and deadzones before shipping gesture recognizers or virtual sticks.
• godot-ui-containers — Anchors, Margin/Box containers, and minimum sizes so safe-area insets and 44–48px touch targets stay layout-correct.
• godot-project-foundations — Feature tags, display stretch, and renderer defaults every Android/iOS export branch depends on.

Complements

• godot-adapt-desktop-to-mobile — Desktop→touch control remap, joystick spawners, and UI scaling that pair with this skill's deeper OS/permission APIs.
• godot-performance-optimization — Profiling and CPU/GPU cuts when thermal FPS caps and ETC2/ASTC alone still miss mid-range budgets.
• godot-save-load-systems — Durable save ownership hooked to pause/resume instead of desktop-only quit notifications.
• godot-autoload-architecture — Singleton homes for permissions, haptics, thermal monitors, and always-on pause handlers.
• godot-audio-systems — Bus mute/duck on APPLICATION_PAUSED so background audio does not keep the device warm.
• godot-shaders-basics — Cheaper CanvasItem/Spatial shader paths and precompile strategies that avoid mobile hitch spikes.
• godot-tweening — Smooth UI lifts when the OS virtual keyboard covers LineEdits during mobile text entry.
• godot-platform-desktop — Keep mouse/keyboard paths correct when the same project remains dual-input beside mobile feature tags.

Downstream / consumers

• godot-export-builds — Signing, CI presets, and store packaging after touch/safe-area/permission gates pass on devices.
• godot-genre-puzzle — Tap/swipe/pinch control schemes that consume mobile gesture and safe-area HUD patterns.
• godot-economy-system — Soft/hard currency and receipt-validated IAP products once Play Billing / App Store plugins are wired.

Master

• godot-master — Library router and mirrored module entry for discovering this platform skill beside sibling domains.