litematica-render 0.1.0__py3-none-any.whl

litematic/__init__.py

@@ -0,0 +1,34 @@
+"""litematic - read-only parser for Minecraft Litematica .litematic schematics.
+
+Instances are not thread-safe: parse and query a Litematic from a single
+thread or asyncio task at a time.
+"""
+
+from litematic.parse.errors import LitematicError, LitematicFormatError, NbtError
+from litematic.parse.model import (
+    BlockEntity,
+    BlockState,
+    Entity,
+    Litematic,
+    LitematicMetadata,
+    Region,
+    Vec3i,
+)
+from litematic.parse.parser import load, loads
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BlockEntity",
+    "BlockState",
+    "Entity",
+    "Litematic",
+    "LitematicError",
+    "LitematicFormatError",
+    "LitematicMetadata",
+    "NbtError",
+    "Region",
+    "Vec3i",
+    "load",
+    "loads",
+]

litematic/parse/__init__.py

@@ -0,0 +1 @@
+"""Parsing core: NBT reading, data model, and .litematic decoding."""

litematic/parse/errors.py

@@ -0,0 +1,13 @@
+"""Public exception tree for litematic."""
+
+
+class LitematicError(Exception):
+    """Base class for all exceptions raised by this library."""
+
+
+class NbtError(LitematicError):
+    """Input is not valid Java NBT: bad tag type, truncated stream, bad compression."""
+
+
+class LitematicFormatError(LitematicError):
+    """Input is valid NBT but violates the .litematic structure constraints."""

litematic/parse/model.py

@@ -0,0 +1,225 @@
+"""Read-only data model: metadata, block states, and lazily materialized regions."""
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Callable, Mapping, NamedTuple, Optional, Sequence
+
+import numpy as np
+
+
+class Vec3i(NamedTuple):
+    """A 3D integer vector (x, y, z)."""
+
+    x: int
+    y: int
+    z: int
+
+
+@dataclass(frozen=True)
+class BlockState:
+    """A palette entry: block id plus blockstate properties."""
+
+    name: str
+    properties: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "properties", MappingProxyType(dict(self.properties))
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.name, frozenset(self.properties.items())))
+
+
+@dataclass(frozen=True)
+class LitematicMetadata:
+    """Schematic-level metadata from the Metadata compound."""
+
+    name: str
+    author: str
+    description: str
+    enclosing_size: Vec3i
+    total_blocks: int
+    total_volume: int
+    time_created: int
+    time_modified: int
+    MinecraftDataVersion: int
+    LitematicVersion: int
+
+
+@dataclass(frozen=True)
+class BlockEntity:
+    """A tile entity: position, id, and its raw NBT payload as a plain mapping.
+
+    The mapping is read-only at the top level only; nested compounds
+    (a chest's items, for example) stay mutable dicts.
+    """
+
+    pos: tuple[int, int, int]
+    id: str
+    data: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class Entity:
+    """An entity: id, position, and its raw NBT payload as a plain mapping.
+
+    The mapping is read-only at the top level only; nested compounds
+    stay mutable dicts.
+    """
+
+    id: str
+    pos: tuple[float, float, float]
+    data: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class Litematic:
+    """A parsed schematic: metadata plus named regions.
+
+    `regions` is exposed as a read-only mapping.
+    """
+
+    metadata: LitematicMetadata
+    regions: Mapping[str, "Region"]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "regions", MappingProxyType(self.regions))
+
+
+class Region:
+    """One schematic region.
+
+    Block data is kept in packed form; `block_indices` materializes it on
+    first access and caches the result until `release()`.
+    `pending_block_ticks`/`pending_fluid_ticks` are sequences of scheduled-tick
+    compounds ({x, y, z, Time, Priority, Block or Fluid, SubTick}), retained
+    verbatim (semantics defined by the writing Litematica version).
+    Not thread-safe.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        position: Vec3i,
+        size: Vec3i,
+        palette: Sequence[BlockState],
+        block_entities: tuple[BlockEntity, ...],
+        entities: tuple[Entity, ...],
+        pending_block_ticks: Optional[tuple[Mapping[str, object], ...]],
+        pending_fluid_ticks: Optional[tuple[Mapping[str, object], ...]],
+        packed_indices: np.ndarray,
+        _unpack: Callable[[], np.ndarray],
+        _unpack_slab: Optional[Callable[[int, int], np.ndarray]] = None,
+    ) -> None:
+        self._name = name
+        self._position = position
+        self._size = size
+        self._palette = tuple(palette)
+        self._block_entities = block_entities
+        self._entities = entities
+        self._pending_block_ticks = pending_block_ticks
+        self._pending_fluid_ticks = pending_fluid_ticks
+        # Read-only view: the caller keeps ownership of the array it passed.
+        packed = packed_indices.view()
+        packed.flags.writeable = False
+        self._packed_indices = packed
+        self._unpack = _unpack
+        self._unpack_slab = _unpack_slab
+        self._indices: Optional[np.ndarray] = None
+
+    @property
+    def name(self) -> str:
+        """Region name as written in the file."""
+        return self._name
+
+    @property
+    def position(self) -> Vec3i:
+        """Min corner in schematic coordinates (negative sizes normalized)."""
+        return self._position
+
+    @property
+    def size(self) -> Vec3i:
+        """Region extents along x, y, z; always positive."""
+        return self._size
+
+    @property
+    def palette(self) -> tuple[BlockState, ...]:
+        """Block states addressable by the values in `block_indices`."""
+        return self._palette
+
+    @property
+    def block_entities(self) -> tuple[BlockEntity, ...]:
+        """Tile entities (chests, signs, spawners, ...) in this region."""
+        return self._block_entities
+
+    @property
+    def entities(self) -> tuple[Entity, ...]:
+        """Entities (mobs, items, item frames, ...) in this region."""
+        return self._entities
+
+    @property
+    def pending_block_ticks(self) -> Optional[tuple[Mapping[str, object], ...]]:
+        """Scheduled block ticks, one compound per tick; None if absent."""
+        return self._pending_block_ticks
+
+    @property
+    def pending_fluid_ticks(self) -> Optional[tuple[Mapping[str, object], ...]]:
+        """Scheduled fluid ticks, one compound per tick; None if absent."""
+        return self._pending_fluid_ticks
+
+    @property
+    def packed_indices(self) -> np.ndarray:
+        """The raw packed BlockStates long array, read-only."""
+        return self._packed_indices
+
+    @property
+    def is_unpacked(self) -> bool:
+        """Whether `block_indices` is currently materialized."""
+        return self._indices is not None
+
+    @property
+    def block_indices(self) -> np.ndarray:
+        """Palette indices as a read-only (x, y, z) array; materializes lazily."""
+        if self._indices is None:
+            indices = self._unpack()
+            indices.flags.writeable = False
+            self._indices = indices
+        return self._indices
+
+    def slab_indices(self, y0: int, y1: int) -> np.ndarray:
+        """Palette indices for rows [y0, y1), shape (x, y1-y0, z); not cached.
+
+        Unpacks only the slab's contiguous entry span of the packed stream
+        when the parser injected a slab unpacker, so callers can stream a
+        region without ever materializing `block_indices`.
+        """
+        if not (0 <= y0 < y1 <= self._size.y):
+            raise IndexError(
+                f"Slab rows out of range: [{y0}, {y1}) for size {self._size}"
+            )
+        if self._unpack_slab is not None:
+            arr = self._unpack_slab(y0, y1)
+        else:
+            arr = np.ascontiguousarray(self.block_indices[:, y0:y1, :])
+        arr.flags.writeable = False
+        return arr
+
+    def get_block(self, x: int, y: int, z: int) -> BlockState:
+        """Return the block state at local coordinates (x, y, z).
+
+        Out-of-range coordinates are a caller bug and raise IndexError;
+        file corruption raises LitematicFormatError on first unpack.
+        """
+        size_x, size_y, size_z = self._size
+        if not (0 <= x < size_x and 0 <= y < size_y and 0 <= z < size_z):
+            raise IndexError(
+                f"Block coordinates out of range: ({x}, {y}, {z})"
+                f" for size {self._size}"
+            )
+        index = int(self.block_indices[x, y, z])
+        return self._palette[index]
+
+    def release(self) -> None:
+        """Drop the materialized `block_indices` cache to reclaim memory."""
+        self._indices = None

litematic/parse/nbt.py

@@ -0,0 +1,167 @@
+"""Minimal Java NBT reader: streaming gzip, big-endian, arrays decoded to numpy."""
+
+import gzip
+import io
+import struct
+import zlib
+from typing import Protocol
+
+import numpy as np
+
+from litematic.parse.errors import NbtError
+
+_GZIP_MAGIC = b"\x1f\x8b"
+
+# 256 levels is far beyond any real schematic and costs 2 stack frames per
+# level, staying safely under CPython's default recursion limit of 1000
+_MAX_DEPTH = 256
+
+_TAG_END = 0
+_TAG_BYTE = 1
+_TAG_SHORT = 2
+_TAG_INT = 3
+_TAG_LONG = 4
+_TAG_FLOAT = 5
+_TAG_DOUBLE = 6
+_TAG_BYTE_ARRAY = 7
+_TAG_STRING = 8
+_TAG_LIST = 9
+_TAG_COMPOUND = 10
+_TAG_INT_ARRAY = 11
+_TAG_LONG_ARRAY = 12
+
+_ARRAY_DTYPES = {
+    _TAG_BYTE_ARRAY: (">i1", 1, np.int8),
+    _TAG_INT_ARRAY: (">i4", 4, np.int32),
+    _TAG_LONG_ARRAY: (">i8", 8, np.int64),
+}
+
+_SCALARS = {
+    _TAG_BYTE: (">b", 1),
+    _TAG_SHORT: (">h", 2),
+    _TAG_INT: (">i", 4),
+    _TAG_LONG: (">q", 8),
+    _TAG_FLOAT: (">f", 4),
+    _TAG_DOUBLE: (">d", 8),
+}
+
+
+def _decode_java_utf8(data: bytes) -> str:
+    """Decode Java's modified UTF-8 (DataOutput.writeUTF): U+0000 as the
+    overlong sequence C0 80, supplementary characters as CESU-8 surrogate pairs."""
+    if b"\xc0\x80" in data:
+        data = data.replace(b"\xc0\x80", b"\x00")
+    try:
+        text = data.decode("utf-8", errors="surrogatepass")
+        if any("\ud800" <= ch <= "\udfff" for ch in text):
+            text = text.encode("utf-16", "surrogatepass").decode("utf-16")
+        return text
+    except UnicodeDecodeError as exc:
+        raise NbtError(f"Invalid UTF-8 in NBT string: {exc}") from exc
+
+
+class _Readable(Protocol):
+    """The only stream capability the reader relies on."""
+
+    def read(self, size: int = -1) -> bytes: ...
+
+
+class _Reader:
+    """Reads an NBT stream sequentially. Any short read raises NbtError."""
+
+    __slots__ = ("_stream",)
+
+    def __init__(self, stream: _Readable) -> None:
+        self._stream = stream
+
+    def read_root(self) -> dict:
+        root_tag = self.u8()
+        if root_tag != _TAG_COMPOUND:
+            raise NbtError(f"Root tag must be TAG_Compound, got type {root_tag}")
+        self.string()  # root tag name is discarded
+        return self._compound(0)
+
+    def _read(self, size: int) -> bytes:
+        data = self._stream.read(size)
+        if len(data) != size:
+            raise NbtError(
+                f"NBT stream truncated: needed {size} bytes, got {len(data)}"
+            )
+        return data
+
+    def u8(self) -> int:
+        return self._read(1)[0]
+
+    def string(self) -> str:
+        length = struct.unpack(">H", self._read(2))[0]
+        return _decode_java_utf8(self._read(length))
+
+    def payload(self, tag: int, depth: int = 0) -> object:
+        scalar = _SCALARS.get(tag)
+        if scalar is not None:
+            fmt, size = scalar
+            return struct.unpack(fmt, self._read(size))[0]
+        if tag == _TAG_STRING:
+            return self.string()
+        array = _ARRAY_DTYPES.get(tag)
+        if array is not None:
+            return self._array(*array)
+        if tag == _TAG_LIST:
+            return self._list(depth)
+        if tag == _TAG_COMPOUND:
+            return self._compound(depth)
+        raise NbtError(f"Unknown tag type {tag}")
+
+    def _array(self, endian_dtype: str, item_size: int, native: type) -> np.ndarray:
+        length = self._i32()
+        if length < 0:
+            raise NbtError(f"Negative array length: {length}")
+        buf = self._read(length * item_size)
+        return np.frombuffer(buf, dtype=endian_dtype).astype(native)
+
+    def _list(self, depth: int) -> list:
+        self._check_depth(depth)
+        element_tag = self.u8()
+        length = self._i32()
+        if length < 0:
+            raise NbtError(f"Negative list length: {length}")
+        if element_tag == _TAG_END:
+            if length:
+                raise NbtError("TAG_List element type is End but length is non-zero")
+            return []
+        return [self.payload(element_tag, depth + 1) for _ in range(length)]
+
+    def _compound(self, depth: int) -> dict:
+        self._check_depth(depth)
+        out: dict = {}
+        while True:
+            tag = self.u8()
+            if tag == _TAG_END:
+                return out
+            name = self.string()
+            out[name] = self.payload(tag, depth + 1)
+
+    def _check_depth(self, depth: int) -> None:
+        if depth >= _MAX_DEPTH:
+            raise NbtError(f"NBT nesting deeper than {_MAX_DEPTH} levels")
+
+    def _i32(self) -> int:
+        return struct.unpack(">i", self._read(4))[0]
+
+
+def read_nbt(data: bytes) -> dict:
+    """Parse gzip-compressed or raw Java NBT and return the root compound payload.
+
+    Compound -> dict, List -> list, string -> str, scalars -> int/float;
+    the three array kinds -> native-endian numpy arrays owning their memory.
+    """
+    stream: _Readable
+    if data[:2] == _GZIP_MAGIC:
+        stream = gzip.GzipFile(fileobj=io.BytesIO(data))
+    else:
+        stream = io.BytesIO(data)
+    reader = _Reader(stream)
+    try:
+        return reader.read_root()
+    except (OSError, EOFError, zlib.error) as exc:
+        raise NbtError(f"Failed to decompress NBT: {exc}") from exc