Added documentation
Added test cases Added comments
This commit is contained in:
parent
7a8d9beedc
commit
32c4d3c10e
10 changed files with 3852 additions and 63 deletions
275
README.md
Normal file
275
README.md
Normal file
|
|
@ -0,0 +1,275 @@
|
|||
# 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*
|
||||
Loading…
Add table
Add a link
Reference in a new issue