Forza Modding Tools

Blender addons and reverse-engineering reference for Xbox 360-era Forza titles: Forza Motorsport 2, 3, 4 and Forza Horizon 1, 2. Goal: a complete game-to-Blender-to-game round-trip pipeline covering car models, track assets, localization, and UI.

Status: active reverse-engineering. Some addons work end-to-end; others are in-progress or pre-release. See the per-tool notes below.

---

Contents

Blender addons (Blender tools/)

Tool	Games	Status
forza_carbin_importer_v14.py	FM2, FM3, FM4, FH1, FH2 (reads)	Working — imports car models into Blender. Known bug: misreads vertex UV channels 2/3 as a TBN quaternion, producing incorrect split normals; doesn't affect geometry but does affect shading on round-trip.
forza_carbin_importer_v18.py / v19.py	FM2-FH2	Alternate importer (commissioned work). v19 stores full round-trip metadata as custom properties for exact-bytes preservation.
forza_carbin_exporter_v6_0.py	FH2	Unreleased — PDB-grounded clean-sheet rewrite. Game-agnostic (works on any Blender geometry, no donor data). Spec-correct per carbin_format_spec_v2.md. Not yet validated in-game.
forza_carbin_exporter_v5_5.py	FH2	Donor-passthrough exporter (preserves original bytes for imported cars). Commissioned companion to v19 importer.
forza_track_importer_v2_12_*.zip	FM4 (primary)	Working — imports tracks via QuickBMS + PVS/RMB parse.
forza_track_exporter_v1_1_22.py	FM4	Round-trip geometry validated in Blender; in-game test in progress.
forza_rmb_exporter_v1_1_0.py	FM4	Track render-mesh exporter.
forza_loc_editor_v1_5_0.py	FM2-FH2	Python/tkinter editor for XSTR and LSB2 .str localization files.

Older versions retained in the folder for reference / diagnostic regression testing.

Format specifications

• carbin_format_spec_v2.md — PDB-grounded FH2 .carbin specification. Complete byte-level layout from file header through per-vertex encoding. Derived from FH2 beta runtime disassembly (CCarBodyModel::Serialize → CCarModelData → CBaseCarModel → CBaseModel chain). Every field maps to a specific runtime class and offset; uncertainties explicitly flagged.
• carbin_format_spec.md — earlier empirical spec; kept for reference, partially corrected by v2.
• track_format_spec.md — FM4 track format reference.
• carbin_io_plan.md — implementation plan for the clean-sheet importer/exporter rewrite against v2 spec.
• carbin_exporter_handoff.md — dev journal / session handoff notes.

Other

• forzazip.py, forza_horizon.bms, forza_motorsport.bms, forza_motorsport_extract.py — QuickBMS scripts and wrappers for extracting bin.zip track archives.
• *.spec — PyInstaller recipes for the localization editor and zip tool.

---

Installation — Blender addons

1. Open Blender (4.5 LTS recommended).
2. Edit → Preferences → Add-ons → Install.
3. Select the .py file (or .zip for the track importer).
4. Enable the addon in the list.
5. Menu location: File → Import/Export → Forza CarBin / Forza Track / etc.

---

Usage notes

Carbin import (existing cars)

Import any .carbin file. Each car section becomes a Blender mesh object; each material subsection becomes a Blender material on that mesh. UV transforms are preserved as material/object custom properties where needed for round-trip.

Object naming convention: body = section "body" LOD 0; body_lod3 = section "body" LOD 3. Blender's .001 suffixes are stripped on export.

Carbin export (game-agnostic goal)

v6.0 is designed to be game-agnostic: any Blender geometry (a cube modeled from scratch, an imported FH2 car, an FBX from a third-party modeler) produces a valid FH2 .carbin through the same code path. No donor data, no source-byte passthrough. Spec-correct per carbin_format_spec_v2.md.

v6.0 is pre-release and untested in-game. Use at your own risk; file any failures with the in-game load error as a clue to which spec section to revisit.

---

Not included (copyright)

This repository contains only original work. No game assets, no Microsoft/Turn 10 files. You must supply your own:

• A dumped copy of the FH1/FH2/FM2/FM3/FM4 game files for any actual usage.
• PDB / XEX / MAP reverse-engineering inputs, if you want to verify spec claims yourself.

The .gitignore excludes all game-asset paths explicitly. Do not commit .xex, .pdb, .map, .carbin, .bix, or any other game content.

---

Reverse-engineering approach

The FH2 spec in this repo is derived exclusively from PDB type dumps and targeted XEX disassembly of the FH2 debug/beta runtime — not from observation of sample binaries. The methodology:

1. PDB class layouts pin down every field's offset and type.
2. Disassembled serialization functions (CCarBodyModel::Serialize, CCarModelData::Serialize, CMesh::SerializePrivate, CIndexBuffer::SerializeWithContext, CUberPackedVertex::SerializePartialVertex, etc.) give exact on-disk field sequence.
3. Every claim in carbin_format_spec_v2.md cites a specific runtime function or class offset.

Items that could not be resolved from the PDB alone (e.g. UV transform composition happens in vertex shader bytecode, not in the exe) are explicitly flagged with [UNCONFIRMED] in the spec.

---

Credits

• ForzaStudio by Mike Davis (http://codeescape.com/) — the carbin importer started as a Python port of this tool.
• FM4CarModelTools — reference for donor-based section swapping approach.
• Forza-X360-IO by austinbaccus — track format reference implementation.
• QuickBMS by Luigi Auriemma — bin.zip extraction engine (not redistributed in this repo).
• Commissioned work from various collaborators, credited per-file where applicable.

---

License

Code in this repository is the author's original work. Game-specific constants (version numbers, enum values, class field offsets) are facts about how Microsoft/Turn 10's shipped software works — stated as facts, not copied code. See individual file headers for any per-file licensing.