iOS Export (When You're Ready)

Module 7 · Lesson 2 · ~30 min · optional second platform

iOS is harder than Android — not because the Godot tooling is worse (it's similar) but because Apple gates everything behind a paid developer account and Xcode. If you're still in the "does anyone want this?" phase, don't bother with iOS yet. Ship Android to the Play Store, get real user data, then pay Apple the $99.

What iOS actually requires

1. A Mac. No way around it. You can't make an iOS build without a macOS machine running Xcode. (You have one — but noting it because the Godot tooling story for Windows/Linux devs is grim.)
2. Xcode 15+. Free on the Mac App Store, ~10GB download. Godot exports an Xcode project, not an IPA — you open it in Xcode and Xcode does the final build.
3. An Apple ID. The free tier lets you install on your own devices for 7 days at a time. Enough to validate the game runs on an iPhone.
4. An Apple Developer Program membership — $99/year. Required for TestFlight (beta distribution) and App Store submission. Not required for the initial "does it work on my phone" test.

Installing iOS export templates

Same download as Android — Editor → Manage Export Templates → Download and Install bundles all platforms. You don't need a separate step.

The iOS export preset

Project → Export → Add → iOS. Key fields:

• App Store Team ID: find in developer.apple.com/account → Membership. Starts with 10 characters. Required even for free-tier builds.
• Bundle Identifier: com.yourname.lexiconduel — should match your Android package name for consistency.
• Bundle Short Version: "1.0.0" — shown in the App Store.
• Bundle Version: "1" — the integer build number, must increment every TestFlight upload.
• Signing → Identity Type: "Automatic" for development, "Manual" once you're uploading to App Store Connect.
• Icons: Godot generates the iOS icon set from a single 1024×1024 PNG you provide. Don't skip this — Apple rejects builds with placeholder icons.

The export → Xcode dance

# Export from Godot (CLI)
godot --headless --export-debug "iOS" build/ios/

# Open the generated Xcode project
open build/ios/lexicon-duel.xcodeproj

In Xcode:

1. Select the project in the left sidebar → Signing & Capabilities
2. Pick your Team from the dropdown
3. Plug in iPhone (authorize computer on phone if prompted)
4. Pick iPhone from the scheme dropdown at the top
5. Cmd+R to build and run

First run, the phone will say "Untrusted Developer" — go to Settings → General → VPN & Device Management and trust your developer identity. After that, Cmd+R works immediately.

The iteration loop

This is slower than Android, honestly:

1. Make change in Godot
2. godot --headless --export-debug "iOS" build/ios/
3. Xcode may prompt to reload project — say yes
4. Cmd+R
5. Wait ~60s for Xcode to sign, install, launch

On Android, the equivalent is ~15 seconds. This is why you prototype on Android and only cut iOS builds when you're doing a real round of iOS-specific testing.

iOS-specific gotchas

• Safe area insets. The notch on iPhones means you need to respect DisplayServer.screen_get_usable_rect() when placing UI. Test on a notched phone early or your HUD will be under the camera cutout.
• Haptics API differs slightly. Input.vibrate_handheld() works on both platforms but the feel is different. Apple's haptic engine is nicer — slightly stronger default patterns feel fine on iOS but overpower on Android.
• 60fps target. Newer iPhones can do 120Hz ProMotion. Godot 4 doesn't use it by default; add OS.low_processor_usage_mode = false and set display refresh rate in Project Settings. Or just target 60 and skip this until v2.
• No "install via browser." There's no sideloading on iOS. The only ways to get your game onto a friend's phone are TestFlight (paid) or running it straight from Xcode with their phone plugged into your Mac.

TestFlight (paid tier)

TestFlight is Apple's beta distribution. Once you have the $99 membership:

1. In Xcode → Product → Archive → Distribute App → App Store Connect → Upload
2. Log into App Store Connect → Your App → TestFlight
3. Add internal testers (up to 100, must have Apple IDs) — they get the build in minutes
4. Or add external testers (up to 10,000) — requires a short Apple review, ~24 hours the first time

TestFlight builds expire after 90 days. Plan your beta cycles accordingly — a stale TestFlight is a dead TestFlight.

The cross-platform discipline

Godot is genuinely cross-platform, but "runs on both" is not the same as "feels good on both." Things that commonly diverge:

• Touch target sizes (Android users tolerate smaller than iOS users in my experience)
• Back button behavior — Android has a hardware back, iOS doesn't. Don't rely on the back button for critical navigation
• Font rendering — iOS favors SF Pro, Android favors Roboto. Bundle your own font to avoid platform-dependent weirdness
• Audio latency — iOS is consistently lower latency. SFX timing that feels tight on Android can feel sloppy on iOS

Test both before publishing. Budget one full dedicated day per platform near launch for this pass.

Do this now (optional)

1. If you have the free Apple ID tier set up, make the iOS preset and get one build running on an iPhone (yours or a friend's).
2. If you don't, skim this lesson and move on — come back in Module 8 or after the Android launch.
3. Write a line in progress/journal.md: "iOS blocker: waiting on [X]" so future-you remembers what's between you and an iOS build.