docs: update documentation for normalized config and improve command

- Add improve command to all command tables and usage sections
- Add normalized_config field to BestCarRecord struct documentation
- Update CarCounts.by_rid type from String to (String, String)
- Update CarCounts.guid_to_rid type to HashMap<String, HashSet<(String, String)>>
- Add owned_configs field to MyCarsData and CarCounts docs
- Add normalize_to_final_build() to API docs
- Update CSV format examples to include FinalBuild column
- Update my_cars.json structure with engineMajor/weightMajor/chassisMajor
- Update timing file example with v2c_ version prefix
- Add version prefix stripping to data transformation docs
- Update CHANGELOG.md with Unreleased section
- Fix compare_records description to include normalized config sorting
This commit is contained in:
Jan-Peter von Hunnius 2026-05-11 16:58:01 +02:00
parent bf21d3d1f6
commit 2b0602d564
6 changed files with 204 additions and 84 deletions

View file

@ -7,6 +7,7 @@ A comprehensive Rust-based tool for analyzing car performance data in the Top Dr
- **Best Car Analysis**: Find the best performing cars across all tracks and conditions
- **Wishlist Optimization**: Identify cars to add to or remove from your wishlist
- **Collection Cleanup**: Identify cars that can be safely removed from your collection
- **Upgrade Prioritization**: Find owned cars not yet at their final tune build
- **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
@ -75,6 +76,11 @@ A comprehensive Rust-based tool for analyzing car performance data in the Top Dr
cargo run --bin records -- wishlist
```
6. **Upgrade Prioritization**: Find cars that need upgrading
```bash
cargo run --bin records -- improve
```
## 📖 Usage Guide
### Basic Commands
@ -140,7 +146,7 @@ cargo run --bin records -- wishlist --max-wishlist 500
```bash
cargo run --bin records -- all
```
Generates all 6 CSV files in a single parse pass. Equivalent to running `best`, `trash`, and `wishlist` together, but more efficient.
Generates all 7 CSV files in a single parse pass. Equivalent to running `best`, `trash`, `wishlist`, and `improve` together, but more efficient.
**Output Files:**
```
@ -150,6 +156,7 @@ 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
```
Supports both `--min-count N` (default 10) and `--max-wishlist M` (default 300):
@ -197,9 +204,10 @@ The analyzer supports multiple track conditions:
| `best` | Generate `best.csv` and `very_best.csv` | `[--min-count N]` |
| `trash` | Generate `trash.csv` (owned cars safe to remove) | None |
| `wishlist` | Generate `wishlist.csv`, `add.csv`, `remove.csv` | `[--min-count N] [--max-wishlist M]` |
| `all` | Generate all 6 CSV files in a single pass | `[--min-count N] [--max-wishlist M]` |
| `all` | Generate all 7 CSV files in a single pass | `[--min-count N] [--max-wishlist M]` |
| `details` | Print detailed timing data for all tracks (stdout) | None |
| `track` | Print best car for specific track (stdout) | `<track_name> <condition> <rq>` |
| `improve` | Generate `improve.csv` (owned cars not at final build) | None |
### Flags
@ -226,12 +234,13 @@ This generates the following output files (all sorted by car RQ):
| File | Format | Description |
|------|--------|-------------|
| `best.csv` | `RQ,Brand,Model,Year,Count` | All cars best on at least one track |
| `very_best.csv` | `RQ,Brand,Model,Year,Count` | Cars best on ≥ min_count tracks |
| `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,Count` | Ideal wishlist (very_best unowned, capped) |
| `add.csv` | `RQ,Brand,Model,Year,Count` | Cars to add to wishlist |
| `remove.csv` | `RQ,Brand,Model,Year,Count` | Cars to remove from wishlist |
| `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 |
### Workflow Steps
@ -241,6 +250,7 @@ This generates the following output files (all sorted by car RQ):
4. **Check** `add.csv` for cars worth adding to your wishlist
5. **Clean up** `remove.csv` entries from your wishlist
6. **Sell** cars listed in `trash.csv` that are no longer useful
7. **Upgrade** cars listed in `improve.csv` to their target final build
## 📊 Data Sources
@ -318,16 +328,17 @@ struct Car {
#### 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
prize: bool, // Whether this is a prize car
guid: String, // Game identifier
car_rid: String, // Car identifier
brand: String, // Manufacturer
only_name: String, // Model name
year: u16, // Year
rq: u8, // Rarity level
config: String, // Original tune config from JSON
normalized_config: String, // Normalized final build (323, 233, or 332)
time: f64, // Track time
owned: bool, // Whether you own this car
prize: bool, // Whether this is a prize car
guid: String, // Game identifier
}
```