# 🚀 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

```powershell
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:**
```powershell
.\RR3-Community-Mod.ps1 -ServerUrl "http://your-server-ip:5001"
```

**Option B - Add Server Browser UI:**
```powershell
.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk"
```

**Option C - Default Local Server:**
```powershell
.\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:
```powershell
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:**
```powershell
# Check if Java is installed
java -version

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

**APKTool:**
```powershell
# Download apktool from:
# https://ibotpeaches.github.io/Apktool/

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

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

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

### 2. Decompile APK

```powershell
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:

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

**Change to:**
```xml
<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:**
```xml
<application
    android:extractNativeLibs="true"
    ...
```

This is required for Android 15+ compatibility.

### 4. Recompile APK

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

### 5. Align APK (Important for Android 15+)

```powershell
# 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

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

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

### 7. Install on Device

```powershell
# 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:**
```powershell
.\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:**
```powershell
.\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:**
```powershell
.\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:**
```xml
<application
    android:extractNativeLibs="true"
    ...
```

2. **Use correct zipalign flag:**
```powershell
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](APK_MODIFICATION_GUIDE.md)** - Complete technical guide
- **[NETWORK_COMMUNICATION_ANALYSIS.md](NETWORK_COMMUNICATION_ANALYSIS.md)** - How the game communicates
- **[KEYSTORE-README.md](KEYSTORE-README.md)** - Creating signing keys
- **[SERVER_BROWSER_GUIDE.md](docs/SERVER_BROWSER_GUIDE.md)** - Server browser feature

---

## 💡 Tips & Tricks

### Speed Up Builds
Once you've built once, subsequent builds are faster:
```powershell
# 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:
```powershell
# 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:
```xml
<manifest package="com.ea.games.r3_row.community" ...>
```

---

## 🆘 Getting Help

**If you're stuck:**

1. Check the [Issues](https://gitea.barrer.net/project-real-resurrection-3/rr3-apk/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:
```powershell
.\RR3-Community-Mod.ps1 -ServerUrl "http://your-server:5001"
```

---

**Happy Racing! 🏎️💨**

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