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

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:

cargo run --bin records -- best

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

Sample Output:

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:

cargo run --bin records -- missing

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

Sample Output:

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:

cargo run --bin records -- trash

Purpose: Identifies cars safe to remove from your collection.

Sample Output:

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:

cargo run --bin records -- details

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

Daily Workflow

The recommended daily workflow uses the full_script command, which runs fetch followed by all analysis commands in a single pipeline:

cargo run --bin records -- full_script

What full_script Does

1. Fetches fresh data from the community repository
2. Runs all analysis commands sequentially
3. Generates all output CSV files

Output Files

File	Purpose	Format
best.csv	Ranked list of best cars — evaluate if a car is worth keeping	RQ,Brand,Model,Year,Count
details.csv	Detailed timing data for all tracks/conditions — find best config for a car	RQ,TrackID,Condition,CarRQ,Brand,Model,Year,Config,Time
add.csv	Cars to add to wishlist — missing cars not yet wishlisted, prefixed with +	+RQ,Brand,Model,Year
remove.csv	Cars to remove from wishlist — stale wishlist entries, prefixed with -	-RQ,Brand,Model,Year
trash.csv	Owned cars that can be safely removed	RQ,Brand,Model,Year
sorted.csv	Best cars sorted by count (descending)	RQ,Brand,Model,Year,Count
very_best.csv	Best cars with count ≥ 10	RQ,Brand,Model,Year,Count
wishlist.csv	Missing cars already on wishlist	RQ,Brand,Model,Year,Count

Typical Daily Routine

1. Run full_script to get fresh data and full analysis
2. Review best.csv to see how your cars rank overall
3. Check add.csv for cars worth adding to your wishlist (prefixed with +)
4. Check remove.csv for wishlist entries to remove (prefixed with -)
5. Review trash.csv for owned cars you can safely sell
6. Use details.csv to find the optimal tune config for a specific car
7. Check very_best.csv for the absolute top performers (count ≥ 10)

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 Priorities

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

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

details.csv

• Comprehensive timing database
• Advanced analysis and research
• Historical performance tracking

add.csv / remove.csv

• Wishlist management
• + prefix indicates cars to add
• - prefix indicates cars to remove

trash.csv

• Cars safe to sell from your collection
• Cross-reference with your garage before selling

sorted.csv / very_best.csv

• Sorted rankings by versatility
• very_best.csv filters to count ≥ 10 for top-tier recommendations

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, track, or full_script

"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. Daily: Run full_script to get latest data and full analysis
2. Weekly: Review missing cars 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.