From 43a74d36508d8b13a539f76e5ad5a2da4880cd74 Mon Sep 17 00:00:00 2001
From: Daniel Elliott <ssfdre38@msn.com>
Date: Thu, 19 Feb 2026 18:31:22 -0800
Subject: [PATCH] Add comprehensive Getting Started guide

- Complete step-by-step build instructions
- Quick start for beginners
- Troubleshooting section
- Android 16 compatibility notes
- Multiple build options explained
- Tips & tricks for faster builds
- Updated README.md with link to guide

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 GETTING-STARTED.md | 423 +++++++++++++++++++++++++++++++++++++++++++++
 README.md          |  12 ++
 2 files changed, 435 insertions(+)
 create mode 100644 GETTING-STARTED.md

diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md
new file mode 100644
index 000000000..20e77aaf3
--- /dev/null
+++ b/GETTING-STARTED.md
@@ -0,0 +1,423 @@
+# 🚀 Getting Started - Building RR3 Community APK
+
+**Welcome!** This guide will walk you through building a modified Real Racing 3 APK that connects to community servers.
+
+---
+
+## 📋 Prerequisites
+
+### What You Need
+
+1. **Original RR3 APK** (v15.0.0 or similar)
+   - Extract from your Android device
+   - Or download from APK mirror sites
+   - File: `realracing3.apk` or `com.ea.games.r3_row.apk`
+
+2. **Windows PC** with PowerShell
+   - Windows 10/11 recommended
+   - PowerShell 5.1+ (comes with Windows)
+
+3. **Java Development Kit (JDK)**
+   - Version 8 or higher
+   - Download: https://adoptium.net/
+
+4. **15-20 minutes** of your time ☕
+
+---
+
+## ⚡ Quick Start (Easiest Method)
+
+### Step 1: Clone This Repository
+
+```powershell
+git clone https://gitea.barrer.net/project-real-resurrection-3/rr3-apk.git
+cd rr3-apk
+```
+
+Or download as ZIP and extract.
+
+### Step 2: Place Original APK
+
+Copy your original RR3 APK to the project folder:
+```
+rr3-apk/
+├── realracing3.apk  ← Place your APK here
+├── RR3-Community-Mod.ps1
+└── ...
+```
+
+### Step 3: Run the Build Script
+
+**Option A - Connect to Your Server:**
+```powershell
+.\RR3-Community-Mod.ps1 -ServerUrl "http://your-server-ip:5001"
+```
+
+**Option B - Add Server Browser UI:**
+```powershell
+.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk"
+```
+
+**Option C - Default Local Server:**
+```powershell
+.\RR3-Community-Mod.ps1 -ServerUrl "http://localhost:5001"
+```
+
+### Step 4: Install on Android Device
+
+1. Enable **USB Debugging** on your Android device:
+   - Settings → About Phone → Tap "Build Number" 7 times
+   - Settings → Developer Options → Enable USB Debugging
+
+2. Connect device to PC via USB
+
+3. Install the APK:
+```powershell
+adb install -r RR3-v15.0.0-community-alpha.apk
+```
+
+Or transfer the APK to your device and install manually.
+
+### Step 5: Launch & Play! 🎮
+
+The game will now connect to your community server instead of EA's servers!
+
+---
+
+## 📚 Detailed Manual Build Process
+
+If you prefer to understand each step or the scripts don't work, follow the manual process:
+
+### 1. Install Required Tools
+
+**Java JDK:**
+```powershell
+# Check if Java is installed
+java -version
+
+# If not installed, download from:
+# https://adoptium.net/temurin/releases/
+```
+
+**APKTool:**
+```powershell
+# Download apktool from:
+# https://ibotpeaches.github.io/Apktool/
+
+# Place apktool.bat and apktool.jar in:
+# C:\Windows\
+```
+
+**Uber APK Signer:**
+```powershell
+# Download from:
+# https://github.com/patrickfav/uber-apk-signer/releases
+
+# Place uber-apk-signer.jar in project folder
+```
+
+### 2. Decompile APK
+
+```powershell
+apktool d realracing3.apk -o rr3-decompiled
+```
+
+This creates a folder `rr3-decompiled` with all APK contents.
+
+### 3. Modify AndroidManifest.xml
+
+Open `rr3-decompiled/AndroidManifest.xml` and find this section:
+
+```xml
+<meta-data
+    android:name="com.ea.nimble.configuration"
+    android:value="live" />
+```
+
+**Change to:**
+```xml
+<meta-data
+    android:name="com.ea.nimble.configuration"
+    android:value="custom" />
+    
+<meta-data
+    android:name="NimbleCustomizedSynergyServerEndpointUrl"
+    android:value="http://your-server-ip:5001" />
+```
+
+**Also add this to the `<application>` tag:**
+```xml
+<application
+    android:extractNativeLibs="true"
+    ...
+```
+
+This is required for Android 15+ compatibility.
+
+### 4. Recompile APK
+
+```powershell
+apktool b rr3-decompiled -o realracing3-community.apk
+```
+
+### 5. Align APK (Important for Android 15+)
+
+```powershell
+# Must use -P 16 flag (uppercase P, page size 16KB)
+zipalign -f -P 16 -v 16 realracing3-community.apk realracing3-community-aligned.apk
+```
+
+### 6. Sign APK
+
+```powershell
+java -jar uber-apk-signer.jar --apks realracing3-community-aligned.apk
+```
+
+This creates: `realracing3-community-aligned-signed.apk`
+
+### 7. Install on Device
+
+```powershell
+# Uninstall original (if installed)
+adb uninstall com.ea.games.r3_row
+
+# Install community version
+adb install realracing3-community-aligned-signed.apk
+```
+
+---
+
+## 🎯 Different Build Options
+
+### Option 1: Direct Server Connection
+**Use when:** You have a specific server you always want to connect to
+
+**Command:**
+```powershell
+.\RR3-Community-Mod.ps1 -ServerUrl "http://community.example.com:8443"
+```
+
+**Result:** APK always connects to that server
+
+---
+
+### Option 2: Server Browser UI
+**Use when:** You want to switch between multiple servers
+
+**Command:**
+```powershell
+.\RR3-Server-Browser-Installer.ps1 -ApkPath "realracing3.apk"
+```
+
+**Result:** APK has in-game menu to add/switch servers
+
+**Features:**
+- Add unlimited servers
+- Save favorites
+- Test connection before connecting
+- Switch servers without reinstalling APK
+
+---
+
+### Option 3: Localhost Testing
+**Use when:** Running server on your PC for testing
+
+**Command:**
+```powershell
+.\RR3-Community-Mod.ps1 -ServerUrl "http://localhost:5001"
+```
+
+**Note:** Your Android device must be on the same network and use your PC's IP (e.g., `http://192.168.1.100:5001`)
+
+---
+
+## 🔧 Troubleshooting
+
+### "APKTool not found"
+**Solution:** Install APKTool and add to PATH, or place in `C:\Windows\`
+
+### "Failed to parse AndroidManifest.xml"
+**Solution:** Use a proper text editor (VS Code, Notepad++), not Notepad. Check XML syntax.
+
+### "Installation failed: INSTALL_FAILED_INVALID_APK"
+**Solution:** 
+- Make sure you ran `zipalign -P 16` (uppercase P!)
+- Check that `extractNativeLibs="true"` is in manifest
+- Verify APK is signed
+
+### "App crashes on startup"
+**Solution:**
+- Check logcat: `adb logcat | grep RR3`
+- Make sure you didn't modify any smali files
+- Verify server URL is correct in manifest
+
+### "Connection refused" or "Cannot connect to server"
+**Solution:**
+- Verify server is running: `curl http://your-server-ip:5001/director/api/android/getDirectionByPackage`
+- Check firewall allows connections
+- If using localhost, use PC's network IP instead
+
+### "JNI Error" or "Native crash"
+**Solution:**
+- This usually means the APK wasn't built correctly
+- Start over from Step 1
+- Make sure you're using the v14 branch: `git checkout v14`
+
+---
+
+## 📱 Android 16 Compatibility
+
+If you're on Android 16 (API 35+), you **must** include these changes:
+
+1. **In AndroidManifest.xml:**
+```xml
+<application
+    android:extractNativeLibs="true"
+    ...
+```
+
+2. **Use correct zipalign flag:**
+```powershell
+zipalign -f -P 16 -v 16 input.apk output.apk
+```
+
+The `-P 16` (uppercase P) is critical! Lowercase `-p` only does 4KB alignment which isn't enough.
+
+---
+
+## 🎮 After Installation
+
+### First Launch
+1. Game will take 2-3 minutes to extract assets (first time only)
+2. You'll see the EA splash screen
+3. Game should connect to your community server
+
+### If Using Server Browser
+1. Open game
+2. Click "Settings" or "Servers" in menu
+3. Add your server URL
+4. Click "Connect"
+
+### Verify Connection
+Check your server logs for:
+```
+Director request for package: com.ea.games.r3_row
+```
+
+If you see this, the APK is successfully connecting! 🎉
+
+---
+
+## 📚 Additional Documentation
+
+For more detailed information, see:
+
+- **[APK_MODIFICATION_GUIDE.md](APK_MODIFICATION_GUIDE.md)** - Complete technical guide
+- **[NETWORK_COMMUNICATION_ANALYSIS.md](NETWORK_COMMUNICATION_ANALYSIS.md)** - How the game communicates
+- **[KEYSTORE-README.md](KEYSTORE-README.md)** - Creating signing keys
+- **[SERVER_BROWSER_GUIDE.md](docs/SERVER_BROWSER_GUIDE.md)** - Server browser feature
+
+---
+
+## 💡 Tips & Tricks
+
+### Speed Up Builds
+Once you've built once, subsequent builds are faster:
+```powershell
+# Just recompile + sign (skip decompile)
+apktool b rr3-decompiled -o output.apk
+zipalign -f -P 16 -v 16 output.apk output-aligned.apk
+java -jar uber-apk-signer.jar --apks output-aligned.apk
+```
+
+### Test Without Device
+Use Android Emulator:
+```powershell
+# Create emulator
+avdmanager create avd -n RR3Test -k "system-images;android-34;google_apis;x86_64"
+
+# Start emulator
+emulator -avd RR3Test
+
+# Install APK
+adb install your-apk.apk
+```
+
+### Multiple Versions
+You can install multiple versions side-by-side by changing the package name in AndroidManifest.xml:
+```xml
+<manifest package="com.ea.games.r3_row.community" ...>
+```
+
+---
+
+## 🆘 Getting Help
+
+**If you're stuck:**
+
+1. Check the [Issues](https://gitea.barrer.net/project-real-resurrection-3/rr3-apk/issues) page
+2. Read the detailed guides in the `docs/` folder
+3. Check server logs for connection errors
+4. Use `adb logcat` to see Android logs
+
+**When asking for help, include:**
+- Android version
+- APK build command you used
+- Error message (full text)
+- Server URL you're connecting to
+
+---
+
+## 🎉 Success!
+
+If you successfully built and installed the APK:
+
+1. **Star this repository** ⭐
+2. **Share with the community** 🎮
+3. **Report any bugs** you find 🐛
+4. **Consider contributing** improvements 💪
+
+---
+
+## 📜 Legal Notice
+
+This project is for **educational purposes** and **game preservation** only. Real Racing 3 is owned by Electronic Arts (EA). This tool is intended for:
+
+- Running private servers after official servers shut down
+- Educational analysis of Android APK structure
+- Game preservation efforts
+- Personal offline play
+
+**Not intended for:**
+- Piracy or unauthorized distribution
+- Circumventing in-app purchases
+- Online cheating or hacking
+- Commercial use
+
+Use responsibly! 🙏
+
+---
+
+## ✅ Quick Checklist
+
+Before building, make sure you have:
+
+- [ ] Original RR3 APK file
+- [ ] Java JDK installed (`java -version` works)
+- [ ] APKTool installed
+- [ ] Uber APK Signer downloaded
+- [ ] USB Debugging enabled on Android device
+- [ ] Server running (if testing connection)
+- [ ] 15-20 minutes of time
+
+Then run:
+```powershell
+.\RR3-Community-Mod.ps1 -ServerUrl "http://your-server:5001"
+```
+
+---
+
+**Happy Racing! 🏎️💨**
+
+*Last Updated: February 20, 2026*
+*Version: v14 (Android 16 Compatible)*
diff --git a/README.md b/README.md
index a45fdac51..e5820c8bf 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,18 @@
 
 This repository contains tools to modify the Real Racing 3 APK to connect to **community-hosted servers** instead of EA's official servers. Perfect for game preservation, private servers, and offline play.
 
+---
+
+## 🚀 **[NEW: Getting Started Guide!](GETTING-STARTED.md)**
+
+**First time building?** Check out our comprehensive **[GETTING-STARTED.md](GETTING-STARTED.md)** guide with:
+- ✅ Step-by-step instructions
+- ✅ Troubleshooting tips
+- ✅ Android 16 compatibility guide
+- ✅ Quick start in 5 minutes
+
+---
+
 ## ✨ NEW: Server Browser UI
 
 **No more rebuilding APKs!** The new Server Browser feature lets users manage multiple community servers from within the game: