# Top Drives Records Analyzer - User Guide

## Introduction

This guide provides comprehensive instructions for using the Top Drives Records Analyzer to optimize your car collection and improve your racing performance. The tool analyzes timing data from thousands of community-submitted runs to help you make informed decisions about your car collection.

## Quick Start Checklist

- [ ] Install Rust development environment
- [ ] Export your car collection from Top Drives game
- [ ] Run initial data fetch
- [ ] Analyze your collection
- [ ] Review recommendations

## Setup Instructions

### 1. Game Data Export

**Export your car collection from Top Drives:**

1. Open Top Drives on your device
2. Go to Settings → Account → Export Data
3. Save the file as `my_cars.json` in the project directory

### 2. Initial Data Download

Fetch the latest car and track databases:

```bash
cargo run --bin records -- fetch
```

**What this does:**
- Downloads `cars_repo.json` (car database)
- Downloads `tracks_repo.json` (track definitions)
- Downloads timing files for all cars (1000+ files in `times/` directory)

**Expected output:**
```
Fetching cars file...
Fetching tracks file...
Fetching https://api.topdrivesrecords.com/car/1001.json.
Fetching https://api.topdrivesrecords.com/car/1002.json.
...
```

## Command Reference

### Basic Analysis Commands

#### Best Cars Analysis

**Command:**
```bash
cargo run --bin records -- best
```

**Purpose:** Shows the best performing cars in your collection, ranked by how often they achieve top times.

**Sample Output:**
```csv
RQ,Brand,Model,Year,Count
85,McLaren,F1,1993,15
82,Ferrari,250 GTO,1962,12
80,Lamborghini,Countach,1974,8
75,Porsche,911 Turbo,1975,6
```

**Understanding the output:**
- **RQ**: Car's rarity level
- **Brand**: Car manufacturer
- **Model**: Car model name
- **Year**: Model year
- **Count**: How many times this car was the fastest across different tracks

**Interpretation:**
- Higher counts indicate more versatile cars
- Focus on cars with counts ≥ 5 for your core collection
- Compare with your owned cars to identify strengths

#### Missing Cars Analysis

**Command:**
```bash
cargo run --bin records -- missing
```

**Purpose:** Identifies high-performing cars you don't own that would improve your collection.

**Sample Output:**
```csv
RQ,Brand,Model,Year,Count
90,Pagani,Zonda R,2010,18
88,Ferrari,F40,1987,15
87,McLaren,Senna,2018,12
```

**Action items:**
- Prioritize cars with high counts (≥10)
- Consider RQ restrictions in your racing bracket
- Look for cars that perform well across multiple track types

#### Collection Optimization (Trash Analysis)

**Command:**
```bash
cargo run --bin records -- trash
```

**Purpose:** Identifies cars safe to remove from your collection.

**Sample Output:**
```csv
RQ,Brand,Model,Year
45,Toyota,Corolla,1995
52,Honda,Civic,1992
38,Ford,Focus,2001
```

**Safety guidelines:**
- Only removes cars below RQ 80
- Excludes prize cars (may have collection value)
- Only suggests cars that never achieve best times
- **Always verify before selling in-game**

#### Detailed Performance Data

**Command:**
```bash
cargo run --bin records -- details
```

**Purpose:** Comprehensive timing data for all tracks and conditions.

**Sample Output:**
```csv
RQ,TrackID,Condition,CarRQ,Brand,Model,Year,Config,Time
85,laguna,Dry,85,McLaren,F1,1993,233,112.45
85,monaco,Dry,85,Pagani,Zonda,2002,111,45.23
82,laguna,Dry,82,Ferrari,250 GTO,1962,111,115.67
```

**Use cases:**
- External spreadsheet analysis
- Track-specific performance research
- Historical performance tracking

#### Track-Specific Analysis

**Command:**
```bash
cargo run --bin records -- track "Laguna Seca" "Dry" "85"
```

**Purpose:** Find the best car for a specific track, condition, and RQ level.

**Sample Output:**
```
Best car for Track: laguna, Condition: Dry, RQ: 85 -> McLaren F1 (1993) with time 112.45
```

**Track name format:**
- Use internal names: `laguna`, `monaco`, `testBowl`
- Full mappings in `translate_track_name()` function

**Condition options:**
- `Dry` - Standard asphalt
- `Wet` - Rain conditions
- `Dirt` - Off-road tracks
- `Snow` - Winter conditions

## Advanced Usage

### RQ Range Analysis

The tool analyzes performance across RQ brackets. Understanding RQ ranges:

- **RQ 10-50**: Entry level cars
- **RQ 51-80**: Mid-tier performance
- **RQ 81-100**: High performance
- **RQ 101-113**: Elite/supercars

**Strategy:**
- Focus on 2-3 RQ brackets where you race most
- Identify cars that perform well across multiple brackets
- Consider upgrade paths for favorite cars

### Collection Planning

#### Step 1: Assess Current Collection
```bash
cargo run --bin records -- best
```
- Identify your strongest cars
- Note RQ distribution
- Find gaps in coverage

#### Step 2: Identify Priorities
```bash
cargo run --bin records -- missing
```
- Focus on high-count cars in your RQ range
- Consider track variety needs
- Factor in prize car availability

#### Step 3: Optimize Collection
```bash
cargo run --bin records -- trash
```
- Remove redundant low performers
- Free up space for better cars
- Maintain diversity for different track types

### Track Type Strategy

Different cars excel on different track types:

#### Speed Tracks
- **Characteristics**: Long straights, high speeds
- **Best cars**: High top speed, good acceleration
- **Examples**: Laguna Seca, Monaco Streets

#### Technical Tracks
- **Characteristics**: Tight corners, elevation changes
- **Best cars**: Good handling, braking
- **Examples**: Deals Gap, Mountain Hairpin

#### Off-Road Tracks
- **Characteristics**: Dirt, gravel, snow surfaces
- **Best cars**: Good grip, durability
- **Examples**: Desert Rally, Forest Road

## Output File Analysis

### CSV File Usage

The tool generates CSV files for external analysis:

#### best.csv
- Your best performing cars
- Import into spreadsheet for sorting/filtering
- Track performance across time

#### missing.csv
- Cars to acquire
- Prioritize by count and RQ relevance
- Plan acquisition strategy

#### details.csv
- Comprehensive timing database
- Advanced analysis and research
- Historical performance tracking

### Spreadsheet Analysis Tips

**Excel/Google Sheets setup:**
1. Import CSV files
2. Create pivot tables by RQ, Brand, Track
3. Add conditional formatting for high performers
4. Create dashboards for collection overview

## Troubleshooting

### Common Issues

#### "Please provide a command"
**Problem:** No arguments provided
**Solution:** Use `best`, `missing`, `trash`, `details`, or `track`

#### "Could not read my cars file"
**Problem:** `my_cars.json` not found or not readable
**Solution:**
1. Export fresh data from Top Drives game
2. Ensure file is named exactly `my_cars.json`
3. Check file permissions

#### "Failed to fetch the file"
**Problem:** Network issues or API unavailable
**Solution:**
1. Check internet connection
2. Try again later (may be temporary)
3. Use existing cached data if available

#### No output or empty results
**Problem:** Missing timing data or configuration issues
**Solution:**
1. Re-run `fetch` command to get fresh data
2. Check that `times/` directory has files
3. Verify `cars_repo.json` exists

### Performance Issues

#### Slow analysis
- **Expected**: First run takes 2-3 minutes (downloads data)
- **Subsequent runs**: Should be fast (uses cached data)
- **Large datasets**: Details command processes all timing data

#### Memory usage
- **Normal**: 100-200MB for full analysis
- **High**: Details command loads all timing data
- **Solution**: Use specific commands instead of details for large datasets

## Tips and Best Practices

### Regular Maintenance
1. **Weekly**: Run `fetch` to get latest data
2. **Monthly**: Review `missing` cars for new acquisitions
3. **Quarterly**: Use `trash` to optimize collection

### Data-Driven Decisions
1. **Trust the numbers**: Count-based recommendations are data-driven
2. **Consider context**: Some cars may have strategic value beyond performance
3. **Track changes**: Keep performance history for trend analysis

### Collection Strategy
1. **Diversify**: Don't focus only on one RQ bracket
2. **Specialize**: Identify your preferred track types
3. **Balance**: Mix proven performers with potential upgrades

## Getting Help

### Documentation
- `README.md`: Project overview and setup
- `docs/ARCHITECTURE.md`: Technical details for developers
- `docs/USER_GUIDE.md`: This comprehensive guide

### Community Resources
- **Data Source**: Community timing database
- **Updates**: Check for new features and improvements
- **Issues**: Report bugs or request features

---

**Remember**: This tool provides data-driven insights, but ultimately you're the best judge of which cars you enjoy driving. Use the analysis as a guide, not a strict rulebook.