Files
rr3-apk/FAQ.md
Daniel Elliott 07075d0777 Expand FAQ with complete code location reference
Added comprehensive 'Code Location Reference' section:
- Network communication files with exact line numbers
- Encryption/security code locations
- Server URL configuration logic
- All game features and managers
- EA Nimble SDK components
- CloudCell API structure
- Android components
- Third-party SDKs
- Search tips and code flow diagrams

Now people can find EXACTLY where code is instead of asking!
2026-02-22 16:55:37 -08:00

836 lines
22 KiB
Markdown

# RR3 Community Server - Frequently Asked Questions (FAQ)
**Last Updated:** February 23, 2026
**Project:** Real Racing 3 Community Server + APK Mod
---
## 🤔 "Just Read The Code" - Common Questions
**Before asking, check here first!** All code is public on Gitea - but here are the most common questions answered quickly.
---
## 🔐 Security & Encryption
### Q: Is the network communication encrypted?
**A:** Yes AND No - it depends what you mean:
- **Transport (HTTPS/TLS):** ✅ YES - data is encrypted in transit
- **Application-level encryption:** ❌ NO - payloads are plaintext over HTTPS
- **Certificate validation:** ❌ DISABLED - accepts any SSL certificate
**Details:** The game uses HTTPS but disables certificate validation, making it vulnerable to MITM attacks but also allowing self-signed certificates for community servers.
**Read More:** `NETWORK-SECURITY-ANALYSIS.md` (16 KB full analysis)
---
### Q: Are the APK network files/code encrypted or obfuscated?
**A:** ❌ NO - completely readable
- **Code obfuscation:** NONE (no ProGuard/R8)
- **Class names:** Readable (Http.java, HttpRequest.java, etc.)
- **Method names:** Readable (sendRequest, postData, etc.)
- **Strings:** Plaintext in smali files
**What IS encrypted:** Local save data on device (AES-256) - NOT network traffic
**Why it matters:** Made reverse engineering easy! If EA had obfuscated the code, this project would be 10x harder.
**See for yourself:**
- `smali_classes2/com/firemint/realracing/Http.smali` - readable class names
- `smali_classes2/com/ea/nimble/SynergyEnvironmentImpl.smali` - readable methods
---
### Q: What encryption DOES the game use?
**A:** Only for local storage:
- **Algorithm:** AES/CBC/PKCS5Padding (256-bit keys)
- **Key derivation:** PBKDF2WithHmacSHA1 (997 rounds)
- **Used for:**
- Saved game data on device
- Cached authentication tokens
- SharedPreferences persistence
**Code location:** `smali_classes2/com/ea/nimble/Encryptor.smali`
**Network payloads:** NOT encrypted (plaintext over HTTPS)
---
## 🌐 Network & Server
### Q: Will the game contact EA servers?
**A:** ❌ NO - EA URLs eliminated in v14 APK
**What we changed:**
- AndroidManifest.xml: `configuration="live"``"customized"`
- EA production URLs unreachable (only if both user config AND manifest fail)
- URL Priority: SharedPreferences > Manifest fallback > Never EA
**Details:** `EA-URL-ELIMINATION.md` (11 KB)
**Test it yourself:**
1. Install APK
2. Monitor with `adb logcat | grep eamobile`
3. Should see ZERO EA domain connections
---
### Q: How does the server URL configuration work?
**A:** 3-tier priority system:
**Priority 1 (Highest):** SharedPreferences
- File: `/data/data/com.ea.games.r3_row/shared_prefs/rr3_community_server.xml`
- Key: `"server_url"`
- Set by: User input in ServerSetupActivity (first launch)
**Priority 2:** AndroidManifest.xml
- Meta-data: `NimbleCustomizedSynergyServerEndpointUrl`
- Default: `http://localhost:5001`
- Used if SharedPreferences empty
**Priority 3:** EA URLs (UNREACHABLE)
- Only accessible if both Priority 1 AND 2 fail
- With `configuration="customized"`, this never happens
**Code:** Lines 959-985 in `SynergyEnvironmentImpl.smali`
---
### Q: What server endpoints are required?
**A:** 73 Synergy API endpoints total
**Status:**
- Implemented: 58/73 (79%)
- Missing: 15 endpoints
**Critical missing:**
- Events Service: 0/4 (blocks career mode)
- Time Trials: 0/5
- Leaderboards: 3/4
- Multiplayer: 0/10+
**Full list:** `SERVER-ENDPOINTS-ANALYSIS.md` (12.7 KB)
---
### Q: Can I use self-signed SSL certificates?
**A:** ✅ YES - the APK accepts ANY certificate
**Why:** Certificate validation is disabled (`ALLOW_ALL_HOSTNAME_VERIFIER`)
**Options:**
1. **Let's Encrypt** (recommended) - free, valid certificates
2. **Self-signed** - works perfectly, free
3. **No SSL (HTTP)** - works but not recommended for production
**Generate self-signed:**
```bash
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
```
---
## 🛠️ APK Modifications
### Q: What was changed in the v14 APK?
**A:** Minimal changes to eliminate EA servers:
**File:** AndroidManifest.xml
- **Line 126:** `android:value="live"``android:value="customized"`
- **Lines 127-128:** Added fallback URL `http://localhost:5001`
**Code added:**
- `CommunityServerManager.smali` - manages server URL preferences
- `ServerSetupActivity.smali` - first-launch server input dialog
- `OfflineModeManager.smali` - online/offline toggle
**That's it!** No other game code modified.
---
### Q: How do I build the APK myself?
**A:** 3-step process:
```bash
# 1. Decompile
apktool d RealRacing3.apk -o rr3-apk
# 2. Make changes (edit AndroidManifest.xml, etc.)
# 3. Rebuild
apktool b rr3-apk -o RR3-modified-unsigned.apk
# 4. Sign
apksigner sign --ks your-keystore.jks \
--out RR3-modified-signed.apk \
RR3-modified-unsigned.apk
```
**Full guide:** `APK-BUILD-AND-TESTING-GUIDE.md` (10 KB)
**Requirements:**
- Java 11+ (OpenJDK recommended)
- apktool 2.10.0+
- Android SDK build-tools
---
### Q: Why isn't ProGuard/obfuscation used?
**A:** EA/Firemonkeys chose not to obfuscate
**Likely reasons:**
- Easier debugging/crash reports
- Faster build times
- Game logic not "secret" (offline mobile game)
- Anti-cheat handled server-side (when servers existed)
**Result:** Made our community server project MUCH easier! 🎉
---
## 🎮 Gameplay & Features
### Q: Can I play offline?
**A:** ✅ YES - offline mode implemented
**How to enable:**
- Settings menu → Toggle "Offline Mode"
- Saves to: `rr3_offline_settings.xml`
- Key: `offline_mode_enabled`
**Limitations:**
- No leaderboards
- No multiplayer
- No cloud save sync
- Career mode works (if Events Service implemented)
**Code:** `smali_classes2/com/firemint/realracing/OfflineModeManager.smali`
---
### Q: Does multiplayer work?
**A:** ❌ NOT YET
**Status:** 0/10+ multiplayer endpoints implemented
**Blockers:**
- Real-time matchmaking system needed
- Race synchronization logic required
- Anti-cheat server-side validation
- P2P or relay server architecture decision
**Priority:** LOW (Phase 3+) - single-player first
---
### Q: Can I charge for in-app purchases?
**A:** ❌ NO - EA's legal restriction
**EA's Terms:**
- ✅ Community servers allowed
- ✅ Donations for server costs allowed
- ❌ Cannot charge for in-app purchases (real money)
- ❌ Cannot charge for the APK itself
**Why:** EA retains the game IP and rights
**Alternative:** Accept donations for server hosting (PayPal, Patreon, etc.)
---
## 🐛 Troubleshooting
### Q: APK won't install - "App not installed"
**A:** Common fixes:
**1. Uninstall existing RR3:**
```bash
adb uninstall com.ea.games.r3_row
```
**2. Check signature:**
```bash
apksigner verify --verbose your-apk.apk
```
**3. Enable "Unknown Sources":**
- Settings → Security → Allow unknown sources
**4. Check architecture:**
- APK supports: armeabi-v7a, arm64-v8a
- Won't work on x86 devices without translation
---
### Q: Game crashes on startup
**A:** Debug steps:
**1. Check logcat:**
```bash
adb logcat -s AndroidRuntime:E
```
**2. Common causes:**
- Missing native libraries (lib/ folder)
- Wrong Android version (need 5.0+)
- Corrupted APK (re-download/rebuild)
**3. Clear app data:**
```bash
adb shell pm clear com.ea.games.r3_row
```
---
### Q: "Cannot connect to server" error
**A:** Checklist:
✅ Server is running: `curl http://localhost:5001/health`
✅ Server URL configured in app
✅ Network connectivity exists
✅ Firewall allows connection
✅ For emulator: Use `http://10.0.2.2:5001` not `localhost`
**Port forwarding (emulator):**
```bash
adb reverse tcp:5001 tcp:5001
```
---
## 📚 Documentation
### Q: Where is all the documentation?
**A:** APK Repository (GitHub) - `rr3-apk` branch `v14`:
**Main Docs:**
- `README.md` - Project overview
- `FAQ.md` - This document!
- `NETWORK-SECURITY-ANALYSIS.md` (16 KB) - Security deep dive
- `EA-URL-ELIMINATION.md` (11 KB) - How EA URLs were eliminated
- `RR3-NETWORK-ANALYSIS-AND-CONFIG-SYSTEM.md` (16 KB) - Network architecture
- `APK-BUILD-AND-TESTING-GUIDE.md` (10 KB) - Build instructions
- `SERVER-ENDPOINTS-ANALYSIS.md` (12.7 KB) - All 73 endpoints mapped
**Server Repository (GitHub) - `RR3CommunityServer` branch `main`:**
- Controllers/*.cs - Server endpoint implementations
- PHASE-1-IMPLEMENTATION-COMPLETE.md - Phase 1 completion docs
---
### Q: How do I contribute?
**A:** Multiple ways to help:
**1. Code:**
- Implement missing endpoints (Events, Time Trials, etc.)
- Fix bugs
- Add features
**2. Documentation:**
- Improve guides
- Write tutorials
- Translate to other languages
**3. Testing:**
- Test on different devices/Android versions
- Report bugs with detailed logs
- Verify endpoint functionality
**4. Assets:**
- Extract game assets (cars, tracks, textures)
- Document asset formats
- Create custom content tools
**Process:**
1. Fork repository on GitHub/Gitea
2. Create feature branch
3. Make changes
4. Submit pull request
5. Describe what you changed and why
---
## 🔧 Development
### Q: What tools do I need?
**A:** APK Development:
- **apktool** 2.10.0+ - APK decompilation/recompilation
- **Java** 11+ - Build environment
- **Android SDK** - Signing & verification
- **Text editor** - VS Code, Sublime, etc.
**Server Development:**
- **.NET 8 SDK** - ASP.NET Core
- **PostgreSQL** (or SQL Server, SQLite) - Database
- **Visual Studio** or **VS Code** - IDE
---
### Q: How long did this project take?
**A:** ~25 checkpoints (sessions) so far
**Breakdown:**
- Checkpoint 1-5: Initial analysis, asset systems, modding
- Checkpoint 6-10: Server browser, daily rewards, progression
- Checkpoint 11-15: Killswitch removal, dual APK variants, settings
- Checkpoint 16-20: Server auth, asset management, APK fixes
- Checkpoint 21-24: Version system, URL configuration, network analysis
**Current Status:** 79% complete (58/73 endpoints)
---
## 💬 Contact & Community
### Q: Where can I ask questions?
**A:** Check these resources first:
1. **This FAQ** - Common questions answered
2. **Documentation** - Deep technical details
3. **Code** - All source code public on Gitea/GitHub
4. **Issues** - GitHub Issues for bug reports
**Still stuck?** Open a GitHub Issue with:
- Detailed description
- Steps to reproduce
- Logcat output
- Device/Android version
---
## 🎯 Quick Reference
### Essential File Locations
**APK (E:\rr3\rr3-apk):**
```
AndroidManifest.xml - App configuration
smali_classes2/
com/firemint/realracing/
Http.smali - Network client
CommunityServerManager.smali - Server URL storage
ServerSetupActivity.smali - First-launch dialog
com/ea/nimble/
SynergyEnvironmentImpl.smali - URL priority logic
Encryptor.smali - AES encryption
```
**Server (E:\rr3\RR3CommunityServer):**
```
Controllers/
ConfigController.cs - Config endpoints
ProgressionController.cs - Save/load, progression
UserController.cs - Authentication
appsettings.json - Server configuration
```
---
## 📂 Complete Code Location Reference
**"Where is [feature] in the code?"** - Here's EVERYTHING:
### 🌐 Network Communication
**HTTP/HTTPS Clients:**
- `smali_classes2/com/firemint/realracing/Http.smali` (189 lines)
- Main HTTP client (POST-only)
- Lines 179-181: ALLOW_ALL_HOSTNAME_VERIFIER (disables SSL validation)
- Lines 38-42: Empty TrustManager (no certificate validation)
- Line 120: URL connection setup
- Lines 158-165: POST data writing
- `smali_classes2/com/firemonkeys/cloudcellapi/HttpRequest.smali` (116 lines)
- CloudCell HTTP client (GET/POST)
- Lines 108-111: SSL context setup with custom TrustManager
- Line 111: ALLOW_ALL_HOSTNAME_VERIFIER enabled
- Lines 45-70: Request execution
- `smali_classes2/com/firemonkeys/cloudcellapi/HttpThread.smali`
- Async HTTP execution
- Chunk-based streaming callbacks
**SSL/TLS Configuration:**
- `smali_classes2/com/firemonkeys/cloudcellapi/CloudcellTrustManager.smali`
- Lines 24: `m_bSSLCheck` flag (default: false)
- Lines 56-76: `checkServerTrusted()` - validation logic (disabled by default)
- Lines 78-89: Certificate chain validation (when enabled)
### 🔐 Encryption & Security
**Data Encryption (Local Storage):**
- `smali_classes2/com/ea/nimble/Encryptor.smali` (286 lines)
- Lines 7-10: Encryption constants (256-bit key, 997 rounds)
- Lines 36-50: Version headers (NEV1, NEV2)
- Lines 62-160: Legacy decryption (PBEWithMD5AndDES)
- Lines 200-270: Modern decryption (AES/CBC/PKCS5Padding)
- Lines 246-260: AES cipher initialization
- Lines 286-320: Key derivation (PBKDF2WithHmacSHA1)
**Persistence:**
- `smali_classes2/com/ea/nimble/PersistenceServiceImpl.smali`
- Uses Encryptor for save data
- Lines 150-200: Save file encryption
- Lines 250-300: Load file decryption
### 🌍 Server URL Configuration
**URL Priority System:**
- `smali_classes2/com/ea/nimble/SynergyEnvironmentImpl.smali` (1800+ lines)
- Lines 953-1049: `getSynergyDirectorServerUrl()` - MAIN URL LOGIC
- Lines 959-985: SharedPreferences check (Priority 1)
- Lines 990-1048: Configuration mode switch
- Lines 1008: EA Integration URL (unreachable with CUSTOMIZED)
- Lines 1041: EA Staging URL (unreachable with CUSTOMIZED)
- Lines 1046: EA Production URL (unreachable with CUSTOMIZED)
**Community Server Manager:**
- `smali_classes2/com/firemint/realracing/CommunityServerManager.smali` (136 lines)
- Lines 24-58: `checkServerUrl()` - returns boolean if URL exists
- Lines 60-96: `getServerUrl()` - retrieves URL from SharedPreferences
- Lines 98-136: `saveServerUrl()` - saves URL to SharedPreferences
- SharedPreferences file: `"rr3_community_server"`
- SharedPreferences key: `"server_url"`
**Server Setup Dialog:**
- `smali_classes2/com/firemint/realracing/ServerSetupActivity.smali`
- First-launch UI for server URL input
- Test connection button logic
- Save and continue functionality
### ⚙️ Configuration Files
**App Manifest:**
- `AndroidManifest.xml`
- Line 126: `com.ea.nimble.configuration` - **"customized"** (was "live")
- Lines 127-128: `NimbleCustomizedSynergyServerEndpointUrl` - fallback URL
- Lines 32-35: Permissions (INTERNET, NETWORK_STATE, etc.)
- Lines 45-120: EA Nimble SDK meta-data
- Line 210: `networkSecurityConfig` reference
- Line 215: `usesCleartextTraffic="false"` (HTTPS enforced)
**Network Security Config:**
- `res/xml/network_security_config.xml`
- Trust settings for HTTPS
- Certificate configuration
### 🎮 Game Features
**Offline Mode:**
- `smali_classes2/com/firemint/realracing/OfflineModeManager.smali` (131 lines)
- Lines 36-77: `init()` - loads preference on startup
- Lines 79-86: `isOfflineMode()` - getter
- Lines 88-131: `setOfflineMode()` - setter with persistence
- SharedPreferences file: `"rr3_offline_settings"`
- SharedPreferences key: `"offline_mode_enabled"`
**Settings Activity:**
- `smali_classes2/com/firemint/realracing/SettingsActivity.smali`
- Offline mode toggle UI
- Server URL change option
- Game settings management
### 🚗 EA Nimble SDK (Core Services)
**Synergy (Authentication/Backend):**
- `smali_classes2/com/ea/nimble/SynergyEnvironmentImpl.smali`
- Main Synergy implementation
- Lines 1-100: Constants and initialization
- Lines 953-1049: Server URL selection logic
- Lines 1100-1200: Director API calls
- `smali_classes2/com/ea/nimble/SynergyIdManager.smali`
- Synergy ID generation/storage
- User identification system
- `smali_classes2/com/ea/nimble/SynergyNetwork.smali`
- Network request handling
- API endpoint calls
**Application Environment:**
- `smali_classes2/com/ea/nimble/ApplicationEnvironmentImpl.smali`
- App bundle ID
- Version information
- Device info
**Tracking/Analytics:**
- `smali_classes2/com/ea/nimble/Tracking*.smali`
- Analytics event tracking
- Synergy event logging
### 💰 CloudCell API (Billing/Social)
**Billing:**
- `smali_classes2/com/firemonkeys/cloudcellapi/GooglePlayWorker.smali`
- Google Play IAB integration
- Purchase handling
- Inventory management
- `smali_classes2/com/firemonkeys/cloudcellapi/AmazonStoreWorker.smali`
- Amazon Appstore integration
- `smali_classes2/com/firemonkeys/cloudcellapi/FacebookWorker.smali`
- Facebook payments
**Inventory/Purchases:**
- `smali_classes2/com/firemonkeys/cloudcellapi/util/Inventory.smali`
- IAB inventory management
- `smali_classes2/com/firemonkeys/cloudcellapi/util/Purchase.smali`
- Purchase data handling
**Security:**
- `smali_classes2/com/firemonkeys/cloudcellapi/Security.smali`
- Signature verification (Google Play)
- Base64 encoding/decoding
### 📱 Android Components
**Main Activity:**
- `smali_classes2/com/firemint/realracing/MainActivity.smali`
- App entry point
- Launches ServerSetupActivity on first run
**Splash Screen:**
- `smali_classes2/com/firemint/realracing/SplashActivity.smali`
- Initial loading screen
- Asset check trigger
**JNI Bridge:**
- `smali_classes2/com/firemint/realracing/JNI*.smali`
- Native code bridge
- C++ game engine communication
### 🗂️ Assets & Resources
**Asset Locations:**
- `assets/`
- Game data files
- Car models, tracks, textures
- Configuration files
- Audio files
**Resources:**
- `res/layout/` - UI layouts
- `res/drawable/` - Images
- `res/values/strings.xml` - String resources
- `res/xml/network_security_config.xml` - Network config
### 📊 Third-Party SDKs
**Firebase:**
- `smali_classes2/com/google/firebase/`
- Analytics
- Crashlytics
- Performance monitoring
**Facebook SDK:**
- `smali_classes2/com/facebook/`
- Login integration
- Graph API
- Share functionality
**Ad Networks:**
- `smali_classes2/com/ironsource/` - IronSource ads
- `smali_classes2/com/vungle/` - Vungle ads
- `smali_classes2/com/fyber/` - Fyber ads
- `smali_classes2/com/tapjoy/` - Tapjoy reward ads
### 🔧 Build Files
**Build Configuration:**
- `apktool.yml` - APK metadata
- Version info
- SDK versions
- Compression settings
**Native Libraries:**
- `lib/armeabi-v7a/` - 32-bit ARM libraries
- `lib/arm64-v8a/` - 64-bit ARM libraries
- `lib/x86/` - x86 libraries (if present)
### 📝 Documentation Files
**Security & Network:**
- `NETWORK-SECURITY-ANALYSIS.md` (16 KB)
- Complete security audit
- SSL/TLS analysis
- Attack vectors
- Mitigation strategies
- `EA-URL-ELIMINATION.md` (11 KB)
- URL priority system
- Code flow analysis
- EA URL removal proof
- `RR3-NETWORK-ANALYSIS-AND-CONFIG-SYSTEM.md` (16 KB)
- Network stack architecture
- CloudCell API docs
- Config system design
**Build & Testing:**
- `APK-BUILD-AND-TESTING-GUIDE.md` (10 KB)
- Build instructions
- Testing procedures
- Troubleshooting
**Implementation Status:**
- `SERVER-ENDPOINTS-ANALYSIS.md` (12.7 KB)
- All 73 endpoints mapped
- Implementation status
- Priority assignments
---
## 🗺️ Code Navigation Tips
### Finding Specific Features:
**1. Search by functionality:**
```bash
# Find network-related code
grep -r "http\|Http\|network" smali_classes2/com/firemint/realracing/
# Find encryption code
grep -r "encrypt\|Encrypt\|cipher\|Cipher" smali_classes2/com/ea/nimble/
# Find server URL logic
grep -r "server.*url\|ServerUrl" smali_classes2/
```
**2. Search by string:**
```bash
# Find EA URLs
grep -r "eamobile.com" smali_classes2/
# Find configuration keys
grep -r "rr3_community_server\|offline_mode" smali_classes2/
# Find SharedPreferences usage
grep -r "SharedPreferences" smali_classes2/
```
**3. Search by method name:**
```bash
# Find URL getter
grep -r "getSynergyDirectorServerUrl" smali_classes2/
# Find encryption methods
grep -r "checkServerTrusted\|init.*Cipher" smali_classes2/
```
### Understanding Code Flow:
**Server URL Resolution:**
```
1. Game starts → MainActivity.smali
2. Check config → CommunityServerManager.checkServerUrl()
3. Get URL → SynergyEnvironmentImpl.getSynergyDirectorServerUrl()
├─ Priority 1: SharedPreferences ("rr3_community_server.xml")
├─ Priority 2: AndroidManifest.xml (NimbleCustomizedSynergyServerEndpointUrl)
└─ Priority 3: EA URLs (UNREACHABLE with configuration="customized")
4. Make API call → Http.smali or HttpRequest.smali
```
**First Launch Flow:**
```
1. MainActivity.smali → onCreate()
2. Check if first launch (no SharedPreferences)
3. Launch → ServerSetupActivity.smali
4. User inputs server URL
5. Save → CommunityServerManager.saveServerUrl()
6. Restart → MainActivty with URL configured
```
**Network Request Flow:**
```
1. Game needs data → SynergyNetwork.smali
2. Build request → URL + parameters
3. Send via → Http.smali (POST) or HttpRequest.smali (GET/POST)
4. TLS handshake → CloudcellTrustManager (accepts all certs)
5. Receive response → Parse JSON
6. If save needed → Encryptor.smali (AES-256)
```
---
### Quick Commands
**Build APK:**
```bash
apktool b rr3-apk -o RR3-unsigned.apk
```
**Sign APK:**
```bash
apksigner sign --ks keystore.jks --out RR3-signed.apk RR3-unsigned.apk
```
**Install APK:**
```bash
adb install -r RR3-signed.apk
```
**Monitor Logs:**
```bash
adb logcat | grep -i "rr3\|synergy\|community"
```
**Check Server URL:**
```bash
adb shell cat /data/data/com.ea.games.r3_row/shared_prefs/rr3_community_server.xml
```
**Run Server:**
```bash
cd RR3CommunityServer
dotnet run
```
---
## 🎉 Did This Help?
If this FAQ answered your question, consider:
- ⭐ Starring the repository
- 📖 Reading the detailed documentation
- 🤝 Contributing improvements
- 💬 Helping others in Issues
**Remember:** All code is public! When in doubt, read the source. 😊
---
**FAQ Version:** 1.0
**Last Updated:** February 23, 2026
**Maintainer:** Community Server Project Team
**Repository Links:**
- APK: https://github.com/supermegamestre/Project-Real-Resurrection-3 (v14 branch)
- Server: https://github.com/supermegamestre/RR3CommunityServer (main branch)