rr3-apk/README.md

# 🏎️ RR3 APK Modification Tools + Server Browser + Killswitch Removal

![License: Educational](https://img.shields.io/badge/license-Educational-blue.svg)
![Platform: Windows](https://img.shields.io/badge/platform-Windows-lightgrey.svg)
![Language: PowerShell](https://img.shields.io/badge/language-PowerShell-blue.svg)

## 🎮 Real Racing 3 - Community Server APK Modifier

This repository contains tools to modify the Real Racing 3 APK to connect to **community-hosted servers** instead of EA's official servers. Perfect for game preservation, private servers, and offline play.

---

## 🔓 NEW: Killswitch Removal Code (Branch: killswitch-killer)

**EA's March 2026 shutdown bypassed!** This branch contains the code modifications that disable EA's server-controlled killswitch.

### What's the Killswitch?

EA added a remote shutdown mechanism to RR3 v14 that checks their servers on every startup. When they flip the switch in March 2026, the stock APK will refuse to launch.

### The Fix

We surgically removed the killswitch by modifying **one single method** in the EA Nimble SDK:

**File:** `smali_classes2/com/ea/nimble/EnvironmentDataContainer.smali`  
**Method:** `getLatestAppVersionCheckResult()` (line 648)  
**Change:** Always returns `0` (APP_VERSION_OK) instead of checking server response

```smali
# Before: 88 lines checking server's "appUpgrade" field
# After: Hardcoded return value of 0 (game always starts)

.method public getLatestAppVersionCheckResult()I
    .locals 1
    
    # KILLSWITCH DISABLED BY COMMUNITY MOD
    const-string v0, "🔓 Killswitch bypassed - returning APP_VERSION_OK"
    invoke-static {v0, v1}, Landroid/util/Log;->i(Ljava/lang/String;Ljava/lang/String;)I
    
    const/4 v0, 0x0  # Always return 0 (OK)
    return v0
.end method
```

### Documentation

📖 **[KILLSWITCH-REMOVAL-GUIDE.md](KILLSWITCH-REMOVAL-GUIDE.md)** - Complete technical breakdown:
- How the killswitch works (server-controlled shutdown)
- Why our patch is permanent (compiled bytecode is immutable)
- Proof EA can't revert it remotely (no hot-patching capability)
- Manual patching instructions for developers
- FAQ addressing community concerns

### Files Modified

| File | Line | Change |
|------|------|--------|
| `smali_classes2/com/ea/nimble/EnvironmentDataContainer.smali` | 648-668 | Replaced entire `getLatestAppVersionCheckResult()` method |

### Result

✅ Game works after EA servers shut down  
✅ No dependency on EA infrastructure  
✅ Can't be remotely disabled  
✅ Progress preserved locally  

---

## 🚀 **[NEW: Getting Started Guide!](GETTING-STARTED.md)**

**First time building?** Check out our comprehensive **[GETTING-STARTED.md](GETTING-STARTED.md)** guide with:
- ✅ Step-by-step instructions
- ✅ Troubleshooting tips
- ✅ Android 16 compatibility guide
- ✅ Quick start in 5 minutes

---

## ✨ NEW: Server Browser UI

**No more rebuilding APKs!** The new Server Browser feature lets users manage multiple community servers from within the game:

- 🌐 **Multiple Servers** - Save unlimited server profiles
- 🎨 **Beautiful UI** - WebView-based interface with real-time status
- ⚡ **One-Click Connect** - Switch servers instantly
- 🔄 **No Reinstalls** - One APK for all servers
- ⭐ **Favorites** - Mark frequently used servers
- 🔍 **Connection Testing** - Verify before saving

## ⚡ Quick Start

### Basic APK Modification
```powershell
# Simple URL redirect (old method)
.\RR3-Community-Mod.ps1 -ServerUrl "http://your-server-ip:5001"
```

### Server Browser Installation (NEW!)
```powershell
# Add server browser UI to APK
.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk"

# With pre-configured server
.\RR3-Server-Browser-Installer.ps1 `
    -ApkPath "realracing3.apk" `
    -DefaultServerUrl "http://localhost:5001" `
    -DefaultServerName "My Local Server"
```

## 📦 What's Included

### Core Tools
- **RR3-Community-Mod.ps1** - Simple APK URL redirect script
- **RR3-Server-Browser-Installer.ps1** - NEW! Adds server browser UI

### Server Browser UI (NEW!)
- **assets/community_servers_list.html** - Server browser interface
- **assets/community_server_edit.html** - Add/edit server form
- **smali-patches/** - Android bridge code (JavascriptInterface)

### Documentation
- **APK_MODIFICATION_GUIDE.md** - Complete guide (14,000 words)
- **APK_MODIFICATION_SUMMARY.md** - Quick reference (12,000 words)  
- **NETWORK_COMMUNICATION_ANALYSIS.md** - Protocol docs (13,000 words)
- **docs/SERVER_BROWSER_GUIDE.md** - NEW! Server browser user guide

### Reference Files
- **reference/** - Original APK analysis (Java decompiled code)

## 🔍 How It Works

### Method 1: Simple URL Redirect (Original)
Real Racing 3 has **built-in support** for custom servers! Just change the configuration in `AndroidManifest.xml`:

```xml
<meta-data android:name="com.ea.nimble.configuration" android:value="custom" />
<meta-data android:name="NimbleCustomizedSynergyServerEndpointUrl" android:value="http://your-server:5001" />
```

### Method 2: Server Browser (NEW!)
Adds a complete UI for managing servers:
1. **HTML/CSS/JS** interfaces stored in APK assets
2. **Smali bridge code** (CommunityServerManager) with JavascriptInterface
3. **SharedPreferences storage** for server configs
4. **Patched game code** to read active server URL at runtime

**Result**: One APK that can connect to any number of community servers!

## 🎯 Use Cases

### For Players
- ✅ Keep one APK, switch between servers
- ✅ Test multiple servers easily
- ✅ Manage LAN + public servers
- ✅ Favorites for frequently used servers

### For Server Owners
- ✅ Share one APK with all users
- ✅ No need to distribute custom builds
- ✅ Users can add your server themselves
- ✅ Professional UI experience

### For Developers
- ✅ Test against multiple server instances
- ✅ Quick switching between local/staging/production
- ✅ Beautiful UI example code

## 📱 Server Browser Screenshots

```
┌─────────────────────────────────────────┐
│  🌐 Community Servers                   │
├─────────────────────────────────────────┤
│  ┌─────────────────────────────────┐   │
│  │ 🏠 My Local Server              │   │
│  │ http://localhost:5001           │   │
│  │ Status: 🟢 Online    [Connect]  │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │ 🌍 RR3 Community #1 (Active)    │   │
│  │ https://rr3-community.com       │   │
│  │ Status: 🟢 Online               │   │
│  └─────────────────────────────────┘   │
│                                         │
│  [+ Add New Server]                     │
└─────────────────────────────────────────┘
```

## 🚀 Getting Started

### Prerequisites
1. **apktool** - For decompiling/rebuilding APKs
2. **uber-apk-signer** - For signing APKs (optional)
3. **Real Racing 3 APK** - Original game file

### Installation
```powershell
# Install apktool (Windows)
choco install apktool

# Download uber-apk-signer
# https://github.com/patrickfav/uber-apk-signer
```

See [docs/SERVER_BROWSER_GUIDE.md](docs/SERVER_BROWSER_GUIDE.md) for complete instructions!

## 🌐 Need a Server?

Check out **[rr3-server](https://github.com/ssfdre38/rr3-server)** - ASP.NET Core 8 community server with:
- ✅ Web admin panel
- ✅ Daily rewards system
- ✅ Time trials
- ✅ Car ownership & upgrades
- ✅ Career progression
- ✅ Player leveling

Together, these projects create a **complete community-run RR3 experience**!

## 📚 Documentation

### Core Documentation
- **[KILLSWITCH-REMOVAL-GUIDE.md](KILLSWITCH-REMOVAL-GUIDE.md)** - 🔓 Bypass EA's March 2026 shutdown (NEW!)
- **[Server Browser Guide](docs/SERVER_BROWSER_GUIDE.md)** - User guide for server browser UI
- **APK_MODIFICATION_GUIDE.md** - Technical APK modding details
- **NETWORK_COMMUNICATION_ANALYSIS.md** - RR3 protocol documentation

### Technical References
- **[CUSTOM-SERVER-CONFIGURATION.md](CUSTOM-SERVER-CONFIGURATION.md)** - Server URL hardcoding & SSL bypass
- **[KEYSTORE-README.md](KEYSTORE-README.md)** - APK signing information

---

## 🛠️ Technical Details

### Killswitch Removal (v14 Ultimate)

**Purpose:** Disable EA's remote shutdown mechanism to preserve the game after March 2026

**Modified Files:**
```
smali_classes2/com/ea/nimble/EnvironmentDataContainer.smali
├── Line 648-668: getLatestAppVersionCheckResult() method
└── Change: Always returns 0 (APP_VERSION_OK)
```

**How It Works:**
1. Original code checks `m_getDirectionResponseDictionary.get("appUpgrade")`
2. EA's server returns `0` (OK), `1` (Warning), or `2` (BLOCKED)
3. Our patch ignores the server response completely
4. Method now hardcoded to return `0` regardless of server state

**Why It's Permanent:**
- Smali bytecode → DEX → machine code = **immutable after installation**
- EA can only change server DATA, not compiled METHOD CODE
- No `DexClassLoader` or hot-patching in RR3
- Firebase Remote Config only affects data/flags, not executable code

**Verification:**
```bash
# Check logcat for this message on startup:
I/RealRacing3: 🔓 Killswitch bypassed - returning APP_VERSION_OK (community mod)
```

---

## 🤝 Contributing

Contributions welcome! Areas for improvement:
- [ ] Auto-generate smali code
- [ ] Server discovery/public list
- [ ] Import/export server configs
- [ ] Server statistics (ping, uptime)
- [ ] QR code sharing

## ⚠️ Legal Disclaimer

This project is for **educational and game preservation purposes only**.
- Real Racing 3 © Electronic Arts Inc.
- Use at your own risk
- Do not distribute EA's assets
- Respect intellectual property rights

## 🎖️ Credits

- **RR3 Community** - Keeping the game alive
- **apktool** - APK toolkit
- **EA/Firemonkeys** - Original developers

---

**Made with ❤️ for game preservation 🏎️💨**

*One APK. Unlimited Servers. Endless Racing.*