top_drives/README.md

# Top Drives Records Analyzer

A comprehensive Rust-based tool for analyzing car performance data in the Top Drives racing game. This tool fetches track times from a community-maintained repository and provides detailed analysis including best cars, missing cars, and optimization recommendations.

## 🚀 Features

- **Best Car Analysis**: Find the best performing cars across all tracks and conditions
- **Missing Cars Detection**: Identify cars missing from your collection that would improve performance
- **Collection Optimization**: Identify cars that can be safely removed from your collection
- **Track-Specific Analysis**: Get detailed performance data for specific tracks and conditions
- **RQ-Based Filtering**: Filter results by car rarity (RQ) levels
- **Multiple Surface Types**: Support for Dry, Wet, Dirt, Snow, and other track conditions

## 📋 Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Guide](#usage-guide)
- [Commands Reference](#commands-reference)
- [Data Sources](#data-sources)
- [Configuration](#configuration)
- [Development](#development)
- [Contributing](#contributing)

## 🛠️ Installation

### Prerequisites

- [Rust](https://rustup.rs/) (latest stable version)
- Internet connection for fetching data

### Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd top_drives
   ```

2. **Build the project**
   ```bash
   cargo build --release
   ```

3. **Run the analyzer**
   ```bash
   cargo run --bin records -- fetch
   ```

## 🚦 Quick Start

1. **Initial Setup**: Fetch the latest car and track data
   ```bash
   cargo run --bin records -- fetch
   ```

2. **Basic Analysis**: Find the best cars in your collection
   ```bash
   cargo run --bin records -- best
   ```

3. **Find Missing Cars**: Discover cars that would improve your performance
   ```bash
   cargo run --bin records -- missing
   ```

4. **Collection Cleanup**: Identify cars safe to remove
   ```bash
   cargo run --bin records -- trash
   ```

## 📖 Usage Guide

### Basic Commands

#### Fetch Data
```bash
cargo run --bin records -- fetch
```
Downloads the latest car database and track information from the community repository.

#### Best Cars Analysis
```bash
cargo run --bin records -- best
```
Shows all cars in your collection ranked by their performance across tracks.

**Sample Output:**
```
RQ,Brand,Model,Year,Count
85,McLaren,F1,1993,15
82,Ferrari,250 GTO,1962,12
80,Lamborghini,Countach,1974,8
```

#### Missing Cars Analysis
```bash
cargo run --bin records -- missing
```
Shows the best cars that you don't own, helping prioritize acquisitions.

#### Collection Optimization
```bash
cargo run --bin records -- trash
```
Identifies cars in your collection that aren't among the best performers and could be removed.

#### Detailed Performance Data
```bash
cargo run --bin records -- details
```
Shows comprehensive timing data for all tracks and conditions.

**Sample Output:**
```
RQ,TrackID,Condition,CarRQ,Brand,Model,Year,Config,Time
85,laguna,Dry,85,McLaren,F1,1993,233,112.45
82,monaco,Dry,82,Ferrari,250 GTO,1962,111,45.23
```

#### Track-Specific Analysis
```bash
cargo run --bin records -- track "Laguna Seca" "Dry" "85"
```
Finds the best car for a specific track, condition, and RQ combination.

### Advanced Usage

#### Multiple RQ Analysis
The tool supports analyzing performance across different RQ ranges. Use the `missing` and `best` commands to see how cars perform at various rarity levels.

#### Track Conditions
The analyzer supports multiple track conditions:
- **Dry**: Standard asphalt conditions
- **Wet**: Rain-affected tracks
- **Dirt**: Off-road conditions
- **Snow**: Winter conditions
- **Gravel**: Loose surface conditions

## 🗃️ Commands Reference

| Command | Description | Arguments |
|---------|-------------|-----------|
| `fetch` | Download latest car and track data | None |
| `best` | Show best performing cars in collection | None |
| `missing` | Show best cars not in collection | None |
| `trash` | Show cars safe to remove from collection | None |
| `details` | Show detailed timing data for all tracks | None |
| `track` | Show best car for specific track | `<track_name> <condition> <rq>` |

## 📊 Data Sources

### Car Data
- **Source**: Community-maintained GitHub repository
- **Format**: JSON files with performance data per car
- **Update Frequency**: Regular updates from community contributors

### Track Data
- **Source**: Same community repository
- **Coverage**: All tracks and conditions in Top Drives
- **Format**: Structured track definitions with conditions

### User Collection
- **File**: `my_cars.json`
- **Format**: Top Drives game export format
- **Usage**: Identifies owned cars for analysis

## ⚙️ Configuration

### Files Structure
```
top_drives/
├── src/
│   ├── records.rs      # Main analyzer binary
│   └── club.rs         # Alternative data source
├── times/              # Car performance data (1000+ files)
├── cars_repo.json      # Car database
├── tracks_repo.json    # Track definitions
├── my_cars.json        # Your car collection
└── Cargo.toml          # Rust project configuration
```

### Dependencies
- **reqwest**: HTTP client for data fetching
- **serde_json**: JSON parsing and serialization
- **tokio**: Asynchronous runtime
- **scraper**: HTML parsing for alternative data source

## 🔧 Development

### Project Structure
The project consists of two main binaries:

1. **records**: Primary analysis tool using JSON data
2. **club**: Alternative tool scraping topdrives.club

### Key Data Structures

#### Car Information
```rust
struct Car {
    rid: String,        // Unique car identifier
    brand: String,      // Manufacturer name
    only_name: String,  // Model name
    year: u16,         // Model year
    rq: u8,            // Rarity level (10-113)
    prize: bool,       // Whether car is prize-only
    guid: String,      // Game-specific identifier
}
```

#### Performance Records
```rust
struct BestCarRecord {
    car_rid: String,   // Car identifier
    brand: String,     // Manufacturer
    only_name: String, // Model name
    year: u16,         // Year
    rq: u8,           // Rarity level
    config: String,    // Tune configuration
    time: f64,        // Track time
    owned: bool,      // Whether you own this car
    guid: String,     // Game identifier
}
```

### Building
```bash
# Debug build
cargo build

# Release build
cargo build --release

# Run specific binary
cargo run --bin records
cargo run --bin club
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

### Adding New Tracks
Track definitions are stored in `tracks_repo.json`. Each track includes:
- Unique identifier
- Display name
- Supported conditions
- Track type classification

### Adding Car Data
New car performance data should be submitted to the upstream repository following their contribution guidelines.

## 📄 License

This project is open source. Please check the upstream data repositories for their respective licenses.

## 🆘 Support

For issues and questions:
1. Check existing documentation
2. Review open issues
3. Create new issue with detailed description

## 🔄 Updates

The tool fetches fresh data each time you run the `fetch` command. Keep your local data updated for best results.

---

*Built with ❤️ for the Top Drives community*