nwn.gff

package documentation

(source)

Transform GFF (Generic File Format) files from/to native python types.

Python representation is (Struct) and (List) objects, which can be nested. They behave just like native python dictionaries and lists, but with some additional methods and properties to make life easier.

Since GFF has strong typing beyond what python offers natively, the module provides a number of custom types to represent the various field types that can be found in a GFF file.

All field types are subclasses of the native python types, and are used to enforce the GFF type system.

This module also provides helpers to transform NWN-style JSON data to/from the native python type schema (eg. this data is returned by the game template functions, and is also the serialisation format used by neverwinter.nim).

Module	`_impl`	Undocumented
Module	`_json`	Undocumented
Module	`_reader`	Undocumented
Module	`_types`	Undocumented
Module	`_writer`	Undocumented

From __init__.py:

Class	`Byte`	Undocumented
Class	`CExoLocString`	Represents a localized string in the NWN engine.
Class	`CExoString`	Undocumented
Class	`Char`	Undocumented
Class	`Double`	Undocumented
Class	`Dword`	Undocumented
Class	`Dword64`	Undocumented
Class	`Float`	Undocumented
Class	`Int`	Undocumented
Class	`Int64`	Undocumented
Class	`List`	GFF Lists are just python lists of Structs. They carry no metadata.
Class	`ResRef`	Undocumented
Class	`Short`	Undocumented
Class	`Struct`	GFF Structs are just python dicts with .attr access and some metadata.
Class	`VOID`	Undocumented
Class	`Word`	Undocumented
Function	`read`	Read a GFF data from a binary stream.
Function	`struct_from_json`	Parse nwn-style json representation into native python types, same as you would get from reading a GFF file with the `read` function.
Function	`struct_to_json`	Convert a Struct to its nwn-style json representation.
Function	`type_label_to_type`	Convert a GFF type label to the corresponding type class.
Function	`write`	Write a GFF data structure to a binary stream.

def read(file: BinaryIO) -> tuple[Struct, FileMagic]: (source) ¶

Read a GFF data from a binary stream.

Example

>>> with open("file.gff", "rb") as f:
...     root, file_type = gff.read(f)
...     print(root)

Parameters
file:`BinaryIO`	The binary stream to read from.
Returns
`tuple[Struct, FileMagic]`	A tuple containing the root struct and the file type.

def struct_from_json(data: dict) -> tuple[Struct, FileMagic]: (source) ¶

Parse nwn-style json representation into native python types, same as you would get from reading a GFF file with the read function.

The data provided must be a dictionary of the root structure; e.g. reading the file as written by the game with the json module.

Example

>>> with open("item.uti.json", "r") as f:
...     data = json.load(f)
...     print(data["AddCost"])  # "AddCost": {"type": "dword", "value": 1000}
...     from nwn.gff import struct_from_json
...     xfrm, ty = struct_from_json(data)
...     print(xfrm["AddCost"])  # Dword(1000)

Parameters
data:`dict`	The json data representing a GFF structure, as emitted by the game or neverwinter.nim.
Returns
`tuple[Struct, FileMagic]`	The parsed GFF structure.
Raises
`ValueError`	If the json data is malformed or contains unsupported types.

def struct_to_json(struct: Struct, data_type: FileMagic) -> dict: (source) ¶

Convert a Struct to its nwn-style json representation.

Parameters
struct:`Struct`	The Struct to convert.
data_type:`FileMagic`	File magic type to include in the json.
Returns
`dict`	A dictionary representing the Struct in json format.
Raises
`ValueError`	If the Struct contains unsupported types.

def type_label_to_type(label: str): (source) ¶

Convert a GFF type label to the corresponding type class.

Parameters
label:`str`	The GFF label to convert.
Returns
The corresponding type class.
Raises
`ValueError`	If the label is not recognized.

def write(file: BinaryIO, root: Struct, magic: FileMagic): (source) ¶

Write a GFF data structure to a binary stream.

The structure must only use supported GFF types, as GFF is a strongly typed format and deviation from these will make the game fail to read them (e.g. storing a byte as a int will make the game not see it).

Example

>>> root = gff.Struct(0, Byte=gff.Byte(255), SomeStruct=gff.Struct(SomeKey=gff.CExoString("5")))
... out = BytesIO()
... gff.write(out, root, "TEST")

Parameters
file:`BinaryIO`	The binary stream to write to.
root:`Struct`	The root structure of the GFF file.
magic:`FileMagic`	The file magic identifier (4 characters).