Android Export, End to End

Module 7 · Lesson 1 · ~45 min · one-time setup + repeatable build

This is the lesson that takes you from "it runs on my laptop" to "I handed my phone to a friend and they played it." Once done, you have a reproducible one-command build. You'll invoke it 50+ times before ship — the investment pays back within a week.

Prerequisites (macOS)

1. Java 17 JDK — brew install openjdk@17, then follow the post-install sudo ln -sfn note brew prints. Verify with java -version.
2. Android Studio — developer.android.com/studio. You don't use the IDE, you need its SDK manager. Install it, launch once, let it finish the first-run setup.
3. Android SDK components — in Android Studio → More Actions → SDK Manager, install:
   • Android SDK Platform-Tools (gives you adb)
   • Android SDK Build-Tools (latest)
   • Android SDK Command-line Tools (latest)
   • Android SDK Platform for the latest API (e.g. 34)
4. Godot — 4.x stable from godotengine.org. The standard download, not the .NET version.

Note the SDK path — it's usually ~/Library/Android/sdk. You'll paste it into Godot.

Telling Godot where Android lives

Open Godot. Editor → Editor Settings → Export → Android. Fill in:

• Android SDK Path: /Users/YOU/Library/Android/sdk
• Debug Keystore: leave blank for now, we'll generate one
• Java SDK Path: the JDK 17 install from brew — /opt/homebrew/opt/openjdk@17

Generating a debug keystore

Android requires every APK to be signed. For testing on your own phone, a "debug" keystore is fine — it's just a throwaway key. Create one:

cd ~/.godot
keytool -keyalg RSA -genkeypair -alias androiddebugkey \
  -keypass android -keystore debug.keystore \
  -storepass android -dname "CN=Android Debug,O=Android,C=US" \
  -validity 9999 -deststoretype pkcs12

Now point Godot at ~/.godot/debug.keystore in Editor Settings. You'll generate a release keystore later for the Play Store — that one you guard with your life (if you lose it, you can never update your app).

Installing the export templates

Export templates are the pre-built platform binaries Godot bundles your game into. Editor → Manage Export Templates → Download and Install. ~700MB download, ~2GB on disk. Grab a coffee.

Once installed, templates live in ~/Library/Application Support/Godot/export_templates/4.x.stable/. If you upgrade Godot, re-download.

Your first Android export preset

Project → Export → Add → Android. A preset appears. The key fields:

• Name: "Android Debug"
• Runnable: ✓ — lets you one-click deploy to a connected phone
• Export Path: build/lexicon-duel-debug.apk (create the build/ folder in your project)
• Options → Package → Unique Name: com.yourname.lexiconduel — a reverse-DNS identifier. It must be globally unique when you publish. Pick something you'll be okay with forever.
• Options → Package → Name: "Lexicon Duel" — the text under the icon
• Options → Launcher Icons: 192×192 PNG for the high-res slot. You can put a placeholder now.
• Options → Screen → Orientation: Portrait (for most phone games) or Sensor if you allow both
• Options → Permissions: uncheck everything. Your game needs zero permissions — don't leak "requires internet" into the Play Store listing for nothing.

Deploying over USB

Enable developer mode on your Android phone: Settings → About phone → tap Build Number 7 times. Then Settings → Developer Options → USB Debugging: on.

Plug phone in. First connection will prompt on the phone for authorization — accept "always allow from this computer." Verify:

adb devices
# Should print:
# List of devices attached
# R58M12ABCDE     device

If it prints unauthorized, re-confirm on phone. If it prints nothing, your USB cable may be charge-only (not data) — swap it.

Back in Godot, you should now see a little Android icon in the top-right next to Play. Click it. Godot builds → installs → launches the game on your phone.

Headless / CLI export

Once you have a preset, you don't need the editor UI. This is what you'll actually use 90% of the time:

# In the project root
godot --headless --export-debug "Android Debug" build/lexicon-duel-debug.apk

# Then install to connected device
adb install -r build/lexicon-duel-debug.apk

# Or one-shot:
adb install -r build/lexicon-duel-debug.apk && adb shell am start -n com.yourname.lexiconduel/com.godot.game.GodotApp

Wrap it in a shell script named deploy.sh and put it at the root of your project. That script is your best friend for the next three months.

Debugging on device

Godot supports remote debugging over USB. With the phone connected:

• In Godot: Debug → Deploy with Remote Debug
• Click the Android-run button again
• Now print() output, errors, and breakpoints all route back to the editor

Without this, you're printing to the void. Turn it on.

Common errors

• "Java SDK Path" validation fails. You pointed at a JRE, not a JDK. Reinstall with brew install openjdk@17, use that path.
• Gradle build fails with cryptic "AAPT2 error". Usually means your launcher icons aren't the required sizes. Godot is strict. Use exact dimensions.
• APK installs but crashes immediately. Check adb logcat:

  adb logcat -s godot | grep -i error

  Most common: missing resource, usually a texture not included in export (check the "Resources" tab in your preset).
• "App not installed" on phone. Another app with same package name. adb uninstall com.yourname.lexiconduel.

Do this now

1. Install the prereqs. Walk through every step.
2. Make the preset. Get one successful debug export.
3. Deploy to your phone. Play one full duel with your thumb.
4. Write deploy.sh. Commit it. You'll thank yourself.
5. Note anything that felt bad on touch — tiny buttons, hit targets, font size. List goes into the Module 7 polish notes.