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
• Quick Start
• Usage Guide
• Commands Reference
• Daily Workflow
• Data Sources
• Configuration
• Development
• Contributing

🛠️ Installation

Prerequisites

• Rust (latest stable version)
• Internet connection for fetching data

Setup

1. Clone the repository

   git clone <repository-url>
   cd top_drives
   

2. Build the project

   cargo build --release
   

3. Run the analyzer

   cargo run --bin records -- fetch
   

🚦 Quick Start

1. Initial Setup: Fetch the latest car and track data

   cargo run --bin records -- fetch
   

2. Basic Analysis: Find the best cars in your collection

   cargo run --bin records -- best
   

3. Find Missing Cars: Discover cars that would improve your performance

   cargo run --bin records -- missing
   

4. Collection Cleanup: Identify cars safe to remove

   cargo run --bin records -- trash
   

📖 Usage Guide

Basic Commands

Fetch Data

cargo run --bin records -- fetch

Downloads the latest car database and track information from the community repository.

Best Cars Analysis

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

cargo run --bin records -- missing

Shows the best cars that you don't own, helping prioritize acquisitions.

Collection Optimization

cargo run --bin records -- trash

Identifies cars in your collection that aren't among the best performers and could be removed.

Detailed Performance Data

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

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:

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

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

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

# 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