rr3-apk/APK_MODIFICATION_GUIDE.md

# Real Racing 3 APK Modification Guide - Community Server Support

## 🎯 Overview

This guide shows how to modify the Real Racing 3 APK to support **community server URLs** without breaking the original game. The game already has built-in support for custom servers through its configuration system!

---

## ✨ Good News!

The app **already supports custom server URLs** via its configuration system! We just need to:
1. Change the configuration from `"live"` to `"custom"`
2. Add a meta-data entry with your community server URL
3. Repackage and re-sign the APK

**No code changes needed!** Just AndroidManifest.xml modifications.

---

## 📋 Prerequisites

### Tools Required
1. **APKTool** - For decompiling/recompiling APKs
2. **Uber APK Signer** - For signing the modified APK
3. **Java JDK 8+** - Required by APKTool

### Installation

**Windows:**
```bash
# Install Chocolatey (if not installed)
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Java
choco install openjdk11

# Download APKTool
# https://ibotpeaches.github.io/Apktool/
# Place apktool.bat and apktool.jar in C:\Windows\

# Download Uber APK Signer
# https://github.com/patrickfav/uber-apk-signer/releases
```

**Linux/macOS:**
```bash
# Install Java
sudo apt install openjdk-11-jdk  # Ubuntu/Debian
brew install openjdk@11           # macOS

# Install APKTool
brew install apktool              # macOS
sudo apt install apktool          # Ubuntu/Debian

# Download Uber APK Signer
wget https://github.com/patrickfav/uber-apk-signer/releases/download/v1.3.0/uber-apk-signer-1.3.0.jar
```

---

## 🔧 Method 1: Simple Configuration Change (Recommended)

This method uses the game's **built-in custom server support**.

### Step 1: Decompile the APK

```bash
# Navigate to APK location
cd E:\rr3

# Decompile
apktool d realracing3.apk -o rr3-modded
```

### Step 2: Edit AndroidManifest.xml

Open `rr3-modded\AndroidManifest.xml` and find this section (around line 225):

**BEFORE:**
```xml
<meta-data
    android:name="com.ea.nimble.configuration"
    android:value="live"/>
```

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

**Replace `https://your-server.com` with your actual community server URL!**

### Step 3: Recompile the APK

```bash
apktool b rr3-modded -o realracing3-community.apk
```

### Step 4: Sign the APK

```bash
# Using Uber APK Signer
java -jar uber-apk-signer.jar --apks realracing3-community.apk

# Or using jarsigner (manual)
keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-key-alias
jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 -keystore my-release-key.jks realracing3-community.apk my-key-alias
```

### Step 5: Install on Device

```bash
# Uninstall original (if installed)
adb uninstall com.ea.games.r3_row

# Install modified APK
adb install realracing3-community-signed.apk
```

**Done!** The game will now connect to your community server.

---

## 🔧 Method 2: Dynamic Server Switching (Advanced)

This creates **two separate APK versions** - one for official servers, one for community servers.

### Create Community APK

1. Follow Method 1 steps 1-4
2. Rename the output: `realracing3-community.apk`

### Create Official APK (Unmodified)

1. Keep original `realracing3.apk`
2. Re-sign it with the same certificate:
   ```bash
   java -jar uber-apk-signer.jar --apks realracing3.apk
   ```

### Usage

- **Official servers**: Install `realracing3.apk`
- **Community servers**: Install `realracing3-community.apk`

Switch by uninstalling one and installing the other.

---

## 🔧 Method 3: Shared Preferences Override (Requires Root)

For advanced users with rooted devices - override server URL at runtime.

### Create Override Script

```bash
# Create override script
cat > /data/data/com.ea.games.r3_row/shared_prefs/rr3_community.xml << 'EOF'
<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
<map>
    <string name="community_server_url">https://your-server.com</string>
    <boolean name="use_community_server" value="true" />
</map>
EOF

# Set permissions
chmod 660 /data/data/com.ea.games.r3_row/shared_prefs/rr3_community.xml
chown u0_a123:u0_a123 /data/data/com.ea.games.r3_row/shared_prefs/rr3_community.xml
```

### Modify Java Code to Read Preferences

This requires smali editing - see Advanced section below.

---

## 🛠️ Advanced: Add In-Game Server Switcher

For maximum flexibility, add a settings UI to switch servers in-game.

### Step 1: Create Settings Activity

Create `rr3-modded/smali/com/firemint/realracing/CommunityServerSettings.smali`:

```smali
.class public Lcom/firemint/realracing/CommunityServerSettings;
.super Landroid/app/Activity;

.method protected onCreate(Landroid/os/Bundle;)V
    .locals 2
    
    # Show simple dialog with server URL input
    # Implementation details omitted for brevity
    
    return-void
.end method
```

### Step 2: Add Settings Button

This is complex and requires understanding of the game's UI structure. Alternative: use external app.

---

## 📱 Automated Solution: Community Server Manager App

The easiest approach for users: Create a separate **Community Server Manager** app.

### Create Android App

```kotlin
// MainActivity.kt
class ServerManagerActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        val serverUrlInput = findViewById<EditText>(R.id.serverUrl)
        val applyButton = findViewById<Button>(R.id.applyButton)
        
        applyButton.setOnClickListener {
            val serverUrl = serverUrlInput.text.toString()
            modifyRR3APK(serverUrl)
        }
    }
    
    private fun modifyRR3APK(serverUrl: String) {
        // Extract RR3 APK
        val pm = packageManager
        val appInfo = pm.getApplicationInfo("com.ea.games.r3_row", 0)
        val apkPath = appInfo.sourceDir
        
        // Decompile, modify, recompile, sign
        // (Requires APKTool library integration)
        
        // Prompt user to install
        installAPK(modifiedApkPath)
    }
}
```

**This gives users a simple UI to enter server URLs without manual APK editing.**

---

## 🔒 Security Considerations

### Certificate Pinning

Real Racing 3 may have SSL certificate pinning. If connections fail:

1. **Disable Certificate Verification** (modify CloudcellTrustManager.java):
   ```java
   // Change checkServerTrusted to do nothing
   public void checkServerTrusted(X509Certificate[] chain, String authType) {
       // Commented out validation
       // Original validation code...
   }
   ```

2. **Install Custom CA Certificate** on device:
   ```bash
   # Push certificate to device
   adb push my-ca-cert.crt /sdcard/
   
   # Install via Settings > Security > Install from SD card
   ```

3. **Use mitmproxy** to intercept and re-sign traffic

---

## 📋 Complete Automated Script

Here's a complete PowerShell script to automate the entire process:

```powershell
# RR3-Community-Mod.ps1
param(
    [Parameter(Mandatory=$true)]
    [string]$ServerUrl,
    
    [string]$ApkPath = "realracing3.apk",
    [string]$OutputPath = "realracing3-community.apk"
)

Write-Host "🏎️ Real Racing 3 Community Server Modifier" -ForegroundColor Cyan
Write-Host "================================================" -ForegroundColor Cyan

# Step 1: Decompile
Write-Host "`n[1/4] Decompiling APK..." -ForegroundColor Yellow
apktool d $ApkPath -o rr3-modded -f

# Step 2: Modify AndroidManifest.xml
Write-Host "[2/4] Modifying configuration..." -ForegroundColor Yellow
$manifestPath = "rr3-modded\AndroidManifest.xml"
$manifest = Get-Content $manifestPath -Raw

# Change configuration to 'custom'
$manifest = $manifest -replace 'android:value="live"/>', 'android:value="custom"/>'

# Add custom server URL
$customServerMeta = @"
    <meta-data
        android:name="NimbleCustomizedSynergyServerEndpointUrl"
        android:value="$ServerUrl"/>
"@

$manifest = $manifest -replace '(<meta-data\s+android:name="com.ea.nimble.configuration"[^>]*/>)', "`$1`n$customServerMeta"

Set-Content -Path $manifestPath -Value $manifest

# Step 3: Recompile
Write-Host "[3/4] Recompiling APK..." -ForegroundColor Yellow
apktool b rr3-modded -o $OutputPath

# Step 4: Sign
Write-Host "[4/4] Signing APK..." -ForegroundColor Yellow
java -jar uber-apk-signer.jar --apks $OutputPath

Write-Host "`n✅ Done! Modified APK: $OutputPath" -ForegroundColor Green
Write-Host "📱 Install with: adb install $OutputPath" -ForegroundColor Green
```

**Usage:**
```powershell
.\RR3-Community-Mod.ps1 -ServerUrl "https://your-server.com" -ApkPath "realracing3.apk"
```

---

## 🧪 Testing the Modified APK

### Verify Server URL

```bash
# Extract and check AndroidManifest.xml
unzip -p realracing3-community.apk AndroidManifest.xml | xmllint --format -

# Look for:
# <meta-data android:name="NimbleCustomizedSynergyServerEndpointUrl" 
#            android:value="https://your-server.com"/>
```

### Monitor Network Traffic

```bash
# Use adb logcat to see connection attempts
adb logcat | grep -i "synergy\|nimble\|director"

# Expected output:
# SynergyEnv: Using custom configuration
# SynergyEnv: Director URL = https://your-server.com
```

### Test Connection

```bash
# Check if app connects to your server
# Monitor server logs for incoming requests

# Expected request:
# GET /director/api/android/getDirectionByPackage?packageName=com.ea.games.r3_row
```

---

## 📦 Distribution

### Option 1: Distribute Modified APK

**Pros:**
- Users just install the APK
- No technical knowledge required

**Cons:**
- Different signature than official app
- Users must uninstall official version first
- Updates require re-distribution

### Option 2: Distribute Patch File

Create a patch file users apply:

```bash
# Create patch
diff -u original/AndroidManifest.xml modified/AndroidManifest.xml > community-server.patch

# Users apply patch
patch rr3-modded/AndroidManifest.xml < community-server.patch
```

### Option 3: Server Manager App

Best option - create a companion app that:
1. Detects installed RR3 APK
2. Extracts it
3. Applies modifications
4. Re-signs
5. Prompts installation

Users just enter server URL in the app!

---

## 🔄 Switching Back to Official Servers

### Method 1: Reinstall Official APK

```bash
adb uninstall com.ea.games.r3_row
adb install realracing3-original.apk
```

### Method 2: Keep Both Versions

Modify package name to run both side-by-side:

```xml
<!-- In AndroidManifest.xml -->
<manifest package="com.ea.games.r3_row.community" ...>
```

Now you can have:
- `com.ea.games.r3_row` - Official
- `com.ea.games.r3_row.community` - Community

**⚠️ Note:** Requires changing package references throughout the codebase (complex).

---

## 📝 Configuration Examples

### Local Server (LAN)
```xml
<meta-data
    android:name="NimbleCustomizedSynergyServerEndpointUrl"
    android:value="http://192.168.1.100:5001"/>
```

### Remote Server (Internet)
```xml
<meta-data
    android:name="NimbleCustomizedSynergyServerEndpointUrl"
    android:value="https://rr3.community-server.net"/>
```

### Localhost (Android Emulator)
```xml
<meta-data
    android:name="NimbleCustomizedSynergyServerEndpointUrl"
    android:value="http://10.0.2.2:5001"/>
```
*(10.0.2.2 is the special IP for host machine from emulator)*

---

## 🐛 Troubleshooting

### Issue: APK Won't Install
**Solution:**
- Uninstall official version first: `adb uninstall com.ea.games.r3_row`
- Check signature: Different signatures can't overwrite

### Issue: App Crashes on Launch
**Solution:**
- Check APKTool version: `apktool --version` (should be 2.7.0+)
- Recompile with: `apktool b -f rr3-modded`

### Issue: Still Connects to Official Servers
**Solution:**
- Verify manifest changes: `unzip -p apk AndroidManifest.xml`
- Check logcat for configuration being read
- Ensure configuration is set to `"custom"`

### Issue: SSL Certificate Error
**Solution:**
- Install custom CA cert on device
- Or disable certificate validation (see Security section)

---

## ✅ Verification Checklist

- [ ] APKTool installed and working
- [ ] Original APK decompiled successfully
- [ ] AndroidManifest.xml modified correctly
- [ ] Configuration changed to `"custom"`
- [ ] Custom server URL added
- [ ] APK recompiled without errors
- [ ] APK signed successfully
- [ ] Signature verification passed
- [ ] APK installed on device
- [ ] App launches without crashes
- [ ] Logcat shows custom server URL
- [ ] Server receives connection requests

---

## 🎉 Success!

You now have three ways to enable community servers:

1. **Method 1 (Simple)**: Modify AndroidManifest.xml - best for most users
2. **Method 2 (Flexible)**: Create separate APKs for switching
3. **Method 3 (Advanced)**: Build a companion manager app

**Recommended:** Use Method 1 + automated script for easy distribution.

---

## 📚 References

- **APKTool Documentation**: https://ibotpeaches.github.io/Apktool/
- **Uber APK Signer**: https://github.com/patrickfav/uber-apk-signer
- **Android Manifest Reference**: https://developer.android.com/guide/topics/manifest/manifest-intro

---

*Created: February 2026*  
*Real Racing 3 Community Server Project*