rr3-apk/smali-patches/README.md

# 🔧 Smali Patches for RR3 Server Browser

This directory contains the Android smali bytecode files that enable the in-game server browser.

## 📁 Files

### Core Bridge Code

**`CommunityServerManager.smali`**
- JavaScript ↔ Android bridge
- SharedPreferences management
- Server CRUD operations
- Annotated with `@JavascriptInterface`

**`CommunityServersActivity.smali`**
- WebView host for server list UI
- Loads `community_servers_list.html`
- Manages lifecycle

**`ServerEditActivity.smali`**
- WebView host for server edit form
- Loads `community_server_edit.html`
- Add/edit server UI

### Game Integration

**`SynergyEnvironmentImpl.patch`**
- Modifies game's network code
- Checks SharedPreferences for community server URL
- Falls back to EA servers if none set

## 🔌 How It Works

```
┌─────────────────────────────────────────────────────────────┐
│                         Game Flow                           │
└─────────────────────────────────────────────────────────────┘

1. User opens Server Browser
   └─> CommunityServersActivity launches
       └─> Loads community_servers_list.html
           └─> JavaScript calls AndroidInterface methods
               └─> CommunityServerManager (smali) handles calls
                   └─> Reads/writes SharedPreferences

2. User adds server and taps "Connect"
   └─> JavaScript: AndroidInterface.setActiveServer(id)
       └─> Smali: Saves active_server_url to SharedPreferences

3. User restarts game
   └─> Game calls getSynergyDirectorServerUrl()
       └─> SynergyEnvironmentImpl (PATCHED) checks:
           ├─> Community server URL in SharedPreferences?
           │   ├─> YES: Return community URL ✅
           │   └─> NO: Return EA server URL (fallback)
```

## 🎯 Installation

### Automatic (Recommended)

Use the installer script:

```powershell
cd E:\rr3\rr3-apk
.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk"
```

The script will:
1. Decompile APK with apktool
2. Copy smali files to `smali/com/community/`
3. Apply SynergyEnvironmentImpl patch
4. Update AndroidManifest.xml
5. Rebuild and sign APK

### Manual

If you prefer manual installation:

1. **Decompile APK**
   ```bash
   apktool d realracing3.apk -o rr3-decompiled
   ```

2. **Create directory structure**
   ```bash
   mkdir -p rr3-decompiled/smali/com/community
   ```

3. **Copy smali files**
   ```bash
   cp CommunityServerManager.smali rr3-decompiled/smali/com/community/
   cp CommunityServersActivity.smali rr3-decompiled/smali/com/community/
   cp ServerEditActivity.smali rr3-decompiled/smali/com/community/
   ```

4. **Apply patch**
   - Open `rr3-decompiled/smali/com/ea/nimble/SynergyEnvironmentImpl.smali`
   - Find `getSynergyDirectorServerUrl` method
   - Insert patch code from `SynergyEnvironmentImpl.patch`
   - Save file

5. **Update AndroidManifest.xml**
   ```xml
   <activity
       android:name="com.community.CommunityServersActivity"
       android:label="Community Servers"
       android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen"
       android:exported="true"/>
       
   <activity
       android:name="com.community.ServerEditActivity"
       android:label="Server Settings"
       android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen"
       android:exported="false"/>
   ```

6. **Rebuild APK**
   ```bash
   apktool b rr3-decompiled -o realracing3-modded.apk
   ```

7. **Sign APK**
   ```bash
   uber-apk-signer -a realracing3-modded.apk
   ```

## 🧪 Testing

### 1. Install Modified APK

```bash
adb install realracing3-community.apk
```

### 2. Launch Server Browser

```bash
adb shell am start -n com.ea.games.r3_row/com.community.CommunityServersActivity
```

Expected: Beautiful server browser UI appears

### 3. Check JavaScript Bridge

Open Chrome DevTools:
1. In Android device: Settings → Developer Options → Enable USB Debugging
2. On PC: Open Chrome → `chrome://inspect`
3. Find WebView → Inspect
4. In console, type:
   ```javascript
   AndroidInterface.getServers()
   AndroidInterface.showToast("Hello from JavaScript!")
   ```

### 4. Test SharedPreferences

```bash
# Check if data is being saved
adb shell run-as com.ea.games.r3_row cat shared_prefs/com.ea.games.r3_row_preferences.xml

# Look for:
# <string name="community_servers">[...]</string>
# <string name="active_server_url">http://...</string>
```

### 5. Verify Game Uses Community Server

```bash
# Start game and watch logs
adb logcat | grep -i -E "(synergy|director|community)"

# You should see requests to your community server URL instead of:
# syn-dir.sn.eamobile.com
```

## 📝 Smali Reference

### JavascriptInterface Methods

These methods are callable from JavaScript:

```javascript
AndroidInterface.getServers()              // Returns: JSON string "[]"
AndroidInterface.getActiveServerId()       // Returns: string ""
AndroidInterface.addServer(jsonString)     // Saves server
AndroidInterface.setActiveServer(id)       // Activates server
AndroidInterface.deleteServer(id)          // Removes server
AndroidInterface.showToast(message)        // Shows Android toast
AndroidInterface.getEditingServerId()      // For edit mode
// ... see CommunityServerManager.smali for all methods
```

### SharedPreferences Keys

```
com.ea.games.r3_row_preferences:
├─ community_servers: "[{...}]"        # JSON array of server objects
├─ active_server_id: "uuid-1234"       # Currently active server
├─ active_server_url: "http://..."     # URL game will connect to
└─ editing_server_id: "uuid-5678"      # Server being edited
```

## 🐛 Troubleshooting

### Server Browser Won't Open

```bash
# Check if activities are registered
adb shell dumpsys package com.ea.games.r3_row | grep -A 20 activity

# Should show:
# com.community.CommunityServersActivity
# com.community.ServerEditActivity
```

**Fix**: Activities not in AndroidManifest.xml - re-run installer

### JavaScript Errors

```bash
# Enable WebView debugging in smali
# Add to onCreate() in CommunityServersActivity:

invoke-static {}, Landroid/webkit/WebView;->setWebContentsDebuggingEnabled(Z)V
```

Then inspect with Chrome DevTools

### Game Ignores Community Server

**Symptom**: Still connects to EA servers

**Check**:
```bash
# Is active_server_url set?
adb shell run-as com.ea.games.r3_row cat shared_prefs/com.ea.games.r3_row_preferences.xml | grep active_server_url
```

**Fix**: 
- Verify SynergyEnvironmentImpl.patch was applied
- Check smali syntax for errors
- Rebuild APK with correct patch

### Crashes on Launch

**Common causes**:
- Smali syntax errors (mismatched registers, labels)
- Missing CommunityServerManager.smali
- Wrong class path (must be `com/community/`)

**Debug**:
```bash
adb logcat | grep -i -E "(fatal|exception)"
```

Look for ClassNotFoundException or VerifyError

## 📚 Additional Resources

### Understanding Smali

- **Registers**: `v0`, `v1` are local variables
- **Parameters**: `p0` is `this`, `p1` is first parameter
- **Types**: 
  - `Ljava/lang/String;` = String
  - `Landroid/content/Context;` = Context
  - `Z` = boolean
  - `I` = int

### Useful Commands

```bash
# Decompile single class
baksmali d classes.dex -o output/

# Compile single class  
smali a output/ -o classes.dex

# Disassemble DEX
dexdump -d classes.dex

# Check APK signature
jarsigner -verify -verbose realracing3.apk
```

## 🎖️ Credits

- **apktool** - APK decompile/recompile
- **smali/baksmali** - DEX assembler/disassembler  
- **uber-apk-signer** - APK signing tool
- **RR3 Community** - Keeping the game alive

## ⚠️ Legal Disclaimer

These patches are for:
- ✅ Game preservation
- ✅ Personal use with owned games
- ✅ Private servers

Do NOT:
- ❌ Distribute modified APKs publicly
- ❌ Use for piracy
- ❌ Violate EA's Terms of Service

---

**With these smali files, the server browser is COMPLETE!** 🎮✨

The JavaScript UI can now communicate with Android, store server configs, and tell the game which server to connect to!