| name | debug-bin |
| description | Debug RaceIQ session .bin/.bin.gz files — unknown track/car, 0 packets, missing laps, import failures. Use when a session bin imports wrong or a user reports bad telemetry data. |
Debug Session Bins
Quick start
bun scripts/inspect-bin.ts <path-to-bin> [--game <gameId>] [--no-import]
One command. Prints header hex dump, game detection, packet count, laps, car/track resolution. Flags UNKNOWN TRACK inline.
Stage-only header check (fast, no import): add --no-import.
Diagnosis flowchart
| Symptom | Likely cause | Where to look |
|---|
game from buffer: (none) | Magic bytes not recognized | detectGameIdFromBuffer in server/import-session-bin.ts (~line 126). Compare hex dump vs known magics (ACEVO_PACKED_MAGIC, META_FRAME_MAGIC) |
packets: 0 | Frame format mismatch or parser rejects frames | iterateFrames + adapter tryParse in server/games/<game>/ |
UNKNOWN TRACK | Track name/ordinal not in CSV, or track extraction never ran | shared/games/ac-evo/tracks.csv, getAcEvoTrackByName, parser track resolution in AC Evo parser |
Unknown car (log line Unknown car "...") | Car missing from CSV | shared/games/ac-evo/cars.csv, getAcEvoCarByDisplayName |
| Laps = 0 with packets > 0 | Lap detector never fires | createLapDetector, check session type, flushIncompleteLap. Note: lap detector defers insertLap via setTimeout(0) — importer waits 100ms |
| Wrong lap times | Sector/timing extraction | scripts/check-lap-times.ts, scripts/check-lap-sequence.ts |
Key facts
importSessionBin(bytes, gameId) accepts gzip'd input (auto-detected by magic bytes) regardless of extension.- MUST call
initServerGameAdapters() (from server/games/init) before getServerGame/importSessionBin in any standalone script — otherwise Unknown server game adapter error.
- Import path uses
ImportCaptureAdapter + NoopWsAdapter + bypassPacketRateFilter: true — no live server needed.
- AC Evo player slot locks after ~60 frames (
Player slot locked log line). Early frames may resolve to wrong car.
- Parser logs (
[AC Evo Parser] Resolved track/car: ...) go to stdout — grep them, don't suppress.
Deeper digging
- Raw hex around a specific offset:
bun scripts/inspect-bin.ts <file> --no-import, then targeted reads.
- Game-specific diagnostics:
scripts/diag-ac-evo-physics.ts, scripts/diag-ac-evo-status.ts, scripts/check-acc-dump.ts, scripts/debug-fm-lap.ts.
- Adding a missing track/car: edit the CSV in
shared/games/<game>/, then re-run inspect-bin to verify resolution end-to-end (parser → ordinal → DB).
- Follow systematic-debugging: reproduce first (inspect-bin IS the repro), find root cause before patching CSVs blindly.
