arkparser 0.4.6__tar.gz → 0.5.3__tar.gz

{arkparser-0.4.6 → arkparser-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.4.6
+Version: 0.5.3
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -56,7 +56,7 @@ A pure-Python library for parsing ARK: Survival Evolved (ASE) and ARK: Survival
 - **Cloud Inventory / Obelisk**: uploaded creatures, items, cryopod contents
 - **World Saves** (`.ark`): full map state (creatures, structures, items, players)
 - **Dual format**: automatic ASE (v5-12) / ASA (v13-14+, SQLite) detection
-- **Legacy-parity export**: drop-in JSON output matching `ASVExport.exe` schema, plus parser-only extras under `extra_*` keys
+- **Legacy-parity export**: drop-in JSON output matching `ASVExport.exe` schema, plus parser-only extras under descriptive snake_case keys (no namespace prefix; never overloading a legacy key)
 - **Fast**: pure-Python `BinaryReader` (`int.from_bytes` + `struct.Struct` unpackers, slots-based dataclasses), a 30 MB ASE save (65k objects) loads in ~3s on CPython 3.14
 
 ## Installation
@@ -297,11 +297,8 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | `tribe` | legacy | tribe name |
 | `sex` | legacy | `"Female"` / `"Male"` |
 | `lvl` | legacy | `BaseCharacterLevel + ExtraCharacterLevel` |
-| `lat`, `lon` | legacy | `0.0` (profile/cluster files carry no in-world location) |
 | `hp` .. `craft`, `fort` | legacy | `NumberOfLevelUpPointsApplied[i]` (10 visible stats) |
 | `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` | 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 |
@@ -325,12 +322,14 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 
 #### `ASV_Tribes` schema
 
+`ASV_Tribes` (and `ASV_TribeLogs` / `ASV_Players`, which iterate the same list) is a **superset** of the loaded `.arktribe` files, mirroring legacy `ContentContainer`: it seeds two sentinels (`[ASV Unclaimed]` id `2000000000`, `[ASV Abandoned]` id `-2147483648`), adds every file-backed tribe, then synthesizes a stub tribe for each player profile not already in a tribe (`Tribe of <name>`, id = `PlayerDataID`), each distinct structure `TargetingTeam` (`>= 50000`), and each distinct in-world tame `TargetingTeam` — deduped by id. Cross-server tribes that exist **only** in cluster cloud-inventory files (no map presence) are not synthesized.
+
 | Field | Origin | Source / formula |
 |---|---|---|
-| `tribeid` | legacy | `TribeID` / parser `Tribe.tribe_id` |
-| `tribe` | legacy | tribe name |
-| `players` | legacy | member count |
-| `members` | legacy | list of `{ign, lvl, playerid, playername, steamid}`. `lvl` and `steamid` only populate when a matching `.arkprofile` is loaded into `save.profiles`, the `.arktribe` file itself doesn't carry per-member level / platform id, so the parser cross-references by `player_id`. Empty (`""`) when no profile is available for that member. |
+| `tribeid` | legacy | `TribeID` / parser `Tribe.tribe_id`, or a synthesized stub/sentinel id (see above) |
+| `tribe` | legacy | tribe name (file `TribeName`; for stubs, `OwnerName`/`TamerString`; or `Tribe of <character>` for a solo) |
+| `players` | legacy | count of players **allocated** to this tribe (profiles whose explicit team / membership / solo id resolves here, plus member back-fill), matching legacy `Players.Count` — not the raw `.arktribe` member count |
+| `members` | legacy | list of `{ign, lvl, playerid, playername, steamid}` built from the allocated players. `lvl` and `steamid` populate from the matching `.arkprofile`; members with no profile (back-filled from the tribe's member list) carry `lvl=0`, `steamid=""`. |
 | `tames`, `structures` | legacy | counts derived from `WorldSave` (creatures + structures whose `TargetingTeam` matches) |
 | `uploadedTames` | legacy | reserved (currently `0`) |
 | `active` | legacy | ISO 8601 datetime of the most recent tribe log entry, converted from in-game "Day N, HH:MM:SS" via the save's anchor. `null` when no parseable log entries or anchors are missing. |
@@ -352,9 +351,9 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | Field | Origin | Source / formula |
 |---|---|---|
 | `id` | added | `GameObject.id`, internal numeric identifier. Cross-references the values in other records' `linked_structures` / `saddle_structures` / `attached_dino_id` lists. |
-| `tribeid` | legacy | `TargetingTeam` |
-| `tribe` | legacy | `OwnerName` |
-| `struct` | legacy | `GameObject.class_name` |
+| `tribeid` | legacy | `TargetingTeam` for player-owned structures (`>= 50000`). Unowned structures fall to the synthetic `[ASV Abandoned]` tribe id `-2147483648` (legacy `int.MinValue`), mirroring `ContentContainer.cs`. |
+| `tribe` | legacy | resolved owning-tribe name: the loaded `.arktribe` `TribeName`, else the structure's `OwnerName` / `TamerString`; `"[ASV Abandoned]"` for unowned. (Legacy emits the resolved tribe name, not the raw `OwnerName`.) |
+| `struct` | legacy | `GameObject.class_name`. Unowned map elements / crates / debug actors (`Button_*`, `*Vein_*`, `*Nest_*`, `*Beaver*`, `BeeHive_C`, `ArtifactCrate_*`, `TributeTerminal_*`, `SupplyCrate_*`) are excluded — surfaced via `ASV_MapStructures` instead, matching legacy's abandoned-structure filter. |
 | `name` | legacy | `BoxName` (empty when it matches the class name, mirroring legacy's no-rename strip) |
 | `locked` | legacy | `bIsPinLocked` or `bIsLocked` |
 | `created` | legacy (richer) | ISO 8601 datetime with the local TZ of the parser machine, computed `save.file_mtime + (OriginalCreationTime - game_time)` (mirrors legacy `ContentContainer.GetApproxDateTimeOf`). `null` when the anchors are missing. |
@@ -362,7 +361,6 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | `lat`, `lon`, `ccc` | legacy | location via `MapConfig`, **rounded to 2 decimals** (parser-only nicety, not legacy parity) |
 | `isSwitchedOn` | legacy | `bContainerActivated`, emitted only when the structure is powered (`bIsPowered` or `bHasFuel`); omitted otherwise. Mirrors legacy `ContentStructure.cs` / `ContentPack.cs` (`IsSwitchedOn.HasValue`). |
 | `decay_reset` | added | `bHasResetDecayTime` |
-| `last_ally_in_range_seconds` | added | raw `LastInAllyRangeTime` / `LastInAllyRangeTimeSerialized` / `LastInAllyRangeSerialized` (in-game seconds, float) |
 | `last_ally_in_range` | added | ISO 8601 datetime with local TZ. `null` when the save lacks the anchors. |
 | `painting_id` | added | `UniquePaintingId` |
 | `feeding_inclusions` | added | `FeedingDinoList` class names when `DinoFeedingListType == 1` (ASA feeding troughs) |

{arkparser-0.4.6 → arkparser-0.5.3}/README.md

@@ -22,7 +22,7 @@ A pure-Python library for parsing ARK: Survival Evolved (ASE) and ARK: Survival
 - **Cloud Inventory / Obelisk**: uploaded creatures, items, cryopod contents
 - **World Saves** (`.ark`): full map state (creatures, structures, items, players)
 - **Dual format**: automatic ASE (v5-12) / ASA (v13-14+, SQLite) detection
-- **Legacy-parity export**: drop-in JSON output matching `ASVExport.exe` schema, plus parser-only extras under `extra_*` keys
+- **Legacy-parity export**: drop-in JSON output matching `ASVExport.exe` schema, plus parser-only extras under descriptive snake_case keys (no namespace prefix; never overloading a legacy key)
 - **Fast**: pure-Python `BinaryReader` (`int.from_bytes` + `struct.Struct` unpackers, slots-based dataclasses), a 30 MB ASE save (65k objects) loads in ~3s on CPython 3.14
 
 ## Installation
@@ -263,11 +263,8 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | `tribe` | legacy | tribe name |
 | `sex` | legacy | `"Female"` / `"Male"` |
 | `lvl` | legacy | `BaseCharacterLevel + ExtraCharacterLevel` |
-| `lat`, `lon` | legacy | `0.0` (profile/cluster files carry no in-world location) |
 | `hp` .. `craft`, `fort` | legacy | `NumberOfLevelUpPointsApplied[i]` (10 visible stats) |
 | `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` | 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 |
@@ -291,12 +288,14 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 
 #### `ASV_Tribes` schema
 
+`ASV_Tribes` (and `ASV_TribeLogs` / `ASV_Players`, which iterate the same list) is a **superset** of the loaded `.arktribe` files, mirroring legacy `ContentContainer`: it seeds two sentinels (`[ASV Unclaimed]` id `2000000000`, `[ASV Abandoned]` id `-2147483648`), adds every file-backed tribe, then synthesizes a stub tribe for each player profile not already in a tribe (`Tribe of <name>`, id = `PlayerDataID`), each distinct structure `TargetingTeam` (`>= 50000`), and each distinct in-world tame `TargetingTeam` — deduped by id. Cross-server tribes that exist **only** in cluster cloud-inventory files (no map presence) are not synthesized.
+
 | Field | Origin | Source / formula |
 |---|---|---|
-| `tribeid` | legacy | `TribeID` / parser `Tribe.tribe_id` |
-| `tribe` | legacy | tribe name |
-| `players` | legacy | member count |
-| `members` | legacy | list of `{ign, lvl, playerid, playername, steamid}`. `lvl` and `steamid` only populate when a matching `.arkprofile` is loaded into `save.profiles`, the `.arktribe` file itself doesn't carry per-member level / platform id, so the parser cross-references by `player_id`. Empty (`""`) when no profile is available for that member. |
+| `tribeid` | legacy | `TribeID` / parser `Tribe.tribe_id`, or a synthesized stub/sentinel id (see above) |
+| `tribe` | legacy | tribe name (file `TribeName`; for stubs, `OwnerName`/`TamerString`; or `Tribe of <character>` for a solo) |
+| `players` | legacy | count of players **allocated** to this tribe (profiles whose explicit team / membership / solo id resolves here, plus member back-fill), matching legacy `Players.Count` — not the raw `.arktribe` member count |
+| `members` | legacy | list of `{ign, lvl, playerid, playername, steamid}` built from the allocated players. `lvl` and `steamid` populate from the matching `.arkprofile`; members with no profile (back-filled from the tribe's member list) carry `lvl=0`, `steamid=""`. |
 | `tames`, `structures` | legacy | counts derived from `WorldSave` (creatures + structures whose `TargetingTeam` matches) |
 | `uploadedTames` | legacy | reserved (currently `0`) |
 | `active` | legacy | ISO 8601 datetime of the most recent tribe log entry, converted from in-game "Day N, HH:MM:SS" via the save's anchor. `null` when no parseable log entries or anchors are missing. |
@@ -318,9 +317,9 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | Field | Origin | Source / formula |
 |---|---|---|
 | `id` | added | `GameObject.id`, internal numeric identifier. Cross-references the values in other records' `linked_structures` / `saddle_structures` / `attached_dino_id` lists. |
-| `tribeid` | legacy | `TargetingTeam` |
-| `tribe` | legacy | `OwnerName` |
-| `struct` | legacy | `GameObject.class_name` |
+| `tribeid` | legacy | `TargetingTeam` for player-owned structures (`>= 50000`). Unowned structures fall to the synthetic `[ASV Abandoned]` tribe id `-2147483648` (legacy `int.MinValue`), mirroring `ContentContainer.cs`. |
+| `tribe` | legacy | resolved owning-tribe name: the loaded `.arktribe` `TribeName`, else the structure's `OwnerName` / `TamerString`; `"[ASV Abandoned]"` for unowned. (Legacy emits the resolved tribe name, not the raw `OwnerName`.) |
+| `struct` | legacy | `GameObject.class_name`. Unowned map elements / crates / debug actors (`Button_*`, `*Vein_*`, `*Nest_*`, `*Beaver*`, `BeeHive_C`, `ArtifactCrate_*`, `TributeTerminal_*`, `SupplyCrate_*`) are excluded — surfaced via `ASV_MapStructures` instead, matching legacy's abandoned-structure filter. |
 | `name` | legacy | `BoxName` (empty when it matches the class name, mirroring legacy's no-rename strip) |
 | `locked` | legacy | `bIsPinLocked` or `bIsLocked` |
 | `created` | legacy (richer) | ISO 8601 datetime with the local TZ of the parser machine, computed `save.file_mtime + (OriginalCreationTime - game_time)` (mirrors legacy `ContentContainer.GetApproxDateTimeOf`). `null` when the anchors are missing. |
@@ -328,7 +327,6 @@ For the richest output, hand `export_players` **both**, assemble a wrapper for e
 | `lat`, `lon`, `ccc` | legacy | location via `MapConfig`, **rounded to 2 decimals** (parser-only nicety, not legacy parity) |
 | `isSwitchedOn` | legacy | `bContainerActivated`, emitted only when the structure is powered (`bIsPowered` or `bHasFuel`); omitted otherwise. Mirrors legacy `ContentStructure.cs` / `ContentPack.cs` (`IsSwitchedOn.HasValue`). |
 | `decay_reset` | added | `bHasResetDecayTime` |
-| `last_ally_in_range_seconds` | added | raw `LastInAllyRangeTime` / `LastInAllyRangeTimeSerialized` / `LastInAllyRangeSerialized` (in-game seconds, float) |
 | `last_ally_in_range` | added | ISO 8601 datetime with local TZ. `null` when the save lacks the anchors. |
 | `painting_id` | added | `UniquePaintingId` |
 | `feeding_inclusions` | added | `FeedingDinoList` class names when `DinoFeedingListType == 1` (ASA feeding troughs) |

{arkparser-0.4.6 → arkparser-0.5.3}/arkparser/__init__.py

@@ -1,98 +1,98 @@
-"""
-ARK Save Parser - Parse ARK: Survival Evolved/Ascended save files.
-
-This package provides tools to parse various ARK save file formats:
-
-- Profile: Player profile data (.arkprofile)
-- Tribe: Tribe data (.arktribe)
-- CloudInventory: Obelisk/cloud inventory data (no extension)
-- WorldSave: World save data (.ark), auto-detects ASE binary and ASA SQLite
-
-Supports both ASE (ARK: Survival Evolved) and ASA (ARK: Survival Ascended)
-formats with automatic detection.
-
-Example usage:
-    >>> from arkparser import Profile, Tribe, CloudInventory, WorldSave
-    >>> profile = Profile.load("path/to/profile.arkprofile")
-    >>> tribe = Tribe.load("path/to/tribe.arktribe")
-    >>> inv = CloudInventory.load("path/to/obelisk_file")
-    >>> save = WorldSave.load("path/to/TheIsland.ark")    # ASE
-    >>> save = WorldSave.load("path/to/Extinction_WP.ark")  # ASA
-"""
-
-from arkparser.common.exceptions import ArkParseError
-from arkparser.common.map_config import MapConfig, get_map_config, get_map_config_by_name
-from arkparser.common.version_detection import (
-    ArkFileFormat,
-    ArkFileType,
-    detect_file_type,
-    detect_format,
-)
-from arkparser.data_models import (
-    CryopodCreature,
-    DinoStats,
-    UploadedCreature,
-    UploadedItem,
-)
-from arkparser.export import (
-    export_all,
-    export_cloud_inventory,
-    export_cluster_items,
-    export_cluster_uploads,
-    export_map_structures,
-    export_players,
-    export_structures,
-    export_tamed,
-    export_to_files,
-    export_tribe_logs,
-    export_tribes,
-    export_wild,
-)
-from arkparser.files import CloudInventory, Profile, Tribe, WorldSave
-from arkparser.game_objects import GameObject, GameObjectContainer, LocationData
-
-# Convenience alias - users may know this as "Obelisk" from the game
-Obelisk = CloudInventory
-
-__all__ = [
-    # File parsers
-    "Profile",
-    "Tribe",
-    "CloudInventory",
-    "Obelisk",
-    "WorldSave",
-    # Cloud-inventory data models
-    "UploadedCreature",
-    "UploadedItem",
-    "CryopodCreature",
-    "DinoStats",
-    # Game objects
-    "GameObject",
-    "GameObjectContainer",
-    "LocationData",
-    # Map config
-    "MapConfig",
-    "get_map_config",
-    "get_map_config_by_name",
-    # Export
-    "export_all",
-    "export_tamed",
-    "export_wild",
-    "export_players",
-    "export_tribes",
-    "export_structures",
-    "export_tribe_logs",
-    "export_map_structures",
-    "export_cluster_uploads",
-    "export_cluster_items",
-    "export_cloud_inventory",
-    "export_to_files",
-    # Utilities
-    "detect_format",
-    "detect_file_type",
-    "ArkFileFormat",
-    "ArkFileType",
-    "ArkParseError",
-]
-
-__version__ = "0.4.6"
+"""
+ARK Save Parser - Parse ARK: Survival Evolved/Ascended save files.
+
+This package provides tools to parse various ARK save file formats:
+
+- Profile: Player profile data (.arkprofile)
+- Tribe: Tribe data (.arktribe)
+- CloudInventory: Obelisk/cloud inventory data (no extension)
+- WorldSave: World save data (.ark), auto-detects ASE binary and ASA SQLite
+
+Supports both ASE (ARK: Survival Evolved) and ASA (ARK: Survival Ascended)
+formats with automatic detection.
+
+Example usage:
+    >>> from arkparser import Profile, Tribe, CloudInventory, WorldSave
+    >>> profile = Profile.load("path/to/profile.arkprofile")
+    >>> tribe = Tribe.load("path/to/tribe.arktribe")
+    >>> inv = CloudInventory.load("path/to/obelisk_file")
+    >>> save = WorldSave.load("path/to/TheIsland.ark")    # ASE
+    >>> save = WorldSave.load("path/to/Extinction_WP.ark")  # ASA
+"""
+
+from arkparser.common.exceptions import ArkParseError
+from arkparser.common.map_config import MapConfig, get_map_config, get_map_config_by_name
+from arkparser.common.version_detection import (
+    ArkFileFormat,
+    ArkFileType,
+    detect_file_type,
+    detect_format,
+)
+from arkparser.data_models import (
+    CryopodCreature,
+    DinoStats,
+    UploadedCreature,
+    UploadedItem,
+)
+from arkparser.export import (
+    export_all,
+    export_cloud_inventory,
+    export_cluster_items,
+    export_cluster_uploads,
+    export_map_structures,
+    export_players,
+    export_structures,
+    export_tamed,
+    export_to_files,
+    export_tribe_logs,
+    export_tribes,
+    export_wild,
+)
+from arkparser.files import CloudInventory, Profile, Tribe, WorldSave
+from arkparser.game_objects import GameObject, GameObjectContainer, LocationData
+
+# Convenience alias - users may know this as "Obelisk" from the game
+Obelisk = CloudInventory
+
+__all__ = [
+    # File parsers
+    "Profile",
+    "Tribe",
+    "CloudInventory",
+    "Obelisk",
+    "WorldSave",
+    # Cloud-inventory data models
+    "UploadedCreature",
+    "UploadedItem",
+    "CryopodCreature",
+    "DinoStats",
+    # Game objects
+    "GameObject",
+    "GameObjectContainer",
+    "LocationData",
+    # Map config
+    "MapConfig",
+    "get_map_config",
+    "get_map_config_by_name",
+    # Export
+    "export_all",
+    "export_tamed",
+    "export_wild",
+    "export_players",
+    "export_tribes",
+    "export_structures",
+    "export_tribe_logs",
+    "export_map_structures",
+    "export_cluster_uploads",
+    "export_cluster_items",
+    "export_cloud_inventory",
+    "export_to_files",
+    # Utilities
+    "detect_format",
+    "detect_file_type",
+    "ArkFileFormat",
+    "ArkFileType",
+    "ArkParseError",
+]
+
+__version__ = "0.5.3"

{arkparser-0.4.6 → arkparser-0.5.3}/arkparser/common/normalization.py

@@ -54,4 +54,10 @@ def normalize_indexed_list(value: t.Any) -> list[t.Any]:
         return []
     if isinstance(normalized, list):
         return normalized
+    # A raw ByteProperty array is stored as `bytes` for memory efficiency
+    # (8x lighter than list[int]); expose it element-wise as a list of ints so
+    # consumers that iterate it (e.g. tribe MembersRankGroups -> int(rank))
+    # see the same shape they did before byte arrays were stored as bytes.
+    if isinstance(normalized, (bytes, bytearray)):
+        return list(normalized)
     return [normalized]

{arkparser-0.4.6 → arkparser-0.5.3}/arkparser/data_models.py

@@ -364,6 +364,14 @@ class CryopodCreature:
                         props_dict[key] = p.value
                     obj["properties"] = props_dict
                 except Exception:
+                    # Don't let one drifted object silently zero out: log it so
+                    # cryopod decode regressions surface instead of returning
+                    # empty stats with no diagnostic (was a blind swallow).
+                    logger.debug(
+                        "Failed to parse cryopod object properties at offset %s",
+                        obj.get("props_offset"),
+                        exc_info=True,
+                    )
                     obj["properties"] = {}
 
             # Find creature object (first one) and status component