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.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **[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:
|
||||
|
||||
Reference in New Issue
Block a user