| 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
InputEventMouseButtonon mobile is unreliable. Always useInputEventScreenTouchandInputEventScreenDragfor 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_changedsignal 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_PAUSEDto dropEngine.max_fpsto 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 withOS.get_granted_permissions(). - NEVER call handheld vibration without permission — On Android, vibration calls are ignored unless the
VIBRATEpermission 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.
Godot 4.7: Mobile
- Built-in virtual joystick — native touch joystick without plugins for mobile builds.
- HDR output on iOS and supported Android devices — test tonemapping on HDR panels.
Available Scripts
MANDATORY: Pick the golden-path branch, then load only the matching scripts.
Golden path
- Run the decision tree below (control × orientation × renderer).
- Touch / stick →
mobile_gesture_recognizer.gd(+ input skill for action maps). Built-in virtual joystick when sufficient. - Layout / notches →
adaptive_safe_area_inset.gd+orientation_layout_adaptor.gd. - Lifecycle / thermal →
thermal_throttle_monitor.gd(pause FPS + heat). - Permissions / share / IAP →
android_runtime_permissions.gd,native_share_invoker.gd,mobile_iap_flow_boilerplate.gdas needed. - 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)
- ANR I/O — Large saves/loads on the main thread trip Android ANR. WHY: OS kills unresponsive apps. Gate: background threads /
WorkerThreadPoolfor disk I/O. - Pause FPS — Backgrounded apps left at 60 FPS drain battery and heat the SoC. WHY:
NOTIFICATION_APPLICATION_PAUSEDmust dropEngine.max_fps(seethermal_throttle_monitor.gd). - 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()viaandroid_runtime_permissions.gd.
Expert notes (script-first)
- Android Back: disable
quit_on_go_back, handleNOTIFICATION_WM_GO_BACK_REQUESTin mobile_navigation_manager.gd. - Haptics: haptic_pattern_generator.gd / mobile_haptics.gd + export
VIBRATEpermission. - Shader hitch: mobile_shader_precompiler.gd; prefer
godot-shaders-basicsfor 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/InputEventScreenDragthe 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 —
mobile/android/iosbranching 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_PAUSEDso 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.