mirror of
https://github.com/bryanthaboi/gen1recomp.git
synced 2026-08-12 00:10:56 +02:00
bryanthaboi
117 lines
4.7 KiB
Markdown
117 lines
4.7 KiB
Markdown
# 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](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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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.
|