arkparser 0.7.0__tar.gz → 0.7.1__tar.gz

{arkparser-0.7.0 → arkparser-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.7.0
+Version: 0.7.1
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -681,6 +681,15 @@ Schema policy:
 
 ASA worldsave property layouts differ between **v13** (`TheIsland_WP` and older single-player saves, legacy `AsaSavegameToolkit`-style `dataSize + position + typeRef + byte` body) and **v14+** (current production ASA, marker-based body). Both are parsed by version-aware property readers; `WorldSave.version` is the source of truth.
 
+### Parse diagnostics (logging)
+
+The parser logs through the standard `logging` module on the `arkparser.*` logger hierarchy. At DEBUG level it reports recoverable parse anomalies, for example ASE objects whose property block terminates early (the run of successfully parsed properties is kept and the remaining bytes are preserved on `GameObject.extra_data`):
+
+```python
+import logging
+logging.getLogger("arkparser").setLevel(logging.DEBUG)
+```
+
 ### Known limitation: ASA cryopod property blocks are partially decoded
 
 ASA cryopods (`PrimalItem_WeaponEmptyCryopod_C`, `SoulTrap`, `Vivarium`, `DinoBall`) store the embedded creature snapshot inside the item's `CustomItemDatas.CustomDataBytes.ByteArrays[0]` as a **zlib + custom-RLE compressed `AsaDataStore` blob**. The parser surfaces the snapshot via the simpler `CustomDataStrings` / `CustomDataFloats` accessors, exposing **species, tamed name, level, color regions, and `CurrentStatusValues[0..11]`** on each cryopodded creature.

{arkparser-0.7.0 → arkparser-0.7.1}/README.md

@@ -647,6 +647,15 @@ Schema policy:
 
 ASA worldsave property layouts differ between **v13** (`TheIsland_WP` and older single-player saves, legacy `AsaSavegameToolkit`-style `dataSize + position + typeRef + byte` body) and **v14+** (current production ASA, marker-based body). Both are parsed by version-aware property readers; `WorldSave.version` is the source of truth.
 
+### Parse diagnostics (logging)
+
+The parser logs through the standard `logging` module on the `arkparser.*` logger hierarchy. At DEBUG level it reports recoverable parse anomalies, for example ASE objects whose property block terminates early (the run of successfully parsed properties is kept and the remaining bytes are preserved on `GameObject.extra_data`):
+
+```python
+import logging
+logging.getLogger("arkparser").setLevel(logging.DEBUG)
+```
+
 ### Known limitation: ASA cryopod property blocks are partially decoded
 
 ASA cryopods (`PrimalItem_WeaponEmptyCryopod_C`, `SoulTrap`, `Vivarium`, `DinoBall`) store the embedded creature snapshot inside the item's `CustomItemDatas.CustomDataBytes.ByteArrays[0]` as a **zlib + custom-RLE compressed `AsaDataStore` blob**. The parser surfaces the snapshot via the simpler `CustomDataStrings` / `CustomDataFloats` accessors, exposing **species, tamed name, level, color regions, and `CurrentStatusValues[0..11]`** on each cryopodded creature.

{arkparser-0.7.0 → arkparser-0.7.1}/arkparser/common/types.py

@@ -21,6 +21,17 @@ from dataclasses import dataclass
 # The "None" name is used as a terminator in property lists
 NAME_NONE = "None"
 
+# Class-name / blueprint fragments that mark a creature-storage item.
+# Single source of truth for cryopod detection: in-world iteration
+# (WorldSave.iter_cryopod_creatures), inventory filtering (export), and
+# uploaded-item checks (UploadedItem.is_cryopod) all match against this.
+CRYOPOD_CLASS_PATTERNS: tuple[str, ...] = (
+    "Cryopod",
+    "SoulTrap",
+    "Vivarium",
+    "DinoBall",
+)
+
 
 # =============================================================================
 # ArkName (FName)

{arkparser-0.7.0 → arkparser-0.7.1}/arkparser/data_models.py

@@ -15,10 +15,14 @@ from dataclasses import dataclass, field
 
 from .common.binary_reader import BinaryReader
 from .common.normalization import normalize_indexed_data, normalize_indexed_list
+from .common.types import CRYOPOD_CLASS_PATTERNS
 from .properties.registry import read_properties
 
 logger = logging.getLogger(__name__)
 
+# Uploaded items match against lowercased blueprint paths.
+_CRYOPOD_PATTERNS_LOWER: tuple[str, ...] = tuple(p.lower() for p in CRYOPOD_CLASS_PATTERNS)
+
 # Trailing UE actor spawn-instance suffix on cryopod class names, e.g.
 # "Raptor_Character_BP_C_2145673735". ARK stores the full instance name in the
 # cryopod CustomDataStrings/SoftClasses blob; the worldsave name-table path
@@ -820,7 +824,7 @@ class UploadedItem:
     def is_cryopod(self) -> bool:
         """Check if this item is a cryopod (or similar creature storage item)."""
         bp_lower = self.blueprint.lower()
-        return any(x in bp_lower for x in ["cryopod", "soultrap", "vivarium", "dinoball"])
+        return any(x in bp_lower for x in _CRYOPOD_PATTERNS_LOWER)
 
     @property
     def cryopod_creature(self) -> CryopodCreature | None:

{arkparser-0.7.0 → arkparser-0.7.1}/arkparser/export.py

@@ -44,21 +44,14 @@ from pathlib import Path
 from arkparser.common.exceptions import ArkParseError
 from arkparser.common.map_config import MapConfig
 from arkparser.common.normalization import normalize_indexed_data, normalize_indexed_list
+from arkparser.common.types import CRYOPOD_CLASS_PATTERNS
 from arkparser.data_models import CryopodCreature
 from arkparser.files import CloudInventory, Profile, Tribe
 
 logger = logging.getLogger(__name__)
 
-_CRYOPOD_CLASS_PATTERNS: tuple[str, ...] = (
-    "Cryopod",
-    "SoulTrap",
-    "Vivarium",
-    "DinoBall",
-)
-
-
 def _is_cryopod_class(class_name: str) -> bool:
-    return any(p in class_name for p in _CRYOPOD_CLASS_PATTERNS)
+    return any(p in class_name for p in CRYOPOD_CLASS_PATTERNS)
 
 
 def _decode_inventory_cryopod(item_obj: t.Any) -> CryopodCreature | None:
@@ -152,6 +145,10 @@ _LEGACY_STAT_ORDER: tuple[str, ...] = (
 )
 _EXTRA_STAT_ORDER: tuple[str, ...] = ("torp", "water", "temp", "fort")
 _FLAT_STAT_ORDER: tuple[str, ...] = _LEGACY_STAT_ORDER + _EXTRA_STAT_ORDER
+# The order tuples are hand-maintained views of _STAT_NAMES; catch drift at
+# import time before it silently misaligns exported stat JSON.
+assert len(_FLAT_STAT_ORDER) == len(_STAT_NAMES), "stat order tuples out of sync"
+assert set(_FLAT_STAT_ORDER) == set(_STAT_NAMES), "stat order tuples out of sync"
 
 
 def _prop(obj: t.Any, name: str, default: t.Any = None, index: int | None = None) -> t.Any:
@@ -2519,8 +2516,7 @@ def _tribe_from_object(
     tribe_id = _int(_prop(obj, "TribeID")) or _int(_prop(obj, "TribeId"))
     owner_id = _int(_prop(obj, "OwnerPlayerDataID")) or _int(_prop(obj, "OwnerPlayerDataId"))
     members: list[dict[str, t.Any]] = []
-    i = 0
-    while True:
+    for i in range(_MAX_TRIBE_MEMBERS):
         pid = _prop(obj, "MembersPlayerDataID", index=i)
         if pid is None:
             break
@@ -2536,15 +2532,14 @@ def _tribe_from_object(
                 "steamid": (profile.unique_id or "") if profile is not None else "",
             }
         )
-        i += 1
+    assert len(members) < _MAX_TRIBE_MEMBERS, "tribe member list exceeded bound"
     alliances: list[int] = []
-    j = 0
-    while True:
+    for j in range(_MAX_TRIBE_MEMBERS):
         val = _prop(obj, "TribeAlliances", index=j)
         if val is None:
             break
         alliances.append(_int(val))
-        j += 1
+    assert len(alliances) < _MAX_TRIBE_MEMBERS, "tribe alliance list exceeded bound"
     c = counts.get(tribe_id, {})
     data: dict[str, t.Any] = {
         "tribeid": tribe_id,
@@ -2569,14 +2564,15 @@ def _tribe_object_logs(obj: t.Any) -> list[str]:
     if isinstance(log_val, list):
         return [e for e in log_val if isinstance(e, str) and e.strip()]
     out: list[str] = []
-    k = 0
-    while True:
+    entries = 0
+    for k in range(_MAX_TRIBE_MEMBERS):
         v = _prop(obj, "TribeLog", index=k)
         if v is None:
             break
+        entries += 1
         if isinstance(v, str) and v.strip():
             out.append(v)
-        k += 1
+    assert entries < _MAX_TRIBE_MEMBERS, "tribe log list exceeded bound"
     return out
 
 

{arkparser-0.7.0 → arkparser-0.7.1}/arkparser/files/world_save.py

@@ -34,6 +34,7 @@ from uuid import UUID
 from ..common.binary_reader import BinaryReader, guid_str_le
 from ..common.exceptions import ArkParseError, CorruptDataError
 from ..common.normalization import normalize_indexed_data, normalize_indexed_list
+from ..common.types import CRYOPOD_CLASS_PATTERNS
 from ..data_models import CryopodCreature
 from ..game_objects.container import GameObjectContainer
 from ..game_objects.game_object import MAX_OBJECT_COUNT, GameObject
@@ -428,13 +429,10 @@ class WorldSave:
         """Return creature nest objects (wyvern, drake, etc.)."""
         return self.container.get_nests()
 
-    # Class-name fragments that indicate a creature-storage item. Mirrors
-    # data_models.UploadedItem.is_cryopod (which matches against blueprint
-    # paths); the in-world version matches against the GameObject's
-    # ``class_name`` directly.
-    _CRYOPOD_PATTERNS: t.ClassVar[tuple[str, ...]] = (
-        "Cryopod", "SoulTrap", "Vivarium", "DinoBall",
-    )
+    # Shared with data_models.UploadedItem.is_cryopod (blueprint paths) and
+    # the export inventory filter; the in-world version matches against the
+    # GameObject's ``class_name`` directly.
+    _CRYOPOD_PATTERNS: t.ClassVar[tuple[str, ...]] = CRYOPOD_CLASS_PATTERNS
 
     def iter_cryopod_creatures(self) -> t.Iterator[tuple[GameObject, CryopodCreature]]:
         """Yield ``(item_obj, CryopodCreature)`` for every *filled* cryopod

{arkparser-0.7.0 → arkparser-0.7.1}/arkparser/game_objects/game_object.py

@@ -7,6 +7,7 @@ Game objects represent creatures, items, structures, players, and other entities
 
 from __future__ import annotations
 
+import logging
 import re
 import typing as t
 from collections import defaultdict
@@ -16,6 +17,8 @@ from ..common.exceptions import CorruptDataError
 from ..properties.registry import read_properties, read_property
 from .location import LocationData
 
+logger = logging.getLogger(__name__)
+
 if t.TYPE_CHECKING:
     from ..common.binary_reader import BinaryReader
     from ..properties.base import Property
@@ -420,11 +423,18 @@ class GameObject:
                     if prop is None:
                         break
                     properties.append(prop)
-            except Exception:
+            except Exception as exc:
                 self.properties = properties
                 self._props_loaded = True
                 if next_object is None:
                     raise
+                logger.debug(
+                    "property parse stopped early for %s after %d properties, "
+                    "remainder kept as extra_data: %s",
+                    self.class_name,
+                    len(properties),
+                    exc,
+                )
 
                 next_offset = properties_block_offset + next_object.properties_offset
                 remaining = next_offset - reader.position

{arkparser-0.7.0 → arkparser-0.7.1}/arkparser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.7.0
+Version: 0.7.1
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -681,6 +681,15 @@ Schema policy:
 
 ASA worldsave property layouts differ between **v13** (`TheIsland_WP` and older single-player saves, legacy `AsaSavegameToolkit`-style `dataSize + position + typeRef + byte` body) and **v14+** (current production ASA, marker-based body). Both are parsed by version-aware property readers; `WorldSave.version` is the source of truth.
 
+### Parse diagnostics (logging)
+
+The parser logs through the standard `logging` module on the `arkparser.*` logger hierarchy. At DEBUG level it reports recoverable parse anomalies, for example ASE objects whose property block terminates early (the run of successfully parsed properties is kept and the remaining bytes are preserved on `GameObject.extra_data`):
+
+```python
+import logging
+logging.getLogger("arkparser").setLevel(logging.DEBUG)
+```
+
 ### Known limitation: ASA cryopod property blocks are partially decoded
 
 ASA cryopods (`PrimalItem_WeaponEmptyCryopod_C`, `SoulTrap`, `Vivarium`, `DinoBall`) store the embedded creature snapshot inside the item's `CustomItemDatas.CustomDataBytes.ByteArrays[0]` as a **zlib + custom-RLE compressed `AsaDataStore` blob**. The parser surfaces the snapshot via the simpler `CustomDataStrings` / `CustomDataFloats` accessors, exposing **species, tamed name, level, color regions, and `CurrentStatusValues[0..11]`** on each cryopodded creature.

{arkparser-0.7.0 → arkparser-0.7.1}/pyproject.toml

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