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.getdisplaysafe_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 NOTIFICATIONAPPLICATIONPAUSED 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.requestpermission() and verify with OS.getgranted_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 → mobilegesturerecognizer.gd (+ input skill for action maps). Built-in virtual joystick when sufficient.
3. Layout / notches → adaptivesafeareainset.gd + orientationlayout_adaptor.gd.
4. Lifecycle / thermal → thermalthrottlemonitor.gd (pause FPS + heat).
5. Permissions / share / IAP → androidruntimepermissions.gd, nativeshareinvoker.gd, mobileiapflow_boilerplate.gd as needed.
6. VRAM / compression → mobilevramoptimizer.gd.

Script index

[mobilegesturerecognizer.gd](scripts/mobilegesturerecognizer.gd)

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

[adaptivesafeareainset.gd](scripts/adaptivesafeareainset.gd)

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

[thermalthrottlemonitor.gd](scripts/thermalthrottlemonitor.gd)

Battery and heat management via NOTIFICATIONAPPLICATIONPAUSED.

[mobileiapflowboilerplate.gd](scripts/mobileiapflowboilerplate.gd)

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

[hapticpatterngenerator.gd](scripts/hapticpatterngenerator.gd)

Advanced vibration patterns for mobile haptic feedback.

[androidruntimepermissions.gd](scripts/androidruntimepermissions.gd)

Expert Android permission requesting and verification logic.

[mobilesensorfusion.gd](scripts/mobilesensorfusion.gd)

Stable motion controls using Accelerometer and Gravity fusion.

[orientationlayoutadaptor.gd](scripts/orientationlayoutadaptor.gd)

Adaptive UI swapping for Landscape/Portrait transitions.

[mobilevramoptimizer.gd](scripts/mobilevramoptimizer.gd)

VRAM monitoring and texture compression enforcement rules.

[nativeshareinvoker.gd](scripts/nativeshareinvoker.gd)

OS-level native share sheet integration for social features.

[platformmobilepatterns.gd](scripts/platformmobilepatterns.gd) / [mobilesafeareahandler.gd](scripts/mobilesafeareahandler.gd)

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

Decision tree (before implementation)

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: NOTIFICATIONAPPLICATIONPAUSED must drop Engine.maxfps (see thermalthrottle_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.getgrantedpermissions() via androidruntimepermissions.gd.

Expert notes (script-first)

• Android Back: disable quitongoback, handle NOTIFICATIONWMGOBACKREQUEST in [mobilenavigationmanager.gd](scripts/mobilenavigation_manager.gd).
• Haptics: [hapticpatterngenerator.gd](scripts/hapticpatterngenerator.gd) / [mobilehaptics.gd](scripts/mobilehaptics.gd) + export VIBRATE permission.
• Shader hitch: [mobileshaderprecompiler.gd](scripts/mobileshaderprecompiler.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](references/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 — NOTIFICATIONAPPLICATIONPAUSED / resume and Android back (WMGOBACK_REQUEST) lifecycle that replaces desktop quit assumptions.
• DisplayServer — getdisplaysafearea(), orientation, and virtual keyboard APIs for notches, foldables, and OSK occlusion.
• OS — requestpermission() / getgrantedpermissions(), feature tags, and memory queries used by Android runtime gates and VRAM watchdogs.
• Input — vibratehandheld(), 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 / ios 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.