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>
This commit is contained in:
423
GETTING-STARTED.md
Normal file
423
GETTING-STARTED.md
Normal file
@@ -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)*
|
||||||
12
README.md
12
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.
|
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
|
## ✨ NEW: Server Browser UI
|
||||||
|
|
||||||
**No more rebuilding APKs!** The new Server Browser feature lets users manage multiple community servers from within the game:
|
**No more rebuilding APKs!** The new Server Browser feature lets users manage multiple community servers from within the game:
|
||||||
|
|||||||
Reference in New Issue
Block a user