Project CARS GDF Gearbox Editor

A definition-driven binary editor and hex viewer for Project CARS Gearbox (GDF) files, designed for safe, in-place modification of known gearbox parameters such as primary/final gears and bevel gears.

This tool scans a GDF (or CDFBIN) file for known byte markers, decodes the associated payloads, and presents them in a structured UI alongside a synchronized hex view. All edits preserve the original file layout and size.

⚠️ This tool modifies binary game files. Always keep backups.

Features

Definition-driven parsing

• Gearbox fields are defined via byte markers and payload layouts
• Each occurrence is discovered dynamically (no fixed offsets)
• Fields are grouped by logical section (e.g. GEARBOX)
• Supports repeated fields (multiple gears)

Safe scalar editing

• Edit decoded values (bytes, ints, floats) via form controls
• In-place only edits — payload size must not change
• Immediate validation (range checks, size checks)
• Per-field revert to original value

Gear-aware display

• Automatically computes and displays gear ratios
• Primary/Final and Bevel gears shown as:

(Driver, Driven)  ratio=Driven/Driver

Integrated hex viewer & editor

• Classic hex + ASCII dump
• Selecting a field highlights:
• marker bytes
• payload bytes
• Click any known byte in hex view to jump back to its field
• Hex overwrite editor (same-length only)
• Revert hex regions to original file contents

Header byte-count validation (GDF-specific)

On open and save-as, the tool validates key Project CARS GDF header registers:

• 0x08 → total file length
• 0x14 → gear block length (file_len - 0x1C)

If mismatches are found:

• Issues are reported clearly
• A conservative auto-repair can be applied

---

Supported File Types

The editor can open:

• .gdf
• .cdfbin
• .cdf

(File dialog also allows opening any binary file.)

---

Requirements

• Python 3.10+ recommended
• Standard library only:
• tkinter, ttk
• struct, dataclasses, typing
• On Windows, DPI awareness is enabled automatically (if supported)

---

Running the Editor

python gdf_editor.py

Then use File → Open… to load a gearbox file.

---

How It Works

Marker-based decoding

Each field is defined by:

• a marker byte sequence
• a payload layout (e.g. ("byte", "byte"))

Example (simplified):

CdfFieldDef(
    "PrimaryOrFinalGear",
    "GEARBOX",
    b"\x24\x9D\x58\xF9\x64\x02",
    ("byte", "byte"),
)

The parser:

1. Finds all occurrences of the marker
2. Decodes the payload immediately following it
3. Tracks offsets for safe overwrite

In-place editing rule

All edits must:

• overwrite exactly the same number of bytes
• remain within the original file bounds

This ensures:

• no offset shifts
• no corruption of following structures
• compatibility with the game’s loader

---

UI Overview

Left pane

• Tree view of discovered fields
• Grouped by section
• Filter box for quick searching

Right pane

• Field metadata (offsets, raw bytes, layout)
• Editable scalar values
• Apply / Revert controls
• Contextual notes about gearbox structure

Bottom pane

• Hex viewer (paged)
• Jump to offset
• Highlighted marker and payload regions
• Hex overwrite & revert controls

---

Known Limitations

• No support for inserting or removing data
• Only fields defined in GDF_DEFS are decoded
• Marker corruption will prevent re-parsing of that field
• This is not a full GDF schema interpreter — it is a targeted gearbox editor

---

Extending the Editor

To add support for more gearbox fields:

1. Identify the marker bytes in the GDF
2. Determine the payload layout
3. Add a new CdfFieldDef entry to GDF_DEFS
4. Re-run the editor

Example layouts:

• "byte" → 1 byte unsigned
• "int32" → 4 byte signed
• "uint32" → 4 byte unsigned
• "float" → IEEE-754 float (little-endian)

---

Safety Notes

• Always keep a copy of the original file
• Make small changes and test in-game
• Use header auto-repair only if you understand the implications