PyREUser3 0.8.0__tar.gz → 0.8.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.8.0
+Version: 0.8.1
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT
@@ -43,7 +43,7 @@ pip install pyreuser3
 
 ## What Is Included
 
-- `.user.3 -> JSON` export.
+- `.user.3` and decorated `.user.3.*` export.
 - `JSON -> .user.3` packing.
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
@@ -51,6 +51,8 @@ pip install 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.
+- il2cpp-validated readable codecs for `via.Int2`, `via.Uint2`, `via.Range`,
+  `via.RangeI`, and `via.Sphere`, with scalar/array round trips and raw fallback.
 
 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
@@ -71,8 +73,8 @@ of Python scalar objects.
 
 - 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.
+- An `il2cpp_dump.json` file when exporting readable enum labels and validated native structures.
+- One or more unpacked `.user.3` or `.user.3.*` files.
 
 `pyreuser3 probe` does not require a schema or `il2cpp_dump.json`.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.8.0
+Version: 0.8.1
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT
@@ -43,7 +43,7 @@ pip install pyreuser3
 
 ## What Is Included
 
-- `.user.3 -> JSON` export.
+- `.user.3` and decorated `.user.3.*` export.
 - `JSON -> .user.3` packing.
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
@@ -51,6 +51,8 @@ pip install 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.
+- il2cpp-validated readable codecs for `via.Int2`, `via.Uint2`, `via.Range`,
+  `via.RangeI`, and `via.Sphere`, with scalar/array round trips and raw fallback.
 
 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
@@ -71,8 +73,8 @@ of Python scalar objects.
 
 - 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.
+- An `il2cpp_dump.json` file when exporting readable enum labels and validated native structures.
+- One or more unpacked `.user.3` or `.user.3.*` files.
 
 `pyreuser3 probe` does not require a schema or `il2cpp_dump.json`.
 

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

@@ -16,6 +16,7 @@ pyreuser3/api.py
 pyreuser3/cli.py
 pyreuser3/core.py
 pyreuser3/enum_codec.py
+pyreuser3/native_structs.py
 pyreuser3/rich_ui.py
 pyreuser3/schema.py
 pyreuser3/usr_container.py
@@ -45,7 +46,9 @@ pyreuser3/web/runners.py
 pyreuser3/web/server.py
 pyreuser3/web/settings.py
 tests/test_api_cache.py
+tests/test_discovery_and_web_depth.py
 tests/test_enum_binary.py
 tests/test_enum_codec.py
 tests/test_export_enums.py
+tests/test_native_structs.py
 tests/test_usr_container.py

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

@@ -27,7 +27,7 @@ from pyreuser3 import REUser3Converter
 
 ## What Is Included
 
-- `.user.3 -> JSON` export.
+- `.user.3` and decorated `.user.3.*` (for example `.user.3.X64`) export.
 - `JSON -> .user.3` packing.
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
@@ -41,8 +41,8 @@ or repository-specific helper scripts.
 
 - 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.
+- An `il2cpp_dump.json` file when exporting readable enum labels and validated native structures.
+- One or more unpacked `.user.3` or `.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`.
@@ -78,7 +78,9 @@ pyreuser3 pack \
   -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.
+The `-p/--il2cpp-dump-path` option is required for export and optional for pack. Pass it
+during pack when enum names or readable native structures need to be resolved back to
+binary values. Legacy `{"raw": "..."}` structure values remain packable without it.
 
 Probe a file or directory without loading game metadata:
 
@@ -99,7 +101,9 @@ Start the local `.user.3` export Web UI:
 pyreuser3-web --port 8765
 ```
 
-The Web UI only handles `.user.3` export. It does not pack files.
+The Web UI handles `.user.3` and `.user.3.*` export. It does not pack files.
+Its **Tree Depth** field accepts `auto` or a non-negative integer; an explicit
+integer is passed through to readable reference-tree expansion.
 
 ## Python API
 
@@ -191,6 +195,16 @@ fixtures validate byte-for-byte repacking. V1 and v2 documents are recognized fo
 diagnostics but must be re-exported as v3 before packing because they do not record
 the required layout metadata.
 
+Fixed-width RE Engine value types use a game-independent, declarative codec registry.
+The first supported codecs are `via.Int2`, `via.Uint2`, `via.Range`, `via.RangeI`,
+and `via.Sphere`, including scalar and array fields. A codec is enabled only when the
+active il2cpp dump exactly validates the value type's parent, boxed size, member types,
+and member offsets, and the schema independently agrees on the original type and payload
+size. Matching values are exported as named JSON objects, for example
+`{"x": 10, "y": 20}` or `{"pos": [1.0, 2.0, 3.0], "r": 4.0}`.
+Any absent or mismatched signature fails closed to the existing raw representation;
+legacy raw scalar and array JSON remains accepted for lossless repacking.
+
 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

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

@@ -10,7 +10,7 @@ pip install pyreuser3
 
 ## What Is Included
 
-- `.user.3 -> JSON` export.
+- `.user.3` and decorated `.user.3.*` export.
 - `JSON -> .user.3` packing.
 - A reusable Python API through `REUser3Converter`.
 - CLI commands through `pyreuser3`.
@@ -18,6 +18,8 @@ pip install 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.
+- il2cpp-validated readable codecs for `via.Int2`, `via.Uint2`, `via.Range`,
+  `via.RangeI`, and `via.Sphere`, with scalar/array round trips and raw fallback.
 
 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
@@ -38,8 +40,8 @@ of Python scalar objects.
 
 - 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.
+- An `il2cpp_dump.json` file when exporting readable enum labels and validated native structures.
+- One or more unpacked `.user.3` or `.user.3.*` files.
 
 `pyreuser3 probe` does not require a schema or `il2cpp_dump.json`.
 

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

@@ -29,7 +29,7 @@ from pyreuser3 import REUser3Converter
 
 PyREUser3 当前提供：
 
-- `.user.3 -> JSON` 导出；
+- `.user.3` 以及 `.user.3.X64` 这类 `.user.3.*` 变体导出；
 - `JSON -> .user.3` 封包；
 - 面向其他项目调用的 `REUser3Converter` Python API；
 - `pyreuser3` 命令行工具；
@@ -42,8 +42,8 @@ PyPI 包不会包含游戏资源、游戏 dump、RE_RSZ 模板、`il2cpp_dump.js
 
 - Python 3.9 或更高版本；
 - 与目标游戏和版本匹配的 RE_RSZ schema JSON；
-- 导出可读枚举标签时需要 `il2cpp_dump.json`；
-- 一个或多个已解包的 `.user.3` 文件。
+- 导出可读枚举标签和经验证的原生结构时需要 `il2cpp_dump.json`；
+- 一个或多个已解包的 `.user.3` 或 `.user.3.*` 文件。
 
 布局探测是例外：`pyreuser3 probe` 只检查 USR/RSZ 容器，不需要 schema 或
 `il2cpp_dump.json`。
@@ -82,7 +82,8 @@ pyreuser3 pack \
 说明：
 
 - `export` 时 `-p/--il2cpp-dump-path` 是必填项，用于生成可读枚举标签；
-- `pack` 时 `-p/--il2cpp-dump-path` 是可选项，但如果 JSON 中包含枚举名称，建议传入；
+- `pack` 时 `-p/--il2cpp-dump-path` 是可选项；如果 JSON 中包含枚举名称或可读原生结构，
+  需要传入。旧版 `{"raw": "..."}` 结构值无需 il2cpp 仍可封回；
 - `-s/--schema-path` 必须指向具体 schema JSON 文件，不应传目录；
 - `-i`、`-j` 都可以传单个文件或目录，目录会递归处理。
 
@@ -117,6 +118,9 @@ pyreuser3 export \
 pyreuser3-web --port 8765
 ```
 
+Web 界面的“树深度”可填写 `auto` 或非负整数；显式整数会直接用于 readable
+引用树展开。
+
 默认地址：
 
 ```text
@@ -205,6 +209,13 @@ API 则把它们报告为结构化警告；repack 导出会把同一诊断写入
 获得真实样本并完成逐字节回封验证后才能启用 repack。v1 和 v2 文档仍可识别以便诊断，但由于
 缺少必要的布局元数据，封回前必须从源文件重新导出为 v3。
 
+定长 RE Engine 值类型由与游戏无关的声明式 codec 注册表处理。首批支持
+`via.Int2`、`via.Uint2`、`via.Range`、`via.RangeI` 和 `via.Sphere`，同时覆盖标量与数组。
+只有当前 il2cpp dump 精确验证其值类型父类、boxed size、成员类型和成员偏移，并且 schema
+中的原始类型与 payload size 也一致时，codec 才会启用。匹配的数据会导出为命名 JSON 对象，
+例如 `{"x": 10, "y": 20}` 或 `{"pos": [1.0, 2.0, 3.0], "r": 4.0}`。
+签名缺失或不匹配时会保守退回原有 raw 表示；旧版 raw 标量与数组 JSON 继续支持无损封回。
+
 部分现代文件会用有符号 `-1` 明确表示空 `Object` 引用；repack 会原样保留这个哨兵，同时继续
 拒绝其他不存在的实例 ID。超过一百万项的定长数组会紧凑保存为 `_raw_array_count` 和
 `_raw_array_hex`。这种表示不提供逐项可读性，但能够无损回封、避免展开数百万个 Python 整数，

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

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

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

{pyreuser3-0.8.0 → pyreuser3-0.8.1}/pyreuser3/api.py

@@ -14,7 +14,12 @@ import threading
 from pathlib import Path
 from typing import Any, Callable, Literal, Optional
 
-from .core import RSZ_MAGIC, USR_MAGIC, resolve_schema_path
+from .core import (
+    RSZ_MAGIC,
+    USR_MAGIC,
+    discover_user3_files,
+    resolve_schema_path,
+)
 from .export import User3Exporter
 from .pack import User3Packer
 from .schema import TypeDB
@@ -547,14 +552,7 @@ class REUser3Converter:
         Raises:
             FileNotFoundError: A required file or directory was missing.
         """
-        if user3_root.is_file():
-            return [user3_root]
-        if not user3_root.is_dir():
-            raise FileNotFoundError(f"user3 root not found: {user3_root}")
-        files = sorted(user3_root.rglob("*.user.3"))
-        if not files:
-            raise FileNotFoundError(f"no *.user.3 found under: {user3_root}")
-        return files
+        return discover_user3_files(user3_root)
 
     @staticmethod
     def _run_callback(

{pyreuser3-0.8.0 → pyreuser3-0.8.1}/pyreuser3/cli.py

@@ -105,7 +105,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--input-dir",
         "-i",
         required=True,
-        help="Root directory or single .user.3 file to export.",
+        help="Root directory or single .user.3 / .user.3.* file to export.",
     )
     export_parser.add_argument(
         "--schema-path",
@@ -139,7 +139,10 @@ def build_parser() -> argparse.ArgumentParser:
         "--il2cpp-dump-path",
         "-p",
         required=True,
-        help="Path to il2cpp_dump.json, used to generate enum labels.",
+        help=(
+            "Path to il2cpp_dump.json, used for enum labels and validated "
+            "native structures."
+        ),
     )
     export_parser.add_argument(
         "--json-format",
@@ -178,7 +181,10 @@ def build_parser() -> argparse.ArgumentParser:
         "--il2cpp-dump-path",
         "-p",
         default="",
-        help="Optional il2cpp_dump.json path, used for enum name lookup.",
+        help=(
+            "Optional il2cpp_dump.json path, used for enum lookup and readable "
+            "native structures."
+        ),
     )
     pack_parser.add_argument(
         "--exclude-regex",
@@ -198,7 +204,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--input-dir",
         "-i",
         required=True,
-        help="Root directory or single .user.3 file to inspect.",
+        help="Root directory or single .user.3 / .user.3.* file to inspect.",
     )
     probe_parser.add_argument(
         "--json-report",

{pyreuser3-0.8.0 → pyreuser3-0.8.1}/pyreuser3/core.py

@@ -32,6 +32,7 @@ HEX32_RE = re.compile(r"^[0-9a-fA-F]{32}$")
 # Register enum values through the shared lookup tables so readable labels and numeric
 # packing stay reversible.
 ENUM_UNUSED_KEY = "value__"
+USER3_NAME_MARKER = ".user.3"
 
 ENUM_UNDERLYING_TYPE_MAP = {
     "byte": "U8",
@@ -76,6 +77,48 @@ class ParseError(RuntimeError):
     pass
 
 
+def is_user3_source_path(path: str | Path) -> bool:
+    """Return whether a filename is a binary ``.user.3`` source variant.
+
+    RE Engine resources may append platform or build qualifiers after the normal
+    suffix, for example ``foo.user.3.X64``.  Generated JSON files deliberately do
+    not qualify, even though their names retain the source filename.
+    """
+
+    name = Path(path).name.casefold()
+    marker_index = name.rfind(USER3_NAME_MARKER)
+    if marker_index < 0 or name.endswith(".json"):
+        return False
+    tail = name[marker_index + len(USER3_NAME_MARKER) :]
+    return not tail or tail.startswith(".")
+
+
+def discover_user3_files(root: str | Path) -> list[Path]:
+    """Discover standard and decorated ``.user.3`` files below a root path.
+
+    An explicitly supplied file is preserved for backward compatibility.  Directory
+    discovery accepts both ``*.user.3`` and ``*.user.3.*`` (case-insensitively), while
+    excluding generated ``*.json`` export and pack documents.
+    """
+
+    source_root = Path(root)
+    if source_root.is_file():
+        return [source_root]
+    if not source_root.is_dir():
+        raise FileNotFoundError(f"user3 root not found: {source_root}")
+
+    files = sorted(
+        path
+        for path in source_root.rglob("*")
+        if path.is_file() and is_user3_source_path(path)
+    )
+    if not files:
+        raise FileNotFoundError(
+            f"no .user.3 or .user.3.* files found under: {source_root}"
+        )
+    return files
+
+
 def align(value: int, alignment: int) -> int:
     """Round an offset up to the requested byte alignment.
 

{pyreuser3-0.8.0 → pyreuser3-0.8.1}/pyreuser3/export/base.py

@@ -16,7 +16,12 @@ from .metadata import ExporterMetadataMixin
 from .postprocess import ExporterPostprocessMixin
 from .tree import ExporterTreeMixin
 from .user3 import ExporterUser3ParserMixin
-from ..core import RSZ_MAGIC, USR_MAGIC, resolve_schema_path
+from ..core import (
+    RSZ_MAGIC,
+    USR_MAGIC,
+    discover_user3_files,
+    resolve_schema_path,
+)
 from ..rich_ui import BatchProgress
 from ..schema import TypeDB
 
@@ -106,6 +111,7 @@ class User3Exporter(
         self.bitset_rules: dict[str, str] = {}
         self.param_type_default_enum: dict[str, str] = {}
         self.enum_underlying_types: dict[str, str] = {}
+        self.native_struct_layouts: dict[str, dict] = {}
         self.enum_flags: set[str] = set()
         self.enum_member_to_types: dict[str, list[str]] = {}
         self._pending_enum_context: dict | None = None
@@ -139,7 +145,7 @@ class User3Exporter(
         with BatchProgress(
             "Exporting user3", total=len(files), unit="file"
         ) as progress:
-            progress.log(f"Found {len(files)} .user.3 file(s).")
+            progress.log(f"Found {len(files)} user3 source file(s).")
             progress.log(f"Schema: {self.schema_path}")
             progress.log(f"Output directory: {self.output_root}")
             for user3_file in files:
@@ -237,14 +243,7 @@ class User3Exporter(
         Raises:
             FileNotFoundError: A required file or directory was missing.
         """
-        if self.user3_root.is_file():
-            files = [self.user3_root]
-        else:
-            if not self.user3_root.is_dir():
-                raise FileNotFoundError(f"user3 root not found: {self.user3_root}")
-            files = sorted(self.user3_root.rglob("*.user.3"))
-            if not files:
-                raise FileNotFoundError(f"no *.user.3 found under: {self.user3_root}")
+        files = discover_user3_files(self.user3_root)
         if not self._exclude_patterns:
             return files
 
@@ -260,7 +259,9 @@ class User3Exporter(
                 continue
             kept.append(file_path)
         if not kept:
-            raise FileNotFoundError("all *.user.3 files were excluded by regex filters")
+            raise FileNotFoundError(
+                "all .user.3 and .user.3.* files were excluded by regex filters"
+            )
         return kept
 
     def _output_path_for(self, user3_file: Path) -> Path:

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

@@ -13,6 +13,7 @@ from pathlib import Path
 from typing import Any
 
 from ..core import ENUM_UNUSED_KEY, normalize_enum_storage_type
+from ..native_structs import collect_validated_native_struct_layout
 
 
 _FIXED_ENUM_RE = re.compile(r"[A-Za-z0-9_.+]+_Fixed")
@@ -298,6 +299,7 @@ class ExporterEnumSourceMixin:
             "bitset_rules": {},
             "generic_candidates": {},
             "enum_underlying_types": {},
+            "native_struct_layouts": {},
             "enum_types": set(),
             "serializable_fallback_candidates": [],
             "fixed_backing_candidates": [],
@@ -311,6 +313,11 @@ class ExporterEnumSourceMixin:
         if not isinstance(class_name, str) or not isinstance(obj, dict):
             return
 
+        native_layout = collect_validated_native_struct_layout(class_name, obj)
+        if native_layout is not None:
+            type_name, descriptor = native_layout
+            state["native_struct_layouts"][type_name] = descriptor
+
         if obj.get("parent") == "System.Enum":
             state["enum_types"].add(class_name)
         if obj.get("parent") == "System.Enum":
@@ -521,6 +528,7 @@ class ExporterEnumSourceMixin:
             "generic_scalar_rules": state["generic_scalar_rules"],
             "bitset_rules": state["bitset_rules"],
             "enum_underlying_types": state["enum_underlying_types"],
+            "native_struct_layouts": state["native_struct_layouts"],
         }
 
     @classmethod

{pyreuser3-0.8.0 → pyreuser3-0.8.1}/pyreuser3/export/fields.py

@@ -18,6 +18,11 @@ from ..core import (
     enum_storage_size,
     enum_storage_type_from_size,
 )
+from ..native_structs import (
+    NativeStructValueError,
+    decode_native_struct,
+    resolve_native_struct_codec,
+)
 from ..schema import ClassDef, FieldDef
 
 
@@ -141,6 +146,18 @@ class ExporterFieldParserMixin:
             count = max(field.size // 4, 1)
             return [reader.read_f32() for _ in range(count)]
 
+        codec = resolve_native_struct_codec(
+            field, getattr(self, "native_struct_layouts", {})
+        )
+        if codec is not None and reader.size - reader.tell() >= codec.payload_size:
+            payload = reader.read(codec.payload_size)
+            try:
+                return decode_native_struct(codec, payload)
+            except NativeStructValueError:
+                # Non-finite float payloads and any future non-lossless cases stay raw
+                # so a JSON round trip cannot silently alter their bit patterns.
+                return {"raw": payload.hex(), "type": t}
+
         if field.size <= 0:
             return None
         to_read = max(0, min(field.size, reader.size - reader.tell()))

{pyreuser3-0.8.0 → pyreuser3-0.8.1}/pyreuser3/export/metadata.py

@@ -12,6 +12,7 @@ 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 ..native_structs import normalize_native_struct_layouts
 from ..rich_ui import get_console
 
 
@@ -242,8 +243,13 @@ class ExporterMetadataMixin:
         self.bitset_rules = {}
         self.param_type_default_enum = {}
         self.enum_underlying_types = {}
+        self.native_struct_layouts = {}
         self.enum_flags = set()
 
+        self.native_struct_layouts = normalize_native_struct_layouts(
+            raw.get("native_struct_layouts")
+        )
+
         class_field_fixed_types = raw.get("class_field_fixed_types")
         if isinstance(class_field_fixed_types, dict):
             for cls_name, field_map in class_field_fixed_types.items():