rr3-server/ASSET-MANIFEST-SPECIFICATION.md

# RR3 Asset Manifest Specification

## Overview
When uploading ZIP files to the RR3 Community Server, you can include a `manifest.json` or `manifest.xml` file to automatically configure asset metadata, version, and categorization.

## File Format Options

### Option 1: JSON Format (Recommended)
Place `manifest.json` in the root of your ZIP file:

```json
{
  "version": "9.3.0",
  "gameVersion": "9.3.0",
  "description": "Porsche Pack - 911 Models",
  "author": "CommunityModder",
  "category": "cars",
  "assets": [
    {
      "file": "porsche/911_turbo.dat",
      "category": "cars/porsche",
      "type": "Model",
      "required": true,
      "description": "Porsche 911 Turbo model"
    },
    {
      "file": "textures/911_turbo_paint.tex",
      "category": "textures/cars",
      "type": "Texture",
      "required": false
    }
  ]
}
```

### Option 2: XML Format
Place `manifest.xml` in the root of your ZIP file:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<AssetManifest>
  <Version>9.3.0</Version>
  <GameVersion>9.3.0</GameVersion>
  <Description>Porsche Pack - 911 Models</Description>
  <Author>CommunityModder</Author>
  <Category>cars</Category>
  <Assets>
    <Asset>
      <File>porsche/911_turbo.dat</File>
      <Category>cars/porsche</Category>
      <Type>Model</Type>
      <Required>true</Required>
      <Description>Porsche 911 Turbo model</Description>
    </Asset>
    <Asset>
      <File>textures/911_turbo_paint.tex</File>
      <Category>textures/cars</Category>
      <Type>Texture</Type>
      <Required>false</Required>
    </Asset>
  </Assets>
</AssetManifest>
```

## Field Descriptions

### Root Fields
- **version**: Asset pack version (e.g., "1.0.0")
- **gameVersion**: RR3 game version this pack is for (e.g., "9.3.0")
- **description**: Brief description of the asset pack
- **author**: Creator name (optional)
- **category**: Default category if not specified per-asset

### Asset Fields
- **file**: Relative path to file within ZIP (required)
- **category**: Asset category (overrides root category)
- **type**: Asset type (Data, Texture, Audio, Model, Config)
- **required**: Whether clients must download this (true/false)
- **description**: Brief description (optional)

## Game Version Format
- Use semantic versioning: `MAJOR.MINOR.PATCH`
- Examples: `9.3.0`, `9.3.1`, `10.0.0`
- **Compatibility**: Patch versions are compatible (9.3.x works with 9.3.0)

## Categories
Standard categories:
- `base` - Core game files
- `cars` - Car models and data
- `tracks` - Track models and data
- `audio` - Sound effects and music
- `textures` - Texture files
- `ui` - User interface elements
- `events` - Event configurations
- `dlc` - Downloadable content
- `updates` - Game updates

Subcategories allowed (e.g., `cars/porsche`, `tracks/silverstone`)

## Asset Types
- `Data` - Generic data files (.dat, .pak, .z)
- `Texture` - Texture files (.tex, .dds, .png)
- `Audio` - Audio files (.ogg, .mp3, .wav)
- `Model` - 3D model files (.nct, .obj)
- `Config` - Configuration files (.json, .xml)

## Automatic Detection Fallback
If no manifest file is provided, the server uses smart detection:
1. Searches folder names for keywords (cars, tracks, audio, etc.)
2. Preserves folder structure as subcategories
3. Falls back to first folder name if no keywords match
4. Version defaults to manual selection or "unknown"

## Example ZIP Structure

```
my-asset-pack.zip
├── manifest.json          # Metadata file
├── cars/
│   ├── porsche/
│   │   ├── 911_turbo.dat
│   │   └── 911_gt3.dat
│   └── ferrari/
│       └── 488_gtb.dat
└── textures/
    └── cars/
        └── paint_textures.pak
```

## Upload Behavior
1. Server extracts ZIP to temp location
2. Searches for `manifest.json` or `manifest.xml` in root
3. If found: Uses metadata from manifest
4. If not found: Uses smart folder detection
5. Processes each file according to configuration
6. Calculates MD5/SHA256 hashes automatically
7. Stores in database with version + category info

## Version Compatibility
When a game client requests assets:
- Client sends version: `9.3.1`
- Server returns assets for: `9.3.0`, `9.3.1` (patch-compatible)
- Server excludes: `9.2.x`, `9.4.x`, `10.x.x`

Major/minor versions must match exactly, patch versions are compatible within the same minor version.

## Best Practices
1. Always include a manifest file for large packs
2. Use semantic versioning for both pack and game version
3. Mark base game assets as `required: true`
4. Use descriptive categories and subcategories
5. Include author information for community tracking
6. Test with single-file upload before bulk ZIP upload
7. Use JSON format for better tool support