🛠️ Core

Abstract core classes for reading and writing binary formats.

BaseFile

Binary stream adapter for file-like sources.

Wraps any binary source (file path, bytes, or IO stream) into a unified interface for reading and writing structured binary data.

class BaseFile(stream, mode='rb')

Bases: StructIO, ABC

Unified binary stream handler.

format: FileFormat = ''

Associated file format.

signature: Optional[bytes] = None

Expected file signature.

options: Options

Shared handlers options.

property suffix: str

property location: str

property closed: bool

size()

Return type:

int

read(size=-1)

Return type:

bytes

write(data)

Return type:

int

seek(pos, whence=0)

Change the stream position to the given byte offset.

offset

The stream position, relative to ‘whence’.

whence

The relative position to seek from.

The offset is interpreted relative to the position indicated by whence. Values for whence are:

• os.SEEK_SET or 0 – start of stream (the default); offset should be zero or positive

• os.SEEK_CUR or 1 – current stream position; offset may be negative

• os.SEEK_END or 2 – end of stream; offset is usually negative

Return the new absolute position.

Return type:

int

skip(size)

tell()

Return current stream position.

Return type:

int

readable()

Return whether object was opened for reading.

If False, read() will raise OSError.

Return type:

bool

writable()

Return whether object was opened for writing.

If False, write() will raise OSError.

Return type:

bool

seekable()

Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

Return type:

bool

flush()

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

Return type:

None

close()

Flush and close the IO object.

This method has no effect if the file is already closed.

Return type:

None

getvalue()

Return type:

bytes

is_eof()

Return type:

bool

Content

Shared content data containers for handlers. Defines data structures that hold parsed file contents.

class BaseContent(type=FileType.NONE)

Bases: ABC

Base class for file content types.

type: FileType = 'none'

reset()

class ModelContent(type=FileType.MODEL, version=0.0, flags=<factory>, scene=<factory>)

Bases: BaseContent

Content container for 3D models.

type: FileType = 'model'

version: float = 0.0

flags: dict[Flag, bool]

scene: ModelScene

class TextureContent(type=FileType.TEXTURE, width=0, height=0, mipmap_count=0, format=<factory>, texture=<factory>)

Bases: BaseContent, Generic[TextureType]

Content container for textures (2D or cubemap).

type: FileType = 'texture'

width: int = 0

height: int = 0

mipmap_count: int = 0

format: bytes

texture: TypeVar(TextureType, bound= Texture)

property is_cubemap: bool

property is_compressed: bool

property fourcc: bytes

class ImageContent(type=FileType.IMAGE, image=<factory>)

Bases: BaseContent

Content container for images.

type: FileType = 'image'

image: bytes

class TexarrContent(type=FileType.TEXARR, count=0, textures=<factory>)

Bases: BaseContent

Content container for texture arrays.

type: FileType = 'texarr'

count: int = 0

textures: list[tuple[str, bytes]]

class NbtContent(type=FileType.NBT, value=None)

Bases: BaseContent

Content container for NBT (Named Binary Tag) data.

type: FileType = 'nbt'

value: None | int | float | bytes | str | list[int] | list[None | int | float | bytes | str | list[int] | list[NbtValue] | dict[str, NbtValue]] | dict[str, None | int | float | bytes | str | list[int] | list[NbtValue] | dict[str, NbtValue]] = None

class RegionContent(type=FileType.REGION, rx=0, rz=0, offsets=<factory>, counts=<factory>, uuid=<factory>, chunks=<factory>)

Bases: BaseContent

Content container for regions (world terrain).

type: FileType = 'region'

rx: int = 0

rz: int = 0

offsets: list[int]

counts: list[int]

uuid: list[UUID]

chunks: list[RegionChunk]

Decoder

Base class for file format decoders.

Defines the contract for parsing binary data into structured content.

class FileDecoder(stream, options=None)

Bases: BaseFile, Generic[ContentType], ABC

Base class for decoding binary data into structured content.

Subclasses define format-specific parsing logic.

decode(seek=True)

Runs decoding pipeline.

Parameters:

seek (bool) – Reset stream position to the beginning after parsing.

Return type:

TypeVar(ContentType, bound= BaseContent)

Returns:

Parsed content data.

convert_to(encoder, options=None, output=None)

Decode and convert to given encoder format.

Parameters:

• encoder (Type[TypeVar(EncoderType, bound= FileEncoder)]) – Encoder class to use for conversion.

• options (optional) – Shared handlers options.

• output (optional) – File path or binary IO stream. Defaults to in-memory buffer.

Return type:

TypeVar(EncoderType, bound= FileEncoder)

Returns:

Clear encoder instance.

convert(encoder, options=None, output=None)

Decode and convert to given encoder format.

Parameters:

• encoder (Type[TypeVar(EncoderType, bound= FileEncoder)]) – Encoder class to use for conversion.

• options (optional) – Shared handlers options.

• output (optional) – File path or binary IO stream. Defaults to in-memory buffer.

Return type:

bytes

Returns:

Encoded file content as bytes.

prelude()

Hook called before signature and parsing.

Return type:

None

abstractmethod parse()

Parse file content into self.data. Called by decode().

Return type:

None

validate_signature()

Validate file signature.

Raises:

EmptyFileError –

Return type:

None

Encoder

Base class for file format encoders.

Defines the contract for serializing structured content into binary data.

class FileEncoder(data, options=None, output=None)

Bases: BaseFile, Generic[ContentType], ABC

Base class for encoding structured content into binary data.

Subclasses define the format-specific serialization logic.

transforms: Optional[list[Callable[[ModelScene], ModelScene]]] = None

Format-specific transforms applied to model data before serialization.

encode(transforms=None)

Runs encoding pipeline.

Parameters:

transforms (Optional[list[Callable[[ModelScene], ModelScene]]]) – Override the default transforms for this call.

Return type:

Self

Returns:

Self (chaining).

prelude()

Hook called before transforms, signature and serialization.

Return type:

None

transform(transforms=None)

Apply format-specific transforms to model data.

add_signature()

Write the format signature to the output stream.

Return type:

None

abstractmethod serialize()

Write self.data to the output stream. Called by encode().

Return type:

None

save_as(path, mode='wb')

Write encoded data to file by name. Keeps encoder open.

Parameters:

• path (str | Path | PathLike[str]) – Output file path.

• mode (Literal['rb', 'rb+', 'wb', 'wb+', 'ab', 'ab+']) – File mode (binary).

Return type:

Self

export_as(path, mode='wb')

Write encoded data to file by stem. Format suffix appended. Keeps the encoder open.

Parameters:

• path (str | Path | PathLike[str]) – Output file path.

• mode (Literal['rb', 'rb+', 'wb', 'wb+', 'ab', 'ab+']) – File mode (binary).

Return type:

Self

save(path, mode='wb')

Write encoded data to file by name. Closes encoder.

Parameters:

• path (str | Path | PathLike[str]) – Output file path.

• mode (Literal['rb', 'rb+', 'wb', 'wb+', 'ab', 'ab+']) – File mode (binary).

Return type:

None

export(path, mode='wb')

Write encoded data to file by stem. Format suffix appended. Closes encoder.

Parameters:

• path (str | Path | PathLike[str]) – Output file path.

• mode (Literal['rb', 'rb+', 'wb', 'wb+', 'ab', 'ab+']) – File mode (binary).

Return type:

None

getvalue()

Return type:

bytes

Options

Shared options for handlers.

class Options(model_formats=None, skeleton=False, animation=False, raw_blocks=False, full_chunk=False, on_conflict='overwrite')

Shared handlers options.

model_formats: Optional[Sequence[FileFormat]] = None

Preferred output formats for models, default_model_formats() used on unset.

skeleton: bool = False

Handle skeleton bones from models.

animation: bool = False

Handle built-in animation clips from models.

raw_blocks: bool = False

Keep raw block IDs in chunks without lookup table replacement.

full_chunk: bool = False

Handle full chunk data including metadata (no export).

on_conflict: Literal['overwrite', 'rename', 'skip'] = 'overwrite'

Action on output file name conflict (if already exists).

• “overwrite” Replace the existing file.

• “skip” Keep the existing file.

• “rename” Add a numeric suffix (e.g. model (1).obj).

property default_model_formats: Sequence[FileFormat]

Default output formats for models based on current options.

StructIO

Low-level binary I/O with structured packing and unpacking operations.

Provides a base class for reading and writing binary data in various formats using struct and numpy. Designed to be subclassed by format-specific I/O classes.

class StructIO

Bases: IOBase

Base class for structured binary I/O.

Extends io.IOBase with methods for packed binary operations. Subclasses must implement io.IOBase interface.

order: ByteOrder = '<'

Default byte order for pack/unpack operations.

unicode_errors: str = 'replace'

Error handling mode for UTF-8 encoding/decoding.