rr3-apk/docs/SERVER_BROWSER_GUIDE.md

# 🌐 RR3 Community Server Browser

## Overview

This is a **Server Browser UI** system for the Real Racing 3 modded APK that allows users to manage multiple community servers without reinstalling the APK.

## 🎯 Features

- ✅ **Multiple Server Profiles** - Add unlimited servers
- ✅ **Easy Management** - Add, edit, delete servers via UI
- ✅ **Server Status** - See which servers are online/offline
- ✅ **One-Click Connect** - Switch servers instantly
- ✅ **Favorites** - Mark frequently used servers
- ✅ **Connection Testing** - Test before saving
- ✅ **No Reinstalls** - One APK for all servers

## 📱 User Guide

### How to Access

1. Launch the modded APK
2. From the main menu, tap **"Community Servers"**
3. The server browser will open

### Adding a Server

1. Tap **"+ Add New Server"**
2. Enter:
   - **Server Name**: A friendly name (e.g., "My Local Server")
   - **Server URL**: Full URL with port (e.g., `http://192.168.1.100:5001`)
3. Tap **"🔍 Test Connection"** to verify it works
4. Tap **"💾 Save"**

### Connecting to a Server

1. Find the server in your list
2. Check the status indicator:
   - 🟢 **Green** = Online
   - 🔴 **Red** = Offline
   - 🟠 **Orange** = Checking...
3. Tap **"Connect"**
4. **Restart the game** to apply

The active server will show **(Active)** and have a green border.

### Editing a Server

1. Tap the **✏️ Edit** button on any server card
2. Modify the name or URL
3. Tap **"💾 Save"**

### Deleting a Server

1. Tap the **🗑️ Delete** button on any server card
2. Confirm deletion

## 🔧 Technical Details

### Data Storage

Server configurations are stored in Android SharedPreferences at:
```
com.ea.games.r3_row_preferences
└── community_servers (JSON array)
└── active_server_id (String)
```

### Server Data Format

```json
{
  "id": "uuid-1234",
  "name": "My Local Server",
  "url": "http://localhost:5001",
  "addedDate": "2026-02-18T10:30:00Z",
  "lastUsed": "2026-02-18T15:20:00Z",
  "isFavorite": false
}
```

### How It Works

1. **UI Layer**: HTML/CSS/JavaScript interfaces in `assets/`
2. **Bridge Layer**: `CommunityServerManager.smali` with JavascriptInterface
3. **Storage**: Android SharedPreferences
4. **Game Integration**: `SynergyEnvironmentImpl` patched to read active URL

### Connection Flow

```
User taps "Connect"
    ↓
JavaScript calls AndroidInterface.setActiveServer(id)
    ↓
CommunityServerManager saves active_server_id to SharedPreferences
    ↓
User restarts game
    ↓
SynergyEnvironmentImpl.getEnvironmentUrls() called
    ↓
Reads active_server_url from SharedPreferences
    ↓
Uses community server instead of EA servers
```

## 🎨 UI Components

### 1. Server List (`community_servers_list.html`)
- Displays all saved servers
- Shows online/offline status
- Connect/Edit/Delete buttons
- Add new server button

### 2. Server Editor (`community_server_edit.html`)
- Add/edit server form
- URL validation
- Connection testing
- Save/Delete/Cancel actions

## 🔌 Server URL Examples

### Local Development
```
http://localhost:5001
http://127.0.0.1:5001
```

### LAN Server
```
http://192.168.1.100:5001
http://10.0.0.50:5001
```

### Public Server
```
https://rr3-community.example.com
https://rr3.mydomain.org:8080
```

## 🚀 Developer Integration

### Adding to Main Menu

Add a button to the game's main menu that launches:
```java
Intent intent = new Intent(this, CommunityServersActivity.class);
startActivity(intent);
```

### Accessing from ADB

```bash
adb shell am start -n com.ea.games.r3_row/com.community.CommunityServersActivity
```

### Programmatic Server Management

```java
CommunityServerManager manager = new CommunityServerManager(context);

// Add server
String serverJson = "{\"id\":\"...\", \"name\":\"...\", \"url\":\"...\"}";
manager.addServer(serverJson);

// Set active
manager.setActiveServer("uuid-1234");

// Get active URL
String url = manager.getActiveServerUrl();
```

## 📝 Files Included

### HTML Assets (`assets/`)
- `community_servers_list.html` - Main server browser
- `community_server_edit.html` - Add/edit form

### Smali Patches (`smali-patches/`)
- `CommunityServerManager.smali` - Core logic + JavascriptInterface
- `CommunityServersActivity.smali` - WebView host for list
- `ServerEditActivity.smali` - WebView host for edit form

### Scripts
- `RR3-Server-Browser-Installer.ps1` - Automated installation script

## 🛠️ Installation

### Automatic (PowerShell Script)

```powershell
.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk" -OutputPath "realracing3-community.apk"
```

### Manual

1. Decompile APK with apktool
2. Copy `assets/` folder contents to APK's assets
3. Copy `smali-patches/` files to `smali/com/community/`
4. Patch `SynergyEnvironmentImpl.smali` (see patch guide)
5. Update `AndroidManifest.xml` to register activities
6. Rebuild and sign APK

## 🔒 Security Notes

- Only use HTTPS for public servers
- Local/LAN servers can use HTTP
- URL validation prevents code injection
- No user credentials are stored

## 🐛 Troubleshooting

### Server shows Offline
- Check URL is correct (including http:// or https://)
- Verify server is running
- Check firewall/network settings
- For LAN servers, ensure devices are on same network

### Can't Connect
- Make sure you **restarted the game** after connecting
- Check server URL is saved correctly
- Verify server responds to `/director` endpoint

### Game Crashes
- Ensure smali files are properly installed
- Check AndroidManifest has activity declarations
- Verify assets are in correct location

## 🎮 Tips

1. **Test Connection** before saving to avoid typos
2. **Use Favorites** for frequently used servers
3. **Keep URLs Short** - use domain names instead of IPs when possible
4. **Restart After Switching** - always restart game when changing servers
5. **Backup Server List** - export before reinstalling

## 📚 For Server Owners

Want users to easily add your server? Share:

```
Server Name: [Your Server Name]
Server URL: https://your-server.com
```

Users can copy-paste directly into the add server form!

## 💡 Future Enhancements

Potential additions:
- Server discovery/public list
- Import/export server configs
- Server statistics (ping, uptime)
- Auto-reconnect on failure
- Server categories/tags
- QR code server sharing

---

**Built for the RR3 Community** 🏎️💨

This system enables **one APK** to work with **unlimited servers** - no more rebuilding APKs for different URLs!