.Dd September 1, 2016
.Dt GFF2XML 1
.Os
.Sh NAME
.Nm gff2xml
.Nd BioWare GFF to XML converter
.Sh SYNOPSIS
.Nm gff2xml
.Op Ar options
.Ar input_file
.Op Ar output_file
.Sh DESCRIPTION
.Nm
converts BioWare's GFF files (versions V3.2/V3.3 and V4.0/V4.1)
into human-readable XML.
GFF are hierarchical data files, similar
to XML in concept, but stored in binary.
As such, these files are used as a basis for many of the file formats
found in the BioWare games.
For example, an UTC file is a GFF holding a template for a
creature, while a GUI file is a GFF describing an in-game menu.
.Pp
Both version 3 of the format (V3.2/V3.3) and version 4 (V4.0/V4.1)
are supported.
While they are similar, the 4th version carries
several changes to make the files more efficient to read in-game.
This includes replacing the string field names (which map
to XML tags) with numerical identifiers, resulting in converted
XML files that are stripped of their meaning.
To compensate, this tool adds readable aliases to many of these
numerical identifiers, giving them back their meaning.
Unfortunately, not all of them are known.
Most notably, the identifiers introduced in
.Em Sonic Chronicles: The Dark Brotherhood
and
.Em Dragon Age 2
are still missing.
.Pp
The changes in the minor versions (V3.2 vs. V3.3 and V4.0 vs.
V4.1) are less significant.
V3.3 simply changes which languages are supported,
and V4.1 adds a common string table at the start of the file.
Both of these additions are handled transparently.
.Pp
LocStrings found in GFF V3.2 and V3.3 contain localized string
data, which, depending on the game and the language, can be encoded
in various ways.
There is no way to autodetect the specific encoding.
.Nm
employs a simple heuristic to combat this, but it may fail
for certain strings and files.
However, there are options to explicitly specify the game this GFF
file is from.
.Nm
will then use the correct game-specific encoding tables.
.Pp
Unfortunately, even these tables might not be completely correct
in all cases.
.Em Neverwinter Nights ,
for example, treated many strings as being encoded in the native
encoding used for the language of the game installation.
This lead to many people putting non-English strings into fields
tagged as language ID 0, nominally reserved for English.
To read these files correctly,
.Nm
provides an --encoding parameter to override the encoding used
for a specific language ID.
.Sh OPTIONS
.Bl -tag -width xxxx -compact
.It Fl h
.It Fl Fl help
Show a help text and exit.
.It Fl Fl version
Show version information and exit.
.It Fl Fl cp1252
Read GFF4 strings as Windows CP-1252.
Usually, strings in version 4 of the GFF format are encoded in
little-endian UTF-16.
But some files store them as Windows CP-1252 instead.
Since there's no clean way to autodetect the different encoding,
this switch manually selects Windows CP-1252.
This option only concerns strings embedded in GFF4 files, not
GFF3 LocStrings.
.It Fl Fl nwnpremium
The GFF files found in the encrypted HAK files of
.Em Neverwinter Nights
premium modules are deliberately broken.
This options tells
.Nm
to work around the brokenness.
.It Fl Fl nwn
Read LocStrings in an encoding appropriate for
.Em Neverwinter Nights .
.It Fl Fl nwn2
Read LocStrings in an encoding appropriate for
.Em Neverwinter Nights 2 .
.It Fl Fl kotor
Read LocStrings in an encoding appropriate for
.Em Knights of the Old Republic .
.It Fl Fl kotor2
Read LocStrings in an encoding appropriate for
.Em Knights of the Old Republic II .
.It Fl Fl jade
Read LocStrings in an encoding appropriate for
.Em Jade Empire .
.It Fl Fl witcher
Read LocStrings in an encoding appropriate for
.Em The Witcher .
.It Fl Fl dragonage
Read LocStrings in an encoding appropriate for
.Em Dragon Age: Origins .
.It Fl Fl dragonage2
Read LocStrings in an encoding appropriate for
.Em Dragon Age II .
.It Fl Fl encoding Ar str
Override an encoding.
The string has to be of the form n=encoding, for example 0=cp-1252
to override the encoding of the (ungendered) language ID 0 to be
Windows codepage 1252.
To override several encodings, specify the --encoding parameter
multiple times.
.El
.Bl -tag -width xxxx -compact
.It Ar input_file
The GFF file to convert.
.It Op Ar output_file
The XML file will be written there.
If no output file is specified, the XML data is written to
.Dv stdout .
The encoding of the XML stream is always UTF-8.
.El
.Sh EXAMPLES
Convert the GFF
.Pa file1.utc
into an XML file:
.Pp
.Dl $ gff2xml file1.utc file2.xml
.Pp
Convert the GFF
.Pa file1.utc
into an XML file on
.Dv stdout :
.Pp
.Dl $ gff2xml file1.utc
.Pp
Convert the GFF
.Pa file1.utc ,
which uses Windows CP-1252 strings:
.Pp
.Dl $ gff2xml --cp1252 file1.utc file2.xml
.Pp
Convert the GFF
.Pa file1.utc ,
which encodes language ID 0 in LocStrings as Windows CP-1250:
.Dl $ gff2xml --encoding 0=cp1250 file1.utc file2.xml
.Sh SEE ALSO
.Xr convert2da 1 ,
.Xr fixpremiumgff 1 ,
.Xr tlk2xml 1 ,
.Xr ssf2xml 1
.Pp
More information about the xoreos project can be found on
.Lk https://xoreos.org/ "its website" .
.Sh AUTHORS
This program is part of the xoreos-tools package, which in turn is
part of the xoreos project, and was written by the xoreos team.
Please see the
.Pa AUTHORS
file for details.