# 🏎️ RR3 APK Modification Tools + Server Browser

![License: Educational](https://img.shields.io/badge/license-Educational-blue.svg)
![Platform: Windows](https://img.shields.io/badge/platform-Windows-lightgrey.svg)
![Language: PowerShell](https://img.shields.io/badge/language-PowerShell-blue.svg)

## 🎮 Real Racing 3 - Community Server APK Modifier

This repository contains tools to modify the Real Racing 3 APK to connect to **community-hosted servers** instead of EA's official servers. Perfect for game preservation, private servers, and offline play.

---

## 🚀 **[NEW: Getting Started Guide!](GETTING-STARTED.md)**

**First time building?** Check out our comprehensive **[GETTING-STARTED.md](GETTING-STARTED.md)** guide with:
- ✅ Step-by-step instructions
- ✅ Troubleshooting tips
- ✅ Android 16 compatibility guide
- ✅ Quick start in 5 minutes

---

## ✨ NEW: Server Browser UI

**No more rebuilding APKs!** The new Server Browser feature lets users manage multiple community servers from within the game:

- 🌐 **Multiple Servers** - Save unlimited server profiles
- 🎨 **Beautiful UI** - WebView-based interface with real-time status
- ⚡ **One-Click Connect** - Switch servers instantly
- 🔄 **No Reinstalls** - One APK for all servers
- ⭐ **Favorites** - Mark frequently used servers
- 🔍 **Connection Testing** - Verify before saving

## ⚡ Quick Start

### Basic APK Modification
```powershell
# Simple URL redirect (old method)
.\RR3-Community-Mod.ps1 -ServerUrl "http://your-server-ip:5001"
```

### Server Browser Installation (NEW!)
```powershell
# Add server browser UI to APK
.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk"

# With pre-configured server
.\RR3-Server-Browser-Installer.ps1 `
    -ApkPath "realracing3.apk" `
    -DefaultServerUrl "http://localhost:5001" `
    -DefaultServerName "My Local Server"
```

## 📦 What's Included

### Core Tools
- **RR3-Community-Mod.ps1** - Simple APK URL redirect script
- **RR3-Server-Browser-Installer.ps1** - NEW! Adds server browser UI

### Server Browser UI (NEW!)
- **assets/community_servers_list.html** - Server browser interface
- **assets/community_server_edit.html** - Add/edit server form
- **smali-patches/** - Android bridge code (JavascriptInterface)

### Documentation
- **APK_MODIFICATION_GUIDE.md** - Complete guide (14,000 words)
- **APK_MODIFICATION_SUMMARY.md** - Quick reference (12,000 words)  
- **NETWORK_COMMUNICATION_ANALYSIS.md** - Protocol docs (13,000 words)
- **docs/SERVER_BROWSER_GUIDE.md** - NEW! Server browser user guide

### Reference Files
- **reference/** - Original APK analysis (Java decompiled code)

## 🔍 How It Works

### Method 1: Simple URL Redirect (Original)
Real Racing 3 has **built-in support** for custom servers! Just change the configuration in `AndroidManifest.xml`:

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

### Method 2: Server Browser (NEW!)
Adds a complete UI for managing servers:
1. **HTML/CSS/JS** interfaces stored in APK assets
2. **Smali bridge code** (CommunityServerManager) with JavascriptInterface
3. **SharedPreferences storage** for server configs
4. **Patched game code** to read active server URL at runtime

**Result**: One APK that can connect to any number of community servers!

## 🎯 Use Cases

### For Players
- ✅ Keep one APK, switch between servers
- ✅ Test multiple servers easily
- ✅ Manage LAN + public servers
- ✅ Favorites for frequently used servers

### For Server Owners
- ✅ Share one APK with all users
- ✅ No need to distribute custom builds
- ✅ Users can add your server themselves
- ✅ Professional UI experience

### For Developers
- ✅ Test against multiple server instances
- ✅ Quick switching between local/staging/production
- ✅ Beautiful UI example code

## 📱 Server Browser Screenshots

```
┌─────────────────────────────────────────┐
│  🌐 Community Servers                   │
├─────────────────────────────────────────┤
│  ┌─────────────────────────────────┐   │
│  │ 🏠 My Local Server              │   │
│  │ http://localhost:5001           │   │
│  │ Status: 🟢 Online    [Connect]  │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │ 🌍 RR3 Community #1 (Active)    │   │
│  │ https://rr3-community.com       │   │
│  │ Status: 🟢 Online               │   │
│  └─────────────────────────────────┘   │
│                                         │
│  [+ Add New Server]                     │
└─────────────────────────────────────────┘
```

## 🚀 Getting Started

### Prerequisites
1. **apktool** - For decompiling/rebuilding APKs
2. **uber-apk-signer** - For signing APKs (optional)
3. **Real Racing 3 APK** - Original game file

### Installation
```powershell
# Install apktool (Windows)
choco install apktool

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

See [docs/SERVER_BROWSER_GUIDE.md](docs/SERVER_BROWSER_GUIDE.md) for complete instructions!

## 🌐 Need a Server?

Check out **[rr3-server](https://github.com/ssfdre38/rr3-server)** - ASP.NET Core 8 community server with:
- ✅ Web admin panel
- ✅ Daily rewards system
- ✅ Time trials
- ✅ Car ownership & upgrades
- ✅ Career progression
- ✅ Player leveling

Together, these projects create a **complete community-run RR3 experience**!

## 📚 Documentation

- **[Server Browser Guide](docs/SERVER_BROWSER_GUIDE.md)** - User guide for server browser UI
- **APK_MODIFICATION_GUIDE.md** - Technical APK modding details
- **NETWORK_COMMUNICATION_ANALYSIS.md** - RR3 protocol documentation

## 🤝 Contributing

Contributions welcome! Areas for improvement:
- [ ] Auto-generate smali code
- [ ] Server discovery/public list
- [ ] Import/export server configs
- [ ] Server statistics (ping, uptime)
- [ ] QR code sharing

## ⚠️ Legal Disclaimer

This project is for **educational and game preservation purposes only**.
- Real Racing 3 © Electronic Arts Inc.
- Use at your own risk
- Do not distribute EA's assets
- Respect intellectual property rights

## 🎖️ Credits

- **RR3 Community** - Keeping the game alive
- **apktool** - APK toolkit
- **EA/Firemonkeys** - Original developers

---

**Made with ❤️ for game preservation 🏎️💨**

*One APK. Unlimited Servers. Endless Racing.*