# 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. Set up HTTP interception (HTTP Toolkit)
2. Open Top Drives on an emulator (Bluestacks)
3. Intercept transmission of your game data
4. Save to file `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

### Global Options

All commands accept these optional flags to customize file paths:

| Flag | Default | Description |
|------|---------|-------------|
| `--my-cars <PATH>` | `my_cars.json` | Path to user's car collection export |
| `--cars-db <PATH>` | `cars_repo.json` | Path to car database file |
| `--times-dir <DIR>` | `times` | Directory containing per-car timing JSON files |
| `--tracks-db <PATH>` | `tracks_repo.json` | Path to tracks database file |

**Example with custom paths:**
```bash
cargo run --bin records -- --cars-db /data/cars.json --times-dir /data/times best
```

### Basic Analysis Commands

#### Best Cars Analysis

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

**Purpose:** 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.

**Flags:**
- `--min-count N` — Minimum number of tracks a car must be best on to qualify as "very best" (default: 10)

**Example with custom threshold:**
```bash
cargo run --bin records -- best --min-count 5
```

**Output Files:**

`best.csv`:
```csv
RQ,Brand,Model,Year,FinalBuild,Count
85,McLaren,F1,1993,323,15
82,Ferrari,250 GTO,1962,332,12
80,Lamborghini,Countach,1974,233,8
75,Porsche,911 Turbo,1975,332,6
```

`very_best.csv`:
```csv
RQ,Brand,Model,Year,FinalBuild,Count
85,McLaren,F1,1993,323,15
82,Ferrari,250 GTO,1962,332,12
```

**Understanding the output:**
- **RQ**: Car's rarity level
- **Brand**: Car manufacturer
- **Model**: Car model name
- **Year**: Model year
- **FinalBuild**: Normalized tune configuration (323, 233, or 332)
- **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

#### Trash Analysis

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

**Purpose:** Generates `trash.csv` — owned cars that are not best on any track, have RQ < 80, and are not prize cars. Sorted by RQ.

**Output File:**

`trash.csv`:
```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**

#### Wishlist Management

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

**Purpose:** Generates three files for wishlist optimization:
- `wishlist.csv` — Ideal wishlist: very_best unowned cars, capped at 300
- `add.csv` — Cars that should be on your wishlist but aren't
- `remove.csv` — Cars on your wishlist that shouldn't be

All files are sorted by RQ.

**Flags:**
- `--min-count N` — Minimum number of tracks for "very best" qualification (default: 10)
- `--max-wishlist M` — Maximum number of cars on the ideal wishlist (default: 300)

**Example with custom flags:**
```bash
cargo run --bin records -- wishlist --min-count 5 --max-wishlist 500
```

**Output Files:**

`wishlist.csv`:
```csv
RQ,Brand,Model,Year,FinalBuild,Count
90,Pagani,Zonda R,2010,323,18
88,Ferrari,F40,1987,332,15
87,McLaren,Senna,2018,233,12
```

`add.csv`:
```csv
RQ,Brand,Model,Year,FinalBuild,Count
90,Pagani,Zonda R,2010,323,18
88,Ferrari,F40,1987,332,15
```

`remove.csv`:
```csv
RQ,Brand,Model,Year,FinalBuild,Count
75,BMW,M3,2003,332,3
72,Audi,RS6,2002,233,2
```

**Action items:**
- Add cars from `add.csv` to your in-game wishlist
- Remove cars from `remove.csv` from your in-game wishlist
- Use `wishlist.csv` as your target wishlist

#### Full Analysis

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

**Purpose:** Generates all 7 CSV files in a single parse pass. Equivalent to running `best`, `trash`, `wishlist`, and `improve` together, but more efficient since data is only parsed once.

**Flags:**
- `--min-count N` — Minimum number of tracks for "very best" qualification (default: 10)
- `--max-wishlist M` — Maximum number of cars on the ideal wishlist (default: 300)

**Example with custom flags:**
```bash
cargo run --bin records -- all --min-count 5 --max-wishlist 500
```

**Output Files:**
- `best.csv` — All cars best on at least one track
- `very_best.csv` — Cars best on ≥ min_count 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

#### Improve Analysis

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

**Purpose:** Generates `improve.csv` — owned cars whose actual tune configuration is not yet a final build (323, 233, or 332). Sorted by number of best tracks descending, so the most impactful upgrades appear first.

**Output File:**

`improve.csv`:
```csv
RQ,Brand,Model,Year,Target,Count
90,Pagani,Zonda R,2010,323,18
85,McLaren,F1,1993,332,15
```

**Understanding the output:**
- **RQ**: Car's rarity level
- **Brand**: Car manufacturer
- **Model**: Car model name
- **Year**: Model year
- **Target**: The final build config the player should upgrade to
- **Count**: How many tracks this car is best on (across all its configs)

**Interpretation:**
- Focus on cars with the highest Count first — upgrading them benefits the most tracks
- The Target column shows which of the three final builds (323, 233, 332) to aim for
- Cars already at a final build or maxed config are automatically excluded

#### Detailed Performance Data

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

**Purpose:** Generates `details.csv` with 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:** Prints the best car for a specific track, condition, and RQ level to stdout.

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

**Track name format:**
- Use display names: `Laguna Seca`, `Monaco`, `Test Bowl`
- Full mappings loaded from `track_names.json`

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

### Command Flags Reference

| Flag | Applicable Commands | Default | Description |
|------|-------------------|---------|-------------|
| `--min-count N` | `best`, `wishlist`, `all` | `10` | Minimum tracks a car must be best on to qualify as "very best" |
| `--max-wishlist M` | `wishlist`, `all` | `300` | Maximum number of cars on the ideal wishlist |

## Daily Workflow

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

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

Or combine them:
```bash
cargo run --bin records -- fetch && cargo run --bin records -- all
```

### What `all` Does

1. **Parses** all timing data in a single pass
2. **Generates** all 7 output CSV files
3. **Sorts** all files by car RQ (and FinalBuild where applicable)

### Output Files

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

### Typical Daily Routine

1. **Run `fetch`** to get fresh data from the community repository
2. **Run `all`** to generate all analysis files in one pass
3. **Review `best.csv`** to see how your cars rank overall
4. **Check `add.csv`** for cars worth adding to your wishlist
5. **Check `remove.csv`** for wishlist entries to remove
6. **Review `trash.csv`** for owned cars you can safely sell
7. **Check `very_best.csv`** for the absolute top performers

## 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 Wishlist Priorities
```bash
cargo run --bin records -- wishlist
```
- 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. All files are sorted by car RQ.

#### best.csv
- All cars that are best on at least one track (owned and unowned)
- Import into spreadsheet for sorting/filtering
- Track performance across time

#### very_best.csv
- Cars best on ≥ min_count tracks (default ≥10)
- These are the most versatile performers
- Use `--min-count N` to adjust the threshold

#### trash.csv
- Owned cars safe to sell from your collection
- Only includes cars with RQ < 80 that are not best on any track
- Excludes prize cars
- Cross-reference with your garage before selling

#### wishlist.csv
- Ideal wishlist: very_best cars you don't own, capped at max-wishlist (default 300)
- Sorted by RQ
- Use as your target wishlist

#### add.csv
- Cars that should be on your wishlist but aren't
- These are very_best unowned cars not currently on your wishlist
- Add these to your in-game wishlist

#### remove.csv
- Cars currently on your wishlist that shouldn't be
- These are cars on your wishlist that don't qualify as very_best
- Remove these from your in-game wishlist

### 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`, `trash`, `wishlist`, `all`, `details`, `track`, `improve`, or `fetch`

#### "Could not read my cars file" / "Missing data file"
**Problem:** `my_cars.json` (or another data file) not found or not readable
**Solution:**
1. Export fresh data from Top Drives game
2. Ensure file is named exactly `my_cars.json` (or use `--my-cars <PATH>` to specify a custom location)
3. Check file permissions
4. If `cars_repo.json` is missing, run `fetch` first (or use `--cars-db <PATH>`)

#### "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. **Daily**: Run `fetch` then `all` to get latest data and full analysis
2. **Weekly**: Review `wishlist` output for new acquisitions
3. **Monthly**: 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.