---
name: mobile-development
description: Use when targeting Android/iOS — export and signing, permissions, plugins, in-app purchases, ads, app lifecycle, device features, and mobile performance
title: mobile-development
canonical_url: https://skilld.dev/gh/jame581/godotprompter/mobile-development
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/crash-debugging.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/mobile-development/references/crash-debugging.md), [references/iap-and-ads.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/mobile-development/references/iap-and-ads.md), [references/plugins.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/mobile-development/references/plugins.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/mobile-development`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/mobile-development`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/mobile-development) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/mobile-development`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/mobile-development --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/mobile-development --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Mobile Development

Ship a Godot 4.x game to Android and iOS. This covers the platform-specific deltas beyond a generic export: signing, lifecycle, permissions, plugins, IAP, device features, and the mobile renderer/perf budget.

> **Related skills:** **export-pipeline** for the generic export flow and CI/CD, **responsive-ui** for safe-area layout, **input-handling** for touch, **godot-optimization** for mobile performance, **csharp-godot** for C# mobile caveats.

---

## 1. Export & signing

**Android:** OpenJDK 17 and the Android SDK; set `Java SDK Path` + `Android SDK Path` in **Editor Settings** (per-user, not per-project). Generate a release keystore:

```bash
keytool -v -genkey -keystore mygame.keystore -alias mygame -keyalg RSA -validity 10000
```

Preset fields: **Release / Release User / Release Password** (keystore and key passwords must currently match); uncheck **Export With Debug**. **AAB is mandatory for new Play uploads.** CI env overrides: `GODOT_ANDROID_KEYSTORE_RELEASE_{PATH,USER,PASSWORD}`.

**iOS:** macOS + Xcode. Export needs an **App Store Team ID** + a reverse-DNS bundle **Identifier**; Godot generates an `.xcodeproj` you build from Xcode. Test on the iOS **simulator with the Compatibility renderer** — Forward+/Mobile support there depends on the simulator's Metal.

A **custom Gradle build** (*Project → Install Android Build Template...*; 4.8: *Project → Setup Android Build...*) is **required for v2 plugins and IAP** (Godot 4.2+). Since Godot 4.7 the **Use Gradle Build** export option is no longer marked experimental ([GH-119172](https://github.com/godotengine/godot/pull/119172)) — treat it as the standard path when you need plugins or IAP.

> ⚠️ **Changed in Godot 4.7:** Deprecated Google Play OBB expansion-file support (the `apk_expansion/*` export options) was removed from the Android export. Projects still relying on APK expansion files should move to Android App Bundles with Play Asset Delivery, or install the separate [Godot OBB plugin](https://github.com/m4gr3d/godot-obb-plugin) that now holds the old logic. See [GH-118283](https://github.com/godotengine/godot/pull/118283).

---

## 2. App lifecycle

Real `Node` notification constants: `NOTIFICATION_APPLICATION_PAUSED` (2015), `NOTIFICATION_APPLICATION_RESUMED` (2014), `NOTIFICATION_APPLICATION_FOCUS_IN`/`_OUT` (2016/2017), `NOTIFICATION_WM_GO_BACK_REQUEST` (1007, Android Back). **There is no `WM_CLOSE_REQUEST` on mobile.** Autosave on PAUSED; **iOS gives ~5 s** after pause to finish work before it kills the app.

### GDScript

```gdscript
func _notification(what: int) -> void:
    match what:
        NOTIFICATION_APPLICATION_PAUSED:
            SaveManager.save_game() # App backgrounded — persist now.
        NOTIFICATION_WM_GO_BACK_REQUEST:
            _confirm_quit()         # Android Back button.
```

### C# Equivalent

The docs only show `NotificationWMCloseRequest` verbatim; these PascalCase names follow the same convention.

```csharp
public override void _Notification(int what)
{
    switch ((long)what)
    {
        case NotificationApplicationPaused:
            SaveManager.SaveGame(); // App backgrounded — persist now.
            break;
        case NotificationWMGoBackRequest:
            ConfirmQuit();          // Android Back button.
            break;
    }
}
```

### Picture-in-Picture (Android, Godot 4.7+)

`DisplayServer.pip_mode_enter(window_id = 0)` enters picture-in-picture mode; `is_in_pip_mode(window_id = 0)` reports the current state; `pip_mode_set_aspect_ratio(numerator, denominator, window_id = 0)` sets the PiP window's aspect ratio; `pip_mode_set_auto_enter_on_background(auto_enter_on_background, window_id = 0)` enters PiP automatically when the app goes to the background. Transitions arrive as `Node` notifications: `NOTIFICATION_APPLICATION_PIP_MODE_ENTERED` (2019) / `NOTIFICATION_APPLICATION_PIP_MODE_EXITED` (2020). All Android-only.

```gdscript
func _ready() -> void:
    DisplayServer.pip_mode_set_aspect_ratio(16, 9)
    DisplayServer.pip_mode_set_auto_enter_on_background(true)

func _notification(what: int) -> void:
    match what:
        NOTIFICATION_APPLICATION_PIP_MODE_ENTERED:
            _set_minimal_hud(true)  # PiP window is tiny — hide non-essential UI.
        NOTIFICATION_APPLICATION_PIP_MODE_EXITED:
            _set_minimal_hud(false)
```

```csharp
public override void _Ready()
{
    DisplayServer.PipModeSetAspectRatio(16, 9);
    DisplayServer.PipModeSetAutoEnterOnBackground(true);
}

public override void _Notification(int what)
{
    switch ((long)what)
    {
        case NotificationApplicationPipModeEntered:
            SetMinimalHud(true);  // PiP window is tiny — hide non-essential UI.
            break;
        case NotificationApplicationPipModeExited:
            SetMinimalHud(false);
            break;
    }
}
```

---

## 3. Permissions

Declare each permission in the export preset as `permissions/<name>`; request it at runtime with `OS.request_permission(name)`. The result arrives via `MainLoop`'s `on_request_permissions_result(permission, granted)`. The permission **must also be enabled in the preset**, not just requested.

### GDScript

```gdscript
func _ready():
    if "android.permission.POST_NOTIFICATIONS" not in OS.get_granted_permissions():
        OS.request_permission("android.permission.POST_NOTIFICATIONS")
    get_tree().on_request_permissions_result.connect(_on_perm_result)

func _on_perm_result(permission: String, granted: bool):
    print("%s granted: %s" % [permission, granted])
```

### C# Equivalent

```csharp
// Contains() on string[] needs: using System.Linq;
public override void _Ready()
{
    if (!OS.GetGrantedPermissions().Contains("android.permission.POST_NOTIFICATIONS"))
        OS.RequestPermission("android.permission.POST_NOTIFICATIONS");
    GetTree().OnRequestPermissionsResult += OnPermResult;
}

private void OnPermResult(string permission, bool granted)
    => GD.Print($"{permission} granted: {granted}");
```

---

## 4. Calling Android APIs (JavaClassWrapper) — Godot 4.4+

**Godot 4.4+.** `JavaClassWrapper.wrap("<java.class>")` (present earlier, but only practical from 4.4) calls Java/Kotlin classes with no plugin; the `AndroidRuntime` singleton, new in 4.4, (`Engine.get_singleton("AndroidRuntime")`) exposes `getActivity()`, `getApplicationContext()`, and `createRunnableFromGodotCallable(callable)`.

The simpler cross-platform alternative needs no 4.4: `Input.vibrate_handheld(duration_ms, amplitude)` (requires the `VIBRATE` permission; iOS needs iOS 13+). See [Plugins](https://skilld.dev/api/skills-raw/jame581/godotprompter/mobile-development/references/plugins.md) for the full JavaClassWrapper/AndroidRuntime API, Toast/Intent recipes, and inner-class syntax.

### GDScript

```gdscript
# Godot 4.4+ — requires the VIBRATE permission in the export preset.
func vibrate_ms(duration_ms: int) -> void:
    if Engine.has_singleton("AndroidRuntime"):
        var runtime := Engine.get_singleton("AndroidRuntime")
        var context := runtime.getApplicationContext()
        var vibrator := context.getSystemService("vibrator")
        if vibrator.hasVibrator():
            var Effect = JavaClassWrapper.wrap("android.os.VibrationEffect")
            var effect = Effect.createOneShot(duration_ms, Effect.DEFAULT_AMPLITUDE)
            vibrator.vibrate(effect)
```

### C# Equivalent

The docs are GDScript-only here; the exact C# Variant-marshaling chain (`.AsGodotObject()` on each Java return) is untested against a device — verify on a real 4.4+ Android build.

```csharp
// Godot 4.4+ — requires the VIBRATE permission in the export preset.
public void VibrateMs(int durationMs)
{
    if (!Engine.HasSingleton("AndroidRuntime")) return;
    var runtime = Engine.GetSingleton("AndroidRuntime");
    var context = runtime.Call("getApplicationContext").AsGodotObject();
    var vibrator = context.Call("getSystemService", "vibrator").AsGodotObject();
    if (vibrator.Call("hasVibrator").AsBool())
    {
        var effect = JavaClassWrapper.Wrap("android.os.VibrationEffect");
        var oneShot = effect.Call("createOneShot", durationMs, effect.Get("DEFAULT_AMPLITUDE"));
        vibrator.Call("vibrate", oneShot);
    }
}
```

### Implementing Java Interfaces from Script (Godot 4.7+)

`JavaClassWrapper.create_proxy(object: Object, interfaces: PackedStringArray) -> JavaObject` implements the given Java interfaces using a Godot object — the object's method signatures must match the Java interfaces' method signatures, and Java calls route to the matching method. `create_sam_callback(sam_interface: String, callable: Callable) -> JavaObject` covers single-abstract-method (SAM) interfaces with a `Callable` matching the SAM method's parameters and return type. Both return `null` on every platform except Android.

```gdscript
class PrintProxy:
    func println(content: String) -> void:
        print(content)

func _demo() -> void:
    var print_proxy := PrintProxy.new()
    var printer := JavaClassWrapper.create_proxy(print_proxy, ["android.util.Printer"])
    printer.println("Hello Godot World!")

    var cb := func(content: String) -> void: print(content)
    var callback := JavaClassWrapper.create_sam_callback("android.util.Printer", cb)
    callback.println("Hello Godot World!")
```

The docs are GDScript-only here. `CreateProxy` matches methods by their registered name, so a C# implementation class would need method names matching the Java interface exactly — prefer `CreateSamCallback` from C#:

```csharp
var cb = Callable.From((string content) => GD.Print(content));
var callback = JavaClassWrapper.CreateSamCallback("android.util.Printer", cb);
callback.Call("println", "Hello Godot World!");
```

---

## 5. Device features & safe area

`DisplayServer.get_display_safe_area() -> Rect2i` (Android/iOS) returns the usable region inside notches/cutouts; `get_display_cutouts()` (Android) lists the cutout rects. Motion sensors live on `Input` (`get_accelerometer/gravity/gyroscope/magnetometer`, returning `Vector3`, Android/iOS only).

### GDScript

```gdscript
func _ready():
    var safe := DisplayServer.get_display_safe_area() # Rect2i
    $UI.position = safe.position
    $UI.size = safe.size
```

### C# Equivalent

```csharp
public override void _Ready()
{
    Rect2I safe = DisplayServer.GetDisplaySafeArea();
    var ui = GetNode<Control>("UI");
    ui.Position = safe.Position;
    ui.Size = safe.Size;
}
```

Native file dialogs (`DisplayServer.file_dialog_show()`) are supported on Android; since Godot 4.7 the native file picker works on all devices — the Android version check gating `FEATURE_NATIVE_DIALOG_FILE` support was removed ([GH-115257](https://github.com/godotengine/godot/pull/115257)).

> **Godot 4.7+:** For on-screen touch joysticks, use the built-in `VirtualJoystick` Control node instead of a hand-rolled `TouchScreenButton` rig — see **input-handling** (`references/touch.md`, "VirtualJoystick (Godot 4.7+)") for the full API.

### Device Orientation Signal (Godot 4.7+)

`DisplayServer.orientation_changed(orientation: int)` (Android/iOS) fires when the device orientation changes: `1` portrait, `2` landscape, `0` undefined.

```gdscript
func _ready() -> void:
    DisplayServer.orientation_changed.connect(_on_orientation_changed)

func _on_orientation_changed(orientation: int) -> void:
    _relayout_hud(orientation == 2)  # 1 portrait, 2 landscape, 0 undefined.
```

```csharp
public override void _Ready()
{
    DisplayServer.Singleton.Connect(DisplayServer.SignalName.OrientationChanged,
        Callable.From((long orientation) => RelayoutHud(orientation == 2)));
}
```

> **Changed in Godot 4.8:** The `orientation` parameter is now typed as the new `DisplayServer.SensorOrientation` enum (`SENSOR_ORIENTATION_UNDEFINED` 0, `_PORTRAIT` 1, `_LANDSCAPE` 2) and the docs say *screen* orientation. The values are unchanged, so the handlers above keep working. Code that uses the generated C# `OrientationChanged` event may need updating, since its delegate type changes (per the draft 4.8 migration guide; unconfirmed).

---

## 6. Mobile performance & renderer

Use the **Mobile** (or **Compatibility**) renderer; prefer Compatibility on the iOS simulator. Enable `rendering/textures/vram_compression/import_etc2_astc = true` (ETC2/ASTC) for Android texture compression. Keep single-arch APKs small; AABs split per-device automatically. Defer deep draw-call/batching tuning to **godot-optimization**.

---

## 7. C# on mobile

C# Android/iOS export is **Godot 4.2+ but experimental**. **Android C# export requires .NET 9+** (with Godot 4.5); iOS export only from macOS (the export also builds arm64 + x86_64 simulator assemblies). **C# cannot export to Web.** Test the C# export pipeline early — it is the riskiest part of a C# mobile project.

> **Changed in Godot 4.8:** Every C# project, not only Android, needs **.NET 10** (`net10.0`); 4.8 writes `net10.0` for Android too. The ".NET 9+" above applies to Godot 4.5 to 4.7.

> **Deeper:** [Plugins (Android v2 / iOS)](https://skilld.dev/api/skills-raw/jame581/godotprompter/mobile-development/references/plugins.md) · [In-app purchases & ads](https://skilld.dev/api/skills-raw/jame581/godotprompter/mobile-development/references/iap-and-ads.md) · [Crash debugging](https://skilld.dev/api/skills-raw/jame581/godotprompter/mobile-development/references/crash-debugging.md)

---

## Implementation Checklist

- [ ] Release keystore (Android) / provisioning + Team ID (iOS) configured
- [ ] AAB for Play uploads; Gradle build installed if using v2 plugins or IAP
- [ ] Autosave wired to `NOTIFICATION_APPLICATION_PAUSED` (iOS ~5 s budget respected)
- [ ] Required permissions enabled in the preset AND requested at runtime
- [ ] JavaClassWrapper usage labeled Godot 4.4+; fallbacks for 4.3 if needed
- [ ] UI anchored inside `get_display_safe_area()`; notch/cutout handled
- [ ] Mobile/Compatibility renderer + ETC2/ASTC compression enabled
- [ ] C# projects: verified .NET 9+ for Android export (Godot 4.8: .NET 10)
- [ ] Play OBB/APK expansion files moved to App Bundles with Play Asset Delivery, or the Godot OBB plugin installed (built-in support removed in Godot 4.7)
- [ ] PiP (Android): aspect ratio + auto-enter configured; HUD reacts to the PIP_MODE notifications (Godot 4.7+)
