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)
- [Daily Workflow](#daily-workflow)
- [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>` |

## 📅 Daily Workflow

The typical daily workflow uses `full_script` which runs `fetch` followed by all analysis commands in sequence:

```bash
cargo run --bin records -- full_script
```

This generates the following output files:

| File | Description |
|------|-------------|
| `best.csv` | Ranked list of best cars — used to evaluate if a car is worth keeping |
| `details.csv` | Detailed timing data for all tracks/conditions — used to find the best config for a car |
| `add.csv` | Cars to add to wishlist — missing cars not yet wishlisted, prefixed with `+` |
| `remove.csv` | Cars to remove from wishlist — stale wishlist entries, prefixed with `-` |
| `trash.csv` | Owned cars that can be safely removed |
| `sorted.csv` | Best cars sorted by count (descending) |
| `very_best.csv` | Best cars with count ≥ 10 |
| `wishlist.csv` | Missing cars already on wishlist |

### Workflow Steps

1. **Fetch** fresh data from the community repository
2. **Analyze** your collection against the latest timing data
3. **Review** `best.csv` to see how your cars rank
4. **Check** `add.csv` for cars worth adding to your wishlist
5. **Clean up** `remove.csv` entries from your wishlist
6. **Sell** cars listed in `trash.csv` that are no longer useful

## 📊 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

### Track Names
- **Source**: `track_names.json` (included in repository)
- **Format**: JSON mapping track codes to human-readable names
- **Loaded**: At compile time via `include_str!`

### 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
│   └── lib.rs          # Shared library (track name translations)
├── times/              # Car performance data (1000+ files)
├── cars_repo.json      # Car database
├── tracks_repo.json    # Track definitions
├── track_names.json    # Track code → name mappings
├── 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
- **futures**: Async utility combinators
- **once_cell**: Lazy static initialization

## 🔧 Development

### Project Structure
The project consists of a single binary with a shared library:

1. **records**: Primary analysis tool using JSON data (`src/records.rs`)
2. **lib**: Shared library with track name translations (`src/lib.rs`)

### Key Constants

- `MAX_RQ: u8 = 113` — Maximum RQ level used in analysis (defined in `records.rs`)

### 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 the analyzer
cargo run --bin records
```

## 🤝 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

Track name mappings are stored in `track_names.json` and loaded at compile time.

### 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*