Add Complete Server Browser UI System

MAJOR UPDATE - In-game server management without rebuilding APK! SERVER BROWSER UI: - Beautiful WebView-based interface - Add/edit/delete unlimited servers - Real-time online/offline status - One-click server switching - Favorites system - Connection testing before save - Professional UX with racing theme HTML ASSETS: + assets/community_servers_list.html - Main server browser interface - Server cards with status indicators - Connect/Edit/Delete actions - Empty state and loading states + assets/community_server_edit.html - Add/edit server form - URL validation and testing - Favorite marking - Professional form design INSTALLATION TOOL: + RR3-Server-Browser-Installer.ps1 - Automated installation script - Decompiles APK with apktool - Injects HTML assets - Updates AndroidManifest.xml - Rebuilds and signs APK - Pre-configure default servers - Full error handling DOCUMENTATION: + docs/SERVER_BROWSER_GUIDE.md - Complete user guide - Adding/editing/deleting servers - Connection flow - Troubleshooting - Developer integration + docs/SMALI_REFERENCE.md - Java bridge code reference - CommunityServerManager class - WebView activity hosts - Smali conversion guide - Testing & debugging tips UPDATED README: * Comprehensive overview * Quick start examples * Feature highlights * Use cases (players/owners/devs) * Architecture explanation * Screenshots in ASCII art ARCHITECTURE: - HTML/CSS/JS UI layer (assets/) - JavascriptInterface bridge (smali) - SharedPreferences storage - SynergyEnvironmentImpl patch - WebView activities for hosting USER FLOW: 1. Open Server Browser from game 2. Add server (name + URL) 3. Test connection 4. Save server 5. Tap Connect 6. Restart game -> Active! BENEFITS: ✓ One APK for unlimited servers ✓ No rebuild needed to change servers ✓ Users can add servers themselves ✓ Server owners can share one APK ✓ Professional UI experience ✓ Local + LAN + public servers ✓ Favorites and status tracking TECHNICAL DETAILS: - Data stored in SharedPreferences - JavaScript <-> Android bridge - Async server pinging - URL validation - Toast notifications - File:// asset loading This enables true community server ecosystem! Users can maintain their own server list without technical knowledge or APK rebuilding. Perfect companion to rr3-server project! Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-02-17 22:29:22 -08:00
parent d144aec853
commit ad15ecb2d7
6 changed files with 1663 additions and 6 deletions
--- a/docs/SERVER_BROWSER_GUIDE.md
+++ b/docs/SERVER_BROWSER_GUIDE.md
@@ -0,0 +1,261 @@
+# 🌐 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!