rr3-server/MODDING_GUIDE.md

# RR3 Community Server - Custom Content & Modding System
**Turn RR3 into a MODDABLE racing game!**

---

## 🎨 Overview

Your RR3 Community Server now supports **FULL CUSTOM CONTENT**:
- ✅ Custom cars (models, textures, audio)
- ✅ Custom tracks (layouts, scenery)
- ✅ Mod packs (bundles of content)
- ✅ Community sharing
- ✅ Version control
- ✅ Rating system

---

## 🚀 Features

### For Players:
- Download & install custom cars/tracks
- Subscribe to mod packs
- Rate & review content
- Automatic updates

### For Modders:
- Upload custom content via API
- Version your mods
- Track download stats
- Build mod packs
- Community showcase

---

## 📦 Custom Car Upload

### API Endpoint:
```
POST /modding/api/cars/upload
Content-Type: multipart/form-data
```

### Required Files:
| File | Type | Max Size | Description |
|------|------|----------|-------------|
| Model3D | .pak | 50 MB | 3D car model |
| Thumbnail | .png | 5 MB | Preview image |
| Textures | .pvr (optional) | 20 MB | Car skin/paint |
| EngineAudio | .ogg (optional) | 10 MB | Engine sound |

### Metadata:
```json
{
  "CarName": "Custom Bugatti Chiron",
  "Manufacturer": "Bugatti",
  "ClassType": "S",
  "PerformanceRating": 95,
  "Year": 2024,
  "CashPrice": 500000,
  "GoldPrice": 1000,
  "Description": "Custom tuned Chiron with 1600HP",
  "AuthorName": "YourUsername",
  "Version": "1.0"
}
```

### Example (PowerShell):
```powershell
$form = @{
    Model3D = Get-Item "bugatti_chiron.pak"
    Thumbnail = Get-Item "bugatti_thumb.png"
    Textures = Get-Item "bugatti_textures.pvr"
    EngineAudio = Get-Item "w16_engine.ogg"
    CarName = "Custom Bugatti Chiron"
    Manufacturer = "Bugatti"
    ClassType = "S"
    PerformanceRating = 95
    Year = 2024
    CashPrice = 500000
    GoldPrice = 1000
    Description = "Custom tuned Chiron"
    AuthorName = "MyUsername"
    Version = "1.0"
}

Invoke-RestMethod -Uri "https://localhost:5001/modding/api/cars/upload" `
    -Method POST `
    -Form $form
```

### Response:
```json
{
  "success": true,
  "carId": "custom_a7f3b2e9d1c4",
  "name": "Custom Bugatti Chiron",
  "message": "Custom car uploaded successfully!",
  "files": {
    "model": "E:\\Assets\\custom\\cars\\custom_a7f3b2e9d1c4\\model.pak",
    "thumbnail": "E:\\Assets\\custom\\cars\\custom_a7f3b2e9d1c4\\thumbnail.png"
  }
}
```

---

## 🏁 Custom Track Upload

### API Endpoint:
```
POST /modding/api/tracks/upload
Content-Type: multipart/form-data
```

### Required Files:
| File | Type | Max Size | Description |
|------|------|----------|-------------|
| TrackData | .pak | 100 MB | Track layout & data |
| Thumbnail | .png | 5 MB | Preview image |
| Scenery | .pak (optional) | 80 MB | Environment assets |

### Metadata:
```json
{
  "TrackName": "Custom Touge Pass",
  "Country": "Japan",
  "Description": "Mountain pass inspired by Akina",
  "AuthorName": "YourUsername",
  "Version": "1.0",
  "LengthKm": 5.2,
  "Corners": 42
}
```

---

## 📋 Get Custom Content

### List Custom Cars:
```http
GET /modding/api/cars
```

**Response:**
```json
{
  "success": true,
  "count": 15,
  "cars": [
    {
      "carId": "custom_a7f3b2e9d1c4",
      "name": "Custom Bugatti Chiron",
      "manufacturer": "Bugatti",
      "classType": "S",
      "performanceRating": 95,
      "author": "ModderName",
      "version": "1.0",
      "createdAt": "2026-02-18T09:00:00Z"
    }
  ]
}
```

### List All Custom Content:
```http
GET /modding/api/content?type=car_model&author=Username
```

---

## 🎁 Mod Packs

### Create a Mod Pack:
```http
POST /modding/api/modpack/create
Content-Type: application/json
```

**Body:**
```json
{
  "PackName": "JDM Legends Pack",
  "Author": "ModderName",
  "Description": "Classic Japanese sports cars",
  "Version": "1.0",
  "CarIds": [
    "custom_skyline_gtr",
    "custom_supra_mk4",
    "custom_rx7_fd"
  ]
}
```

**Response:**
```json
{
  "success": true,
  "packId": "modpack_3f2a1b9c",
  "name": "JDM Legends Pack",
  "downloadUrl": "/modding/api/modpack/modpack_3f2a1b9c/download"
}
```

### Get Mod Packs:
```http
GET /modding/api/modpacks
```

---

## 🛠️ Creating Custom Cars

### Step 1: Extract Original Car Model

Use tools like:
- **Unity Asset Bundle Extractor** (for .pak files)
- **Blender** (for 3D editing)
- **Photoshop/GIMP** (for textures)

### Step 2: Edit the Model

```
1. Import .pak file into Blender
2. Modify mesh (body kit, spoilers, etc.)
3. Adjust materials/shaders
4. Export as .pak with same structure
```

### Step 3: Create Textures

```
- Extract original .pvr textures
- Edit in Photoshop
- Convert back to .pvr format
- Pack into asset bundle
```

### Step 4: Add Custom Audio

```
- Record or find engine sound (.wav)
- Convert to .ogg format
- Match RR3 audio structure
```

### Step 5: Test & Upload

```powershell
# Test locally first
Copy-Item custom_car.pak -Destination "E:\rr3\RR3CommunityServer\Assets\custom\cars\test\"

# Upload to server
.\upload-custom-car.ps1 -CarPak "custom_car.pak" -Thumbnail "thumb.png"
```

---

## 🏗️ Creating Custom Tracks

### Track Requirements:

**Minimum:**
- Track mesh (road surface)
- Collision boundaries
- Start/finish line
- Pit lane (optional)

**Recommended:**
- Scenery (buildings, trees)
- Lighting setup
- Weather support
- Multiple layouts

### Tools Needed:
- Unity (RR3 uses Unity engine)
- Blender (3D modeling)
- Track editor plugins

### Process:
```
1. Design track layout (top-down view)
2. Create 3D mesh in Blender
3. Import to Unity
4. Add collisions & checkpoints
5. Add scenery & lighting
6. Build asset bundle (.pak)
7. Test in game
8. Upload to server
```

---

## 🎮 In-Game Integration

### How Players Get Custom Content:

**Option 1: Automatic (Server-Side)**
```
1. Player opens dealership
2. Sees "CUSTOM" category
3. Custom cars appear with "MOD" badge
4. Purchase with in-game currency
5. Download happens automatically
```

**Option 2: Manual (Mod Browser)**
```
1. Player opens "Mods" menu (custom APK)
2. Browses available mods
3. Clicks "Subscribe"
4. Content downloads & installs
5. Available in garage
```

---

## 📊 Modding Statistics

### Track Your Mods:
```http
GET /modding/api/content?author=YourUsername
```

**See:**
- Download count
- Ratings
- Comments
- Version history

---

## 🔒 Content Guidelines

### Allowed:
✅ Original creations
✅ Inspired-by designs (non-infringing)
✅ Fictional cars/tracks
✅ Performance mods
✅ Visual enhancements

### NOT Allowed:
❌ Stolen assets from other games
❌ Copyright violations
❌ Malicious content
❌ Inappropriate content
❌ Game-breaking exploits

---

## 🚧 Advanced: Mod Pack Creation

### Create a Themed Collection:

**Example: "Formula Legends Pack"**
```json
{
  "PackName": "Formula Legends Pack",
  "Description": "Iconic F1 cars from 1960-2000",
  "Version": "2.0",
  "CarIds": [
    "custom_lotus_49",
    "custom_mclaren_mp4_4",
    "custom_ferrari_f2004",
    "custom_williams_fw14b"
  ],
  "TrackIds": [
    "custom_old_monaco",
    "custom_silverstone_classic"
  ]
}
```

### Versioning:
```
v1.0 - Initial release (4 cars)
v1.1 - Bug fixes
v2.0 - Added 2 custom tracks
v2.1 - Performance tuning
```

---

## 🔧 Server Configuration

### Enable/Disable Modding:

**appsettings.json:**
```json
{
  "ServerSettings": {
    "EnableModding": true,
    "MaxCustomCarUploadSizeMB": 100,
    "MaxCustomTrackUploadSizeMB": 200,
    "RequireModeratorApproval": false,
    "AllowNSFWContent": false
  }
}
```

---

## 🌐 Community Features (Future)

### Planned:
- [ ] Web-based mod browser
- [ ] Rating & review system
- [ ] Mod dependency management
- [ ] Automatic conflict resolution
- [ ] Workshop integration
- [ ] Mod showcase page
- [ ] Creator profiles
- [ ] Donation support

---

## 📚 Resources

### Modding Tools:
- **Unity Asset Bundle Extractor** - Extract/edit .pak files
- **Blender** - 3D modeling
- **Audacity** - Audio editing
- **GIMP/Photoshop** - Texture editing
- **PVRTexTool** - Convert to .pvr format

### Community:
- Discord: RR3 Modding Community (create one!)
- Reddit: r/RR3Mods (create one!)
- GitHub: Share your tools

---

## 🎯 Quick Start (Modders)

1. **Extract original assets** from game
2. **Edit** model/textures in Blender/Photoshop
3. **Export** as .pak with correct format
4. **Test locally** by copying to Assets/custom/
5. **Upload** via API endpoint
6. **Share** with community!

---

## 🎯 Quick Start (Players)

1. **Browse mods**: `GET /modding/api/cars`
2. **Download**: Game handles automatically
3. **Install**: Appears in garage
4. **Race**: Just like any other car!

---

## 💡 Example: Full Workflow

### Creating & Uploading a Custom Nissan GT-R:

```powershell
# Step 1: Prepare files
$modelPak = "E:\rr3\mods\gtr_r35_custom.pak"
$thumbnail = "E:\rr3\mods\gtr_thumbnail.png"
$textures = "E:\rr3\mods\gtr_textures.pvr"

# Step 2: Upload
$response = Invoke-RestMethod `
    -Uri "https://localhost:5001/modding/api/cars/upload" `
    -Method POST `
    -Form @{
        Model3D = Get-Item $modelPak
        Thumbnail = Get-Item $thumbnail
        Textures = Get-Item $textures
        CarName = "Nissan GT-R R35 Nismo"
        Manufacturer = "Nissan"
        ClassType = "A"
        PerformanceRating = 78
        Year = 2024
        CashPrice = 150000
        GoldPrice = 500
        Description = "Custom tuned GT-R with 700HP"
        AuthorName = "GTR_Fanatic"
        Version = "1.0"
    }

Write-Host "✅ Uploaded! Car ID: $($response.carId)"

# Step 3: Players can now download it!
```

---

## 🏆 MAKE RR3 COMMUNITY-DRIVEN!

With this modding system, Real Racing 3 can **LIVE FOREVER** with community-created content!

- ✅ Endless new cars
- ✅ Unlimited tracks
- ✅ Community creativity
- ✅ Game never dies!

**Start modding today!** 🎨🏎️💨