PyREUser3 0.7.1__tar.gz → 0.8.0__tar.gz

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.7.1
+Version: 0.8.0
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT
@@ -60,13 +60,6 @@ Verified H30/modern layouts support repacking. Experimental physical H28 and leg
 RSZ v3 layouts are readable for analysis but intentionally blocked from repacking
 until real fixtures provide byte-for-byte validation.
 
-Version 0.7.1 fixes the 0.7.0 modern RSZ alignment regression. Modern userdata and
-data targets use absolute 16-byte file alignment even though their stored offsets
-remain RSZ-relative. Readable parsing accepts alignment-only deviations without
-hiding structural corruption, while the probe API reports them explicitly. Repack
-output blocks layouts carrying unverified diagnostics. The strict schema-free
-probe can validate large local corpora.
-
 Repeated operations on one `REUser3Converter` reuse schema and il2cpp metadata,
 with automatic file-signature invalidation and an explicit
 `clear_metadata_cache()` escape hatch. Batch patching reuses one exporter and

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/PyREUser3.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.7.1
+Version: 0.8.0
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT
@@ -60,13 +60,6 @@ Verified H30/modern layouts support repacking. Experimental physical H28 and leg
 RSZ v3 layouts are readable for analysis but intentionally blocked from repacking
 until real fixtures provide byte-for-byte validation.
 
-Version 0.7.1 fixes the 0.7.0 modern RSZ alignment regression. Modern userdata and
-data targets use absolute 16-byte file alignment even though their stored offsets
-remain RSZ-relative. Readable parsing accepts alignment-only deviations without
-hiding structural corruption, while the probe API reports them explicitly. Repack
-output blocks layouts carrying unverified diagnostics. The strict schema-free
-probe can validate large local corpora.
-
 Repeated operations on one `REUser3Converter` reuse schema and il2cpp metadata,
 with automatic file-signature invalidation and an explicit
 `clear_metadata_cache()` escape hatch. Batch patching reuses one exporter and

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/PyREUser3.egg-info/SOURCES.txt

@@ -30,8 +30,10 @@ pyreuser3/export/tree.py
 pyreuser3/export/user3.py
 pyreuser3/pack/__init__.py
 pyreuser3/pack/base.py
+pyreuser3/pack/container.py
 pyreuser3/pack/models.py
 pyreuser3/pack/plan.py
+pyreuser3/pack/values.py
 pyreuser3/pack/writer.py
 pyreuser3/web/__init__.py
 pyreuser3/web/__main__.py

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/README.md

@@ -169,8 +169,10 @@ Use `json_format="readable"` for the same shape produced by `export_file()`. Thi
 shape is read-only. Use `json_format="repack"` for the full document accepted by
 `pack()`; the packer rejects readable JSON.
 
-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
+Readable enum fields are rendered as `[numeric] Name` labels using the enum's actual
+storage width and signedness, so signed Fixed IDs match their in-game runtime values.
+Repack documents retain canonical unsigned Fixed prefixes for stable machine editing.
+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_v3`, which records the independently detected USR outer layout, RSZ
@@ -217,33 +219,6 @@ converter.patch_file(
 )
 ```
 
-## Compatibility Validation
-
-The repository includes a schema-free corpus runner. Game files are not committed;
-point it at a locally unpacked `natives` tree:
-
-```bash
-python tests/corpus_probe.py D:/game/natives \
-  --expected-total 62768 \
-  --expected-version 16 \
-  --report layout-report.json
-```
-
-Version 0.7.1 fixes modern RSZ alignment regression found in 0.7.0 and folds the
-planned compatibility work into the bug-fix release: staged layout detection,
-structured diagnostics, safe readable parsing, verified-only repacking, and the
-schema-free probe command. The modern rule was validated against 62,768 MHWS
-`.user.3` files; four SystemSetting fixtures additionally passed readable export,
-repack export, byte-identical packing, and reparse checks.
-
-A second corpus from Monster Hunter Stories 3 was also validated: all 42,945 files
-passed strict layout detection and schema-driven repack export. All 42,945 rebuilt
-without exceptions; 38,548 were byte-identical. The remaining 4,397 are successful
-rebuilds but not byte-identical; observed causes include nonzero padding and
-alternate empty-string encodings, so they are not claimed as byte-identical
-fixtures. Two voxel files use the compact large-array representation; both rebuilt
-byte-identically, including the 6.55 MB `dg100_Root` payload.
-
 ## Build From Source
 
 ```bash

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/docs/PYPI.md

@@ -27,13 +27,6 @@ Verified H30/modern layouts support repacking. Experimental physical H28 and leg
 RSZ v3 layouts are readable for analysis but intentionally blocked from repacking
 until real fixtures provide byte-for-byte validation.
 
-Version 0.7.1 fixes the 0.7.0 modern RSZ alignment regression. Modern userdata and
-data targets use absolute 16-byte file alignment even though their stored offsets
-remain RSZ-relative. Readable parsing accepts alignment-only deviations without
-hiding structural corruption, while the probe API reports them explicitly. Repack
-output blocks layouts carrying unverified diagnostics. The strict schema-free
-probe can validate large local corpora.
-
 Repeated operations on one `REUser3Converter` reuse schema and il2cpp metadata,
 with automatic file-signature invalidation and an explicit
 `clear_metadata_cache()` escape hatch. Batch patching reuses one exporter and

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/docs/README.zh-CN.md

@@ -256,29 +256,6 @@ converter.patch_file(
 )
 ```
 
-## 兼容性验证
-
-仓库内提供无需 schema 的语料测试脚本。游戏文件不会提交到仓库，请让脚本指向本地已解包的
-`natives` 目录：
-
-```bash
-python tests/corpus_probe.py D:/game/natives \
-  --expected-total 62768 \
-  --expected-version 16 \
-  --report layout-report.json
-```
-
-0.7.1 修复了 0.7.0 引入的现代 RSZ 对齐回归，并把原计划中的兼容性工作合并进本次 bugfix：
-分阶段布局探测、结构化诊断、安全 readable 解析、仅验证布局可 repack，以及无需 schema 的
-probe 命令。新的现代布局规则已用 62,768 个 MHWS `.user.3` 文件验证；其中四个
-SystemSetting 样本还完成了 readable 导出、repack 导出、逐字节一致回封和二次解析验证。
-
-另外还验证了 Monster Hunter Stories 3 语料：42,945 个文件全部通过严格 layout 探测和
-schema 驱动的 repack 导出；42,945 个文件全部能够无异常地重新构建，其中 38,548 个逐字节
-一致。其余 4,397 个可以成功重建但并非逐字节一致；已观察到的原因包括非零 padding、空字符串
-的另一种物理编码，因此不把它们宣称为逐字节 fixture。两个使用紧凑超大数组表示的 voxel 文件
-都能逐字节一致回封，其中包括 6.55 MB 的 `dg100_Root` payload。
-
 ## 常见注意事项
 
 - schema JSON、`il2cpp_dump.json` 和 `.user.3` 文件应来自同一个游戏版本；

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PyREUser3"
-version = "0.7.1"
+version = "0.8.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.7.1 → pyreuser3-0.8.0}/pyreuser3/__init__.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any
 
-__version__ = "0.7.1"
+__version__ = "0.8.0"
 
 __all__ = [
     "__version__",

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/pyreuser3/export/enums.py

@@ -18,6 +18,9 @@ from ..core import ENUM_UNUSED_KEY, normalize_enum_storage_type
 _FIXED_ENUM_RE = re.compile(r"[A-Za-z0-9_.+]+_Fixed")
 _PROPERTY_METHOD_RE = re.compile(r"^(?:get|set)_(?P<name>.+?)(?:\d+)?$")
 _BACKING_FIELD_RE = re.compile(r"^<(?P<name>[^>]+)>")
+_INTEGER_STORAGE_TYPES = frozenset(
+    {"S8", "U8", "S16", "U16", "S32", "U32", "S64", "U64"}
+)
 
 
 class ExporterEnumSourceMixin:
@@ -104,6 +107,39 @@ class ExporterEnumSourceMixin:
         for candidate in cls._field_name_variants(field_name):
             field_map.setdefault(candidate, fixed_type)
 
+    @classmethod
+    def _add_fixed_backing_candidate(
+        cls,
+        candidates: dict[str, set[str]],
+        field_name: Any,
+        type_name: Any,
+    ) -> None:
+        """Record an integer ``*_Fixed`` backing field by its runtime property name."""
+        if not isinstance(field_name, str):
+            return
+        storage_type = normalize_enum_storage_type(type_name)
+        if storage_type not in _INTEGER_STORAGE_TYPES:
+            return
+        for field_variant in cls._field_name_variants(field_name):
+            normalized_name = field_variant.lstrip("_")
+            if not normalized_name.endswith("_Fixed"):
+                continue
+            property_name = normalized_name[: -len("_Fixed")]
+            if property_name:
+                candidates.setdefault(property_name, set()).add(field_variant)
+            candidates.setdefault(normalized_name, set()).add(field_variant)
+
+    @staticmethod
+    def _method_return_type(method: Any) -> str | None:
+        """Return one concrete method return type when metadata exposes it."""
+        if not isinstance(method, dict):
+            return None
+        returns = method.get("returns")
+        if not isinstance(returns, dict):
+            return None
+        return_type = returns.get("type")
+        return return_type if isinstance(return_type, str) and return_type else None
+
     @staticmethod
     def _method_matches_property(method_name: str, getter_or_setter: str) -> bool:
         """Return whether an il2cpp method key represents the named property accessor."""
@@ -264,6 +300,7 @@ class ExporterEnumSourceMixin:
             "enum_underlying_types": {},
             "enum_types": set(),
             "serializable_fallback_candidates": [],
+            "fixed_backing_candidates": [],
         }
 
     @classmethod
@@ -282,6 +319,7 @@ class ExporterEnumSourceMixin:
                 state["enum_underlying_types"][class_name] = storage_type
 
         field_map: dict[str, str] = {}
+        fixed_backing_fields: dict[str, set[str]] = {}
         fields_obj = obj.get("fields")
         if isinstance(fields_obj, dict):
             for field_name, field_info in fields_obj.items():
@@ -290,6 +328,9 @@ class ExporterEnumSourceMixin:
                 cls._add_field_fixed_type(
                     field_map, field_name, field_info.get("type")
                 )
+                cls._add_fixed_backing_candidate(
+                    fixed_backing_fields, field_name, field_info.get("type")
+                )
 
         # Older dumps expose RE_RSZ field hints through an explicit RSZ array.
         rsz_fields = obj.get("RSZ")
@@ -303,6 +344,9 @@ class ExporterEnumSourceMixin:
                 cls._add_field_fixed_type(
                     field_map, potential_name, rsz_field.get("type")
                 )
+                cls._add_fixed_backing_candidate(
+                    fixed_backing_fields, potential_name, rsz_field.get("type")
+                )
 
         # Newer dumps can omit RSZ entirely but keep property/type hints here.
         reflection_props = obj.get("reflection_properties")
@@ -311,8 +355,12 @@ class ExporterEnumSourceMixin:
                 if not isinstance(prop_name, str) or not isinstance(prop_info, dict):
                     continue
                 cls._add_field_fixed_type(field_map, prop_name, prop_info.get("type"))
+                cls._add_fixed_backing_candidate(
+                    fixed_backing_fields, prop_name, prop_info.get("type")
+                )
 
         methods_obj = obj.get("methods")
+        runtime_property_types: dict[str, set[str]] = {}
         if isinstance(methods_obj, dict):
             properties_obj = obj.get("properties")
             if isinstance(properties_obj, dict):
@@ -326,6 +374,11 @@ class ExporterEnumSourceMixin:
                                 continue
                             if not cls._method_matches_property(method_name, getter):
                                 continue
+                            return_type = cls._method_return_type(method)
+                            if return_type is not None:
+                                runtime_property_types.setdefault(
+                                    prop_name, set()
+                                ).add(return_type)
                             fixed_type = cls._fixed_type_from_method_return(method)
                             if fixed_type is not None:
                                 cls._add_field_fixed_type(
@@ -350,6 +403,12 @@ class ExporterEnumSourceMixin:
                 method_prop_name = cls._property_name_from_method(method_name)
                 if method_prop_name is None:
                     continue
+                if method_name.startswith("get_"):
+                    return_type = cls._method_return_type(method)
+                    if return_type is not None:
+                        runtime_property_types.setdefault(
+                            method_prop_name, set()
+                        ).add(return_type)
                 fixed_type = None
                 if method_name.startswith("get_"):
                     fixed_type = cls._fixed_type_from_method_return(method)
@@ -358,6 +417,18 @@ class ExporterEnumSourceMixin:
                 if fixed_type is not None:
                     cls._add_field_fixed_type(field_map, method_prop_name, fixed_type)
 
+        for property_name, field_names in fixed_backing_fields.items():
+            runtime_types = runtime_property_types.get(property_name, set())
+            if len(runtime_types) != 1:
+                continue
+            state["fixed_backing_candidates"].append(
+                (
+                    class_name,
+                    tuple(sorted(field_names)),
+                    next(iter(runtime_types)),
+                )
+            )
+
         if field_map:
             state["class_field_fixed_types"][class_name] = field_map
 
@@ -411,6 +482,20 @@ class ExporterEnumSourceMixin:
             if len(fallback_types) == 1:
                 serializable_to_fixed[class_name] = fallback_types[0]
 
+        for class_name, field_names, runtime_type in state[
+            "fixed_backing_candidates"
+        ]:
+            fixed_type = (
+                runtime_type
+                if runtime_type.endswith("_Fixed")
+                else f"{runtime_type}_Fixed"
+            )
+            if fixed_type not in enum_types:
+                continue
+            field_map = state["class_field_fixed_types"].setdefault(class_name, {})
+            for field_name in field_names:
+                field_map.setdefault(field_name, fixed_type)
+
         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))

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/pyreuser3/export/postprocess.py

@@ -13,6 +13,7 @@ from ..enum_codec import (
     decode_bitset,
     decode_flags,
     enum_member_for_value,
+    normalize_integer_for_storage,
 )
 
 
@@ -68,9 +69,18 @@ class ExporterPostprocessMixin:
                 return candidate
         return type_name
 
-    def _format_enum_value(self, fixed_enum_type: str, value: int) -> Any:
+    def _format_enum_value(
+        self,
+        fixed_enum_type: str,
+        value: int,
+        *,
+        runtime_signedness: bool = True,
+    ) -> Any:
         """Format enum value.
 
+        Exact declared members stay intact; flagged enums are decomposed only when the
+        numeric value has no exact member.
+
         The method keeps parsing, metadata lookup, and JSON shaping explicit so incomplete
         templates can still produce inspectable output.
 
@@ -86,7 +96,22 @@ class ExporterPostprocessMixin:
         value_map = self.enum_lookup.get(fixed_enum_type)
         if value_map is None:
             return value
-        # Leave numeric enum values unchanged when no enum lookup is available for the current context.
+        matched = enum_member_for_value(
+            self.enum_lookup,
+            fixed_enum_type,
+            value,
+            getattr(self, "enum_underlying_types", {}),
+        )
+        if matched is not None:
+            member_name, fixed_value = matched
+            return self._id_formatter(
+                member_name,
+                self._normalize_enum_display_value(
+                    fixed_enum_type,
+                    fixed_value,
+                    runtime_signedness=runtime_signedness,
+                ),
+            )
         if fixed_enum_type in getattr(self, "enum_flags", set()):
             return decode_flags(
                 self.enum_lookup,
@@ -94,16 +119,37 @@ class ExporterPostprocessMixin:
                 value,
                 getattr(self, "enum_underlying_types", {}),
             )
-        matched = enum_member_for_value(
-            self.enum_lookup,
-            fixed_enum_type,
-            value,
-            getattr(self, "enum_underlying_types", {}),
-        )
-        if matched is None:
+        if not fixed_enum_type.endswith("_Fixed"):
             return value
-        member_name, fixed_value = matched
-        return self._id_formatter(member_name, fixed_value)
+        return self._id_formatter(
+            "<unknown>",
+            self._normalize_enum_display_value(
+                fixed_enum_type,
+                value,
+                runtime_signedness=runtime_signedness,
+            ),
+        )
+
+    def _normalize_enum_display_value(
+        self,
+        enum_type: str,
+        value: int,
+        *,
+        runtime_signedness: bool,
+    ) -> int:
+        """Normalize IDs to the integer domain exposed by the runtime enum."""
+        storage_type = getattr(self, "enum_underlying_types", {}).get(enum_type)
+        if (
+            not runtime_signedness
+            and enum_type.endswith("_Fixed")
+            and storage_type in {"S8", "S16", "S32", "S64"}
+        ):
+            storage_type = f"U{storage_type[1:]}"
+        return (
+            normalize_integer_for_storage(value, storage_type)
+            if storage_type is not None
+            else value
+        )
 
     @staticmethod
     def _looks_like_class_name(text: str) -> bool:
@@ -425,7 +471,11 @@ class ExporterPostprocessMixin:
         if isinstance(value, int) and scalar_enum_hint is not None:
             # Register enum values through the shared lookup tables so readable labels
             # and numeric packing stay reversible.
-            return self._format_enum_value(scalar_enum_hint, value)
+            return self._format_enum_value(
+                scalar_enum_hint,
+                value,
+                runtime_signedness=output_mode != "repack",
+            )
         return value
 
     def _finalize_export_tree(self, value: Any) -> Any:

{pyreuser3-0.7.1 → pyreuser3-0.8.0}/pyreuser3/pack/base.py

@@ -11,12 +11,10 @@ import re
 from pathlib import Path
 from typing import Any
 
+from .container import RepackContainer
 from .models import (
     ExternalUserdataSpec,
     InstanceSpec,
-    RszUserdataSpec,
-    UsrResourceSpec,
-    UsrUserdataSpec,
 )
 from .plan import PackerPlanMixin
 from .writer import PackerWriterMixin
@@ -25,12 +23,6 @@ from ..enum_codec import is_probable_flags_enum
 from ..export import User3Exporter
 from ..rich_ui import BatchProgress
 from ..schema import TypeDB
-from ..usr_layouts import (
-    DEFAULT_RSZ_HEADER_LAYOUT_ID,
-    DEFAULT_USR_LAYOUT_ID,
-    get_rsz_header_layout,
-    get_usr_layout,
-)
 
 
 class User3Packer(PackerPlanMixin, PackerWriterMixin):
@@ -97,25 +89,9 @@ class User3Packer(PackerPlanMixin, PackerWriterMixin):
             )
         }
         self.instances: list[InstanceSpec | ExternalUserdataSpec | None] = []
-        self.usr_layout = get_usr_layout(DEFAULT_USR_LAYOUT_ID)
-        if self.usr_layout is None:
-            raise RuntimeError(f"default USR layout is not registered: {DEFAULT_USR_LAYOUT_ID}")
-        self.rsz_header_layout = get_rsz_header_layout(
-            DEFAULT_RSZ_HEADER_LAYOUT_ID
-        )
-        if self.rsz_header_layout is None:
-            raise RuntimeError(
-                "default RSZ header layout is not registered: "
-                f"{DEFAULT_RSZ_HEADER_LAYOUT_ID}"
-            )
-        self.usr_header_padding = b"\x00" * self.usr_layout.header_padding_size
-        self.usr_resources: list[UsrResourceSpec] = []
-        self.usr_userdata: list[UsrUserdataSpec] = []
-        # A numeric RSZ version must be loaded from repack metadata.  The modern
-        # header family is shared across games and must not imply MHWS version 16.
-        self.rsz_version: int | None = None
-        self.rsz_reserved = 0
-        self.rsz_userdata: list[RszUserdataSpec] = []
+        # The container is committed atomically only after one complete repack document
+        # has passed layout, table, instance, and resource validation.
+        self.container: RepackContainer | None = None
 
     def pack_json_file(self, json_path: str | Path, output_path: str | Path) -> Path:
         """Pack json file.