Home For Developers GFF Introduction 3. File Format Physical Layout

3. File Format Physical Layout

[Printer Friendly]

This section describes what the actual bytes are in a GFF file, where they are, and what they do.

The file format descriptions in this section use the following terminology:

• BYTE: 1-byte (8-bit) unsigned integer
• CHAR: 1-byte (8-bit) character
• DWORD: 4-byte (32-bit) unsigned integer

Note that GFF byte order is little endian, which is the format used by Intel processors. If an integer value is more than 1 byte long, then the least significant byte is the first one, and the most significant byte is the last one. For example, the number 258 (0x0102 in hex) expressed as a 4-byte integer would be stored as the following sequence of bytes within the file: 0x02, 0x01, 0x00, 0x00.

3.1. Overall File Layout

A GFF file contains 7 distinct sections--1 fixed-size header, 5 arrays of fixed-size elements, and 1 block of raw data. The offset to each section is stored in the header, as is the number of elements in each array.

Figure 3.1: GFF File Structure

3.2. Header

The GFF header contains a number of values, all of them DWORDs (32-bit unsigned integers). The header contains offset information for all the other sections in the GFF file. Values in the header are as follows, and arranged in the order listed:

Table 3.2: Header Format

Value	Description
FileType	4-char file type string
FileVersion	4-char GFF Version. At the time of writing, the version is "V3.2"
StructOffset	Offset of Struct array as bytes from the beginning of the file
StructCount	Number of elements in Struct array
FieldOffset	Offset of Field array as bytes from the beginning of the file
FieldCount	Number of elements in Field array
LabelOffset	Offset of Label array as bytes from the beginning of the file
LabelCount	Number of elements in Label array
FieldDataOffset	Offset of Field Data as bytes from the beginning of the file
FieldDataCount	Number of bytes in Field Data block
FieldIndicesOffset	Offset of Field Indices array as bytes from the beginning of the file
FieldIndicesCount	Number of bytes in Field Indices array
ListIndicesOffset	Offset of List Indices array as bytes from the beginning of the file
ListIndicesCount	Number of bytes in List Indices array

The FileVersion should always be "V3.2" for all GFF files that use the Generic File Format as described in this document. If the FileVersion is different, then the application should abort reading the GFF file.

The FileType is a programmer-defined 4-byte character string that identifies the content-type of the GFF file. By convention, it is a 3-letter file extension in all-caps, followed by a space. For example, "DLG ", "ITP ", etc. When opening a GFF file, the application should check the FileType to make sure that the file being opened is of the expected type.

3.3. Structs

In a GFF file, Struct Fields are stored differently from other fields. Whereas most Fields are stored in the Field array, Structs are stored in the Struct Array.

The very first element in the Struct Array is the Top-Level Struct for the GFF file, and it "contains" all the other Fields, Structs, and Lists. In this sense, the word "contain" refers to conceptual containment (as in Section 2.1) rather than physical containment (as in Section 3). In other words, it does not imply that all the other Fields are physically located inside the Top-Level Struct on disk (in fact, all Structs have the same physical size on disk).

Since the Top-Level Struct is always present, every GFF file contains at least one element in the Struct Array.

The Struct Array looks like this

Struct 0 (Top-Level Struct)	Struct 0 is always present
Struct 1
Struct 2
....
Struct (N-1)	N = Header.StructCount N is always greater than or equal to 1

Physically, a GFF Struct contains the values listed in the table below. All of them are DWORDs.

Table 3.3: Struct Format

Value	Description
Struct.Type	Programmer-defined integer ID.
Struct.DataOrDataOffset	If Struct.FieldCount = 1, this is an index into the Field Array. If Struct.FieldCount > 1, this is a byte offset into the Field Indices array, where there is an array of DWORDs having a number of elements equal to Struct.FieldCount. Each one of these DWORDs is an index into the Field Array.
Struct.FieldCount	Number of fields in this Struct.

The above table shows that the Fields that a Struct conceptually contains are referenced indirectly via the DataOrDataOffset value.

Struct 0, which is the Top-Level Struct, always has a Type (aka Struct ID) of 0xFFFFFFFF.

3.4. Fields

The Field Array contains all the Fields in the GFF file except for the Top-Level Struct.

Figure 3.4: Field Array

Field 0 (Top-Level Struct)	Struct 0 is always present
Field 1
Field 2
....
Field (N-1)	N = Header.FieldCount

Each Field contains the values listed in the table below. All of the values are DWORDs.

Table 3.4a: Field Format

Value	Description
Field.Type	Data type
Field.LabelIndex	Index into the Label Array
Field.DataOrDataOffset	If Field.Type is a simple data type (see table below), then this is the value actual of the field. If Field.Type is a complex data type (see table below), then this is a byte offset into the Field Data block.

The Field Type specifies what data type the Field stores (recall the data types from Section 2.2). The following table lists the values for each Field type. A datatype is considered complex if it would not fit within a DWORD (4 bytes).

Table 3.4b: Field Types

Type ID	Type	Complex?
0	BYTE
1	CHAR
2	WORD
3	SHORT
4	DWORD
5	INT
6	DWORD64	yes
7	INT64	yes
8	FLOAT
9	DOUBLE	yes
10	CExoString	yes
11	ResRef	yes
12	CExoLocString	yes
13	VOID	yes
14	Struct	yes*
15	List	yes**

Non-complex Field data is contained directly within the Field itself, in the DataOrDataOffset member. If the data type is smaller than a DWORD, then the first bytes of the DataOrDataOffset DWORD, up to the size of the data type itself, contain the data value.

If the Field data is complex, then the DataOrDataOffset value is equal to a byte offset from the beginning of the Field Data Block, pointing to the raw bytes that represent the complex data. The exact method of fetching the complex data depends on the actual Field Type, and is described in Section 4.

*As a special case, if the Field Type is a Struct, then DataOrDataOffset is an index into the Struct Array instead of a byte offset into the Field Data Block.

**As another special case, if the Field Type is a List, then DataOrDataOffset is a byte offset from the beginning of the List Indices Array, where there is a DWORD for the size of the array followed by an array of DWORDs. The elements of the array are offsets into the Struct Array. See Section 4.9 for details.

3.5. Labels

A Label is a 16-CHAR array. Unused characters are nulls, but the label itself is non-null-terminated, so a 16-character label would use up all 16 CHARs with no null at the end.

The Label Array is a list of all the Labels used in a GFF file.

Note that a single Label may be referenced by more than one Field. When multiple Fields have Labels with the exact same text, they share the same Label element instead of each having their own copy. This sharing occurs regardless of what Struct the Field belongs to. All Labels in the Label Array should be unique.

Also, the Fields belonging to a Struct must all use different Labels. It is permissible, however, for Fields in two different Structs to use the same Label, regardless of whether one of those Structs is conceptually contained inside the other Struct.

Figure 3.5: Label Array

Label 0
Label 1
Label 2
....
Label (N-1)	N = Header.LabelCount

3.6. Field Data Block

The Field Data block contains raw data for any Fields that have a complex Field Type, as described in Section 3.4. The two exceptions to this rule are Struct and List Fields, which are not stored in the Field Data Block.

The FieldDataCount in the GFF header specifies the number of BYTEs contained in the Field Data block.

The data in the Field Data Block is laid out according to the type of Field that owns each byte of data. See Section 4 for details.

3.7. Field Indices

A Field Index is a DWORD containing the index of the associated Field within the Field array.

The Field Indices Array is an array of such DWORDs.

3.8. List Indices

The List Indices Array contains a sequence of List elements packed end-to-end.

A List is an array of Structs, and being array, its length is variable. The format of a List is as shown below:

Figure 3.8: List Format

The first DWORD is the Size of the List, and it specifies how many Struct elements the List contains. There are Size DWORDS after that, each one an index into the Struct Array.

Go to Page (Previous Page - Index, 2, 3, 4 - Next Page)