Skip to content
Back to top
View this page

# `file_processor`

Submodule for low level Terraria save file operations, and in particular, the `FileProcessor` class.

class lihzahrd.terraria.utils.file_processor.FileProcessor(stream: BinaryIO)

  Helper class for reading and writing C# data structures to Terraria save files.

  stream: BinaryIO

    The binary stream (`BinaryIO`) to operate on.

  read(structure: Struct) → Any

    Read the given structure from `stream`.

    Parameters:

      structure – The structure to read.

    Returns:

      The value of the read structure (will probably be a `tuple`).

  write(structure: Struct, value: Iterable[Any]) → None

    Write the given structure from `stream`.

    Parameters:

      - structure – The structure to write.

      - value – The value of the structure.

  BOOL: Struct = Struct('?')

    A serialized C# `bool`.

  read_bool() → bool

    Read a `BOOL` from `stream`.

    Returns:

      The read value, as a `bool`.

  write_bool(value: bool) → None

    Write a `BOOL` to `stream`.

    Parameters:

      value – The value to write, as a `bool`.

  SBYTE: Struct = Struct('b')

    A serialized C# `sbyte`.

  SBYTE_MIN: Literal[-128] = -128

    The minimum value that a `SBYTE` can have.

  SBYTE_MAX: Literal[127] = 127

    The maximum value that a `SBYTE` can have.

  read_sbyte() → int

    Read a `SBYTE` from `stream`.

    Returns:

      The read value, as a `int`.

  write_sbyte(value: int) → None

    Write a `SBYTE` to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  BYTE: Struct = Struct('B')

    A serialized C# `byte`.

  BYTE_MIN: Literal[0] = 0

    The minimum value that a `BYTE` can have.

  BYTE_MAX: Literal[255] = 255

    The maximum value that a `BYTE` can have.

  read_byte() → int

    Read a `BYTE` from `stream`.

    Returns:

      The read value, as a `int`.

  write_byte(value: int) → None

    Write a `BYTE` to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  INT_TO_BITS: dict[int, tuple[bool, bool, bool, bool, bool, bool, bool, bool]]

    Cache associating each `int` between 0 and 255 to a `tuple` of 8 `bool` elements of its bits in little-endian order.

    Example

        >>> FileProcessor.INT_TO_BITS[0]
        (False, False, False, False, False, False, False, False)
        >>> FileProcessor.INT_TO_BITS[1]
        (True, False, False, False, False, False, False, False)
        >>> FileProcessor.INT_TO_BITS[128]
        (False, False, False, False, False, False, False, True)

    Note

    This is necessary to speed up bits processing, which would otherwise take a long time.

  read_bits() → tuple[bool, bool, bool, bool, bool, bool, bool, bool]

    Read a `BYTE` from `stream`, then get its `INT_TO_BITS`.

    Returns:

      The read bits, as a `tuple` of `bool`.

  write_bits(value: tuple[bool, bool, bool, bool, bool, bool, bool, bool]) → None

    Convert a series of `INT_TO_BITS` to a `BYTE`, then write it to `stream`.

    Parameters:

      value – The bits to write, as a `tuple` of `bool`.

  SHORT: Struct = Struct('h')

    A serialized C# `short`.

  SHORT_MIN: Literal[-32768] = -32768

    The minimum value that a `SHORT` can have.

  SHORT_MAX: Literal[32767] = 32767

    The maximum value that a `SHORT` can have.

  read_short() → int

    Read a `SHORT` from `stream`.

    Returns:

      The read value, as a `int`.

  write_short(value: int) → None

    Write a `SHORT` to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  USHORT: Struct = Struct('H')

    A serialized C# `ushort`.

  USHORT_MIN: Literal[0] = 0

    The minimum value that a `USHORT` can have.

  USHORT_MAX: Literal[65535] = 65535

    The maximum value that a `USHORT` can have.

  read_ushort() → int

    Read a `USHORT` from `stream`.

    Returns:

      The read value, as a `int`.

  write_ushort(value: int) → None

    Write a `USHORT` to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  INT: Struct = Struct('i')

    A serialized C# `int`.

  INT_MIN: Literal[-2147483648] = -2147483648

    The minimum value that a `INT` can have.

  INT_MAX: Literal[2147483647] = 2147483647

    The maximum value that a `INT` can have.

  read_int() → int

    Read a `INT` from `stream`.

    Returns:

      The read value, as a `int`.

  write_int(value: int) → None

    Write a `INT` to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  UINT: Struct = Struct('i')

    A serialized C# `uint`.

  UINT_MIN: Literal[0] = 0

    The minimum value that a `UINT` can have.

  UINT_MAX: Literal[4294967295] = 4294967295

    The maximum value that a `UINT` can have.

  read_uint() → int

    Read a `UINT` from `stream`.

    Returns:

      The read value, as a `int`.

  write_uint(value: int) → None

    Write a `UINT` to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  LONG: Struct = Struct('q')

    A serialized C# `long`.

  LONG_MIN: Literal[-9223372036854775808] = -9223372036854775808

    The minimum value that a `LONG` can have.

  LONG_MAX: Literal[9223372036854775807] = 9223372036854775807

    The maximum value that a `LONG` can have.

  read_long() → int

    Read a `LONG` from `stream`.

    Returns:

      The read value, as a `int`.

  write_long(value: int) → None

    Write a `LONG` to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  ULONG: Struct = Struct('Q')

    A serialized C# `ulong`.

  ULONG_MIN: Literal[0] = 0

    The minimum value that a `ULONG` can have.

  ULONG_MAX: Literal[18446744073709551615] = 18446744073709551615

    The maximum value that a `ULONG` can have.

  read_ulong() → int

    Read a `ULONG` from `stream`.

    Returns:

      The read value, as a `int`.

  write_ulong(value: int) → None

    Write a `ULONG` to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  FLOAT: Struct = Struct('f')

    A serialized C# `float`.

  read_float() → float

    Read a `FLOAT` from `stream`.

    Returns:

      The read value, as a `float`.

  write_float(value: float) → None

    Write a `FLOAT` to `stream`.

    Parameters:

      value – The value to write, as a `float`.

  DOUBLE: Struct = Struct('d')

    A serialized C# `double`.

  read_double() → float

    Read a `DOUBLE` from `stream`.

    Note

    Since Python’s `float` is 64-bit, no data is lost in the conversion.

    Returns:

      The read value, as a `float`.

  write_double(value: float) → None

    Write a `DOUBLE` to `stream`.

    Parameters:

      value – The value to write, as a `float`.

  RECT = Struct('iiii')

    A `Rectangle` of `INT`.

  read_rect() → Rectangle[int]

    Read a `RECT` from `stream`.

    Returns:

      The read value, as a `Rectangle` of `int`.

  write_rect(value: Rectangle[int]) → None

    Write a `RECT` to `stream`.

    Parameters:

      value – The value to write, as a `Rectangle` of `int`.

  read_uleb128() → int

    Read a ULEB128 from `stream`.

    Returns:

      The read value, as a `int`.

  write_uleb128(value: int) → None

    Write a ULEB128 to `stream`.

    Parameters:

      value – The value to write, as a `int`.

  read_bytes_count(count: int) → bytes

    Read a fixed number of bytes from `stream`.

    Parameters:

      count – The number of bytes to read.

    Returns:

      The read `bytes`.

  read_bytes_until(address: int | None) → bytes

    Read bytes from `stream` until the given address.

    Parameters:

      address – The address to read bytes until.

    Returns:

      The read `bytes`.

  write_bytes(value: bytes) → None

    Write some `bytes` to `stream`.

    Parameters:

      value – The `bytes` to write.

  read_string_raw(count: int) → str

    Read a fixed number of bytes into a `latin1` string.

    Parameters:

      count – The number of bytes to read.

    Returns:

      The read bytes, as a `str` with `latin1` encoding.

  write_string_raw(value: str) → None

    Write a `str` to `stream`.

    Warning

    This does not write the size of the string!

    Parameters:

      value – The `str` to write.

  read_string_variable() → str

    Read a `str` of variable length from `stream`:

    1. First, `read_uleb128()` is called to determine the size of the string in bytes.

    2. Then, `read_string_raw()` is called to read the actual string.

    Returns:

      The read `str`.

  write_string_variable(value: str) → None

    Write a `str` of variable length to `stream`:

    1. First, the string is converted to `bytes` using the `latin1` encoding.

    2. Then, the size of the string in bytes is written with `write_uleb128()`.

    3. Finally, the `bytes` are written with `write_bytes()`.

    Parameters:

      value – The `str` to write.

  read_uuid() → UUID

    Read 16 bytes from `stream`, and consider them an `UUID`.

    Returns:

      The read `UUID`.

  write_uuid(value: UUID) → None

    Write the 16 bytes corresponding to the given `UUID` to `stream`.

    Parameters:

      value – The `UUID` to write.

  read_datetime() → datetime

    Read a `ULONG` from `stream`, then convert it to a `datetime`, following the same algorithm C# uses.

    Returns:

      The read `datetime`.

    See also

    - System.DateTimeKind in the C# docs

    - DateTime.FromBinary in the C# source

    Warning

    Some precision might be lost due to how `timedelta` objects work in Python.

  write_datetime(value: datetime) → None

    Convert the given `datetime` to a `ULONG` using the same algorithm C# uses, then write it to `stream`.

    Parameters:

      value – The `datetime` to write.