GFF (Generic File Format)

The Generic File Format (GFF) is BioWare’s core binary serialization format, functioning like a binary JSON object or XML tree. It holds arbitrarily nested structures, typed fields, and lists, powering UI layouts, character sheets, dialogues, and area descriptions.

At a Glance

Data Model Structure

The rakata-formats crate maps the GFF struct/field/list indexing graph into an in-memory model (rakata_formats::Gff).

• Typed values: GFF fields carry discrete types (BYTE, SHORT, VOID, STRUCT, LIST, …). rakata_formats::GffValue mirrors them one-to-one, so callers never touch raw byte layouts or indirect index arrays.
• Label deduplication: GFF caps field labels at 16 characters and deduplicates them in a contiguous LabelTable. The writer reproduces this layout exactly, so serialized binaries are deterministic and byte-compatible with what the engine emits.

Engine Audits & Decompilation

Binary: swkotor.exe

Serialization Architecture (WriteGFFFile)

Derived from 0x00413030 / 0x004113d0.

The engine allocates the output buffer entirely in-memory and serializes exactly 7 contiguous sections in an absolutely strict order. No inter-section padding or reserved alignment bytes are inserted anywhere natively. Each section’s byte-offset is dynamically snapshotted into the 56-byte header, operating as the canonical write path utilized for save games and area extraction.

Warning

Because BioWare enforces fixed 16-byte elements inside the Label arrays, any label that exceeds 16 characters is strictly truncated by the engine array bounds.

Note

The GFF version is always V3.2. The header’s version field is written by CResGFF::CreateGFFFile (0x00411260) from a single global value, and the version string a caller passes in is ignored. So the on-disk version never varies, even where the calling code asks for something else (several save-game writers request V2.0, but it never reaches disk). Read the V3.2 you observe; the version is not a per-resource signal.

Note

Field-label lookup is case-sensitive. Every CResGFF::ReadField* wrapper resolves its label through CResGFF::GetFieldByLabel (0x00411630), which copies the requested label into a fixed 16-byte buffer with no case-folding and compares it against each field’s stored label with an inlined byte-for-byte comparison, not a case-insensitive string function. A label that differs from the one the engine’s own code constructs only in capitalization – FortBonus versus the engine’s fortbonus, for instance – never matches, full stop; it isn’t a fallback path, it’s a different, unmatched string. This holds for the whole ReadField* family (every scalar and string type), so exact-string field matching in a reader is the behaviorally-correct model of this engine, not a shortcut that happens to work on vanilla data.

Engine Blueprints: Specialized GFF Containers

While the gff.md reference explains the layout of raw GFF nodes, the engine frequently uses GFF as a structural wrapper to serialize completely deterministic entities known as Blueprints. These blueprints operate as the strict layouts defining creatures, dialogue trees, placeables, and area parameters.

Because rakata-lint provides deep behavioral validation over these blueprints natively, we have comprehensively audited how the K1 GOG executable (swkotor.exe) maps these layouts into active memory via its Load*FromGFF functions.

Note

The typed blueprint structs documented below (Utc, Uti, Are, Git, Dlg, Ifo, Utd, Ute, Utm, Utp, Uts, Utt, Utw) are projections over raw GFF, not replacements. Each from_gff extracts only the documented fields and silently drops anything else; to_gff writes only those documented fields. The raw Gff tree stays alongside the typed view for callers that need byte-exact fidelity. See Typed Views and Raw GFF in the architecture guide for the full rationale and the choose-which-layer guidance.

The Blueprint Engine Audits

The audits listed in this section’s navigation bar are formal, decompilation-backed blueprints cataloging KOTOR’s physical constraints. They document the exact fields, load phrasing, and engine rule evaluations that supersede any generic structural validity.

If a field exists in GFF but breaks the engine, our Linter rules will flag it using these documentation audits as the source of truth.