From 83d1f8ff61bb9fca2a6a56a4a4ec66f18f56a6c2 Mon Sep 17 00:00:00 2001
From: Daniel Elliott <ssfdre38@msn.com>
Date: Sun, 22 Feb 2026 16:51:33 -0800
Subject: [PATCH] Add comprehensive FAQ - 'Just Read The Code' edition
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers most common questions people ask instead of reading:
- Network encryption/obfuscation status
- EA URL elimination details
- Server configuration system
- SSL certificate options
- APK building process
- Gameplay features status
- Troubleshooting guide
- Quick reference commands

Now we can just link the FAQ when people ask! 😊
---
 FAQ.md | 507 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 507 insertions(+)
 create mode 100644 FAQ.md

diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 000000000..9d37a3bbc
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,507 @@
+# 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
+```
+
+---
+
+### 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)