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

{
  "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:

Intent intent = new Intent(this, CommunityServersActivity.class);
startActivity(intent);

Accessing from ADB

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

Programmatic Server Management

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)

.\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!