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:

{
  "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 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