Initial commit: RR3 OTA Update System

Complete standalone package for adding OTA (Over-The-Air) auto-updates to Real Racing 3 APK mods. Features: - Manifest-based version control (versions.json) - Prevents unwanted major version jumps - Material Design WebView UI - WiFi/mobile data download options - Preserves user data during updates - Multi-version channel support Package Contents: - UpdateManager.java - Source code implementation - UpdateManager.smali - Compiled smali for APK integration - community_update_checker.html - Material Design UI - README.md - Complete documentation - INTEGRATION-GUIDE.md - Step-by-step integration instructions Ready for integration into any RR3 APK version (v15, v14, v13, etc.) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-02-23 21:10:22 -08:00
commit b9191a0e86
5 changed files with 3263 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,474 @@
+# 🔄 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 * 100000) + (minor * 1000) + 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>