PyREUser3 0.4.0__tar.gz → 0.6.0__tar.gz

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.4.0
+Version: 0.6.0
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/PyREUser3.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.4.0
+Version: 0.6.0
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/PyREUser3.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ pyreuser3/__main__.py
 pyreuser3/api.py
 pyreuser3/cli.py
 pyreuser3/core.py
+pyreuser3/enum_codec.py
 pyreuser3/rich_ui.py
 pyreuser3/schema.py
 pyreuser3/export/__init__.py
@@ -40,4 +41,5 @@ pyreuser3/web/runners.py
 pyreuser3/web/server.py
 pyreuser3/web/settings.py
 tests/test_enum_binary.py
+tests/test_enum_codec.py
 tests/test_export_enums.py

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/README.md

@@ -112,6 +112,13 @@ repack_data = converter.user3_to_json(
 
 Use `json_format="readable"` for the same shape produced by `export_file()`, or `json_format="repack"` for the full instance-table document accepted by `pack()`.
 
+Enum fields are rendered as `[numeric] Name` labels using the enum's actual storage
+width. Scalar flag enums are rendered as arrays of labels. ``ace.Bitset`1<T>`` values are
+rendered as enum-index labels together with `_MaxElement` and `_WordCount`, so unknown
+bits and padded word arrays remain reversible. Repack exports use
+`re_user3_pack_v2`; the packer continues to accept v1 documents with raw numeric Bitset
+word arrays.
+
 For stable patch-and-repack workflows, use `patch_file()` or `parse_pack_file()`:
 
 ```python

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/docs/README.zh-CN.md

@@ -140,6 +140,11 @@ repack_data = converter.user3_to_json(
 
 使用 `json_format="readable"` 时返回与 `export_file()` 一致的可读导出结构；使用 `json_format="repack"` 时返回可传给 `pack()` 的完整实例表结构。
 
+枚举字段会按照真实底层存储宽度输出为 `[数值] 名称`。标量位标志枚举输出为标签数组；
+``ace.Bitset`1<T>`` 输出为枚举索引标签，并保留 `_MaxElement` 与 `_WordCount`，因此未知位和
+填充词也可以无损封回。新的 repack 文档格式为 `re_user3_pack_v2`，封回器仍兼容使用原始
+数值词数组的 v1 文档。
+
 批量处理目录：
 
 ```python

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PyREUser3"
-version = "0.4.0"
+version = "0.6.0"
 description = "Pure Python tools for converting RE Engine .user.3 files to and from JSON."
 readme = "docs/PYPI.md"
 requires-python = ">=3.9"

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/pyreuser3/core.py

@@ -20,7 +20,9 @@ USR_MAGIC = 5395285
 RSZ_MAGIC = 5919570
 # Preserve instance numbering and reference identity; RSZ object links depend on these
 # indexes remaining stable.
-PACK_JSON_FORMAT = "re_user3_pack_v1"
+PACK_JSON_FORMAT_V1 = "re_user3_pack_v1"
+PACK_JSON_FORMAT = "re_user3_pack_v2"
+PACK_JSON_FORMATS = frozenset({PACK_JSON_FORMAT_V1, PACK_JSON_FORMAT})
 # Decode strings and GUID-like values conservatively so invalid data does not corrupt
 # subsequent parsing.
 HEX32_RE = re.compile(r"^[0-9a-fA-F]{32}$")

pyreuser3-0.6.0/pyreuser3/enum_codec.py

@@ -0,0 +1,231 @@
+"""Shared enum, flag, and ``ace.Bitset`` conversion helpers.
+
+The exporter and packer deliberately share these operations so readable labels remain
+lossless across signed/unsigned storage widths and generic container wrappers.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+ENUM_LABEL_RE = re.compile(r"^\[(-?\d+)\]\s*(.*)$")
+_GENERIC_RE = re.compile(r"^[^<]+<(.+)>$")
+
+
+def normalize_integer_for_storage(value: int, storage_type: str | None) -> int:
+    """Normalize an integer according to an enum's declared storage width/sign."""
+    storage = storage_type or "S32"
+    widths = {
+        "S8": (8, True),
+        "U8": (8, False),
+        "S16": (16, True),
+        "U16": (16, False),
+        "S32": (32, True),
+        "U32": (32, False),
+        "S64": (64, True),
+        "U64": (64, False),
+    }
+    bits, signed = widths.get(storage, (32, True))
+    mask = (1 << bits) - 1
+    normalized = int(value) & mask
+    if signed and normalized >= 1 << (bits - 1):
+        normalized -= 1 << bits
+    return normalized
+
+
+def parse_enum_label(value: Any) -> int | None:
+    """Return the authoritative numeric prefix from ``[N] Name`` labels."""
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if not isinstance(value, str):
+        return None
+    match = ENUM_LABEL_RE.match(value.strip())
+    if match:
+        return int(match.group(1))
+    return None
+
+
+def enum_member_for_value(
+    enum_lookup: dict[str, dict[int, tuple[str, int]]],
+    enum_type: str,
+    value: int,
+    enum_underlying_types: dict[str, str] | None = None,
+) -> tuple[str, int] | None:
+    """Resolve a value without inventing 32-bit aliases for wider enum types."""
+    value_map = enum_lookup.get(enum_type)
+    if not value_map:
+        return None
+    storage = (enum_underlying_types or {}).get(enum_type, "S32")
+    target = normalize_integer_for_storage(value, storage)
+    direct = value_map.get(value)
+    if direct is not None and normalize_integer_for_storage(direct[1], storage) == target:
+        return direct
+    for member_name, raw_value in value_map.values():
+        if normalize_integer_for_storage(raw_value, storage) == target:
+            return member_name, raw_value
+    return None
+
+
+def generic_arguments(type_name: str) -> list[str]:
+    """Parse the simple, fully-qualified generic type names emitted by il2cpp dumps."""
+    if not isinstance(type_name, str):
+        return []
+    match = _GENERIC_RE.match(type_name)
+    if not match:
+        return []
+    # These metadata names are not assembly-qualified and current RE generic arguments
+    # are flat. Keeping this parser intentionally strict prevents ambiguous guesses.
+    return [part.strip() for part in match.group(1).split(",") if part.strip()]
+
+
+def bitset_enum_type(class_name: str) -> str | None:
+    """Return the generic enum argument for one ``ace.Bitset`1`` class."""
+    if not isinstance(class_name, str) or not class_name.startswith("ace.Bitset`1<"):
+        return None
+    args = generic_arguments(class_name)
+    return args[0] if len(args) == 1 else None
+
+
+def is_probable_flags_enum(
+    enum_type: str,
+    value_map: dict[int, tuple[str, int]],
+    storage_type: str | None = None,
+) -> bool:
+    """Conservatively identify bit-mask enums from their name and member values."""
+    upper = enum_type.upper()
+    markers = ("BIT", "BITS", "FLAG", "FLAGS", "MASK", "ATTR")
+    if not any(marker in upper for marker in markers):
+        return False
+    storage = storage_type or "S32"
+    width = int(storage[1:])
+    mask = (1 << width) - 1
+    values = {
+        normalize_integer_for_storage(raw, storage) & mask
+        for _name, raw in value_map.values()
+        if raw != 0
+    }
+    basis = {value for value in values if value and value & (value - 1) == 0}
+    if len(basis) < 2:
+        return False
+    known_mask = 0
+    for value in basis:
+        known_mask |= value
+    return all(value & ~known_mask == 0 for value in values)
+
+
+def decode_flags(
+    enum_lookup: dict[str, dict[int, tuple[str, int]]],
+    enum_type: str,
+    value: int,
+    enum_underlying_types: dict[str, str] | None = None,
+) -> list[str]:
+    """Expand a scalar mask to stable labels, preserving unknown bits explicitly."""
+    storage = (enum_underlying_types or {}).get(enum_type, "S32")
+    normalized = normalize_integer_for_storage(value, storage)
+    bits = normalized if normalized >= 0 else normalized & ((1 << int(storage[1:])) - 1)
+    value_map = enum_lookup.get(enum_type, {})
+    if bits == 0:
+        zero = enum_member_for_value(enum_lookup, enum_type, 0, enum_underlying_types)
+        return [f"[0] {zero[0]}"] if zero else []
+    labels: list[str] = []
+    remaining = bits
+    width_mask = (1 << int(storage[1:])) - 1
+    members: list[tuple[int, str, int]] = []
+    for name, raw in value_map.values():
+        normalized_raw = normalize_integer_for_storage(raw, storage)
+        mask_value = normalized_raw & width_mask
+        if mask_value and mask_value & (mask_value - 1) == 0:
+            members.append((mask_value, name, raw))
+    for mask_value, name, raw in sorted(members):
+        if remaining & mask_value:
+            labels.append(f"[{raw}] {name}")
+            remaining &= ~mask_value
+    bit_index = 0
+    while remaining:
+        if remaining & 1:
+            unknown_value = 1 << bit_index
+            labels.append(f"[{unknown_value}] <unknown>")
+        remaining >>= 1
+        bit_index += 1
+    return labels
+
+
+def decode_bitset(
+    words: list[int],
+    enum_type: str,
+    enum_lookup: dict[str, dict[int, tuple[str, int]]],
+    max_element: int | None = None,
+    enum_underlying_types: dict[str, str] | None = None,
+) -> list[str]:
+    """Decode 32-bit words into enum-index labels."""
+    labels: list[str] = []
+    for word_index, raw_word in enumerate(words):
+        word = int(raw_word) & 0xFFFFFFFF
+        for bit in range(32):
+            index = word_index * 32 + bit
+            if not (word & (1 << bit)):
+                continue
+            member = enum_member_for_value(
+                enum_lookup, enum_type, index, enum_underlying_types
+            )
+            labels.append(f"[{index}] {member[0] if member else '<unknown>'}")
+    return labels
+
+
+def encode_bitset(
+    labels: list[Any],
+    enum_type: str,
+    member_lookup: dict[str, dict[str, int]],
+    max_element: int | None = None,
+    word_count: int | None = None,
+) -> list[int]:
+    """Encode enum-index labels into 32-bit words, preserving requested padding."""
+    indexes: list[int] = []
+    members = member_lookup.get(enum_type, {})
+    for item in labels:
+        index = parse_enum_label(item)
+        if index is None and isinstance(item, str):
+            index = members.get(item.strip())
+        if index is None or index < 0:
+            raise ValueError(f"invalid {enum_type} bitset member: {item!r}")
+        if (
+            max_element is not None
+            and index >= max_element
+            and (word_count is None or index >= word_count * 32)
+        ):
+            raise ValueError(
+                f"bitset index {index} exceeds _MaxElement {max_element} for {enum_type}"
+            )
+        indexes.append(index)
+    selected_minimum = (max(indexes) + 32) // 32 if indexes else 0
+    derived_count = max(
+        selected_minimum,
+        (max_element + 31) // 32 if max_element else 0,
+    )
+    count = derived_count if word_count is None else word_count
+    if count < selected_minimum:
+        raise ValueError(f"_WordCount {count} is too small for {enum_type} bitset")
+    words = [0] * count
+    for index in indexes:
+        words[index // 32] |= 1 << (index % 32)
+    return words
+
+
+def encode_flags(
+    values: list[Any], enum_type: str, member_lookup: dict[str, dict[str, int]]
+) -> int:
+    """Combine readable scalar flag labels back into one integer mask."""
+    result = 0
+    members = member_lookup.get(enum_type, {})
+    for item in values:
+        numeric = parse_enum_label(item)
+        if numeric is None and isinstance(item, str):
+            numeric = members.get(item.strip())
+        if numeric is None:
+            raise ValueError(f"invalid {enum_type} flag member: {item!r}")
+        result |= numeric
+    return result

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/pyreuser3/export/base.py

@@ -87,8 +87,11 @@ class User3Exporter(
         self.class_field_fixed_types: dict[str, dict[str, str]] = {}
         self.serializable_to_fixed: dict[str, str] = {}
         self.generic_container_rules: dict[str, tuple[str, str]] = {}
+        self.generic_scalar_rules: dict[str, str] = {}
+        self.bitset_rules: dict[str, str] = {}
         self.param_type_default_enum: dict[str, str] = {}
         self.enum_underlying_types: dict[str, str] = {}
+        self.enum_flags: set[str] = set()
         self.enum_member_to_types: dict[str, list[str]] = {}
         self._pending_enum_context: dict | None = None
 

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/pyreuser3/export/enums.py

@@ -258,6 +258,9 @@ class ExporterEnumSourceMixin:
             "class_field_fixed_types": {},
             "serializable_to_fixed": {},
             "generic_container_rules": {},
+            "generic_scalar_rules": {},
+            "bitset_rules": {},
+            "generic_candidates": {},
             "enum_underlying_types": {},
             "enum_types": set(),
             "serializable_fallback_candidates": [],
@@ -271,7 +274,7 @@ class ExporterEnumSourceMixin:
         if not isinstance(class_name, str) or not isinstance(obj, dict):
             return
 
-        if class_name.endswith("_Fixed") and obj.get("parent") == "System.Enum":
+        if obj.get("parent") == "System.Enum":
             state["enum_types"].add(class_name)
         if obj.get("parent") == "System.Enum":
             storage_type = cls._extract_enum_underlying_type(obj)
@@ -383,25 +386,18 @@ class ExporterEnumSourceMixin:
                 state["serializable_fallback_candidates"].append(class_name)
 
         generic_args = obj.get("generic_arg_types")
-        if isinstance(generic_args, list) and len(generic_args) >= 2:
-            enum_types_in_args: list[str] = []
-            param_types: list[str] = []
-            for arg in generic_args:
-                if not isinstance(arg, dict):
-                    continue
-                raw_type = arg.get("type")
-                fixed_type = cls._extract_fixed_enum_type(raw_type)
-                if fixed_type is not None:
-                    enum_types_in_args.append(fixed_type)
-                elif isinstance(raw_type, str) and raw_type != "unknown":
-                    param_types.append(raw_type)
-            enum_types_unique = list(dict.fromkeys(enum_types_in_args))
-            param_types_unique = list(dict.fromkeys(param_types))
-            if len(enum_types_unique) == 1 and len(param_types_unique) == 1:
-                state["generic_container_rules"][class_name] = {
-                    "param_type": param_types_unique[0],
-                    "enum_type": enum_types_unique[0],
-                }
+        if isinstance(generic_args, list):
+            raw_types = [
+                arg.get("type")
+                for arg in generic_args
+                if isinstance(arg, dict)
+                and isinstance(arg.get("type"), str)
+                and arg.get("type") != "unknown"
+            ]
+            if raw_types:
+                # Resolution is deferred until every top-level enum entry has been
+                # observed; il2cpp dump ordering is not a semantic contract.
+                state["generic_candidates"][class_name] = raw_types
 
     @classmethod
     def _finalize_enum_context_state(cls, state: dict[str, Any]) -> dict:
@@ -415,10 +411,30 @@ class ExporterEnumSourceMixin:
             if len(fallback_types) == 1:
                 serializable_to_fixed[class_name] = fallback_types[0]
 
+        for class_name, raw_types in state["generic_candidates"].items():
+            enum_args = list(dict.fromkeys(t for t in raw_types if t in enum_types))
+            param_args = list(dict.fromkeys(t for t in raw_types if t not in enum_types))
+            if len(enum_args) != 1:
+                continue
+            enum_type = enum_args[0]
+            if class_name.startswith("ace.Bitset`1<"):
+                state["bitset_rules"][class_name] = enum_type
+            elif class_name.startswith("ace.btable.cEditFieldEnum`1<"):
+                state["generic_scalar_rules"][class_name] = enum_type
+            elif len(param_args) == 1 and (
+                enum_type.endswith("_Fixed") or "cEnumerableParam" in class_name
+            ):
+                state["generic_container_rules"][class_name] = {
+                    "param_type": param_args[0],
+                    "enum_type": enum_type,
+                }
+
         return {
             "class_field_fixed_types": state["class_field_fixed_types"],
             "serializable_to_fixed": serializable_to_fixed,
             "generic_container_rules": state["generic_container_rules"],
+            "generic_scalar_rules": state["generic_scalar_rules"],
+            "bitset_rules": state["bitset_rules"],
             "enum_underlying_types": state["enum_underlying_types"],
         }
 

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/pyreuser3/export/fields.py

@@ -74,7 +74,7 @@ class ExporterFieldParserMixin:
             return {"ref_instance_id": reader.read_s32()}
         if t in ("String", "Resource"):
             return read_len_utf16(reader)
-        if t == "C8":
+        if t in ("C8", "RuntimeType"):
             return read_len_c8(reader)
         if t in ("Guid", "GameObjectRef", "Uri"):
             return read_guid_like(reader)
@@ -230,7 +230,7 @@ class ExporterFieldParserMixin:
             t = field.field_type
             if field.is_array:
                 pos += 4
-            elif t in ("String", "Resource", "C8"):
+            elif t in ("String", "Resource", "C8", "RuntimeType"):
                 pos += 4
             elif t in ("Object", "UserData"):
                 pos += 4
@@ -250,7 +250,9 @@ class ExporterFieldParserMixin:
                 pos += max(field.size, 0)
         return max(pos, 1)
 
-    def _parse_instance(self, reader: BinaryReader, class_hash: int) -> dict[str, Any]:
+    def _parse_instance(
+        self, reader: BinaryReader, class_hash: int, crc: int | None = None
+    ) -> dict[str, Any]:
         """Parse instance.
 
         The method keeps parsing, metadata lookup, and JSON shaping explicit so incomplete
@@ -259,6 +261,7 @@ class ExporterFieldParserMixin:
         Args:
             reader (BinaryReader): BinaryReader positioned at the value to parse.
             class_hash (int): RE_RSZ type hash for a class.
+            crc (int | None): Optional CRC used to choose among same-hash layout variants.
 
         Returns:
             dict[str, Any]: JSON-compatible dictionary for API or conversion callers.
@@ -266,7 +269,7 @@ class ExporterFieldParserMixin:
         Raises:
             ParseError: Binary data did not match the expected .user.3 or RSZ layout.
         """
-        cls = self.typedb.get_class(class_hash)
+        cls = self.typedb.get_class(class_hash, crc)
         if cls is None:
             raise ParseError(f"class hash 0x{class_hash:08x} not found in schema")
         out: dict[str, Any] = {"_class": cls.name, "fields": {}}

{pyreuser3-0.4.0 → pyreuser3-0.6.0}/pyreuser3/export/metadata.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from typing import Any
 
 from ..core import ParseError, enum_storage_type_from_size
+from ..enum_codec import enum_member_for_value, is_probable_flags_enum
 from ..rich_ui import get_console
 
 
@@ -100,8 +101,6 @@ class ExporterMetadataMixin:
                 # Register enum values through the shared lookup tables so readable
                 # labels and numeric packing stay reversible.
                 value_map[raw_value] = entry
-                value_map[self._to_s32(raw_value)] = entry
-                value_map[self._to_u32(raw_value)] = entry
             if value_map:
                 lookup[enum_type] = value_map
         return lookup
@@ -205,11 +204,12 @@ class ExporterMetadataMixin:
             value_map = self.enum_lookup.get(enum_type)
             if value_map is None:
                 continue
-            if (
-                value in value_map
-                or self._to_s32(value) in value_map
-                or self._to_u32(value) in value_map
-            ):
+            if enum_member_for_value(
+                self.enum_lookup,
+                enum_type,
+                value,
+                self.enum_underlying_types,
+            ) is not None:
                 matched.append(enum_type)
         if len(matched) == 1:
             return matched[0]
@@ -232,8 +232,11 @@ class ExporterMetadataMixin:
         self.class_field_fixed_types = {}
         self.serializable_to_fixed = {}
         self.generic_container_rules = {}
+        self.generic_scalar_rules = {}
+        self.bitset_rules = {}
         self.param_type_default_enum = {}
         self.enum_underlying_types = {}
+        self.enum_flags = set()
 
         class_field_fixed_types = raw.get("class_field_fixed_types")
         if isinstance(class_field_fixed_types, dict):
@@ -268,7 +271,6 @@ class ExporterMetadataMixin:
                 if (
                     isinstance(serializable_name, str)
                     and isinstance(fixed_name, str)
-                    and fixed_name.endswith("_Fixed")
                 ):
                     self.serializable_to_fixed[serializable_name] = fixed_name
 
@@ -285,7 +287,6 @@ class ExporterMetadataMixin:
                 if (
                     isinstance(param_type, str)
                     and isinstance(enum_type, str)
-                    and enum_type.endswith("_Fixed")
                 ):
                     self.generic_container_rules[container_name] = (
                         param_type,
@@ -299,6 +300,32 @@ class ExporterMetadataMixin:
                 # labels and numeric packing stay reversible.
                 self.param_type_default_enum[param_type] = next(iter(enum_types))
 
+        generic_scalar_rules = raw.get("generic_scalar_rules")
+        if isinstance(generic_scalar_rules, dict):
+            self.generic_scalar_rules = {
+                class_name: enum_type
+                for class_name, enum_type in generic_scalar_rules.items()
+                if isinstance(class_name, str)
+                and isinstance(enum_type, str)
+                and enum_type in self.enum_lookup
+            }
+        bitset_rules = raw.get("bitset_rules")
+        if isinstance(bitset_rules, dict):
+            self.bitset_rules = {
+                class_name: enum_type
+                for class_name, enum_type in bitset_rules.items()
+                if isinstance(class_name, str)
+                and isinstance(enum_type, str)
+                and enum_type in self.enum_lookup
+            }
+        self.enum_flags = {
+            enum_type
+            for enum_type, value_map in self.enum_lookup.items()
+            if is_probable_flags_enum(
+                enum_type, value_map, self.enum_underlying_types.get(enum_type)
+            )
+        }
+
     def _enum_type_candidates_for_lookup(self, type_name: str) -> list[str]:
         """Yield enum lookup candidates for schema or il2cpp type names."""
         candidates = [type_name]
@@ -337,11 +364,11 @@ class ExporterMetadataMixin:
         if typedb is None or not enum_lookup:
             return
 
-        for class_def in typedb.classes.values():
+        iter_classes = getattr(typedb, "iter_classes", None)
+        class_defs = iter_classes() if callable(iter_classes) else typedb.classes.values()
+        for class_def in class_defs:
             field_map = self.class_field_fixed_types.setdefault(class_def.name, {})
             for field in class_def.fields:
-                if field.field_type != "Enum":
-                    continue
                 enum_type = self._resolve_enum_type_for_lookup(field.original_type)
                 if enum_type is not None:
                     field_map.setdefault(field.name or "unnamed", enum_type)