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, trash identification, and wishlist optimization.

🚀 Features

• Best Car Analysis: Find the best performing cars across all tracks and conditions
• Wishlist Optimization: Identify cars to add to or remove from your wishlist
• Collection Cleanup: Identify cars that can be safely removed from your collection
• Upgrade Prioritization: Find owned cars not yet at their final tune build
• 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. Full Analysis: Generate all output files in a single pass

   cargo run --bin records -- all
   

3. Best Cars: Find the best cars across all tracks

   cargo run --bin records -- best
   

4. Collection Cleanup: Identify cars safe to remove

   cargo run --bin records -- trash
   

5. Wishlist Management: Optimize your wishlist

   cargo run --bin records -- wishlist
   

6. Upgrade Prioritization: Find cars that need upgrading

   cargo run --bin records -- improve
   

📖 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

Generates best.csv (all cars best on at least one track) and very_best.csv (cars best on ≥10 tracks). Both files are sorted by RQ.

Output Files:

best.csv        — All cars best on at least one track
very_best.csv   — Cars best on ≥10 tracks (default)

Use --min-count N to change the threshold for very_best.csv:

cargo run --bin records -- best --min-count 5

Trash Analysis

cargo run --bin records -- trash

Generates trash.csv — owned cars that are not best on any track, have RQ < 80, and are not prize cars, plus low-value upgrade fodder: unfinished cars whose best config reaches at most a per-RQ-band track count (RQ 10-19: ≤4, RQ 20-29: ≤2, RQ 30-39: ≤1 by default). Sorted by RQ.

Output File:

trash.csv       — Owned cars safe to remove or use as fusion material

The band thresholds derive from a single base value (--trash-base-count, default 4); each higher band gets half of the previous one. The tool prints the effective thresholds and a garage-space projection (user.garageSlots/garageSlotsUsed from the export). When the projected free slots after clean-up fall below --garage-min-free (default 20), the base count is raised automatically — and printed — until the target is reached or no more cars qualify:

cargo run --bin records -- trash --trash-base-count 5 --garage-min-free 30

Pass --trash-base-count 0 to disable the improve-based criteria entirely.

Protect & Storage Analysis

cargo run --bin records -- protect

Generates protect.csv — cars in the garage that are currently not locked and are worth locking more copies of — and storage.csv, a keep/trash recommendation for cars in the storage ("Lager", state == 0 in the export). Both apply the same dynamic criteria (including garage-space escalation and its printed plan) as the trash command.

Output Files:

protect.csv     — Unlocked garage cars worth locking
storage.csv     — Keep/Trash recommendation for storage cars

protect.csv columns: RQ,Brand,Model,Year,FinalBuild,Count,ToLock. A car drops off the list once its locked copies cover every best config surviving the RQ-band thresholds; ToLock is the number of additional copies worth locking. Cars not best on any track never appear.

storage.csv columns: RQ,Brand,Model,Year,FinalBuild,Count,Recommendation. Cars not best on any track, best only in configs at or below their RQ-band threshold, or with enough locked copies already (surplus unlocked copies are fusion material), are Trash; prize cars and RQ ≥ 80 are always Keep.

The trash criteria flags apply here as well:

cargo run --bin records -- protect --trash-base-count 5 --garage-min-free 30

Wishlist Management

cargo run --bin records -- wishlist

Generates wishlist.csv (ideal wishlist: very_best unowned cars, capped at 300), add.csv (cars that should be on your wishlist but aren't), and remove.csv (cars on your wishlist that shouldn't be). All sorted by RQ. Prize cars are excluded from the ideal wishlist; prize cars still on your actual wishlist appear in remove.csv.

Output Files:

wishlist.csv    — Ideal wishlist (very_best unowned, capped)
add.csv         — Cars to add to wishlist
remove.csv      — Cars to remove from wishlist

Use --min-count N to change the threshold for very_best cars (default 10):

cargo run --bin records -- wishlist --min-count 5

Use --max-wishlist M to change the wishlist cap (default 300):

cargo run --bin records -- wishlist --max-wishlist 500

Full Analysis

cargo run --bin records -- all

Generates all 10 CSV files in a single parse pass. Equivalent to running best, trash, wishlist, improve, and protect together, but more efficient.

Output Files:

best.csv        — All cars best on at least one track
very_best.csv   — Cars best on ≥10 tracks
trash.csv       — Owned cars safe to remove
wishlist.csv    — Ideal wishlist (very_best unowned, capped)
add.csv         — Cars to add to wishlist
remove.csv      — Cars to remove from wishlist
improve.csv     — Owned cars not yet at final build config
protect.csv     — Unlocked garage cars worth locking
storage.csv     — Keep/Trash recommendation for storage cars

Supports --min-count N (default 10), --max-wishlist M (default 300), and the trash criteria flags:

cargo run --bin records -- all --min-count 5 --max-wishlist 500 --trash-base-count 4 --garage-min-free 20

Detailed Performance Data

cargo run --bin records -- details

Generates details.csv with 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"

Prints the best car for a specific track, condition, and RQ combination to stdout.

Advanced Usage

Multiple RQ Analysis

The tool supports analyzing performance across different RQ ranges. Use the best and wishlist 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	Generate best.csv and very_best.csv	[--min-count N]
trash	Generate trash.csv (owned cars safe to remove)	[--trash-base-count N] [--garage-min-free N]
protect	Generate protect.csv (unlocked garage cars) and storage.csv (storage keep/trash)	[--trash-base-count N] [--garage-min-free N]
wishlist	Generate wishlist.csv, add.csv, remove.csv	[--min-count N] [--max-wishlist M]
all	Generate all 10 CSV files in a single pass	[--min-count N] [--max-wishlist M] [--trash-base-count N] [--garage-min-free N]
details	Print detailed timing data for all tracks (stdout)	None
track	Print best car for specific track (stdout)	<track_name> <condition> <rq>
improve	Generate improve.csv (owned cars not at final build)	None

Flags

Flag	Default	Description
--min-count N	10	Minimum number of tracks a car must be best on to qualify as "very best"
--max-wishlist M	300	Maximum number of cars on the ideal wishlist
--trash-base-count N	4	Maximum improve track count for RQ 10-19 to count as trash; RQ 20-29/30-39 get half/a quarter. 0 disables the criteria
--garage-min-free N	20	Minimum projected free garage slots; the trash base count is raised automatically when the projection falls short

📅 Daily Workflow

The typical daily workflow uses the all command, which runs all analysis in a single efficient parse pass:

cargo run --bin records -- fetch
cargo run --bin records -- all

Or combine them:

cargo run --bin records -- fetch && cargo run --bin records -- all

This generates the following output files (all sorted by car RQ):

File	Format	Description
best.csv	RQ,Brand,Model,Year,FinalBuild,Count	All cars best on at least one track
very_best.csv	RQ,Brand,Model,Year,FinalBuild,Count	Cars best on ≥ min_count tracks
trash.csv	RQ,Brand,Model,Year	Owned cars not best on any track (RQ<80, not prize)
wishlist.csv	RQ,Brand,Model,Year,FinalBuild,Count	Ideal wishlist (very_best unowned, capped)
add.csv	RQ,Brand,Model,Year,FinalBuild,Count	Cars to add to wishlist
remove.csv	RQ,Brand,Model,Year,FinalBuild,Count	Cars to remove from wishlist
improve.csv	RQ,Brand,Model,Year,Target,Count	Owned cars not yet at final build config

Workflow Steps

1. Fetch fresh data from the community repository
2. Analyze your collection with all to generate all CSV files
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
7. Upgrade cars listed in improve.csv to their target final build

📊 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 / serde_json: JSON parsing and serialization (with serde::Deserialize derive for Car)
• tokio: Asynchronous runtime (rt-multi-thread, macros, fs, sync, io-util)
• futures: Async utility combinators
• clap: CLI argument parsing (with derive macros)
• thiserror: Ergonomic error type definitions

🔧 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,            // Original tune config from JSON
    normalized_config: String, // Normalized final build (323, 233, or 332)
    time: f64,                 // Track time
    owned: bool,               // Whether you own this car
    prize: bool,               // Whether this is a prize 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