rr3-apk/GETTING-STARTED.md

🚀 Getting Started - Building RR3 Community APK

Welcome! This guide will walk you through building a modified Real Racing 3 APK that connects to community servers.

---

📋 Prerequisites

What You Need

1. Original RR3 APK (v15.0.0 or similar)

   • Extract from your Android device
   • Or download from APK mirror sites
   • File: realracing3.apk or com.ea.games.r3_row.apk

2. Windows PC with PowerShell

   • Windows 10/11 recommended
   • PowerShell 5.1+ (comes with Windows)

3. Java Development Kit (JDK)

   • Version 8 or higher
   • Download: https://adoptium.net/

4. 15-20 minutes of your time ☕

---

⚡ Quick Start (Easiest Method)

Step 1: Clone This Repository

git clone https://gitea.barrer.net/project-real-resurrection-3/rr3-apk.git
cd rr3-apk

Or download as ZIP and extract.

Step 2: Place Original APK

Copy your original RR3 APK to the project folder:

rr3-apk/
├── realracing3.apk  ← Place your APK here
├── RR3-Community-Mod.ps1
└── ...

Step 3: Run the Build Script

Option A - Connect to Your Server:

.\RR3-Community-Mod.ps1 -ServerUrl "http://your-server-ip:5001"

Option B - Add Server Browser UI:

.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk"

Option C - Default Local Server:

.\RR3-Community-Mod.ps1 -ServerUrl "http://localhost:5001"

Step 4: Install on Android Device

1. Enable USB Debugging on your Android device:

   • Settings → About Phone → Tap "Build Number" 7 times
   • Settings → Developer Options → Enable USB Debugging

2. Connect device to PC via USB

3. Install the APK:

adb install -r RR3-v15.0.0-community-alpha.apk

Or transfer the APK to your device and install manually.

Step 5: Launch & Play! 🎮

The game will now connect to your community server instead of EA's servers!

---

📚 Detailed Manual Build Process

If you prefer to understand each step or the scripts don't work, follow the manual process:

1. Install Required Tools

Java JDK:

# Check if Java is installed
java -version

# If not installed, download from:
# https://adoptium.net/temurin/releases/

APKTool:

# Download apktool from:
# https://ibotpeaches.github.io/Apktool/

# Place apktool.bat and apktool.jar in:
# C:\Windows\

Uber APK Signer:

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

# Place uber-apk-signer.jar in project folder

2. Decompile APK

apktool d realracing3.apk -o rr3-decompiled

This creates a folder rr3-decompiled with all APK contents.

3. Modify AndroidManifest.xml

Open rr3-decompiled/AndroidManifest.xml and find this section:

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

Change to:

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

Also add this to the <application> tag:

<application
    android:extractNativeLibs="true"
    ...

This is required for Android 15+ compatibility.

4. Recompile APK

apktool b rr3-decompiled -o realracing3-community.apk

5. Align APK (Important for Android 15+)

# Must use -P 16 flag (uppercase P, page size 16KB)
zipalign -f -P 16 -v 16 realracing3-community.apk realracing3-community-aligned.apk

6. Sign APK

java -jar uber-apk-signer.jar --apks realracing3-community-aligned.apk

This creates: realracing3-community-aligned-signed.apk

7. Install on Device

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

# Install community version
adb install realracing3-community-aligned-signed.apk

---

🎯 Different Build Options

Option 1: Direct Server Connection

Use when: You have a specific server you always want to connect to

Command:

.\RR3-Community-Mod.ps1 -ServerUrl "http://community.example.com:8443"

Result: APK always connects to that server

---

Option 2: Server Browser UI

Use when: You want to switch between multiple servers

Command:

.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk"

Result: APK has in-game menu to add/switch servers

Features:

• Add unlimited servers
• Save favorites
• Test connection before connecting
• Switch servers without reinstalling APK

---

Option 3: Localhost Testing

Use when: Running server on your PC for testing

Command:

.\RR3-Community-Mod.ps1 -ServerUrl "http://localhost:5001"

Note: Your Android device must be on the same network and use your PC's IP (e.g., http://192.168.1.100:5001)

---

🔧 Troubleshooting

"APKTool not found"

Solution: Install APKTool and add to PATH, or place in C:\Windows\

"Failed to parse AndroidManifest.xml"

Solution: Use a proper text editor (VS Code, Notepad++), not Notepad. Check XML syntax.

"Installation failed: INSTALL_FAILED_INVALID_APK"

Solution:

• Make sure you ran zipalign -P 16 (uppercase P!)
• Check that extractNativeLibs="true" is in manifest
• Verify APK is signed

"App crashes on startup"

Solution:

• Check logcat: adb logcat | grep RR3
• Make sure you didn't modify any smali files
• Verify server URL is correct in manifest

"Connection refused" or "Cannot connect to server"

Solution:

• Verify server is running: curl http://your-server-ip:5001/director/api/android/getDirectionByPackage
• Check firewall allows connections
• If using localhost, use PC's network IP instead

"JNI Error" or "Native crash"

Solution:

• This usually means the APK wasn't built correctly
• Start over from Step 1
• Make sure you're using the v14 branch: git checkout v14

---

📱 Android 16 Compatibility

If you're on Android 16 (API 35+), you must include these changes:

1. In AndroidManifest.xml:

<application
    android:extractNativeLibs="true"
    ...

2. Use correct zipalign flag:

zipalign -f -P 16 -v 16 input.apk output.apk

The -P 16 (uppercase P) is critical! Lowercase -p only does 4KB alignment which isn't enough.

---

🎮 After Installation

First Launch

1. Game will take 2-3 minutes to extract assets (first time only)
2. You'll see the EA splash screen
3. Game should connect to your community server

If Using Server Browser

1. Open game
2. Click "Settings" or "Servers" in menu
3. Add your server URL
4. Click "Connect"

Verify Connection

Check your server logs for:

Director request for package: com.ea.games.r3_row

If you see this, the APK is successfully connecting! 🎉

---

📚 Additional Documentation

For more detailed information, see:

• APK_MODIFICATION_GUIDE.md - Complete technical guide
• NETWORK_COMMUNICATION_ANALYSIS.md - How the game communicates
• KEYSTORE-README.md - Creating signing keys
• SERVER_BROWSER_GUIDE.md - Server browser feature

---

💡 Tips & Tricks

Speed Up Builds

Once you've built once, subsequent builds are faster:

# Just recompile + sign (skip decompile)
apktool b rr3-decompiled -o output.apk
zipalign -f -P 16 -v 16 output.apk output-aligned.apk
java -jar uber-apk-signer.jar --apks output-aligned.apk

Test Without Device

Use Android Emulator:

# Create emulator
avdmanager create avd -n RR3Test -k "system-images;android-34;google_apis;x86_64"

# Start emulator
emulator -avd RR3Test

# Install APK
adb install your-apk.apk

Multiple Versions

You can install multiple versions side-by-side by changing the package name in AndroidManifest.xml:

<manifest package="com.ea.games.r3_row.community" ...>

---

🆘 Getting Help

If you're stuck:

1. Check the Issues page
2. Read the detailed guides in the docs/ folder
3. Check server logs for connection errors
4. Use adb logcat to see Android logs

When asking for help, include:

• Android version
• APK build command you used
• Error message (full text)
• Server URL you're connecting to

---

🎉 Success!

If you successfully built and installed the APK:

1. Star this repository ⭐
2. Share with the community 🎮
3. Report any bugs you find 🐛
4. Consider contributing improvements 💪

---

📜 Legal Notice

This project is for educational purposes and game preservation only. Real Racing 3 is owned by Electronic Arts (EA). This tool is intended for:

• Running private servers after official servers shut down
• Educational analysis of Android APK structure
• Game preservation efforts
• Personal offline play

Not intended for:

• Piracy or unauthorized distribution
• Circumventing in-app purchases
• Online cheating or hacking
• Commercial use

Use responsibly! 🙏

---

✅ Quick Checklist

Before building, make sure you have:

• Original RR3 APK file
• Java JDK installed (java -version works)
• APKTool installed
• Uber APK Signer downloaded
• USB Debugging enabled on Android device
• Server running (if testing connection)
• 15-20 minutes of time

Then run:

.\RR3-Community-Mod.ps1 -ServerUrl "http://your-server:5001"

---

Happy Racing! 🏎️💨

Last Updated: February 20, 2026 Version: v14 (Android 16 Compatible)