PyREUser3 0.1.0__py3-none-any.whl

pyreuser3/export/user3.py

@@ -0,0 +1,415 @@
+"""完整 `.user.3` 文件结构解析逻辑。
+
+本模块按 RE Engine 的物理布局读取 ``.user.3``：先解析 USR 头与可选的外部
+用户数据路径表，再读取内嵌 RSZ 块的头部、对象表、实例表和用户数据表，最后
+逐个解析实例数据段。解析结果既可用于构造可读紧凑树，也可转成可稳定回封的
+完整实例表 JSON。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..core import BinaryReader, PACK_JSON_FORMAT, ParseError, align
+
+
+class ExporterUser3ParserMixin:
+    """负责读取 USR/RSZ 头、实例表和根对象列表。"""
+
+    def _parse_user3_document(self, user3_path: Path) -> dict[str, Any]:
+        """解析完整 `.user.3` 文件并保留实例表级中间结果。
+
+        参数：
+            user3_path (Path): 源 ``.user.3`` 文件路径。
+
+        返回：
+            dict[str, Any]: 解析文档，含 USR/RSZ 头、根对象编号、实例元数据、
+            已解析实例、实例编号映射以及用户数据引用等键，供后续构造紧凑树或
+            封包 JSON 使用。
+
+        异常：
+            ParseError: 当 USR 或 RSZ magic 不匹配时抛出。
+        """
+        reader = BinaryReader(user3_path.read_bytes())
+
+        # `.user.3` 最外层是 USR 头，magic 可由用户覆盖以兼容不同游戏。
+        magic = reader.read_u32()
+        if magic != self.user_magic:
+            raise ParseError(f"not a user file: magic={magic}")
+
+        usr_header = {
+            "signature": magic,
+            "resource_count": reader.read_s32(),
+            "userdata_count": reader.read_s32(),
+            "info_count": reader.read_s32(),
+            "resource_info_tbl": reader.read_u64(),
+            "userdata_info_tbl": reader.read_u64(),
+            "data_offset": reader.read_u64(),
+        }
+        header_userdata_infos: list[dict[str, Any]] = []
+        if usr_header["userdata_count"] > 0 and usr_header["userdata_info_tbl"] > 0:
+            try:
+                # 部分文件在 USR 头中带有外部 userdata 路径表。
+                reader.seek(usr_header["userdata_info_tbl"])
+                for idx in range(usr_header["userdata_count"]):
+                    class_hash = reader.read_u32()
+                    _crc = reader.read_u32()
+                    path_offset = reader.read_u64()
+                    class_name = (
+                        self.typedb.get_class(class_hash).name
+                        if self.typedb.get_class(class_hash)
+                        else "Unknown Class"
+                    )
+                    header_userdata_infos.append(
+                        {
+                            "index": idx,
+                            "class_hash": class_hash,
+                            "class_name": class_name,
+                            "path": reader.read_wstring_null(path_offset),
+                        }
+                    )
+            except Exception:
+                # 路径表解析失败不影响主 RSZ 数据块，降级为空列表。
+                header_userdata_infos = []
+
+        rsz_start = usr_header["data_offset"]
+
+        # 数据偏移指向内嵌 RSZ 块；后续偏移大多是相对 RSZ 起点。
+        reader.seek(rsz_start)
+        rsz_header = {
+            "magic": reader.read_u32(),
+            "version": reader.read_u32(),
+            "object_count": reader.read_s32(),
+            "instance_count": reader.read_s32(),
+            "userdata_count": reader.read_s32(),
+            "reserved": reader.read_s32(),
+            "instance_offset": reader.read_s64(),
+            "data_offset": reader.read_s64(),
+            "userdata_offset": reader.read_s64(),
+        }
+        if rsz_header["magic"] != self.rsz_magic:
+            raise ParseError(
+                f"RSZ magic mismatch at data_offset: {rsz_header['magic']}"
+            )
+
+        # 对象表保存根对象实例编号，是构造最终 JSON 根节点的首选来源。
+        reader.seek(rsz_start + 48)
+        object_table = [
+            reader.read_s32() for _i in range(max(rsz_header["object_count"], 0))
+        ]
+        object_table_set = set(object_table)
+
+        instance_infos: list[dict[str, Any]] = []
+        reader.seek(rsz_start + rsz_header["instance_offset"])
+        for idx in range(max(rsz_header["instance_count"], 0)):
+            # 实例表只保存类型哈希和 CRC，真正字段数据在数据偏移后连续存放。
+            class_hash = reader.read_u32()
+            crc = reader.read_u32()
+            class_def = self.typedb.get_class(class_hash)
+            instance_infos.append(
+                {
+                    "index": idx,
+                    "hash": class_hash,
+                    "class_name": class_def.name if class_def else "Unknown Class",
+                    "crc": crc,
+                    "is_object": idx in object_table_set,
+                }
+            )
+        instance_info_map = {item["index"]: item for item in instance_infos}
+
+        rsz_userdata_instance_ids: list[int] = []
+        rsz_userdata_path_by_instance: dict[int, str] = {}
+        if rsz_header["userdata_count"] > 0 and rsz_header["userdata_offset"] > 0:
+            try:
+                # RSZ 用户数据表表示对其他用户数据文件的引用。
+                reader.seek(rsz_start + rsz_header["userdata_offset"])
+                for _i in range(rsz_header["userdata_count"]):
+                    instance_id = reader.read_s32()
+                    _type_hash = reader.read_u32()
+                    path_offset = reader.read_u64()
+                    if instance_id >= 0:
+                        rsz_userdata_instance_ids.append(instance_id)
+                        path = ""
+                        if path_offset > 0 and rsz_start + path_offset < reader.size:
+                            path = reader.read_wstring_null(rsz_start + path_offset)
+                        rsz_userdata_path_by_instance[instance_id] = path
+            except Exception:
+                # 用户数据表异常时仍尝试解析内联实例，避免整文件失败。
+                rsz_userdata_instance_ids = []
+                rsz_userdata_path_by_instance = {}
+        rsz_userdata_instance_set = set(rsz_userdata_instance_ids)
+
+        parsed_instances: list[dict[str, Any]] = []
+        reader.seek(rsz_start + rsz_header["data_offset"])
+        for idx, info in enumerate(instance_infos):
+            class_hash = int(info["hash"])
+            if idx == 0:
+                # RSZ 实例 0 是固定空槽，引用 0 表示空引用。
+                parsed_instances.append(
+                    {
+                        "index": idx,
+                        "class_name": info["class_name"],
+                        "note": "null instance slot",
+                    }
+                )
+                continue
+            if idx in rsz_userdata_instance_set:
+                # 外部用户数据引用不在当前数据段内展开，只记录路径和实例编号。
+                parsed_instances.append(
+                    {
+                        "index": idx,
+                        "class_name": info["class_name"],
+                        "is_userdata_reference": True,
+                        "path": rsz_userdata_path_by_instance.get(idx, ""),
+                    }
+                )
+                continue
+            cls = self.typedb.get_class(class_hash)
+            if cls is None:
+                # 模板不认识的类型无法解析字段，但保留元数据方便定位。
+                parsed_instances.append(
+                    {
+                        "index": idx,
+                        "class_name": info["class_name"],
+                        "unparsed": True,
+                        "reason": "class_not_found_in_schema",
+                    }
+                )
+                continue
+            if cls.fields:
+                first = cls.fields[0]
+                # 实例数据没有显式尺寸，读取前按首字段对齐来同步游标。
+                reader.seek(
+                    align(reader.tell(), 4 if first.is_array else max(first.align, 1))
+                )
+            start_pos = reader.tell()
+            try:
+                parsed_instances.append(
+                    {"index": idx, "data": self._parse_instance(reader, class_hash)}
+                )
+            except Exception as exc:
+                # 某个实例解析失败时，尽量按估算最小尺寸跳过，继续解析后续实例。
+                parsed_instances.append(
+                    {
+                        "index": idx,
+                        "class_name": info["class_name"],
+                        "unparsed": True,
+                        "reason": str(exc),
+                    }
+                )
+                min_skip = self._estimate_min_instance_size(cls)
+                next_pos = min(reader.size, start_pos + min_skip)
+                if next_pos <= start_pos:
+                    break
+                reader.seek(next_pos)
+
+        idx_map = {
+            inst["index"]: inst
+            for inst in parsed_instances
+            if isinstance(inst.get("index"), int)
+        }
+        object_roots = sorted(
+            set(i for i in object_table if isinstance(i, int) and i >= 0)
+        )
+        if not object_roots:
+            # 某些文件对象表为空，需要从引用关系推断根节点。
+            object_roots = self._infer_roots_when_object_table_empty(
+                idx_map, parsed_instances
+            )
+        if not object_roots and rsz_userdata_instance_ids:
+            # 如果只存在用户数据引用，也可把这些引用作为根节点导出。
+            object_roots = sorted(
+                set(
+                    i
+                    for i in rsz_userdata_instance_ids
+                    if i in instance_info_map and i > 0
+                )
+            )
+        if not object_roots:
+            # 最后兜底：导出所有非空实例，保证信息尽可能不丢失。
+            object_roots = sorted(i for i in instance_info_map.keys() if i > 0)
+
+        return {
+            "user3_path": user3_path,
+            "usr_header": usr_header,
+            "rsz_header": rsz_header,
+            "object_roots": object_roots,
+            "instance_infos": instance_infos,
+            "instance_info_map": instance_info_map,
+            "parsed_instances": parsed_instances,
+            "idx_map": idx_map,
+            "header_userdata_infos": header_userdata_infos,
+            "rsz_userdata_instance_ids": rsz_userdata_instance_ids,
+            "rsz_userdata_path_by_instance": rsz_userdata_path_by_instance,
+        }
+
+    def _parse_user3(self, user3_path: Path) -> list[dict[str, Any]]:
+        """解析完整 `.user.3` 文件并构造成紧凑对象树。
+
+        参数：
+            user3_path (Path): 源 ``.user.3`` 文件路径。
+
+        返回：
+            list[dict[str, Any]]: 以类名包裹的紧凑对象树列表；只含头部用户数据
+            信息的文件则返回可读的引用列表。
+        """
+        document = self._parse_user3_document(user3_path)
+        parsed_instances = document["parsed_instances"]
+        object_roots = document["object_roots"]
+        instance_info_map = document["instance_info_map"]
+        idx_map = document["idx_map"]
+        header_userdata_infos = document["header_userdata_infos"]
+        # depth 为 "auto" 时根据复杂度自动决定，否则使用用户指定的固定深度。
+        depth = (
+            self._auto_pick_tree_depth(parsed_instances, object_roots)
+            if self.tree_depth == "auto"
+            else self.tree_depth
+        )
+        object_trees = [
+            # 从根实例开始展开引用，生成更适合人工修改的嵌套 JSON。
+            self._build_compact_tree(
+                root_idx,
+                idx_map,
+                depth=depth,
+                instance_info_map=instance_info_map,
+            )
+            for root_idx in object_roots
+            if root_idx in instance_info_map
+        ]
+        if not object_trees and header_userdata_infos:
+            # 对只包含头部用户数据信息的文件，仍返回可读的引用列表。
+            return [
+                {
+                    item["class_name"]: {
+                        "ref_instance_id": item["index"],
+                        "path": item["path"],
+                    }
+                }
+                for item in header_userdata_infos
+            ]
+        return object_trees
+
+    def _parse_user3_pack(self, user3_path: Path) -> dict[str, Any]:
+        """解析 `.user.3` 并返回适合稳定封包的完整实例表 JSON。
+
+        参数：
+            user3_path (Path): 源 ``.user.3`` 文件路径。
+
+        返回：
+            dict[str, Any]: 完整实例表封包文档（见 :meth:`_build_pack_json`）。
+        """
+        return self._build_pack_json(self._parse_user3_document(user3_path))
+
+    def _build_pack_json(self, document: dict[str, Any]) -> dict[str, Any]:
+        """把解析中间结果转换为完整实例表文档。
+
+        参数：
+            document (dict[str, Any]): :meth:`_parse_user3_document` 返回的解析文档。
+
+        返回：
+            dict[str, Any]: 封包格式文档，含 ``_format``、``_version``、``_source``、
+            ``_roots``、``_instances``、``_userdata``、``_unsupported``、``_warnings``
+            等键；其中 ``_unsupported`` 记录当前写回器尚不支持的原始数据段。
+        """
+        instances: dict[str, Any] = {}
+        warnings: list[str] = []
+        unsupported: list[str] = []
+        idx_map = document["idx_map"]
+        path_by_userdata = document["rsz_userdata_path_by_instance"]
+        usr_header = document["usr_header"]
+        rsz_header = document["rsz_header"]
+
+        # 记录当前最小写回器无法重建的原始数据段，封包阶段据此拒绝有损回封。
+        if int(usr_header.get("resource_count", 0)) > 0:
+            unsupported.append("USR resource table")
+        if int(usr_header.get("userdata_count", 0)) > 0:
+            unsupported.append("USR userdata table")
+        if int(usr_header.get("info_count", 0)) > 0:
+            unsupported.append("USR info table")
+        if int(rsz_header.get("userdata_count", 0)) > 0:
+            unsupported.append("RSZ userdata table")
+
+        for info in document["instance_infos"]:
+            idx = int(info["index"])
+            class_hash = int(info["hash"])
+            crc = int(info["crc"])
+            entry: dict[str, Any] = {
+                "_class": info.get("class_name"),
+                "_hash": self._format_hex_u32(class_hash),
+                "_crc": self._format_hex_u32(crc),
+            }
+            inst = idx_map.get(idx)
+            if idx == 0:
+                # 实例 0 是固定空槽，标记为 null 即可。
+                entry["_class"] = None
+                entry["_kind"] = "null"
+            elif inst is None:
+                entry["_unparsed"] = True
+                entry["reason"] = "missing parsed instance"
+                warnings.append(f"instance {idx} is missing from parsed data")
+            elif inst.get("is_userdata_reference"):
+                entry["_kind"] = "userdata_reference"
+                entry["path"] = path_by_userdata.get(idx, inst.get("path", ""))
+                warnings.append(
+                    f"instance {idx} is an external userdata reference and "
+                    "cannot be rebuilt by the current minimal writer"
+                )
+            elif inst.get("unparsed"):
+                entry["_unparsed"] = True
+                entry["reason"] = inst.get("reason", "unparsed")
+                warnings.append(
+                    f"instance {idx} ({entry.get('_class')}) is unparsed: "
+                    f"{entry['reason']}"
+                )
+            else:
+                data = inst.get("data", {})
+                class_name = data.get("_class") or entry.get("_class")
+                entry["_class"] = class_name
+                fields = data.get("fields", {})
+                if not isinstance(fields, dict):
+                    fields = {}
+                # 字段同样经过枚举后处理，使封包 JSON 中的枚举也呈现可读标签。
+                entry["fields"] = self._postprocess_enum_nodes(
+                    fields,
+                    current_class=class_name if isinstance(class_name, str) else None,
+                )
+            instances[str(idx)] = entry
+
+        return {
+            "_format": PACK_JSON_FORMAT,
+            "_version": 1,
+            "_source": {
+                "file": str(document["user3_path"]),
+                "user_magic": self._format_hex_u32(self.user_magic),
+                "rsz_magic": self._format_hex_u32(self.rsz_magic),
+                "schema": str(self.schema_path),
+                "resource_count": int(usr_header.get("resource_count", 0)),
+                "userdata_count": int(usr_header.get("userdata_count", 0)),
+                "info_count": int(usr_header.get("info_count", 0)),
+                "rsz_userdata_count": int(rsz_header.get("userdata_count", 0)),
+            },
+            "_roots": document["object_roots"],
+            "_instances": instances,
+            "_userdata": [
+                {
+                    "instance_id": int(instance_id),
+                    "path": path_by_userdata.get(instance_id, ""),
+                }
+                for instance_id in document["rsz_userdata_instance_ids"]
+            ],
+            "_unsupported": unsupported,
+            "_warnings": warnings,
+        }
+
+    @staticmethod
+    def _format_hex_u32(value: int) -> str:
+        """把 32 位整数格式化为稳定的十六进制字符串。
+
+        参数：
+            value (int): 待格式化的整数（按无符号 32 位截断）。
+
+        返回：
+            str: 形如 ``0x0012abcd`` 的 8 位小写十六进制字符串。
+        """
+        return f"0x{value & 0xFFFFFFFF:08x}"

pyreuser3/pack/__init__.py

@@ -0,0 +1,10 @@
+"""封包功能子包。
+
+这个子包负责把项目导出的 JSON 数据重新写回 `.user.3` 二进制格式。
+内部会先规划实例表、字符串表和资源引用，再按 RE_RSZ 模板写入字段。
+"""
+
+from .base import User3Packer
+from .models import PackError
+
+__all__ = ["PackError", "User3Packer"]