Jan-Peter von Hunnius 32c4d3c10e Added documentation

Added test cases
Added comments

2025-10-02 17:35:56 +02:00

7.3 KiB

Raw Blame History

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

🛠️ Installation

Prerequisites

Rust (latest stable version)
Internet connection for fetching data

Setup

Clone the repository

git clone <repository-url>
cd top_drives

Build the project
```
cargo build --release
```
Run the analyzer
```
cargo run --bin records -- fetch
```

🚦 Quick Start

Initial Setup: Fetch the latest car and track data
```
cargo run --bin records -- fetch
```
Basic Analysis: Find the best cars in your collection
```
cargo run --bin records -- best
```
Find Missing Cars: Discover cars that would improve your performance
```
cargo run --bin records -- missing
```
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>`

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

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

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 specific binary
cargo run --bin records
cargo run --bin club

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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:

Check existing documentation
Review open issues
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

7.3 KiB Raw Blame History