Initial commit: RR3 APK and documentation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
527
APK_MODIFICATION_GUIDE.md
Normal file
527
APK_MODIFICATION_GUIDE.md
Normal file
@@ -0,0 +1,527 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user