Module gff 

GFF binary container support. GFF V3.2 binary reader and writer.

GFF is a typed, table-backed binary graph format used for most KotOR game data objects (UTC, UTI, ARE, DLG, and others).

Shape of the container

A 56-byte header carrying an offset-and-count pair for each of six sections: structs, fields, labels, the field data blob, and two index arrays. Every section is located by its own header entry.

One trap worth knowing before reading the header: the last three counts are byte lengths while the first three are element counts.

The overloaded word

Both struct and field records carry a data_or_offset that means different things by context, with no discriminator stored beside it. On a field it is the value itself when the type fits in four bytes and an offset into the data blob or an index array otherwise. On a struct it is a field index directly when field_count is exactly one, and a byte offset into the field indices array for any other count.

Getting that wrong does not fail loudly, it reads a plausible number out of the wrong region, which is why this module validates every range before decoding rather than trusting the arithmetic.

Logical Data Model

Gff
 `-- root GffStruct
      `-- [GffField(label, GffValue)]
           `-- nested structs/lists recursively reference tables

Offsets in struct and field records reference table locations or blob offsets depending on field type. This module keeps those rules explicit and validates all ranges before decoding.

Macros

gff_label

Builds a GffLabel from a literal, rejecting an invalid one at compile time.

Structs

Change

What happened at one address, from open until now.

Gff

In-memory representation of a binary GFF file.

GffDocument

One open GFF file: its bytes, its tree, and what has happened to it.

GffField

One labeled GFF field.

GffLabel

Canonicalized GFF field label.

GffLocalizedString

CExoLocString payload.

GffLocalizedSubstring

One localized substring entry.

GffPath

An address into a GFF tree, such as ClassList[0].Class.

GffStruct

One GFF struct node.

GffWalk

Every value in a GFF tree, in the order the file carries them.

Enums

GffBinaryError

Errors produced while parsing or writing binary GFF data.

GffDocumentError

A path that does not parse, or does not name one field of this tree.

GffLabelError

Error returned when constructing a GffLabel fails validation.

GffPathError

A path that does not resolve, or an edit the tree will not take.

GffPathParseError

A path string that does not describe an address.

GffPathSegment

One step of a GffPath.

GffValue

Runtime value for one GFF field.

Constants

GENERIC_FILE_TYPE

The magic a GFF carries when it claims no format of its own.

MAX_GFF_LABEL_LEN

Maximum number of ASCII characters for a GFF field label.

Functions

get_binary

Reads a VOID field’s bytes.

get_bool

Reads a boolean from numeric fields (non-zero is true).

get_f32

Reads an f32 from single/double fields.

get_i8

Reads an i8 from compatible integer field encodings.

get_i16

Reads an i16 from compatible integer field encodings.

get_i32

Reads an i32 from compatible integer field encodings.

get_locstring

Reads a localized-string field by reference.

get_resref

Reads a ResRef field.

get_string

Reads a string field.

get_u8

Reads a u8 from compatible integer field encodings.

get_u16

Reads a u16 from compatible integer field encodings.

get_u32

Reads a u32 from canonical integer encodings.

get_u64

Reads a u64 from compatible integer field encodings.

get_u32_extended_signed

Reads a u32 with additional signed-narrow coercions for compatibility.

read_gff

Reads a binary GFF file from a reader.

read_gff_from_bytes

Reads a binary GFF file from bytes.

upsert_field

Updates an existing field value or inserts a new field when missing.

write_gff

Writes a GFF in binary V3.2 format.

write_gff_to_vec

Serializes a GFF to a byte vector.