rr3-ota/README.md

# 🔄 RR3 OTA Update System

**Standalone OTA (Over-The-Air) update system for Real Racing 3 Community Edition**

This package provides a complete, drop-in OTA update system that can be integrated into any RR3 APK version (EA's official or community editions).

---

## 📦 What's Included

```
rr3-ota/
├── UpdateManager.java              (Main update logic - manifest-based)
├── UpdateManager.smali             (Compiled smali version)
├── community_update_checker.html   (WebView UI for updates)
├── README.md                       (This file)
└── INTEGRATION-GUIDE.md            (Step-by-step integration)
```

---

## ✨ Features

- 🔄 **Manifest-based updates** - Full control over upgrade paths
- 📡 **GitHub integration** - Uses GitHub Releases for hosting
- 🌐 **Network flexibility** - WiFi or mobile data support
- 📊 **Progress tracking** - Real-time download progress
- 🎨 **Material Design UI** - Beautiful WebView interface
- ⚙️ **User preferences** - WiFi-only mode, auto-check settings
- 🔒 **Version control** - Prevents unwanted major version jumps
- 📱 **Android 6.0+** - Compatible with API 23+

---

## 🎯 How It Works

### Manifest System

Instead of relying on GitHub's `/releases/latest` API, this system uses a **version manifest** (`versions.json`) that you control:

```json
{
  "versions": [
    {
      "version": "15.1.0",
      "version_code": 151000,
      "download_url": "https://github.com/.../RR3-v15.1.0.apk",
      "upgrade_from": ["15.0.0", "15.0.1"]
    }
  ]
}
```

**Benefits:**
- ✅ You control which versions get updates
- ✅ Users on v14.x won't be forced to v15.x
- ✅ Can create multiple update channels (stable, beta, legacy)
- ✅ Easy to manage (edit single JSON file)

### Update Flow

```
1. User opens app
   ↓
2. UpdateManager fetches versions.json
   ↓
3. Finds applicable update (checks upgrade_from)
   ↓
4. Shows update dialog with changelog
   ↓
5. User clicks Download
   ↓
6. DownloadManager downloads APK
   ↓
7. Installation prompt (preserves user data)
   ↓
8. Updated!
```

---

## 🚀 Quick Integration

### For RR3 Community Edition (Already Integrated)

If you're building RR3 Community Edition from our repository:
- ✅ UpdateManager is already patched in
- ✅ HTML UI already in assets
- ✅ Just build the APK

### For Other RR3 Versions (Integration Required)

Follow the detailed guide: **[INTEGRATION-GUIDE.md](./INTEGRATION-GUIDE.md)**

**Quick steps:**
1. Decompile your RR3 APK with apktool
2. Add `UpdateManager.smali` to `smali/com/community/`
3. Add `community_update_checker.html` to `assets/`
4. Add "Check for Updates" button to your UI
5. Recompile and sign APK

---

## 📝 Configuration

### Update Version Constants

Edit `UpdateManager.java` (or `.smali`) before building:

```java
// IMPORTANT: Update these for each build
private static final String CURRENT_VERSION = "15.0.0-community-alpha";
private static final int CURRENT_VERSION_CODE = 150000;
```

**Version Code Formula:**
```
versionCode = (major * 10000) + (minor * 100) + patch

Examples:
15.0.0 → 150000
15.1.0 → 151000
14.5.2 → 145200
```

### Manifest URL

The manifest URL is hardcoded in UpdateManager:

```java
private static final String UPDATE_API_URL = 
    "https://raw.githubusercontent.com/YOUR-ORG/YOUR-REPO/main/versions.json";
```

**Change this to your own manifest location!**

---

## 📊 Version Manifest Setup

### 1. Create versions.json

Create a `versions.json` file in your releases repository:

```json
{
  "schema_version": 1,
  "last_updated": "2026-02-24T04:00:00Z",
  "channels": {
    "stable": {
      "description": "Stable releases",
      "latest": "15.0.0"
    }
  },
  "versions": [
    {
      "version": "15.0.0",
      "version_code": 150000,
      "channel": "stable",
      "release_date": "2026-02-24",
      "min_android": 23,
      "target_android": 34,
      "download_url": "https://github.com/YOUR-ORG/releases/download/v15.0.0/RR3-v15.0.0.apk",
      "file_size": 240000000,
      "sha256": "abc123...",
      "changelog": "## Initial Release\n- Feature 1\n- Feature 2",
      "upgrade_from": []
    }
  ]
}
```

### 2. Host on GitHub

Upload `versions.json` to your GitHub repository (main branch, root or any folder).

**Access URL:**
```
https://raw.githubusercontent.com/YOUR-ORG/YOUR-REPO/main/versions.json
```

### 3. Add New Versions

When releasing a new version:

1. **Create GitHub Release** (hosts APK file)
2. **Update versions.json:**
   ```json
   {
     "version": "15.1.0",
     "version_code": 151000,
     "download_url": "https://github.com/.../v15.1.0/RR3-v15.1.0.apk",
     "upgrade_from": ["15.0.0"],
     ...
   }
   ```
3. **Update channel latest:**
   ```json
   "channels": {
     "stable": { "latest": "15.1.0" }
   }
   ```
4. **Commit and push** versions.json

Users will see the update within seconds!

---

## 🎨 UI Integration

### Add Update Button

The easiest way to integrate the UI is to add a button that opens the update checker:

**Example (in your HTML UI):**
```html
<button onclick="showUpdateChecker()">🔄 Check for Updates</button>

<script>
function showUpdateChecker() {
    window.location.href = 'file:///android_asset/community_update_checker.html';
}
</script>
```

### WebView Bridge Setup

The UpdateManager must be added as a JavaScript interface to your WebView:

```java
webView.addJavascriptInterface(new UpdateManager(context), "UpdateManager");
```

**In smali:**
```smali
new-instance v0, Lcom/community/UpdateManager;
move-object v1, p0  # context
invoke-direct {v0, v1}, Lcom/community/UpdateManager;-><init>(Landroid/content/Context;)V

const-string v1, "UpdateManager"
invoke-virtual {webView, v0, v1}, Landroid/webkit/WebView;->addJavascriptInterface(Ljava/lang/Object;Ljava/lang/String;)V
```

---

## 🧪 Testing

### Test Manifest Parsing

```bash
# Fetch your manifest
curl https://raw.githubusercontent.com/YOUR-ORG/YOUR-REPO/main/versions.json

# Check structure
jq . versions.json

# Verify accessible
curl -I https://raw.githubusercontent.com/YOUR-ORG/YOUR-REPO/main/versions.json
```

### Test Update Flow

1. **Set current version lower** (e.g., 15.0.0)
2. **Add test version to manifest** (e.g., 15.0.1)
3. **Set upgrade_from** to current version
4. **Open app and check for updates**
5. **Verify update is offered**

### Test Download

1. **Create actual GitHub release with APK**
2. **Update manifest download_url**
3. **Test download (WiFi only, then mobile)**
4. **Verify progress tracking works**
5. **Test installation**

---

## 🔧 Customization

### Change Manifest URL

Edit `UpdateManager.java` line ~23:
```java
private static final String UPDATE_API_URL = "YOUR_MANIFEST_URL";
```

### Modify UI

Edit `community_update_checker.html`:
- Change colors (CSS variables at top)
- Modify layout
- Add custom branding
- Change button text

### Add Update Channels

In your manifest:
```json
"channels": {
  "stable": { "latest": "15.0.0" },
  "beta": { "latest": "15.1.0-beta" },
  "legacy-v14": { "latest": "14.5.2" }
}
```

Then add channel selection in your UI.

### Network Preferences

Users can toggle WiFi-only mode:
```javascript
UpdateManager.setWifiOnlyPreference(true);  // WiFi only
UpdateManager.setWifiOnlyPreference(false); // WiFi + Mobile
```

---

## 📱 Android Permissions

Add to `AndroidManifest.xml`:

```xml
<!-- Network access for checking updates -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Download updates -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" 
    android:maxSdkVersion="32" />

<!-- Install updates -->
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
```

---

## 🔒 Security

### APK Verification

**Recommended:** Verify SHA-256 checksum after download

```java
// Add to UpdateManager
public boolean verifyDownload(String expectedSha256) {
    // Calculate SHA-256 of downloaded APK
    // Compare with manifest value
    // Return true if match
}
```

### HTTPS Only

- ✅ Manifest URL uses HTTPS (raw.githubusercontent.com)
- ✅ Download URLs use HTTPS (github.com)
- ✅ No insecure connections

### Code Signing

Always sign your APK with the same keystore for update continuity.

---

## 📂 File Structure

### After Integration

```
your-rr3-apk/
├── smali/
│   └── com/
│       └── community/
│           └── UpdateManager.smali        ← Add this
├── assets/
│   └── community_update_checker.html      ← Add this
└── AndroidManifest.xml                    ← Add permissions
```

### Your GitHub Release Repo

```
your-releases-repo/
├── versions.json                          ← Version manifest
└── README.md                              ← Usage instructions
```

---

## ❓ FAQ

### Q: Does this work with EA's official RR3?

**A:** Technically yes, but EA may ban your account for modified APKs. This is designed for community servers where EA's servers are shut down.

### Q: Can users downgrade versions?

**A:** No. The system only offers updates to versions with higher version codes.

### Q: What if GitHub goes down?

**A:** Update checks will fail gracefully. Users can still play, just won't get updates until GitHub is back.

### Q: Can I host the manifest elsewhere?

**A:** Yes! Just change the `UPDATE_API_URL`. Any HTTPS endpoint that returns the JSON works.

### Q: How do I prevent v14 users from updating to v15?

**A:** In your v15 manifest entry, don't include v14.x in `upgrade_from`:
```json
"upgrade_from": ["15.0.0", "15.0.1"]  // No 14.x!
```

### Q: Can I have multiple APK variants (arm64, x86)?

**A:** Not currently, but you can extend the manifest:
```json
"variants": [
  {"arch": "arm64-v8a", "url": "...-arm64.apk"},
  {"arch": "armeabi-v7a", "url": "...-arm.apk"}
]
```

Then update UpdateManager to select based on device architecture.

---

## 🤝 Contributing

Found a bug? Have an improvement?

1. Test your changes thoroughly
2. Update documentation
3. Submit with clear description

---

## 📜 License

This OTA system is part of the RR3 Community Edition project.

**License:** MIT License

**Credits:**
- Project Lead: [@ssfdre38](https://github.com/ssfdre38) (Daniel Elliott)
- AI Assistant: GitHub Copilot CLI

---

## 🔗 Links

- **Main Project:** [RR3 Community Edition](https://github.com/project-real-resurrection-3)
- **Releases:** [rr3-releases](https://github.com/project-real-resurrection-3/rr3-releases)
- **Legal:** [LEGAL.md](https://github.com/project-real-resurrection-3/.github/blob/main/LEGAL.md)

---

## 🆘 Support

**Need help?**
- 🐛 Report issues on GitHub
- 💬 Join community Discord (link TBA)
- 📧 Contact: [@ssfdre38](https://github.com/ssfdre38)

---

<div align="center">

**🔄 Keep your RR3 Community Edition up to date! 🏁**

Made with ❤️ by the RR3 Community

</div>