PyREUser3 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.6.0
+Version: 0.7.0
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT
@@ -48,11 +48,17 @@ pip install pyreuser3
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
 - A local `.user.3` export Web UI through `pyreuser3-web`.
+- Automatic separation of the USR outer layout from the embedded RSZ header family;
+  modern RSZ v4+ files preserve their original numeric version during repack.
 
 The published package intentionally does not include game resources, dumped game data, RE_RSZ templates,
 `il2cpp_dump.json`, or repository-specific helper scripts. You need to provide data files that match the target game and
 version.
 
+Verified H30/modern layouts support repacking. Experimental physical H28 and legacy
+RSZ v3 layouts are readable for analysis but intentionally blocked from repacking
+until real fixtures provide byte-for-byte validation.
+
 ## Requirements
 
 - Python 3.9 or newer.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.6.0
+Version: 0.7.0
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT
@@ -48,11 +48,17 @@ pip install pyreuser3
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
 - A local `.user.3` export Web UI through `pyreuser3-web`.
+- Automatic separation of the USR outer layout from the embedded RSZ header family;
+  modern RSZ v4+ files preserve their original numeric version during repack.
 
 The published package intentionally does not include game resources, dumped game data, RE_RSZ templates,
 `il2cpp_dump.json`, or repository-specific helper scripts. You need to provide data files that match the target game and
 version.
 
+Verified H30/modern layouts support repacking. Experimental physical H28 and legacy
+RSZ v3 layouts are readable for analysis but intentionally blocked from repacking
+until real fixtures provide byte-for-byte validation.
+
 ## Requirements
 
 - Python 3.9 or newer.

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

@@ -18,6 +18,8 @@ pyreuser3/core.py
 pyreuser3/enum_codec.py
 pyreuser3/rich_ui.py
 pyreuser3/schema.py
+pyreuser3/usr_container.py
+pyreuser3/usr_layouts.py
 pyreuser3/export/__init__.py
 pyreuser3/export/base.py
 pyreuser3/export/enums.py
@@ -42,4 +44,5 @@ pyreuser3/web/server.py
 pyreuser3/web/settings.py
 tests/test_enum_binary.py
 tests/test_enum_codec.py
-tests/test_export_enums.py
+tests/test_export_enums.py
+tests/test_usr_container.py

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

@@ -55,11 +55,20 @@ pyreuser3 export \
   -p <il2cpp_dump.json>
 ```
 
-Pack JSON back to `.user.3`:
+Export full repack JSON, then pack it back to `.user.3`:
+
+```bash
+pyreuser3 export \
+  -i <input-user3-file-or-directory> \
+  -s <RE_RSZ-schema.json> \
+  -o <repack-json-output-directory> \
+  -p <il2cpp_dump.json> \
+  --json-format repack
+```
 
 ```bash
 pyreuser3 pack \
-  -j <input-json-file-or-directory> \
+  -j <input-repack-json-file-or-directory> \
   -s <RE_RSZ-schema.json> \
   -o <user3-output-directory> \
   -p <il2cpp_dump.json>
@@ -90,8 +99,14 @@ converter.export_file(
     "json/OtomonData.user.3.json",
 )
 
+# Packing only accepts the full repack document. Readable exports are read-only.
+converter.export_file(
+    "input/OtomonData.user.3",
+    "json/OtomonData.user.3.pack.json",
+    json_format="repack",
+)
 converter.pack_file(
-    "json/OtomonData.user.3.json",
+    "json/OtomonData.user.3.pack.json",
     "mod/OtomonData.user.3",
 )
 ```
@@ -110,14 +125,24 @@ 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()`.
+Use `json_format="readable"` for the same shape produced by `export_file()`. This
+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
 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.
+`re_user3_pack_v3`, which records the independently detected USR outer layout, RSZ
+header family, and numeric RSZ version while preserving resource and userdata
+dependency tables. Layout candidates and their read/repack capability status are
+declared in `pyreuser3/usr_layouts.py`; RSZ field definitions still come from the
+supplied REFramework-compatible schema. The verified modern header family accepts
+structurally valid RSZ v4+ files and preserves their original version instead of
+forcing MHWS version 16. Experimental physical H28 and legacy RSZ v3 candidates are
+read-only until real fixtures validate byte-for-byte repacking. V1 and v2 documents
+are recognized for diagnostics but must be re-exported as v3 before packing because
+they do not record the required layout metadata.
 
 For stable patch-and-repack workflows, use `patch_file()` or `parse_pack_file()`:
 

{pyreuser3-0.6.0 → pyreuser3-0.7.0}/docs/PYPI.md

@@ -15,11 +15,17 @@ pip install pyreuser3
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
 - A local `.user.3` export Web UI through `pyreuser3-web`.
+- Automatic separation of the USR outer layout from the embedded RSZ header family;
+  modern RSZ v4+ files preserve their original numeric version during repack.
 
 The published package intentionally does not include game resources, dumped game data, RE_RSZ templates,
 `il2cpp_dump.json`, or repository-specific helper scripts. You need to provide data files that match the target game and
 version.
 
+Verified H30/modern layouts support repacking. Experimental physical H28 and legacy
+RSZ v3 layouts are readable for analysis but intentionally blocked from repacking
+until real fixtures provide byte-for-byte validation.
+
 ## Requirements
 
 - Python 3.9 or newer.

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

@@ -56,11 +56,20 @@ pyreuser3 export \
   -p <il2cpp_dump.json>
 ```
 
-将 JSON 封回 `.user.3`：
+导出完整 repack JSON，然后封回 `.user.3`：
+
+```bash
+pyreuser3 export \
+  -i <输入的-user3-文件或目录> \
+  -s <RE_RSZ-schema.json> \
+  -o <repack-JSON-输出目录> \
+  -p <il2cpp_dump.json> \
+  --json-format repack
+```
 
 ```bash
 pyreuser3 pack \
-  -j <输入的-JSON-文件或目录> \
+  -j <输入的-repack-JSON-文件或目录> \
   -s <RE_RSZ-schema.json> \
   -o <user3-输出目录> \
   -p <il2cpp_dump.json>
@@ -118,8 +127,14 @@ converter.export_file(
     "json/OtomonData.user.3.json",
 )
 
+# 封包只接受完整 repack 文档；readable 导出仅供读取。
+converter.export_file(
+    "input/OtomonData.user.3",
+    "json/OtomonData.user.3.pack.json",
+    json_format="repack",
+)
 converter.pack_file(
-    "json/OtomonData.user.3.json",
+    "json/OtomonData.user.3.pack.json",
     "mod/OtomonData.user.3",
 )
 ```
@@ -138,12 +153,18 @@ repack_data = converter.user3_to_json(
 )
 ```
 
-使用 `json_format="readable"` 时返回与 `export_file()` 一致的可读导出结构；使用 `json_format="repack"` 时返回可传给 `pack()` 的完整实例表结构。
+使用 `json_format="readable"` 时返回与 `export_file()` 一致的只读导出结构；使用
+`json_format="repack"` 时返回可传给 `pack()` 的完整实例表结构。封回器会拒绝 readable JSON。
 
 枚举字段会按照真实底层存储宽度输出为 `[数值] 名称`。标量位标志枚举输出为标签数组；
 ``ace.Bitset`1<T>`` 输出为枚举索引标签，并保留 `_MaxElement` 与 `_WordCount`，因此未知位和
-填充词也可以无损封回。新的 repack 文档格式为 `re_user3_pack_v2`，封回器仍兼容使用原始
-数值词数组的 v1 文档。
+填充词也可以无损封回。新的 repack 文档格式为 `re_user3_pack_v3`，它会分别记录自动探测到的
+USR 外层布局、RSZ 头族和文件中的真实 RSZ 版本，并保留 resource 与 userdata 依赖表。布局
+候选及其读取/回封能力状态集中声明在 `pyreuser3/usr_layouts.py`，RSZ 字段定义仍来自传入的
+REFramework 兼容模板。已验证的现代头族接受通过完整结构校验的 RSZ v4+ 文件，并原样保留
+版本号，不再固定为 MHWS 的版本 16。实验性的物理 H28 与 legacy RSZ v3 候选暂时只读，获得
+真实样本并完成逐字节回封验证后才能启用 repack。v1 和 v2 文档仍可识别以便诊断，但由于缺少
+必要的布局元数据，封回前必须从源文件重新导出为 v3。
 
 批量处理目录：
 
@@ -158,6 +179,7 @@ converter = REUser3Converter(
 export_result = converter.export_directory(
     "D:/game/unpacked",
     "D:/game/json",
+    json_format="repack",
 )
 
 pack_result = converter.pack_directory(

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PyREUser3"
-version = "0.6.0"
+version = "0.7.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.6.0 → pyreuser3-0.7.0}/pyreuser3/__init__.py

@@ -9,7 +9,10 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any
 
+__version__ = "0.7.0"
+
 __all__ = [
+    "__version__",
     "BinaryReader",
     "ClassDef",
     "FieldDef",

{pyreuser3-0.6.0 → pyreuser3-0.7.0}/pyreuser3/api.py

@@ -73,6 +73,7 @@ class REUser3Converter:
         user3_root: str | Path,
         output_root: str | Path,
         exclude_regexes: list[str] | None = None,
+        json_format: JsonFormat = "readable",
     ) -> dict[str, int]:
         """Export every selected .user.3 file under a directory or single-file root.
 
@@ -81,33 +82,42 @@ class REUser3Converter:
             output_root (str | Path): Directory where generated output is written.
             exclude_regexes (list[str] | None): Regular expressions used to skip matching
             relative paths.
+            json_format (JsonFormat): "readable" for read-only exports or "repack"
+            for documents accepted by pack().
 
         Returns:
             dict[str, int]: Counters describing total, successful, and failed items.
         """
-        exporter = self._new_exporter(user3_root, output_root, exclude_regexes)
+        exporter = self._new_exporter(
+            user3_root,
+            output_root,
+            exclude_regexes,
+            json_format=self._normalize_json_format(json_format),
+        )
         return exporter.run()
 
     def export_file(
         self,
         user3_path: str | Path,
         json_path: str | Path,
+        json_format: JsonFormat = "readable",
     ) -> Path:
         """Export one .user.3 file to the requested JSON path.
 
         Args:
             user3_path (str | Path): Path to the .user.3 file being parsed, exported, patched, or packed.
             json_path (str | Path): Path to the JSON document read from or written by this workflow.
+            json_format (JsonFormat): "readable" for a read-only tree or "repack"
+            for a document accepted by pack().
 
         Returns:
             Path: Concrete filesystem path returned after the read, write, or resolution step finishes.
         """
-        # Reuse parse_file so single-file and batch exports keep the same parsed JSON shape and metadata handling.
-        # Preserve the exported JSON structure so external scripts and hand-edited files
-        # remain compatible across workflows.
+        # Use the same in-memory format selector as parse_file/parse_pack_file so
+        # single-file and batch exports keep identical document shapes.
         tree = self.user3_to_json(
             user3_path,
-            json_format="readable",
+            json_format=json_format,
             round_floats=True,
         )
         target = Path(json_path)
@@ -343,6 +353,7 @@ class REUser3Converter:
         user3_root: str | Path,
         output_root: str | Path,
         exclude_regexes: list[str] | None,
+        json_format: str = "readable",
     ) -> User3Exporter:
         """Create an exporter with this facade's schema, enum metadata, and magic values.
 
@@ -351,6 +362,7 @@ class REUser3Converter:
             output_root (str | Path): Directory where generated output is written.
             exclude_regexes (list[str] | None): Regular expressions used to skip matching
             relative paths.
+            json_format (str): Export document shape requested by the caller.
 
         Returns:
             User3Exporter: Configured object or normalized value returned for the caller to use directly.
@@ -369,6 +381,7 @@ class REUser3Converter:
             il2cpp_dump_path=self.il2cpp_dump_path,
             user_magic=self.user_magic,
             rsz_magic=self.rsz_magic,
+            json_format=json_format,
         )
 
     def _new_packer(self, output_root: str | Path | None) -> User3Packer:

{pyreuser3-0.6.0 → pyreuser3-0.7.0}/pyreuser3/cli.py

@@ -8,9 +8,9 @@ from __future__ import annotations
 
 import argparse
 import json
-from importlib.metadata import PackageNotFoundError, version
 from typing import Sequence
 
+from . import __version__
 from .core import RSZ_MAGIC, USR_MAGIC
 
 
@@ -33,10 +33,7 @@ def package_version() -> str:
     Returns:
         str: Normalized or formatted text.
     """
-    try:
-        return version("PyREUser3")
-    except PackageNotFoundError:
-        return "0.1.0"
+    return __version__
 
 
 def normalize_tree_depth(value: str) -> int | str:
@@ -143,6 +140,12 @@ def build_parser() -> argparse.ArgumentParser:
         required=True,
         help="Path to il2cpp_dump.json, used to generate enum labels.",
     )
+    export_parser.add_argument(
+        "--json-format",
+        choices=("readable", "repack"),
+        default="readable",
+        help="Export read-only readable JSON or packable repack JSON (default: readable).",
+    )
     add_magic_args(export_parser)
     export_parser.set_defaults(func=run_export)
 
@@ -154,7 +157,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--input-json",
         "-j",
         required=True,
-        help="JSON file or root directory that contains .user.3.json files.",
+        help="Repack JSON file or root directory that contains repack documents.",
     )
     pack_parser.add_argument(
         "--schema-path",
@@ -212,6 +215,7 @@ def run_export(args: argparse.Namespace) -> int:
         il2cpp_dump_path=args.il2cpp_dump_path,
         user_magic=args.user_magic,
         rsz_magic=args.rsz_magic,
+        json_format=args.json_format,
     )
     result = exporter.run()
     console.log("Export complete:", json.dumps(result, ensure_ascii=False))

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

@@ -21,8 +21,11 @@ RSZ_MAGIC = 5919570
 # Preserve instance numbering and reference identity; RSZ object links depend on these
 # indexes remaining stable.
 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})
+PACK_JSON_FORMAT_V2 = "re_user3_pack_v2"
+PACK_JSON_FORMAT = "re_user3_pack_v3"
+PACK_JSON_FORMATS = frozenset(
+    {PACK_JSON_FORMAT_V1, PACK_JSON_FORMAT_V2, 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-0.7.0}/pyreuser3/export/base.py

@@ -43,6 +43,7 @@ class User3Exporter(
         il2cpp_dump_path: str | Path = "",
         user_magic: int = USR_MAGIC,
         rsz_magic: int = RSZ_MAGIC,
+        json_format: str = "readable",
     ):
         """Initialize User3Exporter with validated configuration and state.
 
@@ -57,6 +58,8 @@ class User3Exporter(
             il2cpp_dump_path (str | Path): Path to il2cpp_dump.json for enum metadata.
             user_magic (int): Expected magic value for the outer .user.3 container header.
             rsz_magic (int): Expected magic value for embedded RSZ blocks.
+            json_format (str): "readable" for display-only trees or "repack" for
+            full pack documents.
 
         Returns:
             None. The method performs its documented side effect in place and raises on invalid input.
@@ -77,6 +80,10 @@ class User3Exporter(
         self.tree_depth = self._normalize_tree_depth(tree_depth)
         self.user_magic = int(user_magic)
         self.rsz_magic = int(rsz_magic)
+        normalized_format = str(json_format).strip().lower().replace("-", "_")
+        if normalized_format not in {"readable", "repack"}:
+            raise ValueError("json_format must be 'readable' or 'repack'")
+        self.json_format = normalized_format
         self.exclude_regexes = exclude_regexes or []
         self._exclude_patterns = [re.compile(p) for p in self.exclude_regexes]
         self.schema_path = self._resolve_schema_path(self.schema_dir)
@@ -155,10 +162,13 @@ class User3Exporter(
             # and numeric packing stay reversible.
             # Preserve the exported JSON structure so external scripts and hand-edited
             # files remain compatible across workflows.
-            tree = self._parse_user3(user3_file)
-            tree = self._postprocess_enum_nodes(tree)
-            tree = self._finalize_export_tree(tree)
-            tree = self._round_export_floats(tree)
+            if self.json_format == "repack":
+                tree = self._parse_user3_pack(user3_file)
+            else:
+                tree = self._parse_user3(user3_file)
+                tree = self._postprocess_enum_nodes(tree)
+                tree = self._finalize_export_tree(tree)
+                tree = self._round_export_floats(tree)
             output_path = self._output_path_for(user3_file)
             output_path.parent.mkdir(parents=True, exist_ok=True)
             with output_path.open("w", encoding="utf-8") as f:
@@ -254,5 +264,6 @@ class User3Exporter(
             relative_parent = Path()
         else:
             relative_parent = user3_file.relative_to(self.user3_root).parent
-        output_name = f"{user3_file.name}.json"
+        suffix = ".pack.json" if self.json_format == "repack" else ".json"
+        output_name = f"{user3_file.name}{suffix}"
         return self.output_root / relative_parent / output_name