# Mobile 2D Map Game — Framework & Deployment Research

*A practical guide for Linux users targeting Android + iOS*

---

## The Problem

You want a 2D map-based mobile game. It should be lightweight, easy to implement, and as portable as possible. You're on Linux with Python experience and no game dev background.

**Key constraint:** Android builds work from Linux. iOS always needs macOS somewhere in the chain.

---

## Framework Comparison

| Framework | Language | APK Size | Learning Curve | 2D Map Support | Linux Build | iOS from Linux |
|-----------|----------|----------|----------------|----------------|-------------|----------------|
| **Defold** | Lua | 3–5 MB | Easy | ⭐⭐⭐⭐⭐ Built-in tilemap | ✅ Native | ⚠️ Needs macOS CI |
| **Phaser + Capacitor** | JavaScript | <5 MB | Easy | ⭐⭐⭐⭐⭐ Excellent tilemap | ✅ Native | ⚠️ Needs macOS CI |
| **Godot 4** | GDScript | 36–77 MB | Medium | ⭐⭐⭐⭐⭐ Best features | ✅ CLI | ⚠️ Needs macOS CI |
| **Solar2D** | Lua | 5–10 MB | Easy | ⭐⭐⭐ Basic | ✅ Native | ⚠️ Needs macOS CI |
| **Kivy/Buildozer** | Python | 15–30 MB | Easy (if Python) | ⭐⭐ Manual | ✅ Native | ❌ No iOS |
| **Flutter Flame** | Dart | 15–25 MB | Medium | ⭐⭐⭐ Growing | ✅ Native | ⚠️ Needs macOS |
| **Raylib** | C | 3–8 MB | Hard | ⭐ No built-in | ✅ | ❌ |
| **PWA (no wrapper)** | JS/HTML | <1 MB | Easy | ⭐⭐⭐⭐ Via Phaser | ✅ | ✅ No build needed |

### Tier 1: Best Options

**Defold** — Smallest native APK (3–5 MB), built-in tilemap, Lua scripting, cloud builds available. Designed specifically for small mobile games. Free, no royalties.

**Phaser + Capacitor** — HTML5 game wrapped as native app. Phaser has massive community (40k+ GitHub stars), excellent tilemap support. If you know JavaScript, this is the fastest path.

**PWA (no wrapper)** — Build with Phaser, add `manifest.json` + service worker. Installable from browser, no app store needed. Smallest possible size (<1 MB). Works on Android + iOS Safari.

### Tier 2: Good but Heavier

**Godot 4** — Best features, largest community, but 36–77 MB APK. Worth it if file size doesn't matter.

**Kivy/Buildozer** — Python-native, but limited game features and no iOS.

### Avoid

- **React Native** — Not designed for games
- **Pygame Android** — Abandoned (2013)
- **Raylib** — No built-in tilemap, requires C/C++

---

## Deployment from Linux

### Android (Fully Supported)

```bash
# Option 1: Defold (recommended for smallest APK)
# Download Defold from defold.com → Export → Android Bundle

# Option 2: Godot 4 CLI export
# Install Android SDK command-line tools + JDK 17
godot --export-release "Android" game.apk

# Option 3: Kivy/Buildozer (Python)
pip install buildozer
buildozer android debug
```

All three work headlessly on Linux. No Android Studio required.

### iOS (Requires macOS Somewhere)

| Approach | How It Works | Cost |
|----------|-------------|------|
| **GitHub Actions** | Free macOS runner, build IPA in CI | Free (2000 min/month) |
| **Codemagic** | Cloud CI with macOS builders | Free tier available |
| **MacStadium** | Rent a Mac in the cloud | ~$50/month |

**Recommended:** GitHub Actions + macOS runner. Write the workflow once, build iOS from Linux.

### Testing on Real Devices

```bash
# Android (USB or WiFi)
sudo apt install adb
adb install game.apk

# Android (WiFi, Android 11+)
adb connect <phone-ip>:5555
adb install game.apk

# iOS
# Upload IPA → TestFlight → testers install via TestFlight app
```

### App Store Requirements

| Store | Account Cost | New App Requirement |
|-------|-------------|---------------------|
| Google Play | $25 one-time | 12+ testers, 14 days closed testing |
| Apple App Store | $99/year | macOS build, stricter review |

---

## Recommended Stack

For a Linux user with Python experience, no game dev background, targeting mobile:

### Option A: Fastest to Mobile (PWA)
1. **Phaser.js** — HTML5 game framework, learn via tutorials
2. **PWA** — Add manifest.json + service worker
3. **Deploy** — Host anywhere, share URL, installable on phones
4. **iOS support** — Works via Safari, no app store needed
5. **Size** — <1 MB

### Option B: Smallest Native APK (Defold)
1. **Defold** — Download from defold.com
2. **Lua scripting** — Simple, Python-like syntax
3. **Built-in tilemap** — Perfect for 2D map games
4. **Android APK** — 3–5 MB, builds on Linux
5. **iOS** — Via GitHub Actions with macOS runner

### Option C: Most Features (Godot 4)
1. **Godot 4** — Full game engine, best tooling
2. **GDScript** — Python-like syntax
3. **Android APK** — Builds on Linux via CLI
4. **iOS** — Via GitHub Actions with macOS runner
5. **Size** — 36–77 MB (largest option)

---

## Quick Start: PWA Path (Zero Build Complexity)

```bash
# 1. Install Node.js
sudo apt install -y nodejs npm

# 2. Create Phaser project
npx create-phaser-game my-game
cd my-game

# 3. Add PWA support
npm install -D vite-plugin-pwa

# 4. Configure manifest.json with your app name/icon

# 5. Build
npm run build

# 6. Deploy to any web host (GitHub Pages, Netlify, Vercel)

# 7. Share URL → users install from browser
```

**Total time to first playable:** ~2 hours with AI assistance.

---

## APK Size Comparison

| Framework | Empty APK | With 2D Map Assets |
|-----------|-----------|---------------------|
| **PWA** | N/A | <1–5 MB |
| **Defold** | 3–5 MB | 5–15 MB |
| **Phaser + Capacitor** | <5 MB | 5–15 MB |
| **Godot 4** | 36–50 MB | 40–80 MB |
| **Kivy** | 15–25 MB | 20–40 MB |
| **Flutter** | 15–25 MB | 20–40 MB |

---

## Verdict

**For a 2D map game targeting mobile:**

- **PWA** is the simplest path — no build toolchain, works everywhere, instant updates
- **Defold** is the best native option — tiny APK, built-in tilemap, Lua is easy
- **Godot 4** is overkill unless you need advanced features

**My recommendation:** Start with **PWA + Phaser**. If you need native app store presence later, wrap with **Capacitor** for Android or use **Defold** for the smallest possible APK.

---

*Report generated by Hermes Agent — 2026-07-20*