nnnotes 0.1.0__py3-none-any.whl

nnnotes/atoms/mesh.py

@@ -0,0 +1,289 @@
+"""Atom `mesh.arrays`: every vertex channel, the primitives and the skin of a Mesh (or a Sprite's render mesh).
+
+The input (`MeshInput`, made by a reader) carries the vertex and index buffers as stored. Vertex buffers of Unity
+2018.2 and later are decoded here: channel formats (VertexFormat; VertexFormat2017 before 2019) and dimensions come
+from the channel table, streams are laid out as Unity lays them (each stream's vertices packed, streams 16-byte
+aligned). A channel keeps its stored component type and its dimension (the low four bits of the stored dimension
+byte: a normal stored as four half floats has 4 float16 components); UNorm / SNorm channels are marked normalized.
+The stored channel table, dimension bytes included, is kept in `MeshArrays.layout`. Meshes of other layouts (older
+versions, compressed meshes) come already decoded by the reader (`MeshInput.decoded`, UnityPy's MeshHandler).
+
+Primitives: one per submesh, with the submesh's indices plus its baseVertex. Triangle lists are (n, 3) arrays in
+Unity's winding; quads become two triangles each and triangle strips a triangle list (degenerate triangles dropped,
+every other triangle's winding swapped), as UnityPy's MeshHandler.get_triangles does; lines, line strips and points
+stay what they are. A mesh without an index buffer has one `points` primitive without indices (every vertex).
+
+Skin: the BlendIndices / BlendWeight channels as four joints and four weights per vertex (unused slots 0); bind
+poses, bone name hashes and the root bone hash as serialized. What this atom does not convert is listed in
+`MeshArrays.issues` as (reason code, message): skins with more than four weights per vertex or inconsistent
+channels (`partial.mesh.skin`), blend shapes (`unsupported.mesh.blendshapes`).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from . import Unsupported, estimate
+
+# channel index (Unity 2018 and later) -> name
+CHANNELS = ("position", "normal", "tangent", "color", "uv0", "uv1", "uv2", "uv3", "uv4", "uv5", "uv6", "uv7",
+            "blendWeight", "blendIndices")
+# vertex format -> (numpy dtype, normalized)
+FORMATS_2019 = {0: ("<f4", False), 1: ("<f2", False), 2: ("u1", True), 3: ("i1", True), 4: ("<u2", True),
+                5: ("<i2", True), 6: ("u1", False), 7: ("i1", False), 8: ("<u2", False), 9: ("<i2", False),
+                10: ("<u4", False), 11: ("<i4", False)}
+FORMATS_2017 = {0: ("<f4", False), 1: ("<f2", False), 2: ("u1", True), 3: ("u1", True), 4: ("i1", True),
+                5: ("<u2", True), 6: ("<i2", True), 7: ("u1", False), 8: ("i1", False), 9: ("<u2", False),
+                10: ("<i2", False), 11: ("<u4", False), 12: ("<i4", False)}
+TOPOLOGIES = {0: "triangles", 1: "triangle_strip", 2: "quads", 3: "lines", 4: "line_strip", 5: "points"}
+RAW_LAYOUT_SINCE = (2018, 2)
+
+
+@dataclass(frozen=True)
+class Submesh:
+    first_byte: int
+    index_count: int
+    topology: int = 0
+    base_vertex: int = 0
+    first_vertex: int = 0
+    vertex_count: int = 0
+
+
+@dataclass(frozen=True)
+class MeshInput:
+    """A mesh as stored. `channels`: the channel table ((stream, offset, format, dimension) per channel index),
+    `vertex_data` the vertex buffer (the streamed resource data when the mesh streams it); `index_buffer` raw bytes
+    of `index_bits`-bit indices, or a sequence of ints when the reader decoded it; `decoded`: {channel name:
+    (array (vertices, components), normalized)} for meshes whose buffers the reader decoded; `bind_poses`:
+    Matrix4x4f typetrees (e00 .. e33)."""
+    name: str
+    version: tuple
+    vertex_count: int
+    channels: tuple = ()
+    vertex_data: bytes = b""
+    index_buffer: object = b""
+    index_bits: int = 16
+    submeshes: tuple = ()
+    decoded: dict | None = None
+    bind_poses: tuple = ()
+    bone_name_hashes: tuple = ()
+    root_bone_name_hash: int | None = None
+    blend_shapes: int = 0
+    variable_bone_weights: int = 0
+
+
+@dataclass
+class Channel:
+    data: np.ndarray                  # (vertices, components), the stored component type
+    normalized: bool = False          # integers standing for [0, 1] (unsigned) or [-1, 1] (signed)
+
+    def as_float(self) -> np.ndarray:
+        """The values as float32 (normalized integers dequantized as Unity does: v / max, signed clamped to -1)."""
+        a = self.data
+        if a.dtype.kind == "f":
+            return a.astype(np.float32)
+        if not self.normalized:
+            return a.astype(np.float32)
+        top = float(np.iinfo(a.dtype).max)
+        f = a.astype(np.float64) / top
+        return (np.maximum(f, -1.0) if a.dtype.kind == "i" else f).astype(np.float32)
+
+
+@dataclass
+class Primitive:
+    topology: str                     # triangles | lines | line_strip | points
+    indices: np.ndarray | None        # triangles (n, 3), others flat; absolute vertex indices; None: every vertex
+    submesh: int | None = None        # submesh index (None: the mesh has no index buffer)
+
+
+@dataclass
+class Skin:
+    joints: np.ndarray                # (vertices, 4) uint16
+    weights: Channel                  # (vertices, 4)
+
+
+@dataclass
+class MeshArrays:
+    name: str
+    vertex_count: int
+    channels: dict = field(default_factory=dict)       # name -> Channel, in channel order
+    primitives: list = field(default_factory=list)
+    submeshes: list = field(default_factory=list)      # Submesh per submesh, as stored
+    skin: Skin | None = None
+    bind_poses: np.ndarray = field(default_factory=lambda: np.zeros((0, 4, 4), np.float32))  # row-major, Unity space
+    bone_name_hashes: list = field(default_factory=list)
+    root_bone_name_hash: int | None = None
+    layout: list = field(default_factory=list)         # the stored channel table (vertex buffers decoded here)
+    issues: list = field(default_factory=list)         # (reason code, message)
+
+
+def _formats(version: tuple) -> dict:
+    return FORMATS_2019 if tuple(version)[:1] >= (2019,) else FORMATS_2017
+
+
+def decode_vertex_data(inp: MeshInput) -> dict:
+    """{channel name: Channel} of a Unity 2018.2+ vertex buffer."""
+    if tuple(inp.version)[:2] < RAW_LAYOUT_SINCE:
+        raise ValueError(f"mesh {inp.name!r}: vertex layout of Unity {inp.version[:2]} is decoded by the reader")
+    count = int(inp.vertex_count)
+    if not count or not inp.channels:
+        return {}
+    formats = _formats(inp.version)
+    chans = []
+    for i, (stream, offset, fmt, dim) in enumerate(inp.channels):
+        dim = int(dim) & 0xF
+        if not dim:
+            continue
+        if i >= len(CHANNELS):
+            raise ValueError(f"mesh {inp.name!r}: channel {i} of {len(inp.channels)}")
+        if int(fmt) not in formats:
+            raise ValueError(f"mesh {inp.name!r}: channel {CHANNELS[i]}: vertex format {fmt}")
+        dtype, norm = formats[int(fmt)]
+        chans.append((i, int(stream), int(offset), np.dtype(dtype), norm, dim))
+    streams, pos = {}, 0
+    for s in range(1 + max(int(c[0]) for c in inp.channels)):
+        stride = sum(dt.itemsize * dim for _, st, _, dt, _, dim in chans if st == s)
+        streams[s] = (pos, stride)
+        pos = (pos + count * stride + 15) & ~15
+    raw = np.frombuffer(bytes(inp.vertex_data), np.uint8)
+    out = {}
+    for i, s, offset, dt, norm, dim in chans:
+        start, stride = streams[s]
+        end = start + count * stride
+        if end > raw.size or offset + dt.itemsize * dim > stride:
+            raise ValueError(f"mesh {inp.name!r}: channel {CHANNELS[i]} outside the vertex data "
+                             f"({raw.size} bytes, stream {s} ends at {end})")
+        cols = raw[start:end].reshape(count, stride)[:, offset:offset + dt.itemsize * dim]
+        values = np.ascontiguousarray(cols).view(dt).reshape(count, dim)
+        out[CHANNELS[i]] = Channel(values.astype(dt.newbyteorder("=")), norm)
+    return out
+
+
+def _indices(inp: MeshInput) -> np.ndarray:
+    ib = inp.index_buffer
+    if isinstance(ib, (bytes, bytearray, memoryview)):
+        if inp.index_bits not in (16, 32):
+            raise ValueError(f"mesh {inp.name!r}: {inp.index_bits}-bit indices")
+        return np.frombuffer(bytes(ib), "<u2" if inp.index_bits == 16 else "<u4").astype(np.int64)
+    return np.asarray(list(ib), np.int64)
+
+
+def _strip(idx: np.ndarray) -> np.ndarray:
+    tris = []
+    for i in range(len(idx) - 2):
+        a, b, c = (int(x) for x in idx[i:i + 3])
+        if a == b or a == c or b == c:
+            continue
+        tris.append((b, a, c) if i & 1 else (a, b, c))
+    return np.asarray(tris, np.int64).reshape(-1, 3)
+
+
+def _primitives(inp: MeshInput, count: int) -> list[Primitive]:
+    idx = _indices(inp)
+    if not idx.size or not inp.submeshes:
+        return [Primitive("points", None)]
+    per = 2 if inp.index_bits == 16 else 4
+    prims = []
+    for n, sm in enumerate(inp.submeshes):
+        first = int(sm.first_byte) // per
+        part = idx[first:first + int(sm.index_count)]
+        if len(part) != int(sm.index_count):
+            raise ValueError(f"mesh {inp.name!r}: submesh {n} indices {first}..{first + sm.index_count} of "
+                             f"{len(idx)}")
+        topology = TOPOLOGIES.get(int(sm.topology or 0))
+        if topology is None:
+            raise ValueError(f"mesh {inp.name!r}: submesh {n} topology {sm.topology}")
+        if topology == "triangles":
+            if len(part) % 3:
+                raise ValueError(f"mesh {inp.name!r}: submesh {n}: {len(part)} triangle indices")
+            part = part.reshape(-1, 3)
+        elif topology == "triangle_strip":
+            part, topology = _strip(part), "triangles"
+        elif topology == "quads":
+            if len(part) % 4:
+                raise ValueError(f"mesh {inp.name!r}: submesh {n}: {len(part)} quad indices")
+            q = part.reshape(-1, 4)
+            part, topology = np.stack([q[:, [0, 1, 2]], q[:, [0, 2, 3]]], 1).reshape(-1, 3), "triangles"
+        part = part + int(sm.base_vertex or 0)
+        if part.size and (part.min() < 0 or part.max() >= count):
+            raise ValueError(f"mesh {inp.name!r}: submesh {n} index {int(part.max())} of {count} vertices")
+        prims.append(Primitive(topology, part, n))
+    return prims
+
+
+def _skin(channels: dict, inp: MeshInput, issues: list) -> Skin | None:
+    ix, w = channels.get("blendIndices"), channels.get("blendWeight")
+    if inp.variable_bone_weights:
+        issues.append(("partial.mesh.skin", f"{inp.variable_bone_weights} variable bone count weights (more than "
+                                            f"four bones per vertex) not converted; four per vertex kept"))
+    if ix is None:
+        if w is not None:
+            issues.append(("partial.mesh.skin", "BlendWeight without BlendIndices"))
+        return None
+    count, k = ix.data.shape
+    if w is None:
+        if k != 1:
+            issues.append(("partial.mesh.skin", f"{k} BlendIndices per vertex without BlendWeight"))
+            return None
+        weights = Channel(np.zeros((count, 4), np.float32))
+        weights.data[:, 0] = 1.0
+    else:
+        if w.data.shape[1] != k:
+            issues.append(("partial.mesh.skin", f"{w.data.shape[1]} BlendWeight / {k} BlendIndices per vertex"))
+            return None
+        wd = np.zeros((count, 4), w.data.dtype)
+        wd[:, :k] = w.data
+        weights = Channel(wd, w.normalized)
+    if ix.data.dtype.kind == "f" or (ix.data.size and (ix.data.min() < 0 or ix.data.max() > 0xFFFF)):
+        issues.append(("partial.mesh.skin", "BlendIndices outside 0..65535"))
+        return None
+    joints = np.zeros((count, 4), np.uint16)
+    joints[:, :k] = ix.data
+    return Skin(joints, weights)
+
+
+def _matrix(m: dict) -> list:
+    return [[m[f"e{r}{c}"] for c in range(4)] for r in range(4)]
+
+
+def arrays(inp: MeshInput) -> MeshArrays:
+    count = int(inp.vertex_count)
+    if inp.decoded is not None:
+        channels = {}
+        for name in CHANNELS:
+            if name in inp.decoded:
+                data, norm = inp.decoded[name]
+                a = np.asarray(data)
+                a = a.reshape(len(a), -1) if a.ndim == 1 and count and a.size == count else a
+                if a.ndim != 2 or a.shape[0] != count:
+                    raise ValueError(f"mesh {inp.name!r}: decoded {name} shape {a.shape} for {count} vertices")
+                channels[name] = Channel(a, bool(norm))
+    else:
+        channels = decode_vertex_data(inp)
+    issues: list = []
+    out = MeshArrays(inp.name, count, channels, _primitives(inp, count) if count else [], list(inp.submeshes),
+                     _skin(channels, inp, issues), bone_name_hashes=[int(h) for h in inp.bone_name_hashes],
+                     root_bone_name_hash=inp.root_bone_name_hash, issues=issues)
+    if inp.decoded is None:
+        out.layout = [{"channel": CHANNELS[i] if i < len(CHANNELS) else str(i), "stream": int(st),
+                       "offset": int(off), "format": int(fmt), "dimension": int(dim)}
+                      for i, (st, off, fmt, dim) in enumerate(inp.channels) if int(dim) & 0xF]
+    if inp.bind_poses:
+        out.bind_poses = np.asarray([_matrix(m) for m in inp.bind_poses], np.float32).reshape(-1, 4, 4)
+    if inp.blend_shapes:
+        issues.append(("unsupported.mesh.blendshapes", f"{inp.blend_shapes} blend shapes not converted"))
+    return out
+
+
+def require_vertices(m: MeshArrays) -> None:
+    """Unsupported (`empty.mesh`) for a mesh without vertices."""
+    if not m.vertex_count or "position" not in m.channels:
+        raise Unsupported("empty.mesh", f"mesh {m.name!r} has no vertices")
+
+
+def cost(facts: dict) -> dict:
+    """facts: vertexCount, indexCount, vertexBytes."""
+    v, i = int(facts.get("vertexCount", 0)), int(facts.get("indexCount", 0))
+    vb = int(facts.get("vertexBytes", v * 48))
+    return estimate(2e-5 + v * 1e-7 + i * 2e-8, vb * 4 + i * 16)

nnnotes/atoms/png.py

@@ -0,0 +1,28 @@
+"""Atom `png.encode`: PNG bytes of a PIL image, written by Pillow.
+
+Level 6 (the default) gives the bytes Pillow writes without options (`image.save(f, "PNG")`), which the other
+commands write for textures; other levels (0-9) change the bytes, never the pixels.
+"""
+from __future__ import annotations
+
+import io
+
+from . import estimate
+
+DEFAULT_LEVEL = 6
+
+
+def encode(image, level: int = DEFAULT_LEVEL) -> bytes:
+    """PNG bytes of `image` (any mode Pillow writes as PNG) at zlib level `level`."""
+    if not isinstance(level, int) or isinstance(level, bool) or not 0 <= level <= 9:
+        raise ValueError(f"PNG level {level!r}: expected 0-9")
+    buf = io.BytesIO()
+    image.save(buf, format="PNG", compress_level=level)
+    return buf.getvalue()
+
+
+def cost(facts: dict) -> dict:
+    """facts: width, height, channels (default 4), level (default 6)."""
+    raw = int(facts.get("width", 0)) * int(facts.get("height", 0)) * int(facts.get("channels", 4))
+    per_byte = {0: 1e-9, 1: 4e-9, 2: 4e-9, 3: 5e-9}.get(int(facts.get("level", DEFAULT_LEVEL)), 1.2e-8)
+    return estimate(5e-5 + raw * per_byte, raw * 2)

nnnotes/atoms/reader.py

@@ -0,0 +1,269 @@
+"""Atom `reader`: one bundle's serialized files, objects and the inputs of the other atoms.
+
+`BundleView` is what a stage reads a bundle through; `UnityBundle` is the reference implementation (UnityPy, the
+bundle loaded alone from its bytes: references into other bundles are not followed, resource files inside the
+bundle -- `.resS` -- are read). Objects are named by `ObjectInfo` (serialized file name and path id), never by
+library objects, so another implementation can stand in.
+
+`texture_input` and `mesh_input` collect exactly what `texture.decode` and `mesh.arrays` need: a Texture2D's image
+data (the streamed resource data when it is streamed), size, format, Unity version, build target and platform blob;
+a Mesh's (or a Sprite's render data's) vertex buffer, channel table, index buffer and submeshes as stored. Meshes of
+layouts `mesh.arrays` does not decode itself (compressed meshes, Unity before 2018.2) are decoded here by UnityPy's
+MeshHandler.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from . import estimate
+from .mesh import CHANNELS, RAW_LAYOUT_SINCE, MeshInput, Submesh
+from .texture import TextureInput
+from .. import contract
+
+
+@dataclass(frozen=True)
+class ObjectInfo:
+    file: str                       # serialized file name (CAB-...)
+    path_id: int
+    class_id: int
+    class_name: str
+    byte_size: int
+    type_hash: str | None = None    # the type's stored hash (hex), None when the file does not store it
+
+    @property
+    def id(self) -> str:
+        return contract.object_id(self.file, self.path_id)
+
+
+class BundleView(Protocol):
+    def files(self) -> list[str]:
+        """Serialized file names, in bundle order."""
+
+    def objects(self) -> list[ObjectInfo]:
+        """Every object, file by file in bundle order, each file's objects in stored order."""
+
+    def raw(self, obj: ObjectInfo) -> bytes:
+        """The object's serialized bytes."""
+
+    def typetree(self, obj: ObjectInfo) -> dict:
+        """The object read through its typetree, fields in stored order."""
+
+    def container(self) -> list[tuple[str, str, int]]:
+        """(container path, serialized file, path id) of every container entry, in stored order."""
+
+    def externals(self, file: str) -> list[str]:
+        """The paths of a serialized file's externals (PPtr file id i names externals[i - 1])."""
+
+    def unity_version(self, file: str) -> str:
+        """The Unity version a serialized file was written by."""
+
+    def texture_input(self, obj: ObjectInfo) -> TextureInput:
+        ...
+
+    def mesh_input(self, obj: ObjectInfo) -> MeshInput:
+        ...
+
+
+def _bytes(v) -> bytes:
+    return v if isinstance(v, bytes) else bytes(v or b"")
+
+
+def _file_name(path: str) -> str:
+    """The serialized file an external path names (archive:/CAB-x/CAB-x -> CAB-x)."""
+    return path.replace("\\", "/").rsplit("/", 1)[-1]
+
+
+def submeshes(tt_submeshes) -> tuple:
+    return tuple(Submesh(int(s["firstByte"]), int(s["indexCount"]), int(s.get("topology", 0) or 0),
+                         int(s.get("baseVertex", 0) or 0), int(s.get("firstVertex", 0) or 0),
+                         int(s.get("vertexCount", 0) or 0))
+                 for s in tt_submeshes or ())
+
+
+def mesh_input_from_typetree(tt: dict, version: tuple, resource=None) -> MeshInput:
+    """MeshInput of a Mesh typetree (or a Sprite typetree: its m_RD) of a Unity 2018.2+ file. `resource(path,
+    offset, size)` reads streamed vertex data (m_StreamData)."""
+    sprite = "m_RD" in tt
+    src = tt["m_RD"] if sprite else tt
+    vd = src["m_VertexData"]
+    data = _bytes(vd.get("m_DataSize"))
+    stream = None if sprite else tt.get("m_StreamData")
+    if stream and stream.get("path"):
+        if resource is None:
+            raise ValueError(f"mesh {tt.get('m_Name')!r}: streamed vertex data and no resource reader")
+        data = resource(stream["path"], int(stream["offset"]), int(stream["size"]))
+    if sprite:
+        bits = 16
+    elif "m_Use16BitIndices" in tt:
+        bits = 16 if tt["m_Use16BitIndices"] else 32
+    else:
+        bits = 32 if tt.get("m_IndexFormat", 0) == 1 else 16
+    shapes = tt.get("m_Shapes")
+    n_shapes = len(shapes.get("channels", ()) or shapes.get("shapes", ())) if isinstance(shapes, dict) else 0
+    vbw = tt.get("m_VariableBoneCountWeights")
+    return MeshInput(
+        name=tt.get("m_Name", ""), version=tuple(version), vertex_count=int(vd.get("m_VertexCount", 0)),
+        channels=tuple((int(c["stream"]), int(c["offset"]), int(c["format"]), int(c["dimension"]))
+                       for c in vd.get("m_Channels") or ()),
+        vertex_data=data, index_buffer=_bytes(src.get("m_IndexBuffer")), index_bits=bits,
+        submeshes=submeshes(src.get("m_SubMeshes")),
+        bind_poses=tuple(src.get("m_Bindpose" if sprite else "m_BindPose") or ()),
+        bone_name_hashes=() if sprite else tuple(tt.get("m_BoneNameHashes") or ()),
+        root_bone_name_hash=None if sprite else tt.get("m_RootBoneNameHash"),
+        blend_shapes=n_shapes, variable_bone_weights=len((vbw or {}).get("m_Data") or ()))
+
+
+def needs_handler(tt: dict, version: tuple) -> bool:
+    """True when UnityPy's MeshHandler decodes the mesh (older layouts, compressed meshes)."""
+    if tuple(version)[:2] < RAW_LAYOUT_SINCE:
+        return True
+    cm = tt.get("m_CompressedMesh")
+    return bool(cm) and int(cm["m_Vertices"]["m_NumItems"]) > 0
+
+
+_HANDLER_FIELDS = {"position": "m_Vertices", "normal": "m_Normals", "tangent": "m_Tangents", "color": "m_Colors",
+                   **{f"uv{i}": f"m_UV{i}" for i in range(8)}, "blendWeight": "m_BoneWeights",
+                   "blendIndices": "m_BoneIndices"}
+
+
+def handler_input(src, tt: dict, version: tuple) -> MeshInput:
+    """MeshInput decoded by UnityPy's MeshHandler from `src` (a Mesh object, or a Sprite's m_RD)."""
+    import numpy as np
+    from UnityPy.helpers.MeshHelper import MeshHandler
+    h = MeshHandler(src, tuple(version))
+    h.process()
+    decoded = {}
+    for name in CHANNELS:
+        values = getattr(h, _HANDLER_FIELDS[name], None)
+        if not values:
+            continue
+        a = np.asarray(values)
+        if a.dtype.kind in "iu":
+            a = a.astype(np.uint32 if name == "blendIndices" else np.uint8)
+            decoded[name] = (a, name != "blendIndices")
+        else:
+            decoded[name] = (a.astype(np.float32), False)
+    base = mesh_input_from_typetree({**tt, "m_StreamData": None} if "m_RD" not in tt else tt, version)
+    ib = h.m_IndexBuffer
+    return MeshInput(
+        name=base.name, version=base.version, vertex_count=int(h.m_VertexCount or 0), decoded=decoded,
+        index_buffer=[] if not ib else list(ib) if not isinstance(ib, (bytes, bytearray)) else bytes(ib),
+        index_bits=16 if h.m_Use16BitIndices else 32, submeshes=base.submeshes, bind_poses=base.bind_poses,
+        bone_name_hashes=base.bone_name_hashes, root_bone_name_hash=base.root_bone_name_hash,
+        blend_shapes=base.blend_shapes, variable_bone_weights=base.variable_bone_weights)
+
+
+def _resource(assets_file, path: str, offset: int, size: int) -> bytes:
+    """`size` bytes at `offset` of the resource file `path` (a .resS / .resource inside the same bundle). Unlike
+    UnityPy's own lookup, nothing outside the loaded bundle is searched."""
+    import ntpath
+    base = ntpath.basename(path)
+    stem = ntpath.splitext(base)[0]
+    env = assets_file.environment
+    for name in (base, f"{stem}.resource", f"{stem}.assets.resS", f"{stem}.resS"):
+        reader = env.get_cab(name)
+        if reader is not None:
+            reader.Position = offset
+            data = reader.read_bytes(size)
+            if len(data) != size:
+                raise ValueError(f"resource {base}: {len(data)} of {size} bytes at {offset}")
+            return bytes(data)
+    raise FileNotFoundError(f"resource file {base} is not in the bundle")
+
+
+class UnityBundle:
+    """BundleView of a UnityPy environment holding one bundle (open_bundle loads it from the bundle's bytes)."""
+
+    def __init__(self, env):
+        self.env = env
+        self._files = {f.name: f for f in self.env.assets}
+        self._readers: dict[tuple[str, int], object] = {}
+        self._infos: list[ObjectInfo] = []
+        for name, f in self._files.items():
+            for pid, r in f.objects.items():
+                st = r.serialized_type
+                h = getattr(st, "old_type_hash", None) if st is not None else None
+                self._readers[(name, pid)] = r
+                self._infos.append(ObjectInfo(name, int(pid), int(r.class_id), r.type.name, int(r.byte_size),
+                                              h.hex() if h else None))
+
+    def _reader(self, obj: ObjectInfo):
+        return self._readers[(obj.file, obj.path_id)]
+
+    def reader(self, obj: ObjectInfo):
+        """The library's object reader of `obj` (UnityPy's ObjectReader), for code that works on library objects."""
+        return self._readers[(obj.file, obj.path_id)]
+
+    def files(self) -> list[str]:
+        return list(self._files)
+
+    def objects(self) -> list[ObjectInfo]:
+        return list(self._infos)
+
+    def raw(self, obj: ObjectInfo) -> bytes:
+        return self._reader(obj).get_raw_data()
+
+    def typetree(self, obj: ObjectInfo) -> dict:
+        return self._reader(obj).read_typetree()
+
+    def container(self) -> list[tuple[str, str, int]]:
+        out = []
+        for name, f in self._files.items():
+            for path, info in f.container.container:
+                pptr = info.asset
+                fid = int(pptr.m_FileID)
+                target = name if fid == 0 else _file_name(f.externals[fid - 1].path)
+                out.append((path, target, int(pptr.m_PathID)))
+        return out
+
+    def externals(self, file: str) -> list[str]:
+        return [e.path for e in self._files[file].externals]
+
+    def unity_version(self, file: str) -> str:
+        f = self._files[file]
+        v = getattr(f, "unity_version", None)
+        return v if isinstance(v, str) else ".".join(str(x) for x in f.version)
+
+    def texture_input(self, obj: ObjectInfo) -> TextureInput:
+        r = self._reader(obj)
+        tex = r.read()
+        w, h = int(tex.m_Width), int(tex.m_Height)
+        blob = getattr(tex, "m_PlatformBlob", None)
+        # the arguments UnityPy's Texture2D.image passes to parse_image_data (as export._decode_inputs); a texture
+        # without pixels has no image data to read
+        data = b""
+        if w and h:
+            stream = getattr(tex, "m_StreamData", None)
+            if tex.image_data:
+                data = bytes(tex.image_data)
+            elif stream is not None and stream.path:
+                data = _resource(r.assets_file, stream.path, int(stream.offset), int(stream.size))
+            else:
+                raise ValueError(f"{obj.id}: texture without image data")
+        return TextureInput(data, w, h, int(tex.m_TextureFormat), tuple(getattr(r, "version", (0, 0, 0, 0))),
+                            int(getattr(r, "platform", 0) or 0), None if blob is None else bytes(blob))
+
+    def mesh_input(self, obj: ObjectInfo) -> MeshInput:
+        r = self._reader(obj)
+        if obj.class_name not in ("Mesh", "Sprite"):
+            raise TypeError(f"{obj.id}: {obj.class_name} has no mesh")
+        tt = r.read_typetree()
+        version = tuple(r.version)
+        if needs_handler(tt, version):
+            o = r.read()
+            return handler_input(o.m_RD if obj.class_name == "Sprite" else o, tt, version)
+        return mesh_input_from_typetree(tt, version, lambda path, offset, size: _resource(r.assets_file, path,
+                                                                                           offset, size))
+
+
+def open_bundle(data: bytes) -> UnityBundle:
+    """The BundleView of a bundle's bytes (decrypted UnityFS), loaded alone."""
+    from ..unity import load_bytes
+    return UnityBundle(load_bytes(bytes(data)))
+
+
+def cost(facts: dict) -> dict:
+    """facts: size (bundle bytes), objects (count)."""
+    size, n = int(facts.get("size", 0)), int(facts.get("objects", 0))
+    return estimate(0.01 + size * 1.5e-8 + n * 1.2e-4, 7e7 + size * 8)