arkparser 0.4.4__tar.gz → 0.4.5__tar.gz

{arkparser-0.4.4 → arkparser-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.4.4
+Version: 0.4.5
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -302,7 +302,8 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | `torp`, `temp` | added | same source, indices legacy never emitted |
 | `active` | legacy | last-active datetime; currently `null` (placeholder for parity) |
 | `ccc` | legacy | `"0 0 0"` (no in-world position from profile/cluster source) |
-| `achievements`, `inventory`, `netAddress` | legacy | reserved arrays/string (currently empty for parity) |
+| `achievements` | legacy | reserved array (currently empty for parity) |
+| `netAddress` | legacy (now populated) | Last client IP ARK persisted (`SavedNetworkAddress` in profile `MyData`). Legacy ASVExport reads the same field (ContentPlayer.cs:157 ASE / :341 ASA). `""` when the profile lacks it (e.g. never-played placeholders). ASA stores a clean IPv4/IPv6 string; some ASE saves store an engine-truncated value (e.g. `"[2001"`) reproduced verbatim, matching legacy. |
 | `steamid`, `dataFile` | legacy | platform net id and `{steamid}.arkprofile` filename |
 | `active` | legacy (now populated) | ISO 8601 datetime of last login, converted from profile `LastLoginTime` or in-world pawn `SavedLastTimeHadController`. Legacy schema reserved the field but the old C# exporter only filled it for in-world pawns; the parser fills it for profiles too. `null` when neither source is present. |
 | `lat`, `lon`, `ccc` | legacy (now populated) | In-world position when the record was built from a `PlayerPawn` GameObject. Records sourced from profile / cluster files keep the legacy `0` / `"0 0 0"` placeholders since profiles carry no world position. |

{arkparser-0.4.4 → arkparser-0.4.5}/README.md

@@ -268,7 +268,8 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | `torp`, `temp` | added | same source, indices legacy never emitted |
 | `active` | legacy | last-active datetime; currently `null` (placeholder for parity) |
 | `ccc` | legacy | `"0 0 0"` (no in-world position from profile/cluster source) |
-| `achievements`, `inventory`, `netAddress` | legacy | reserved arrays/string (currently empty for parity) |
+| `achievements` | legacy | reserved array (currently empty for parity) |
+| `netAddress` | legacy (now populated) | Last client IP ARK persisted (`SavedNetworkAddress` in profile `MyData`). Legacy ASVExport reads the same field (ContentPlayer.cs:157 ASE / :341 ASA). `""` when the profile lacks it (e.g. never-played placeholders). ASA stores a clean IPv4/IPv6 string; some ASE saves store an engine-truncated value (e.g. `"[2001"`) reproduced verbatim, matching legacy. |
 | `steamid`, `dataFile` | legacy | platform net id and `{steamid}.arkprofile` filename |
 | `active` | legacy (now populated) | ISO 8601 datetime of last login, converted from profile `LastLoginTime` or in-world pawn `SavedLastTimeHadController`. Legacy schema reserved the field but the old C# exporter only filled it for in-world pawns; the parser fills it for profiles too. `null` when neither source is present. |
 | `lat`, `lon`, `ccc` | legacy (now populated) | In-world position when the record was built from a `PlayerPawn` GameObject. Records sourced from profile / cluster files keep the legacy `0` / `"0 0 0"` placeholders since profiles carry no world position. |

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser/__init__.py

@@ -95,4 +95,4 @@ __all__ = [
     "ArkParseError",
 ]
 
-__version__ = "0.4.4"
+__version__ = "0.4.5"

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser/common/binary_reader.py

@@ -22,7 +22,6 @@ Example:
 from __future__ import annotations
 
 import struct
-import typing as t
 from pathlib import Path
 from uuid import UUID
 

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser/common/map_config.py

@@ -11,7 +11,6 @@ Where x, y are Unreal Engine world coordinates.
 from __future__ import annotations
 
 import logging
-import typing as t
 from dataclasses import dataclass
 from pathlib import Path
 

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser/common/version_detection.py

@@ -19,7 +19,6 @@ World saves (.ark files) have different headers:
 
 from __future__ import annotations
 
-import typing as t
 from enum import Enum
 from pathlib import Path
 

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser/export.py

@@ -1684,7 +1684,7 @@ def _player_from_profile(
         "ccc": "0 0 0",
         "achievements": [],
         "inventory": [],
-        "netAddress": "",
+        "netAddress": _str(profile.last_net_address),
         "engram_points": profile.total_engram_points,
         "experience": _int(profile.experience),
         "current_stats": _current_stats_dict(status),

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser/files/profile.py

@@ -207,6 +207,25 @@ class Profile(ArkFile):
         except (TypeError, ValueError):
             return None
 
+    @property
+    def last_net_address(self) -> str | None:
+        """Last client IP / network address ARK persisted for this player.
+
+        Read from ``SavedNetworkAddress`` on the profile's ``MyData`` struct
+        (same level as ``LastLoginTime``). Legacy ASVExport reads this exact
+        field (ContentPlayer.cs:157 ASE / :341 ASA) and emits it as the
+        ``netAddress`` player key. Returns ``None`` when the field is absent
+        (e.g. empty placeholder profiles that were never played).
+
+        ASA stores a clean IPv4/IPv6 string; some ASE saves store an
+        engine-truncated value (e.g. ``"[2001"``) which is reproduced
+        verbatim - matching what legacy ASVExport emits for the same save.
+        """
+        val = self._player_data.get("SavedNetworkAddress")
+        if val is None:
+            return None
+        return str(val)
+
     @property
     def total_engram_points(self) -> int:
         """Get total engram points spent."""

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser/files/world_save.py

@@ -44,6 +44,11 @@ logger = logging.getLogger(__name__)
 # ASE GUIDs are always all-zero; precomputed sentinel skips UUID construction.
 _ZERO_GUID = b"\x00" * 16
 
+# Upper bound on ASA name-table entries (largest observed real table ~4.6k).
+# A count above this means the read is misaligned (a garbage int32 length),
+# so we fail loudly instead of looping over ~billions of phantom entries.
+_MAX_ASA_NAME_TABLE = 1_000_000
+
 
 @dataclass
 class EmbeddedData:
@@ -683,50 +688,79 @@ class WorldSave:
         reader = BinaryReader.from_bytes(row[0])
 
         self.version = reader.read_int16()
-        _legacy_offset = reader.read_int32()
-        # v14+ adds two int32 fields (unk1, actual_offset) between
+        legacy_offset = reader.read_int32()
+        # v14+ adds two int32 fields (unk1, name_table_offset) between
         # legacy_offset and game_time; v13 saves jump straight to game_time.
         # Without this version gate we mis-align the read by 8 bytes and the
-        # data_files / name_table loops walk into garbage.
+        # data_files loop walks into garbage.
+        name_table_offset = legacy_offset  # v13: table follows the parts section
         if self.version >= 14:
             _unknown1 = reader.read_int32()
-            _actual_offset = reader.read_int32()
+            name_table_offset = reader.read_int32()  # absolute offset of name table
         self.game_time = reader.read_double()
         _unknown2 = reader.read_int32()
 
-        # Data files
+        # Data files (immediately follow the header; populate self.data_files).
         count = reader.read_int32()
         self.data_files = []
         for _ in range(count):
             self.data_files.append(reader.read_string())
-            _term = reader.read_int32()
-
-        _pad1 = reader.read_int32()
-        _pad2 = reader.read_int32()
+            _term = reader.read_int32()  # per-entry terminator, always -1
 
-        # Name table (dict keyed by hash for ASA).
+        # Name table (dict keyed by FName hash for ASA).
         #
-        # Most ASA saves serialize the table as a flat ``(hash, strlen,
-        # string)`` triple per entry.  Some maps (observed on Ragnarok,
-        # Scorched Earth and TheIsland on busy servers) prepend
-        # user-placed-structure name entries that carry an extra 4-byte
-        # trailer after the string; those entries always have
-        # ``hash == 1`` as a sentinel.  Detect that sentinel per-entry and
-        # consume the trailer so the rest of the table parses normally.
-        # Without this, parsing the next entry's hash misreads the trailer
-        # as a string length and explodes with EndOfDataError on a ~500 MB
-        # phantom string.
+        # v14+: the engine stores the table at an explicit absolute offset
+        # (name_table_offset = the 2nd int32 after legacy_offset). The bytes
+        # between the data-files section and that offset are NOT a fixed pad
+        # pair on every map - on busy/modded saves (measured: Ragnarok +26 B,
+        # Scorched Earth +31 B past where a sequential read lands) the table
+        # would be read truncated, leaving ~half the class refs resolving to
+        # __UNKNOWN_CLASS_<hash>__. Seek to the offset like the C# reference
+        # (AsaSavegame.readNametable: ``archive.Position = nameTableOffset``).
+        # Where the gap is zero (TheIsland, Aberration, Extinction) the seek is
+        # a no-op; where it drifts it recovers every leaked class name.
+        if self.version >= 14:
+            assert 0 <= name_table_offset <= reader.size, (
+                f"ASA name-table offset {name_table_offset} out of range "
+                f"(blob size {reader.size})"
+            )
+            reader.position = name_table_offset
+            self.name_table = self._read_asa_name_table(reader)
+        else:
+            # v13: no explicit offset field. Retain the historical sequential
+            # read (two pad int32s, then the table) - there is no live v13
+            # fixture to validate a seek against. The idx==1 sentinel consumes
+            # the 4-byte trailer on user-placed-actor entries.
+            reader.read_int32()  # pad1
+            reader.read_int32()  # pad2
+            self.name_table = self._read_asa_name_table(reader, sentinel=True)
+
+    def _read_asa_name_table(
+        self, reader: BinaryReader, sentinel: bool = False
+    ) -> dict[int, str]:
+        """Read an ASA name table (FName-hash -> class string) at ``reader``'s position.
+
+        Preconditions: ``reader`` is positioned at the table's int32 entry
+        count. Postconditions: returns ``{hash: trimmed_class_string}`` (the
+        substring after the last ``.``) and advances the reader past the table.
+        ``sentinel`` consumes the extra 4-byte trailer following
+        user-placed-actor entries (``idx == 1``) on the v13 sequential path; it
+        is unused on the v14 seek path.
+        """
+        assert reader.remaining >= 4, "no room for ASA name-table count"
         name_count = reader.read_int32()
+        assert 0 <= name_count <= _MAX_ASA_NAME_TABLE, (
+            f"implausible ASA name-table count {name_count} - misaligned read"
+        )
         nt: dict[int, str] = {}
         for _ in range(name_count):
             idx = reader.read_int32()
             raw = reader.read_string()
             nt[idx] = raw.rsplit(".", 1)[-1] if "." in raw else raw
-            if idx == 1:
-                # User-placed-actor name sentinel: skip the 4-byte sub-id /
-                # trailing tag that follows on these entries.
+            if sentinel and idx == 1:
+                # User-placed-actor sentinel: skip the trailing 4-byte tag.
                 reader.skip(4)
-        self.name_table = nt
+        return nt
 
     def _read_asa_actor_locations(self, conn: sqlite3.Connection) -> None:
         """Parse the ``ActorTransforms`` blob."""

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser/properties/compound.py

@@ -540,14 +540,36 @@ def _read_array_elements(
             if reader.position < array_data_end:
                 reader.skip(array_data_end - reader.position)
         else:
-            # ASE struct arrays - read as property-based structs
+            # ASE struct arrays. Resolve the element struct type the way legacy
+            # does (ArkArrayStruct.Init): the array-name map first, else INFER a
+            # native fixed-size type from the body size, where the body is the
+            # int32 count prefix (4) plus count * element_size. Without the size
+            # inference, native struct arrays addressed only by name (e.g.
+            # CustomItemColors = Color[6], data_size 28 = 6*4+4) are misread as
+            # property-list structs, the cursor drifts, and every later property
+            # in the object is corrupted (EndOfDataError on a garbage length).
+            struct_type = struct_registry.get_array_struct_type(array_name)
+            # ASE only: infer the native element type from the body size when the
+            # array name isn't mapped (legacy ArkArrayStruct.Init). Gated to ASE
+            # (not is_asa) so the ASA v6 struct-array path is untouched. The check
+            # is exact, and a property-list element is >= 9 bytes (min "None"
+            # terminator), so these equalities never match a property-list array.
+            if struct_type is None and not is_asa and count > 0:
+                if count * 4 + 4 == data_size:
+                    struct_type = "Color"
+                elif count * 12 + 4 == data_size:
+                    struct_type = "Vector"
+                elif count * 16 + 4 == data_size:
+                    struct_type = "LinearColor"
             for _ in range(count):
-                struct = struct_registry.read_struct_for_array(
-                    reader,
-                    array_name,
-                    is_asa,
-                    name_table=name_table,
-                )
+                if struct_type is not None:
+                    struct = struct_registry.read_struct(
+                        reader, struct_type, is_asa, name_table=name_table
+                    )
+                else:
+                    struct = struct_registry.read_struct_for_array(
+                        reader, array_name, is_asa, name_table=name_table
+                    )
                 if hasattr(struct, "to_dict"):
                     values.append(struct.to_dict())
                 else:
@@ -1206,7 +1228,7 @@ class MapProperty(Property):
         # Handle value type sub-header
         if value_type == "StructProperty":
             _struct_marker = reader.read_int32()  # Usually 1, sometimes 2+
-            struct_type_id = reader.read_int32()
+            _struct_type_id = reader.read_int32()
             _struct_type_inst = reader.read_int32()
             _script_marker = reader.read_int32()
             _script_path_id = reader.read_int32()

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.4.4
+Version: 0.4.5
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -302,7 +302,8 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | `torp`, `temp` | added | same source, indices legacy never emitted |
 | `active` | legacy | last-active datetime; currently `null` (placeholder for parity) |
 | `ccc` | legacy | `"0 0 0"` (no in-world position from profile/cluster source) |
-| `achievements`, `inventory`, `netAddress` | legacy | reserved arrays/string (currently empty for parity) |
+| `achievements` | legacy | reserved array (currently empty for parity) |
+| `netAddress` | legacy (now populated) | Last client IP ARK persisted (`SavedNetworkAddress` in profile `MyData`). Legacy ASVExport reads the same field (ContentPlayer.cs:157 ASE / :341 ASA). `""` when the profile lacks it (e.g. never-played placeholders). ASA stores a clean IPv4/IPv6 string; some ASE saves store an engine-truncated value (e.g. `"[2001"`) reproduced verbatim, matching legacy. |
 | `steamid`, `dataFile` | legacy | platform net id and `{steamid}.arkprofile` filename |
 | `active` | legacy (now populated) | ISO 8601 datetime of last login, converted from profile `LastLoginTime` or in-world pawn `SavedLastTimeHadController`. Legacy schema reserved the field but the old C# exporter only filled it for in-world pawns; the parser fills it for profiles too. `null` when neither source is present. |
 | `lat`, `lon`, `ccc` | legacy (now populated) | In-world position when the record was built from a `PlayerPawn` GameObject. Records sourced from profile / cluster files keep the legacy `0` / `"0 0 0"` placeholders since profiles carry no world position. |

{arkparser-0.4.4 → arkparser-0.4.5}/arkparser.egg-info/SOURCES.txt

@@ -40,6 +40,8 @@ arkparser/structs/property_list.py
 arkparser/structs/registry.py
 arkparser/structs/vectors.py
 tests/test_asa_header_position.py
+tests/test_asa_name_table.py
+tests/test_ase_cluster_drift.py
 tests/test_binary_reader.py
 tests/test_binary_reader_layouts.py
 tests/test_cloud_export.py

{arkparser-0.4.4 → arkparser-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arkparser"
-version = "0.4.4"
+version = "0.4.5"
 description = "Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files"
 readme = "README.md"
 license = "MIT"

arkparser-0.4.5/tests/test_asa_name_table.py

@@ -0,0 +1,51 @@
+"""Regression test for KNOWN_ISSUES #1: ASA ``__UNKNOWN_CLASS_`` name-table leak.
+
+Root cause: arkparser read the ASA worldsave name table sequentially after the
+data-files section instead of seeking to the v14 header's name-table offset
+(``actual_offset``). On maps where the sequential cursor landed short of that
+offset (ragnarok, scorchedearth) the table was truncated and ~half the class
+references resolved to ``__UNKNOWN_CLASS_<hash>__``. Fix: seek to
+``actual_offset`` on v14+ (mirrors C# ``AsaSavegame.readNametable``).
+
+Fixture-gated: uses real saves under
+``references/local_saves/survival_ascended/`` which are not committed; skips
+when absent (same convention as ``conftest`` example fixtures).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from arkparser import WorldSave
+
+SAVES = (
+    Path(__file__).resolve().parent.parent
+    / "references"
+    / "local_saves"
+    / "survival_ascended"
+)
+
+
+def _ark_or_skip(map_name: str) -> Path:
+    d = SAVES / map_name
+    arks = sorted(d.glob("*_WP.ark")) if d.exists() else []
+    if not arks:
+        pytest.skip(f"Fixture not available: {d}\\*_WP.ark")
+    return arks[0]
+
+
+@pytest.mark.parametrize("map_name", ["scorchedearth_wp", "ragnarok_wp"])
+def test_asa_name_table_no_unknown_class(map_name: str) -> None:
+    """Every parsed object resolves to a real class name (no name-table drift)."""
+    save = WorldSave.load(_ark_or_skip(map_name))
+    unknown = [
+        o.class_name
+        for o in save.objects
+        if str(getattr(o, "class_name", "") or "").startswith("__UNKNOWN_CLASS_")
+    ]
+    assert not unknown, (
+        f"{map_name}: {len(unknown)} objects leaked __UNKNOWN_CLASS_ "
+        f"(e.g. {unknown[:3]})"
+    )

arkparser-0.4.5/tests/test_ase_cluster_drift.py

@@ -0,0 +1,51 @@
+"""Regression test for KNOWN_ISSUES #2: ASE cloud/cluster cursor drift.
+
+Root cause: ASE struct arrays of native fixed-size structs addressed only by
+name (e.g. ``CustomItemColors`` = ``Color[]``) were read as property-list
+structs because the array name was not in ``ARRAY_NAME_TO_STRUCT_TYPE``. That
+mis-read drifted the cursor and a later property-name length read exploded with
+``EndOfDataError``, so the whole cluster file (and all its uploads) was dropped.
+
+Fix: ``_read_array_elements`` now infers the native element type from the array
+body size when the name is unmapped (mirrors legacy ``ArkArrayStruct.Init``:
+``count*4+4 == data_size`` -> Color, ``*12`` -> Vector, ``*16`` -> LinearColor).
+
+Fixture-gated: uses real cluster files under
+``references/local_saves/ase_cluster_drift/`` (not committed - they hold player
+upload data); skips when absent.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from arkparser import CloudInventory
+
+DRIFT_DIR = (
+    Path(__file__).resolve().parent.parent
+    / "references"
+    / "local_saves"
+    / "ase_cluster_drift"
+)
+
+# (filename, minimum uploaded-item count) for files that used to raise
+# EndOfDataError mid-parse on the CustomItemColors native-struct array.
+CASES = [
+    ("2533274829298794", 50),
+    ("2533274854487560", 9),
+    ("2533274905839355", 3),
+]
+
+
+@pytest.mark.parametrize(("name", "min_items"), CASES)
+def test_ase_cluster_native_struct_array_no_drift(name: str, min_items: int) -> None:
+    """Previously-drifting cluster files parse fully and recover their uploads."""
+    p = DRIFT_DIR / name
+    if not p.exists():
+        pytest.skip(f"Fixture not available: {p}")
+    inv = CloudInventory.load(p)  # used to raise EndOfDataError mid-parse
+    assert inv.item_count >= min_items, (
+        f"{name}: expected >= {min_items} items, got {inv.item_count}"
+    )