PyREUser3 0.1.0__py3-none-any.whl

pyreuser3/pack/writer.py

@@ -0,0 +1,313 @@
+"""RSZ/USR 二进制写回逻辑。
+
+写入阶段消费规划阶段产出的实例列表，按 RE Engine 物理布局拼出字节：先连续
+写入各实例数据段，再写 RSZ 头、对象表、实例表，最后包上最小 USR 头。字段值
+按类型写入，并兼容枚举标签/成员名、原始字节回写等多种来源。
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from typing import Any
+
+from .models import BinaryWriter, InstanceRef, PackError, StructValue
+from ..core import align
+from ..schema import FieldDef
+
+# 匹配导出格式 `[123] MemberName`，用于从枚举标签中取出括号内数值。
+ENUM_LABEL_RE = re.compile(r"^\[(-?\d+)\]\s*(.*)$")
+
+
+class PackerWriterMixin:
+    """负责把规划后的实例表编码成 `.user.3` 字节。"""
+
+    def _build_binary(self, root_ids: list[int]) -> bytes:
+        """构造完整 USR + RSZ 二进制内容。
+
+        参数：
+            root_ids (list[int]): 根实例编号列表，写入 RSZ 对象表。
+
+        返回：
+            bytes: 完整的 ``.user.3`` 二进制字节。
+        """
+        data_writer = BinaryWriter()
+        for spec in self.instances[1:]:
+            if spec is None:
+                continue
+            # 先连续写入所有实例的数据段，稍后再计算 RSZ 表偏移。
+            self._write_instance(data_writer, spec)
+
+        object_count = len(root_ids)
+        instance_count = len(self.instances)
+        # 对象表紧跟 48 字节 RSZ 头，实例表再随其后，数据段按 16 字节对齐。
+        instance_offset = 48 + object_count * 4
+        data_offset = align(instance_offset + instance_count * 8, 16)
+
+        rsz_writer = BinaryWriter()
+        # RSZ 头固定为 48 字节，偏移均相对 RSZ 块起点。
+        rsz_writer.write_struct(
+            "<IIiiiiqqq",
+            self.rsz_magic,
+            16,
+            object_count,
+            instance_count,
+            0,
+            0,
+            instance_offset,
+            data_offset,
+            data_offset,
+        )
+        for root_id in root_ids:
+            rsz_writer.write_struct("<i", root_id)
+        rsz_writer.pad_to(instance_offset)
+        # 实例 0 是空引用槽，对应哈希和 CRC 均为 0。
+        rsz_writer.write_struct("<II", 0, 0)
+        for spec in self.instances[1:]:
+            if spec is None:
+                continue
+            rsz_writer.write_struct("<II", spec.class_hash, spec.class_def.crc)
+        rsz_writer.pad_to(data_offset)
+        rsz_writer.write(bytes(data_writer.data))
+
+        usr_writer = BinaryWriter()
+        # 当前封包器生成最小 USR 头：资源表和用户数据表为空，数据偏移指向 RSZ。
+        usr_writer.write_struct("<IiiiQQQ", self.user_magic, 0, 0, 0, 0x30, 0x30, 0x30)
+        usr_writer.write(b"\x00" * 8)
+        usr_writer.write(bytes(rsz_writer.data))
+        return bytes(usr_writer.data)
+
+    def _write_instance(self, writer: BinaryWriter, spec: InstanceSpec) -> None:
+        """按模板字段顺序写入一个实例。
+
+        参数：
+            writer (BinaryWriter): 目标二进制写入器（数据段）。
+            spec (InstanceSpec): 规划好的实例规格。
+
+        返回：
+            None: 把实例数据写入 ``writer``。
+        """
+        for field_def in spec.class_def.fields:
+            # 数组字段按 4 字节对齐，普通字段按模板声明的对齐值对齐。
+            writer.align(4 if field_def.is_array else max(field_def.align, 1))
+            key = field_def.name or "unnamed"
+            self._write_field(writer, field_def, spec.fields.get(key))
+
+    def _write_field(
+        self, writer: BinaryWriter, field_def: FieldDef, value: Any
+    ) -> None:
+        """写入一个字段，自动处理数组和标量。
+
+        参数：
+            writer (BinaryWriter): 目标二进制写入器。
+            field_def (FieldDef): 字段定义。
+            value (Any): 字段的中间表示值。
+
+        返回：
+            None: 把字段数据写入 ``writer``。
+        """
+        if field_def.is_array:
+            items = value if isinstance(value, list) else []
+            writer.write_struct("<I", len(items))
+            non_array = FieldDef(
+                name=field_def.name,
+                field_type=field_def.field_type,
+                original_type=field_def.original_type,
+                size=field_def.size,
+                align=field_def.align,
+                is_array=False,
+            )
+            for item in items:
+                writer.align(max(field_def.align, 1))
+                # 数组元素不再写数组头，按非数组字段写入。
+                self._write_scalar(writer, non_array, item)
+            return
+        self._write_scalar(writer, field_def, value)
+
+    def _write_scalar(
+        self, writer: BinaryWriter, field_def: FieldDef, value: Any
+    ) -> None:
+        """按字段类型写入标量值。
+
+        参数：
+            writer (BinaryWriter): 目标二进制写入器。
+            field_def (FieldDef): 字段定义，决定写入格式与尺寸。
+            value (Any): 待写入的标量值（可能是数字、字符串、引用或保留原始字节的 dict）。
+
+        返回：
+            None: 把标量数据写入 ``writer``；无法识别的类型按声明尺寸补零。
+        """
+        t = field_def.field_type
+        if t == "Bool":
+            writer.write_struct("<B", 1 if bool(value) else 0)
+            return
+        if t == "S8":
+            writer.write_struct("<b", self._coerce_int(value, field_def))
+            return
+        if t == "U8":
+            writer.write_struct("<B", self._coerce_int(value, field_def) & 0xFF)
+            return
+        if t == "S16":
+            writer.write_struct("<h", self._coerce_int(value, field_def))
+            return
+        if t == "U16":
+            writer.write_struct("<H", self._coerce_int(value, field_def) & 0xFFFF)
+            return
+        if t in {"S32", "Enum", "Sfix"}:
+            writer.write_struct("<i", self._to_s32(self._coerce_int(value, field_def)))
+            return
+        if t == "U32":
+            writer.write_struct("<I", self._coerce_int(value, field_def) & 0xFFFFFFFF)
+            return
+        if t == "S64":
+            writer.write_struct("<q", self._coerce_int(value, field_def))
+            return
+        if t == "U64":
+            writer.write_struct(
+                "<Q", self._coerce_int(value, field_def) & 0xFFFFFFFFFFFFFFFF
+            )
+            return
+        if t == "F32":
+            writer.write_struct("<f", float(value or 0.0))
+            return
+        if t == "F64":
+            writer.write_struct("<d", float(value or 0.0))
+            return
+        if t in {"Object", "UserData"}:
+            # 对象字段最终只写入目标实例编号。
+            ref_id = (
+                value.index
+                if isinstance(value, InstanceRef)
+                else self._coerce_int(value, field_def)
+            )
+            writer.write_struct("<i", ref_id)
+            return
+        if t in {"String", "Resource"}:
+            # RE Engine 字符串保存长度前缀，并以 UTF-16LE 空字符结尾。
+            writer.align(4)
+            raw = f"{value or ''}\x00".encode("utf-16-le")
+            writer.write_struct("<I", len(raw) // 2)
+            writer.write(raw)
+            return
+        if t == "C8":
+            # C8 使用 UTF-8 字节长度，同样保留结尾空字符。
+            writer.align(4)
+            raw = f"{value or ''}\x00".encode("utf-8")
+            writer.write_struct("<I", len(raw))
+            writer.write(raw)
+            return
+        if t in {"Guid", "GameObjectRef", "Uri"}:
+            writer.write(uuid.UUID(str(value)).bytes_le)
+            return
+        if t == "Struct":
+            self._write_struct(writer, value)
+            return
+        if t in {
+            "Float2",
+            "Float3",
+            "Float4",
+            "Vec2",
+            "Vec3",
+            "Vec4",
+            "Quaternion",
+            "Color",
+            "AABB",
+            "Capsule",
+            "OBB",
+            "Mat3",
+            "Mat4",
+            "Position",
+        }:
+            # 向量/矩阵类型按 4 字节浮点元素写入，不足部分补 0。
+            values = value if isinstance(value, list) else []
+            count = max(field_def.size // 4, 1)
+            for i in range(count):
+                writer.write_struct("<f", float(values[i]) if i < len(values) else 0.0)
+            return
+        if isinstance(value, dict) and isinstance(value.get("raw"), str):
+            # 未知字段或未知结构体保留原始十六进制时，尽量原样写回。
+            writer.write(bytes.fromhex(value["raw"]))
+            return
+        # 仍无法识别时按声明尺寸补零，保证后续字段偏移不被破坏。
+        writer.write(b"\x00" * max(field_def.size, 0))
+
+    def _write_struct(self, writer: BinaryWriter, value: Any) -> None:
+        """写入结构体字段。
+
+        参数：
+            writer (BinaryWriter): 目标二进制写入器。
+            value (Any): 结构体值，应为 :class:`StructValue`；保留原始字节的 dict 也可。
+
+        返回：
+            None: 把结构体数据写入 ``writer``，并按声明尺寸补齐尾部填充。
+        """
+        if not isinstance(value, StructValue):
+            raw = value.get("raw") if isinstance(value, dict) else None
+            if isinstance(raw, str):
+                writer.write(bytes.fromhex(raw))
+            return
+        start = writer.tell()
+        for field_def in value.class_def.fields:
+            writer.align(4 if field_def.is_array else max(field_def.align, 1))
+            key = field_def.name or "unnamed"
+            self._write_field(writer, field_def, value.fields.get(key))
+        consumed = writer.tell() - start
+        if value.declared_size > consumed:
+            # 结构体实际字段小于声明尺寸时，需要补齐尾部填充。
+            writer.write(b"\x00" * (value.declared_size - consumed))
+
+    def _coerce_int(self, value: Any, field_def: FieldDef) -> int:
+        """把 JSON 值转换为整数，兼容枚举标签和成员名。
+
+        参数：
+            value (Any): JSON 值：布尔、整数、浮点或字符串（数字 / ``[值] 名称`` / 成员名）。
+            field_def (FieldDef): 字段定义，提供枚举成员反查所需的类型上下文。
+
+        返回：
+            int: 转换后的整数值。
+
+        异常：
+            PackError: 当值无法解析为整数且不是已知枚举成员名时抛出。
+        """
+        if isinstance(value, bool):
+            return int(value)
+        if isinstance(value, int):
+            return value
+        if isinstance(value, float):
+            return int(value)
+        if isinstance(value, str):
+            text = value.strip()
+            match = ENUM_LABEL_RE.match(text)
+            if match:
+                # 导出格式 `[123] MemberName` 优先使用括号内数值。
+                return int(match.group(1))
+            try:
+                return int(text, 0)
+            except ValueError:
+                # 如果不是数字字符串，再尝试按枚举成员名反查。
+                enum_value = self._resolve_enum_member(text, field_def)
+                if enum_value is not None:
+                    return enum_value
+        raise PackError(f"cannot convert {value!r} to int for field {field_def.name}")
+
+    def _resolve_enum_member(self, text: str, field_def: FieldDef) -> int | None:
+        """按字段类型上下文把枚举成员名解析成数值。
+
+        参数：
+            text (str): 枚举成员名。
+            field_def (FieldDef): 字段定义，其原始类型用于推断对应的固定枚举类型。
+
+        返回：
+            int | None: 命中时返回成员数值；无法解析时返回 ``None``。
+        """
+        candidates = []
+        original = field_def.original_type
+        if original.endswith("_Serializable"):
+            candidates.append(f"{original[:-13]}_Fixed")
+        if original.endswith("_Fixed"):
+            candidates.append(original)
+        for enum_type in candidates:
+            member_map = self.member_lookup.get(enum_type)
+            if member_map and text in member_map:
+                return member_map[text]
+        return None

pyreuser3/rich_ui.py

@@ -0,0 +1,126 @@
+"""基于 Rich 的批处理进度条和日志输出工具。
+
+提供一个全局共享的 Rich 控制台，以及把进度条固定在底部、日志滚动输出到上方的
+:class:`BatchProgress` 上下文管理器，供导出/封包批处理复用。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TaskID,
+    TextColumn,
+    TimeElapsedColumn,
+    TimeRemainingColumn,
+)
+
+# 全局唯一的 Rich 控制台，确保进度条与日志共享同一渲染区域。
+_CONSOLE = Console()
+
+
+def get_console() -> Console:
+    """返回命令行批处理共用的 Rich 控制台。
+
+    返回：
+        Console: 模块级单例 :class:`rich.console.Console` 实例。
+    """
+    return _CONSOLE
+
+
+class BatchProgress:
+    """让 Rich 进度条固定在底部，并把日志滚动输出到上方。
+
+    作为上下文管理器使用：进入时启动进度条并创建任务，退出时关闭进度条。
+    期间可通过 :meth:`log` 输出滚动日志、:meth:`update` 推进进度。
+    """
+
+    def __init__(self, description: str, total: int, unit: str = "file") -> None:
+        """初始化批处理进度条配置。
+
+        参数：
+            description (str): 进度条左侧显示的任务描述。
+            total (int): 任务总量，用于计算完成度和预计剩余时间。
+            unit (str): 计量单位文本（如 ``"file"``），仅用于展示。
+
+        返回：
+            None: 构造函数，仅准备 Rich 进度条对象（尚未启动）。
+        """
+        self.description = description
+        self.total = total
+        self.unit = unit
+        self.console = get_console()
+        # 预先组装进度条的各列：转轮、描述、进度条、计数、已用时和预计剩余时间。
+        self._progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            MofNCompleteColumn(),
+            TextColumn(unit),
+            TextColumn("elapsed"),
+            TimeElapsedColumn(),
+            TextColumn("eta"),
+            TimeRemainingColumn(),
+            console=self.console,
+            expand=True,
+            transient=False,
+        )
+        self._task_id: TaskID | None = None
+
+    def __enter__(self) -> "BatchProgress":
+        """进入上下文：启动进度条并创建任务。
+
+        返回：
+            BatchProgress: 自身，便于 ``with ... as progress`` 语法使用。
+        """
+        self._progress.__enter__()
+        self._task_id = self._progress.add_task(self.description, total=self.total)
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        """退出上下文：关闭进度条。
+
+        参数：
+            exc_type (Any): 异常类型（无异常时为 ``None``）。
+            exc (Any): 异常实例（无异常时为 ``None``）。
+            tb (Any): 异常回溯对象（无异常时为 ``None``）。
+
+        返回：
+            bool: 始终返回 ``False``，表示不吞掉上下文内发生的异常。
+        """
+        self._progress.__exit__(exc_type, exc, tb)
+        return False
+
+    def log(self, message: str, style: str | None = None) -> None:
+        """在实时进度条上方输出一行日志。
+
+        参数：
+            message (str): 日志文本。
+            style (str | None): 可选的 Rich 样式名（如 ``"green"`` / ``"red"``）。
+
+        返回：
+            None: 直接输出到共享控制台。
+        """
+        self.console.log(message, style=style)
+
+    def update(self, advance: int = 1, description: str | None = None) -> None:
+        """推进当前任务，并可同时更新底部进度条标签。
+
+        参数：
+            advance (int): 本次推进的进度量；传 0 可只更新描述不推进进度。
+            description (str | None): 可选的新任务描述；为 ``None`` 时保持不变。
+
+        返回：
+            None: 更新内部进度状态；尚未创建任务时直接返回。
+        """
+        if self._task_id is None:
+            return
+        kwargs: dict[str, Any] = {"advance": advance}
+        if description is not None:
+            kwargs["description"] = description
+        self._progress.update(self._task_id, **kwargs)

pyreuser3/schema.py

@@ -0,0 +1,193 @@
+"""RE_RSZ 模板类型数据库。
+
+本模块负责把外部的 RE_RSZ 模板 JSON 加载成内存中的类型索引，供导出器和
+封包器按类型哈希查找字段布局，并提供 RE_RSZ 类型名常用的 MurmurHash3 计算。
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def murmur3_32(data: bytes, seed: int = 0xFFFFFFFF) -> int:
+    """计算 RE_RSZ 类型名常用的 MurmurHash3 32 位哈希。
+
+    参数：
+        data (bytes): 输入字节，通常是 UTF-8 编码的类型名。
+        seed (int): 哈希种子，RE_RSZ 模板通常使用 ``0xFFFFFFFF``。
+
+    返回：
+        int: 32 位无符号哈希值（0 ~ 0xFFFFFFFF）。
+    """
+    c1 = 0xCC9E2D51
+    c2 = 0x1B873593
+    h1 = seed & 0xFFFFFFFF
+    length = len(data)
+    # 主体按 4 字节块处理，rounded_end 是最后一个完整块的结束位置。
+    rounded_end = length & ~0x3
+
+    # MurmurHash3 以 4 字节块为主体处理，尾部不足 4 字节再单独混合。
+    for i in range(0, rounded_end, 4):
+        k1 = int.from_bytes(data[i : i + 4], "little")
+        k1 = (k1 * c1) & 0xFFFFFFFF
+        k1 = ((k1 << 15) | (k1 >> 17)) & 0xFFFFFFFF
+        k1 = (k1 * c2) & 0xFFFFFFFF
+        h1 ^= k1
+        h1 = ((h1 << 13) | (h1 >> 19)) & 0xFFFFFFFF
+        h1 = (h1 * 5 + 0xE6546B64) & 0xFFFFFFFF
+
+    # 处理尾部 1-3 字节。这里严格保持小端序位移顺序。
+    k1 = 0
+    tail = data[rounded_end:]
+    if len(tail) == 3:
+        k1 ^= tail[2] << 16
+    if len(tail) >= 2:
+        k1 ^= tail[1] << 8
+    if len(tail) >= 1:
+        k1 ^= tail[0]
+        k1 = (k1 * c1) & 0xFFFFFFFF
+        k1 = ((k1 << 15) | (k1 >> 17)) & 0xFFFFFFFF
+        k1 = (k1 * c2) & 0xFFFFFFFF
+        h1 ^= k1
+
+    # 最终混合阶段把长度和高低位充分混合，得到最终 32 位结果。
+    h1 ^= length
+    h1 ^= h1 >> 16
+    h1 = (h1 * 0x85EBCA6B) & 0xFFFFFFFF
+    h1 ^= h1 >> 13
+    h1 = (h1 * 0xC2B2AE35) & 0xFFFFFFFF
+    h1 ^= h1 >> 16
+    return h1 & 0xFFFFFFFF
+
+
+@dataclass
+class FieldDef:
+    """RE_RSZ 模板中的字段定义。
+
+    描述一个类型内单个字段的二进制布局信息，是解析和封包时按类型读写
+    数据段的依据。
+
+    属性：
+        name (str): 字段名；模板中可能为空字符串。
+        field_type (str): 字段的逻辑类型（如 ``S32``、``String``、``Struct`` 等）。
+        original_type (str): 字段在游戏中的原始类型名，用于结构体/枚举推断。
+        size (int): 字段声明的字节尺寸。
+        align (int): 字段要求的对齐字节数。
+        is_array (bool): 是否为数组字段（数组带 4 字节长度前缀）。
+    """
+
+    name: str
+    field_type: str
+    original_type: str
+    size: int
+    align: int
+    is_array: bool
+
+
+@dataclass
+class ClassDef:
+    """RE_RSZ 模板中的类型定义。
+
+    属性：
+        name (str): 类型完整名称（通常含命名空间）。
+        crc (int): 类型的 CRC 校验值，写回 RSZ 实例表时需要。
+        fields (list[FieldDef]): 按声明顺序排列的字段列表。
+    """
+
+    name: str
+    crc: int
+    fields: list[FieldDef]
+
+
+class TypeDB:
+    """封装 RE_RSZ 模板中的类型索引。
+
+    内部以“类型哈希 -> 类型定义”为主索引，并额外维护“类型名 -> 哈希”的
+    反查表，供封包阶段从 JSON 中的类名还原出类型哈希。
+    """
+
+    def __init__(self, classes: dict[int, ClassDef]):
+        """初始化类型数据库。
+
+        参数：
+            classes (dict[int, ClassDef]): 以类型哈希为键、类型定义为值的映射。
+        """
+        self.classes = classes
+        # name_to_hash 用于封包时从 JSON 类名反查类型哈希。
+        self.name_to_hash = {c.name: h for h, c in classes.items()}
+
+    @classmethod
+    def load(cls, json_path: Path) -> "TypeDB":
+        """从 RE_RSZ 模板 JSON 读取并构建类型数据库。
+
+        参数：
+            json_path (Path): 模板 JSON 文件路径。
+
+        返回：
+            TypeDB: 已加载完毕、可供查询的类型数据库实例。
+        """
+        with json_path.open("r", encoding="utf-8") as f:
+            raw = json.load(f)
+
+        classes: dict[int, ClassDef] = {}
+        for key, value in raw.items():
+            try:
+                # RE_RSZ 模板通常以十六进制字符串保存类型哈希。
+                class_hash = int(key, 16)
+            except ValueError:
+                # 非十六进制键（如说明性字段）直接跳过，不影响类型加载。
+                continue
+            fields: list[FieldDef] = []
+            for field in value.get("fields", []):
+                # 字段缺省值尽量保守，保证模板中少数字段缺属性时仍能加载。
+                fields.append(
+                    FieldDef(
+                        name=field.get("name", ""),
+                        field_type=field.get("type", "Data"),
+                        original_type=field.get("original_type", ""),
+                        size=int(field.get("size", 0)),
+                        align=int(field.get("align", 1)),
+                        is_array=bool(field.get("array", False)),
+                    )
+                )
+            crc_raw = value.get("crc", "0")
+            # CRC 可能是十六进制字符串，也可能已经是整数，两种都兼容。
+            crc = int(crc_raw, 16) if isinstance(crc_raw, str) else int(crc_raw)
+            classes[class_hash] = ClassDef(
+                name=value.get("name", ""), crc=crc, fields=fields
+            )
+        return cls(classes)
+
+    def get_class(self, class_hash: int) -> ClassDef | None:
+        """按类型哈希查询类型定义。
+
+        参数：
+            class_hash (int): RE_RSZ 类型哈希。
+
+        返回：
+            ClassDef | None: 对应的类型定义；不存在时返回 ``None``。
+        """
+        return self.classes.get(class_hash)
+
+    def resolve_struct_hash(self, original_type: str) -> int | None:
+        """把结构体类型名解析为类型哈希。
+
+        参数：
+            original_type (str): 模板字段中记录的原始结构体类型名。
+
+        返回：
+            int | None: 找到的类型哈希；无法解析时返回 ``None``。
+        """
+        if not original_type:
+            return None
+        known = self.name_to_hash.get(original_type)
+        if known is not None:
+            return known
+        # 有些结构体不会直接出现在 name_to_hash 中，需要按 RE_RSZ 规则
+        # 对类型名做 MurmurHash3 后再查模板。
+        maybe = murmur3_32(original_type.encode("utf-8"), seed=0xFFFFFFFF)
+        if maybe in self.classes:
+            return maybe
+        return None

pyreuser3/web/__init__.py

@@ -0,0 +1,6 @@
+"""RE User3 JSON 转换器的本地 Vue Web UI。"""
+
+from .server import main, run_server
+from .settings import WebSettings
+
+__all__ = ["WebSettings", "main", "run_server"]

pyreuser3/web/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m pyreuser3.web` 的模块入口。"""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()