PyREUser3 0.6.0__tar.gz → 0.7.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.6.0
+Version: 0.7.1
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT
@@ -47,12 +47,33 @@ pip install pyreuser3
 - `JSON -> .user.3` packing.
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
+- Schema-free layout probing through `pyreuser3 probe` and the public probe API.
 - 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.
+
+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
+packer. Signed `-1` null object references and very large fixed-width arrays are
+preserved losslessly; large arrays use a compact raw payload instead of millions
+of Python scalar objects.
+
 ## Requirements
 
 - Python 3.9 or newer.
@@ -60,6 +81,8 @@ version.
 - An `il2cpp_dump.json` file when exporting readable enum labels.
 - One or more unpacked `.user.3` files.
 
+`pyreuser3 probe` does not require a schema or `il2cpp_dump.json`.
+
 ## Usage
 
 Usage details may change as the package evolves. For the latest command-line and Python API examples, read the GitHub README:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.6.0
+Version: 0.7.1
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT
@@ -47,12 +47,33 @@ pip install pyreuser3
 - `JSON -> .user.3` packing.
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
+- Schema-free layout probing through `pyreuser3 probe` and the public probe API.
 - 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.
+
+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
+packer. Signed `-1` null object references and very large fixed-width arrays are
+preserved losslessly; large arrays use a compact raw payload instead of millions
+of Python scalar objects.
+
 ## Requirements
 
 - Python 3.9 or newer.
@@ -60,6 +81,8 @@ version.
 - An `il2cpp_dump.json` file when exporting readable enum labels.
 - One or more unpacked `.user.3` files.
 
+`pyreuser3 probe` does not require a schema or `il2cpp_dump.json`.
+
 ## Usage
 
 Usage details may change as the package evolves. For the latest command-line and Python API examples, read the GitHub README:

{pyreuser3-0.6.0 → pyreuser3-0.7.1}/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
@@ -40,6 +42,8 @@ pyreuser3/web/picker.py
 pyreuser3/web/runners.py
 pyreuser3/web/server.py
 pyreuser3/web/settings.py
+tests/test_api_cache.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.7.1/README.md

@@ -0,0 +1,269 @@
+<h1 align="center">PyREUser3</h1>
+
+<p align="center">
+  English | <a href="https://github.com/dzxrly/PyREUser3/blob/main/docs/README.zh-CN.md">简体中文</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/PyREUser3/"><img alt="PyPI Project" src="https://img.shields.io/badge/PyPI-PyREUser3-blue"></a>
+  <a href="https://pypi.org/project/PyREUser3/"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/PyREUser3"></a>
+  <a href="https://pepy.tech/project/PyREUser3"><img alt="Downloads" src="https://static.pepy.tech/badge/PyREUser3"></a>
+  <a href="https://github.com/dzxrly/PyREUser3/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/PyREUser3"></a>
+</p>
+
+PyREUser3 is a pure Python package for converting RE Engine `.user.3` database files to JSON and packing compatible JSON back to `.user.3`.
+
+Install it with:
+
+```bash
+pip install pyreuser3
+```
+
+Import it with the same normalized package name:
+
+```python
+from pyreuser3 import REUser3Converter
+```
+
+## What Is Included
+
+- `.user.3 -> JSON` export.
+- `JSON -> .user.3` packing.
+- A reusable Python API through `REUser3Converter`.
+- CLI commands through `pyreuser3`.
+- Schema-free layout probing for individual files and whole corpora.
+- A local `.user.3` export Web UI through `pyreuser3-web`.
+
+This PyPI package intentionally does not include game resources, dumped game data, RE_RSZ templates, `il2cpp_dump.json`,
+or repository-specific helper scripts.
+
+## Requirements
+
+- Python 3.9 or newer.
+- A RE_RSZ schema JSON file for the target game/version.
+- An `il2cpp_dump.json` file when exporting readable enum labels.
+- One or more unpacked `.user.3` files.
+
+Layout probing is the exception: `pyreuser3 probe` only inspects the USR/RSZ
+container and does not require a schema or `il2cpp_dump.json`.
+
+## Command Line
+
+Export `.user.3` files to JSON:
+
+```bash
+pyreuser3 export \
+  -i <input-user3-file-or-directory> \
+  -s <RE_RSZ-schema.json> \
+  -o <json-output-directory> \
+  -p <il2cpp_dump.json>
+```
+
+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-repack-json-file-or-directory> \
+  -s <RE_RSZ-schema.json> \
+  -o <user3-output-directory> \
+  -p <il2cpp_dump.json>
+```
+
+The `-p/--il2cpp-dump-path` option is required for export and optional for pack. Passing it during pack is recommended when enum names need to be resolved back to numeric values.
+
+Probe a file or directory without loading game metadata:
+
+```bash
+pyreuser3 probe -i <input-user3-file-or-directory>
+pyreuser3 probe -i <input-user3-file-or-directory> --strict -o layout-report.json
+```
+
+The default probe uses the same safety policy as readable export: structural
+corruption remains fatal, while non-canonical alignment is reported as a warning.
+`--strict` rejects every layout deviation and is intended for corpus validation.
+The optional JSON report contains totals grouped by detected layout, RSZ version,
+and diagnostic code.
+
+Start the local `.user.3` export Web UI:
+
+```bash
+pyreuser3-web --port 8765
+```
+
+The Web UI only handles `.user.3` export. It does not pack files.
+
+## Python API
+
+```python
+from pyreuser3 import REUser3Converter
+
+converter = REUser3Converter(
+    schema_path="D:/schema/rsz_game.json",
+    il2cpp_dump_path="D:/game/il2cpp_dump.json",
+)
+
+converter.export_file(
+    "input/OtomonData.user.3",
+    "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.pack.json",
+    "mod/OtomonData.user.3",
+)
+```
+
+`REUser3Converter` loads schema and il2cpp metadata lazily and caches it for the
+lifetime of that converter. Repeated readable, repack, pack, and patch calls no
+longer rescan large metadata files. Cache entries are invalidated automatically
+when the source path, size, or nanosecond modification time changes; callers that
+replace metadata in an unusual way can force a reload with:
+
+```python
+converter.clear_metadata_cache()
+```
+
+`patch_directory()` also reuses one prepared exporter and packer for the complete
+batch instead of constructing them once per file.
+
+Container layout probing is also available without constructing a converter or
+loading a schema:
+
+```python
+from pyreuser3 import probe_usr_file, probe_usr_path
+
+one_file = probe_usr_file("input/example.user.3")
+whole_tree = probe_usr_path("input/natives", policy="strict_probe")
+```
+
+Convert a `.user.3` file to an in-memory JSON-compatible Python object without writing a JSON file:
+
+```python
+readable_data = converter.user3_to_json(
+    "input/OtomonData.user.3",
+    json_format="readable",
+)
+
+repack_data = converter.user3_to_json(
+    "input/OtomonData.user.3",
+    json_format="repack",
+)
+```
+
+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_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. For this family, offset values remain relative to the RSZ
+section, but the userdata and data targets are aligned to absolute 16-byte file
+positions. Readable export accepts alignment-only deviations, and the probe API
+reports them as structured warnings. Repack export records the same diagnostics in
+`_warnings` and blocks packing through `_unsupported` until the layout is verified.
+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.
+
+Modern files may use signed `-1` as an explicit null `Object` reference; repack
+preserves that sentinel while continuing to reject every other missing instance
+ID. Fixed-width arrays above one million elements are kept compactly as
+`_raw_array_count` plus `_raw_array_hex`. This representation is intentionally
+opaque but lossless, avoids expanding millions of Python integers, and validates
+the count/payload length before packing.
+
+For stable patch-and-repack workflows, use `patch_file()` or `parse_pack_file()`:
+
+```python
+from pyreuser3 import REUser3Converter
+
+converter = REUser3Converter(
+    schema_path="D:/schema/rsz_game.json",
+    il2cpp_dump_path="D:/game/il2cpp_dump.json",
+)
+
+def patch(data, source_path):
+    # Modify the full instance-table JSON in place.
+    return None
+
+converter.patch_file(
+    "input/example.user.3",
+    "output/example.user.3",
+    patch,
+)
+```
+
+## 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
+python -m pip install -U build twine
+python -m build
+python -m twine check dist/*
+```
+
+Upload to TestPyPI first:
+
+```bash
+python -m twine upload -r testpypi dist/*
+```
+
+Then upload the same checked distribution files to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+## License
+
+MIT License.

pyreuser3-0.7.1/docs/PYPI.md

@@ -0,0 +1,63 @@
+# PyREUser3
+
+PyREUser3 is a pure Python package for converting RE Engine `.user.3` database files to JSON and packing compatible JSON back to `.user.3`.
+
+## Installation
+
+```bash
+pip install pyreuser3
+```
+
+## What Is Included
+
+- `.user.3 -> JSON` export.
+- `JSON -> .user.3` packing.
+- A reusable Python API through `REUser3Converter`.
+- CLI commands through `pyreuser3`.
+- Schema-free layout probing through `pyreuser3 probe` and the public probe API.
+- 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.
+
+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
+packer. Signed `-1` null object references and very large fixed-width arrays are
+preserved losslessly; large arrays use a compact raw payload instead of millions
+of Python scalar objects.
+
+## Requirements
+
+- Python 3.9 or newer.
+- A RE_RSZ schema JSON file for the target game/version.
+- An `il2cpp_dump.json` file when exporting readable enum labels.
+- One or more unpacked `.user.3` files.
+
+`pyreuser3 probe` does not require a schema or `il2cpp_dump.json`.
+
+## Usage
+
+Usage details may change as the package evolves. For the latest command-line and Python API examples, read the GitHub README:
+
+https://github.com/dzxrly/PyREUser3#readme
+
+## Links
+
+- Homepage: https://github.com/dzxrly/PyREUser3
+- Issues: https://github.com/dzxrly/PyREUser3/issues
+- License: MIT License

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

@@ -33,6 +33,7 @@ PyREUser3 当前提供：
 - `JSON -> .user.3` 封包；
 - 面向其他项目调用的 `REUser3Converter` Python API；
 - `pyreuser3` 命令行工具；
+- 无需 schema 的单文件与整批布局探测；
 - `pyreuser3-web` 本地 Web 导出界面。
 
 PyPI 包不会包含游戏资源、游戏 dump、RE_RSZ 模板、`il2cpp_dump.json`、或特定仓库脚本。调用方需要自己准备与目标游戏版本匹配的数据文件。
@@ -44,6 +45,9 @@ PyPI 包不会包含游戏资源、游戏 dump、RE_RSZ 模板、`il2cpp_dump.js
 - 导出可读枚举标签时需要 `il2cpp_dump.json`；
 - 一个或多个已解包的 `.user.3` 文件。
 
+布局探测是例外：`pyreuser3 probe` 只检查 USR/RSZ 容器，不需要 schema 或
+`il2cpp_dump.json`。
+
 ## 命令行使用
 
 导出 `.user.3` 为 JSON：
@@ -56,11 +60,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>
@@ -73,6 +86,17 @@ pyreuser3 pack \
 - `-s/--schema-path` 必须指向具体 schema JSON 文件，不应传目录；
 - `-i`、`-j` 都可以传单个文件或目录，目录会递归处理。
 
+无需加载游戏元数据即可探测单个文件或整个目录：
+
+```bash
+pyreuser3 probe -i <输入的-user3-文件或目录>
+pyreuser3 probe -i <输入的-user3-文件或目录> --strict -o layout-report.json
+```
+
+默认探测采用与 readable 导出相同的安全策略：结构损坏仍会直接失败，只有非规范对齐会记录为
+警告。`--strict` 会拒绝任何布局偏差，适合整批语料验证。可选的 JSON 报告会按布局、RSZ
+版本和诊断代码汇总结果。
+
 可用 `--user-magic` 和 `--rsz-magic` 覆盖默认 magic，例如：
 
 ```bash
@@ -118,12 +142,39 @@ 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",
 )
 ```
 
+`REUser3Converter` 会延迟加载 schema 和 il2cpp metadata，并在该 converter 的生命周期内复用。
+连续执行 readable、repack、pack 或 patch 时，不再反复扫描大型 metadata 文件。源文件的绝对
+路径、大小或纳秒修改时间变化后缓存会自动失效；如果调用方以特殊方式原地替换文件，也可以强制
+清理：
+
+```python
+converter.clear_metadata_cache()
+```
+
+`patch_directory()` 现在也会让整批文件复用同一个已准备好的 exporter 和 packer，不再为每个
+文件重复构造。
+
+也可以不创建 converter、不加载 schema，直接调用容器布局探测 API：
+
+```python
+from pyreuser3 import probe_usr_file, probe_usr_path
+
+one_file = probe_usr_file("input/example.user.3")
+whole_tree = probe_usr_path("input/natives", policy="strict_probe")
+```
+
 不写入 JSON 文件，直接把 `.user.3` 转成内存中的 JSON 兼容 Python 对象：
 
 ```python
@@ -138,12 +189,26 @@ 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。这个头族中的 offset 数值仍以 RSZ 段为基准，但 userdata
+与 data 的目标位置按整个文件的绝对 16 字节边界对齐。readable 导出会接受仅对齐偏差，probe
+API 则把它们报告为结构化警告；repack 导出会把同一诊断写入 `_warnings`，并通过
+`_unsupported` 阻止未经验证的布局被封回。实验性的物理 H28 与 legacy RSZ v3 候选暂时只读，
+获得真实样本并完成逐字节回封验证后才能启用 repack。v1 和 v2 文档仍可识别以便诊断，但由于
+缺少必要的布局元数据，封回前必须从源文件重新导出为 v3。
+
+部分现代文件会用有符号 `-1` 明确表示空 `Object` 引用；repack 会原样保留这个哨兵，同时继续
+拒绝其他不存在的实例 ID。超过一百万项的定长数组会紧凑保存为 `_raw_array_count` 和
+`_raw_array_hex`。这种表示不提供逐项可读性，但能够无损回封、避免展开数百万个 Python 整数，
+并会在封包前校验 count 与 payload 长度是否匹配。
 
 批量处理目录：
 
@@ -158,6 +223,7 @@ converter = REUser3Converter(
 export_result = converter.export_directory(
     "D:/game/unpacked",
     "D:/game/json",
+    json_format="repack",
 )
 
 pack_result = converter.pack_directory(
@@ -190,6 +256,29 @@ 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.6.0 → pyreuser3-0.7.1}/pyproject.toml

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

@@ -9,15 +9,21 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any
 
+__version__ = "0.7.1"
+
 __all__ = [
+    "__version__",
     "BinaryReader",
     "ClassDef",
     "FieldDef",
     "PackError",
     "ParseError",
+    "LayoutValidationIssue",
     "TypeDB",
     "REUser3Converter",
     "RSZ_MAGIC",
+    "probe_usr_file",
+    "probe_usr_path",
     "User3Exporter",
     "User3Packer",
     "USR_MAGIC",
@@ -28,6 +34,9 @@ _EXPORT_MODULES = {
     "ParseError": ".core",
     "RSZ_MAGIC": ".core",
     "USR_MAGIC": ".core",
+    "LayoutValidationIssue": ".usr_container",
+    "probe_usr_file": ".usr_container",
+    "probe_usr_path": ".usr_container",
     "ClassDef": ".schema",
     "FieldDef": ".schema",
     "TypeDB": ".schema",