top_drives/docs/USER_GUIDE.md

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:

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:

cargo run --bin records -- --cars-db /data/cars.json --times-dir /data/times best

Basic Analysis Commands

Best Cars Analysis

Command:

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:

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

Output Files:

best.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:

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:

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:

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:

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:

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

Output Files:

wishlist.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:

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

remove.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:

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:

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:

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:

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:

cargo run --bin records -- details

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

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:

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

Or combine them:

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

cargo run --bin records -- best

• Identify your strongest cars
• Note RQ distribution
• Find gaps in coverage

Step 2: Identify Wishlist Priorities

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

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.