gen1recomp/docs/ios-install.md

Build & install on your iPhone — step by step

Don't want to install Xcode? Download the release IPA and sideload it with AltStore instead — see ios-sideload.md.

This guide assumes zero programming experience. Follow it top to bottom and you'll have the game running on your own iPhone in roughly an hour (most of it is waiting for downloads).

What you need

• A Mac (any Apple-silicon or recent Intel Mac on macOS 14 or newer)
• An iPhone and its charging cable
• A free Apple ID (the same account you use for the App Store)
• Your own, legally obtained Pokémon Red or Blue ROM file (a 1 MB .gb file). This project ships no game data — the app rebuilds everything from your cartridge dump and verifies it before use.
• About 15 GB free disk space (Xcode is enormous; the game itself is tiny)

Free vs. paid Apple account: a free Apple ID works. The only catch: apps signed with a free account stop launching after 7 days — just re-run the install command (step 5) to re-sign; your save data is kept. A paid Apple Developer account ($99/yr) extends that to a year.

---

Step 1 — Install Xcode (once)

1. On the Mac, open the App Store, search Xcode, click Get. It's a ~10 GB download — go make tea.
2. Open Xcode once. Accept the license. If it offers to install extra components or the iOS platform, say yes and let it finish.

Step 2 — Sign Xcode into your Apple ID (once)

1. In Xcode's menu bar: Xcode → Settings → Accounts.
2. Click the + in the bottom-left → Apple Account → sign in.
3. Close the window. (This quietly creates the "signing certificate" the build uses — you never have to touch it again.)

Step 3 — Get this project onto the Mac

If you received it as a folder, put it somewhere easy like your home folder. If it's on GitHub, click the green Code button → Download ZIP, then double-click the zip to unpack it.

Step 4 — Build it (one command)

1. Open the Terminal app (press ⌘-space, type terminal, press return).

2. Type cd (c, d, space — don't press return yet), then drag the project folder from Finder onto the Terminal window — it fills in the path — and press return.

3. Paste this and press return:

   scripts/build_ios.sh --fetch
   

   The first run downloads the LÖVE engine and compiles everything (5–15 minutes). Lines of build output scrolling by is normal. You're done when you see ==> done.

Step 5 — Put it on your iPhone

1. Plug the iPhone into the Mac with the cable. Unlock it and keep it unlocked. If it asks "Trust This Computer?" → Trust.

2. Paste this and press return:

   scripts/build_ios.sh --device --install
   

   The script finds your signing identity and your phone by itself. If it complains, it tells you exactly what to fix (usually: the phone was locked — unlock and re-run).

3. First time only, the iPhone will want two approvals:

   • Developer Mode: Settings → Privacy & Security → scroll to Developer Mode → turn on → restart the phone → confirm.
   • Trust the developer: Settings → General → VPN & Device Management → tap the entry under Developer App → Trust.

   Then re-run the command in step 5.2 if the install had failed.

Step 6 — Give it your ROM and play

1. Get your .gb file onto the phone — AirDrop it to yourself, or save it in iCloud Drive / Files.
2. Open the app. On the RED tab, tap Import ROM and pick your .gb file in the file browser that appears. (Alternative: in the Files app, drop the .gb into On My iPhone → the game's folder and just reopen the app — it imports automatically.)
3. Import takes ~10 seconds, the button turns into Play Red — tap it.

Optional goodies

• Mods: launcher → MODS tab → Import mod .zip.
• Save import/export: buttons on each game's tab, using the normal iOS file picker.

When things go wrong

Symptom	Fix
xcodebuild not found	Xcode isn't installed or wasn't opened once — do Step 1
no Apple signing identity found	Do Step 2, then re-run
no iPhone/iPad found	Cable in? Phone unlocked? Tapped "Trust"?
Install fails with "locked"	Unlock the phone, keep it unlocked, re-run
App icon appears then won't open	Do the two approvals in Step 5.3
App stops launching after a week	Free-account 7-day limit — re-run Step 5.2
"That ROM could not be imported"	The file isn't a canonical 1 MB US Red/Blue dump — the importer checks its fingerprint

Every build/install command is safe to re-run; your saves live on the phone and survive reinstalls.