arkparser 0.3.2__tar.gz → 0.4.0__tar.gz

{arkparser-0.3.2 → arkparser-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.3.2
+Version: 0.4.0
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -57,7 +57,7 @@ A pure-Python library for parsing ARK: Survival Evolved (ASE) and ARK: Survival
 - **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
-- **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
+- **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
 
@@ -180,10 +180,10 @@ The parser reuses the legacy short stat tokens consistently across every export
 
 These map 1:1 to in-game stat indices 0..11. Stat blocks use suffixes to disambiguate:
 
-- **no suffix** — base wild stats (wild creatures, players)
-- **`-w`** — base wild stats (tamed creatures, points the creature had before being tamed)
-- **`-t`** — post-tame level-up points (tamed creatures only)
-- **`-m`** — mutation points applied (tamed creatures only)
+- **no suffix**, base wild stats (wild creatures, players)
+- **`-w`**, base wild stats (tamed creatures, points the creature had before being tamed)
+- **`-t`**, post-tame level-up points (tamed creatures only)
+- **`-m`**, mutation points applied (tamed creatures only)
 
 The legacy ASVExport.exe emitted only the visible 8 stats (`hp`, `stam`, `melee`, `weight`, `speed`, `food`, `oxy`, `craft`) under each suffix. The parser appends the four legacy never surfaced (`torp`, `water`, `temp`, `fort`) at the end of each block, so e.g. a tamed creature now carries `torp-w`, `water-w`, `temp-w`, `fort-w` alongside the legacy `hp-w`..`craft-w`.
 
@@ -209,8 +209,8 @@ The legacy ASVExport.exe emitted only the visible 8 stats (`hp`, `stam`, `melee`
 | `torp-t`, `water-t`, `temp-t`, `fort-t` | added | same source, indices legacy never emitted |
 | `hp-m` .. `fort-m` (all 12) | added | `NumberOfMutationsAppliedTamed[i]` (mutation point counts per stat) |
 | `c0` .. `c5` | legacy | `ColorSetIndices[i]` |
-| `mut-f`, `mut-m` | legacy | **Ancestor-line totals.** `RandomMutationsFemale` and `RandomMutationsMale` — single integers counting the total number of mutations that occurred down the maternal and paternal ancestry lines respectively. These are *not* per-stat — they share the `-m` token with the per-stat mutation block below but mean a different thing. Kept under the legacy names for ASVExport parity. |
-| `cryo` | legacy | `IsInCryo` |
+| `mut-f`, `mut-m` | legacy | **Ancestor-line totals.** `RandomMutationsFemale` and `RandomMutationsMale`, single integers counting the total number of mutations that occurred down the maternal and paternal ancestry lines respectively. These are *not* per-stat, they share the `-m` token with the per-stat mutation block below but mean a different thing. Kept under the legacy names for ASVExport parity. |
+| `cryo` | legacy | `True` for creatures embedded inside cryopod / soultrap / vivarium / dinoball items in the world save, `False` for actor-in-world tames. `export_tamed` walks `WorldSave.iter_cryopod_creatures()` and emits one ASV_Tamed record per embedded creature in addition to the actor-in-world tames; on busy PvE servers cryopodded tames are the majority of the roster (e.g. 10,277 of 11,054 on a live Ragnarok_WP). Cluster-uploaded tames also surface here (via `export_cluster_uploads`) with `cryo=True`. |
 | `ccc` | legacy | `"{x} {y} {z}"` from `LocationData` |
 | `dinoid` | legacy | string form of `id` |
 | `isMating` | legacy | `bEnableTamedMating` |
@@ -220,29 +220,29 @@ The legacy ASVExport.exe emitted only the visible 8 stats (`hp`, `stam`, `melee`
 | `uploadedServer` | legacy | `UploadedFromServerName` |
 | `maturation` | legacy | `str(int(BabyAge * 100))` (string for legacy parity) |
 | `traits` | legacy | `CreatureTraits` (full list of mutation trait class names) |
-| `inventory` | legacy | items from `MyInventoryComponent.InventoryItems`. Each entry carries `itemId`, `qty`, `blueprint`. When the item is a **cryopod / soultrap / vivarium / dinoball** with an embedded creature, the entry is enriched with `dino_id` (combined 64-bit id matching the corresponding `ASV_Tamed` record), `dino_creature` (species / class name), and `dino_name` (`TamedName` if set). Cryopods stored in containers (cryofridges, vaults, dedicated storage) get the same enrichment. |
+| `inventory` | legacy | items from `MyInventoryComponent.InventoryItems`. Each entry carries `itemId`, `qty`, `blueprint`, plus a full snake_case property dump flattened in at the top level (`id`, `rating`, `durability`, `quality`, `damage`, `armor`, `durability_max`, `hypo`, `hyper`, `clip_size`, `weight`, `crafter`, `crafter_tribe`, `skill_bonus`, `loaded_ammo`, `spoils_at`, `spoiled_at`, `c0`..`c5`, `egg_*`, etc). `item_stat_values` is unpacked into the universal 8-slot ARK map (slot 0 `gen_quality`, 1 `armor`, 2 `durability_max`, 3 `damage`, 4 `clip_size`, 5 `hypo`, 6 `weight`, 7 `hyperthermal_insulation`); raw uint16s scaled by the per-blueprint multiplier (which lives in the UE blueprint, not the save). Default / unset values are filtered (no `craft_queue=0`, `skin=-1`, `color_pre_skin=[0]*6`, NaN spoil timers, etc). When the item is a **cryopod / soultrap / vivarium / dinoball** with an embedded creature, the entry is enriched with `dino_id` (combined 64-bit id matching the corresponding `ASV_Tamed` record), `dino_creature` (species / class name), and `dino_name` (`TamedName` if set). Cryopods stored in containers (cryofridges, vaults, dedicated storage) get the same enrichment. |
 | `father_id`, `mother_id` | added | combined dino id from the first `DinoAncestors` entry (`null` when missing) |
 | `father_name`, `mother_name` | added | name strings from the first `DinoAncestors` entry |
 | `level_added` | added | `ExtraCharacterLevel` (post-tame levels, broken out from `lvl`) |
 | `experience` | added | `ExperiencePoints` (status), integer |
 | `wandering` | added | `bEnableTamedWandering` |
 | `tamed_at` | added | ISO 8601 datetime with local TZ, converted from `TamedAtTime` (in-game seconds) via `file_mtime + (tamed_at - game_time)`. `null` when the save lacks the anchors. |
-| `last_ally_in_range` | added | ISO 8601 datetime with local TZ — converted from `LastInAllyRangeTime` / `LastInAllyRangeSerialized` via the same anchor formula as `tamed_at`. `null` when the save lacks the anchors. |
+| `last_ally_in_range` | added | ISO 8601 datetime with local TZ, converted from `LastInAllyRangeTime` / `LastInAllyRangeSerialized` via the same anchor formula as `tamed_at`. `null` when the save lacks the anchors. |
 | `imprinter_player_id` | added | `ImprinterPlayerDataID` |
 | `imprinter_net_id` | added | `ImprinterPlayerUniqueNetId` (ASA only) |
 | `taming_team_id` | added | `TamingTeamID` (fallback tribe id when `TargetingTeam` was stripped on cryo) |
-| `owning_player_id`, `owning_player_name` | added | `OwningPlayerID` / `OwningPlayerName` — current owner (may differ from the original `tamer` after transfer / cryo). |
-| `aggression_level` | added | `TamedAggressionLevel` — 0 Passive, 1 Neutral, 2 Aggressive, 3 Passive Flee, 4 Attack-My-Target (ARK in-game order). |
-| `ai_targeting_range` | added | `TamedAITargetingRange` — aggro range (UE units). |
-| `follow_stopping_distance` | added | `FollowStoppingDistance` — follow-AI stopping radius. |
+| `owning_player_id`, `owning_player_name` | added | `OwningPlayerID` / `OwningPlayerName`, current owner (may differ from the original `tamer` after transfer / cryo). |
+| `aggression_level` | added | `TamedAggressionLevel`, 0 Passive, 1 Neutral, 2 Aggressive, 3 Passive Flee, 4 Attack-My-Target (ARK in-game order). |
+| `ai_targeting_range` | added | `TamedAITargetingRange`, aggro range (UE units). |
+| `follow_stopping_distance` | added | `FollowStoppingDistance`, follow-AI stopping radius. |
 | `is_flying` | added | `bIsFlying`. |
-| `is_turret_mode` | added | `bIsInTurretMode` — e.g. plant Y, Tek tape sentry mode. |
-| `ignore_whistles`, `only_target_conscious`, `attack_team_member_dinos` | added | `bIgnoreAllWhistles` / `bOnlyTargetConscious` / `bAttackTeamMemberDinos` — behavior toggles. |
-| `next_cuddle_food`, `next_cuddle_type` | added | `BabyCuddleFood` / `BabyCuddleType` — next imprint requirement. |
-| `latest_uploaded_server`, `previous_uploaded_server` | added | `LatestUploadedFromServerName` / `PreviousUploadedFromServerName` — recent upload history alongside the legacy `uploadedServer`. |
+| `is_turret_mode` | added | `bIsInTurretMode`, e.g. plant Y, Tek tape sentry mode. |
+| `ignore_whistles`, `only_target_conscious`, `attack_team_member_dinos` | added | `bIgnoreAllWhistles` / `bOnlyTargetConscious` / `bAttackTeamMemberDinos`, behavior toggles. |
+| `next_cuddle_food`, `next_cuddle_type` | added | `BabyCuddleFood` / `BabyCuddleType`, next imprint requirement. |
+| `latest_uploaded_server`, `previous_uploaded_server` | added | `LatestUploadedFromServerName` / `PreviousUploadedFromServerName`, recent upload history alongside the legacy `uploadedServer`. |
 | `saddle_structures` | added | List of structure object-ref strings placed on this creature's platform saddle (paracer / brontosaurus / titanosaur etc.). |
-| `harvest_resource_levels` | added | `HarvestResourceLevels` — per-resource harvest levels (mortar / feeding trough variants). |
-| `wild_spawn_region` | added | `OriginalNPCVolumeName` — name of the `NPCZoneVolume` where this creature first spawned. Lets consumers answer "where on the map did this tame originate". |
+| `harvest_resource_levels` | added | `HarvestResourceLevels`, per-resource harvest levels (mortar / feeding trough variants). |
+| `wild_spawn_region` | added | `OriginalNPCVolumeName`, name of the `NPCZoneVolume` where this creature first spawned. Lets consumers answer "where on the map did this tame originate". |
 | `downloaded_at` | added | ISO 8601 datetime of the last cluster/obelisk download (`DinoDownloadedAtTime`). `null` when the creature was never cluster-downloaded. |
 | `original_created` | added | ISO 8601 datetime of the dino's first spawn (`OriginalCreationTime`), e.g. when the egg was laid or the wild dino spawned. Distinct from `tamed_at`. |
 | `next_mating_at` | added | ISO 8601 datetime when the next mating is allowed (`NextAllowedMatingTime`). `null` when no cooldown is set. |
@@ -250,7 +250,7 @@ The legacy ASVExport.exe emitted only the visible 8 stats (`hp`, `stam`, `melee`
 | `last_baby_age_update` | added | ISO 8601 datetime of `LastUpdatedBabyAgeAtTime`. |
 | `last_gestation_update` | added | ISO 8601 datetime of `LastUpdatedGestationAtTime`. |
 | `next_cuddle` | added | ISO 8601 datetime of `BabyNextCuddleTime`. |
-| `current_stats` | added | Live in-world stat values from the dino's status component (`CurrentStatusValues[0..11]`) as a `{hp, stam, torp, oxy, food, water, temp, weight, melee, speed, fort, craft}` dict of floats. These are the *current* values (e.g. `hp: 11013.62` = current HP, drops as the dino takes damage). Max values are NOT persisted by ARK — compute downstream from species stat tables + `*-w`/`*-t` points + `imprint` + server multipliers if you need them. `null` when the status component carries no `CurrentStatusValues` entries (e.g. uninitialised baby actor). |
+| `current_stats` | added | Live in-world stat values from the dino's status component (`CurrentStatusValues[0..11]`) as a `{hp, stam, torp, oxy, food, water, temp, weight, melee, speed, fort, craft}` dict of floats. These are the *current* values (e.g. `hp: 11013.62` = current HP, drops as the dino takes damage). Max values are NOT persisted by ARK, compute downstream from species stat tables + `*-w`/`*-t` points + `imprint` + server multipliers if you need them. `null` when the status component carries no `CurrentStatusValues` entries (e.g. uninitialised baby actor). |
 
 #### `ASV_Wild` schema
 
@@ -267,7 +267,7 @@ The legacy ASVExport.exe emitted only the visible 8 stats (`hp`, `stam`, `melee`
 | `tameable` | legacy | mirror of legacy `ContentWildCreature.IsTameable` rule |
 | `trait` | legacy | first entry of `CreatureTraits` (or empty string) |
 | `traits` | added | full `CreatureTraits` list |
-| `wild_spawn_region` | added | `OriginalNPCVolumeName` — `NPCZoneVolume` the creature spawned in. |
+| `wild_spawn_region` | added | `OriginalNPCVolumeName`, `NPCZoneVolume` the creature spawned in. |
 | `current_stats` | added | Live in-world stat values from the creature's status component (`CurrentStatusValues[0..11]`) as a `{hp, stam, torp, oxy, food, water, temp, weight, melee, speed, fort, craft}` dict of floats. Max values are NOT in the save (would need species stat tables). `null` when uninitialised. |
 
 #### Player data: `.arkprofile` vs in-world pawn
@@ -284,7 +284,7 @@ The export pipeline (`export_players`) loops over `save.profiles` (a list the ca
 - If it's a `Profile` instance → `_player_from_profile` runs: fills core identity (name, gender, level, stats, tribe id, engram count, experience, active datetime from `LastLoginTime`). Leaves `lat`/`lon`/`ccc` as zero, `inventory` empty, pawn-state flags (`is_sleeping`, `is_dead`, `chibi_levels`, …) absent.
 - Otherwise it's treated as a wrapped `(profile, objects)` pair pointing at an in-world `PlayerPawn` → `_player_from_object` runs: fills location, inventory, pawn-state flags, body/hair cosmetics, death timestamps, and `active` from `SavedLastTimeHadController`.
 
-For the richest output, hand `export_players` **both** — assemble a wrapper for each player that carries the `Profile` (for offline identity) *and* the in-world pawn (when present) so the merged record gets identity + live state. The current validation script only passes `Profile` instances, which is why fields like `is_sleeping` / `body_colors` / `current_weapon` show up empty in the validation output even though the parser supports them.
+For the richest output, hand `export_players` **both**, assemble a wrapper for each player that carries the `Profile` (for offline identity) *and* the in-world pawn (when present) so the merged record gets identity + live state. The current validation script only passes `Profile` instances, which is why fields like `is_sleeping` / `body_colors` / `current_weapon` show up empty in the validation output even though the parser supports them.
 
 #### `ASV_Players` schema
 
@@ -309,18 +309,18 @@ For the richest output, hand `export_players` **both** — assemble a wrapper fo
 | `inventory` | legacy (now populated) | Items from the pawn's `MyInventoryComponent` when built from an in-world pawn. Empty list otherwise. |
 | `engram_points` | added | `TotalEngramPoints` |
 | `experience` | added | `ExperiencePoints` (status), integer |
-| `is_sleeping`, `is_dead` | added | `bIsSleeping` / `bIsDead` — pawn state flags. Always `false` for profile-sourced records (no pawn). |
+| `is_sleeping`, `is_dead` | added | `bIsSleeping` / `bIsDead`, pawn state flags. Always `false` for profile-sourced records (no pawn). |
 | `is_prone`, `is_crouched`, `hat_hidden` | added | `bIsProne` / `bIsCrouched` / `bHatHidden`. |
-| `current_weapon` | added | `CurrentWeapon` ref — equipped weapon identifier. |
-| `seated_on_ref` | added | `SeatingStructure` ref — what the player is sitting on (chair / saddle). |
-| `original_hair_color` | added | `OriginalHairColor` — color index at character creation. |
+| `current_weapon` | added | `CurrentWeapon` ref, equipped weapon identifier. |
+| `seated_on_ref` | added | `SeatingStructure` ref, what the player is sitting on (chair / saddle). |
+| `original_hair_color` | added | `OriginalHairColor`, color index at character creation. |
 | `head_hair_growth`, `facial_hair_growth` | added | `PercentOfFullHeadHairGrowth` / `PercentOfFullFacialHairGrowth`. |
-| `body_colors` | added | `BodyColors` — per-region skin color indices. |
+| `body_colors` | added | `BodyColors`, per-region skin color indices. |
 | `died_at` | added | ISO 8601 datetime of `LocalDiedAtTime`. |
 | `corpse_destruction` | added | ISO 8601 datetime of `CorpseDestructionTime`. |
-| `chibi_levels` | added | `NumChibiLevelUps` — bonus levels from chibi pets. |
-| `ascensions_scorched` | added | `NumAscensionsScorched` — ASE ascension counter (legacy `ContentPlayer` parses the ASA ascension block differently; this is the ASE-specific field). |
-| `current_stats` | added | Live in-world stat values for the player from the pawn's `MyCharacterStatusComponent` (`CurrentStatusValues[0..11]`) as a `{hp, stam, torp, oxy, food, water, temp, weight, melee, speed, fort, craft}` dict of floats. For profile-sourced records the parser joins on `PlayerDataID == LinkedPlayerDataID` to find the spawned pawn in the world save. `null` when the player has no in-world pawn (never spawned this server / corpse cleared) or the status component has no values — only currently / recently spawned characters have live stats. Max values are NOT persisted by ARK. |
+| `chibi_levels` | added | `NumChibiLevelUps`, bonus levels from chibi pets. |
+| `ascensions_scorched` | added | `NumAscensionsScorched`, ASE ascension counter (legacy `ContentPlayer` parses the ASA ascension block differently; this is the ASE-specific field). |
+| `current_stats` | added | Live in-world stat values for the player from the pawn's `MyCharacterStatusComponent` (`CurrentStatusValues[0..11]`) as a `{hp, stam, torp, oxy, food, water, temp, weight, melee, speed, fort, craft}` dict of floats. For profile-sourced records the parser joins on `PlayerDataID == LinkedPlayerDataID` to find the spawned pawn in the world save. `null` when the player has no in-world pawn (never spawned this server / corpse cleared) or the status component has no values, only currently / recently spawned characters have live stats. Max values are NOT persisted by ARK. |
 
 #### `ASV_Tribes` schema
 
@@ -329,7 +329,7 @@ For the richest output, hand `export_players` **both** — assemble a wrapper fo
 | `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. |
+| `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. |
 | `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. |
@@ -350,7 +350,7 @@ For the richest output, hand `export_players` **both** — assemble a wrapper fo
 
 | 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. |
+| `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` |
@@ -369,27 +369,27 @@ For the richest output, hand `export_players` **both** — assemble a wrapper fo
 | `feeding_exclusions` | added | `FeedingDinoList` class names when `DinoFeedingListType == 2` |
 | `health` | added | `Health` (often `0.0` because ARK strips live health on save) |
 | `max_health` | added | `MaxHealth` |
-| `owning_player_id`, `owning_player_name` | added | `OwningPlayerID` / `OwningPlayerName` — who placed the structure (distinct from `tribe`, which is the current owning tribe). |
-| `colors` | added | `StructureColors` — list of 6 color region indices (0 = unpainted). |
-| `current_item_count`, `max_item_count` | added | `CurrentItemCount` / `MaxItemCount` — container fullness (e.g. dedicated storage, generators). Both `0` for non-container structures. |
-| `num_bullets` | added | `NumBullets` — loaded ammo count on auto-turrets. `0` for non-turrets. |
-| `range_setting` | added | `RangeSetting` — turret targeting range tier (`0` Low, `1` Med, `2` High, `3` Highest). `0` for non-turrets too — disambiguate via `num_bullets` / `struct`. |
-| `has_fuel` | added | `bHasFuel` — generator / lamp fuel state. |
+| `owning_player_id`, `owning_player_name` | added | `OwningPlayerID` / `OwningPlayerName`, who placed the structure (distinct from `tribe`, which is the current owning tribe). |
+| `colors` | added | `StructureColors`, list of 6 color region indices (0 = unpainted). |
+| `current_item_count`, `max_item_count` | added | `CurrentItemCount` / `MaxItemCount`, container fullness (e.g. dedicated storage, generators). Both `0` for non-container structures. |
+| `num_bullets` | added | `NumBullets`, loaded ammo count on auto-turrets. `0` for non-turrets. |
+| `range_setting` | added | `RangeSetting`, turret targeting range tier (`0` Low, `1` Med, `2` High, `3` Highest). `0` for non-turrets too, disambiguate via `num_bullets` / `struct`. |
+| `has_fuel` | added | `bHasFuel`, generator / lamp fuel state. |
 | `is_foundation` | added | `bIsFoundation`. |
-| `placement_snapped` | added | `bWasPlacementSnapped` — placement-snap flag. |
-| `variant` | added | `CurrentVariant` — structure variant index (e.g. flexible pipe / gate style). |
-| `selected_resource_class` | added | `SelectedResourceClass` ref — resource type chosen on dedicated storage / similar. |
+| `placement_snapped` | added | `bWasPlacementSnapped`, placement-snap flag. |
+| `variant` | added | `CurrentVariant`, structure variant index (e.g. flexible pipe / gate style). |
+| `selected_resource_class` | added | `SelectedResourceClass` ref, resource type chosen on dedicated storage / similar. |
 | `resource_count` | added | `ResourceCount`. |
 | `dedicated_storage_version` | added | `SavedDedicatedStorageVersion`. |
-| `painting_ref` | added | `PaintingComponent` ref — canvas component identifier when painted. |
-| `saddle_dino_ref`, `attached_dino_id` | added | `SaddleDino` ref + `AttachedToDinoID1/2` combined — links saddle-mounted structures back to their host dino. |
-| `linked_structures` | added | `LinkedStructures` — refs of network-linked structures (pipes / wires / gates → motors). Useful for reconstructing infrastructure topology. |
+| `painting_ref` | added | `PaintingComponent` ref, canvas component identifier when painted. |
+| `saddle_dino_ref`, `attached_dino_id` | added | `SaddleDino` ref + `AttachedToDinoID1/2` combined, links saddle-mounted structures back to their host dino. |
+| `linked_structures` | added | `LinkedStructures`, refs of network-linked structures (pipes / wires / gates → motors). Useful for reconstructing infrastructure topology. |
 | `last_activated` | added | ISO 8601 datetime of `LastActivatedTime`. |
 | `last_deactivated` | added | ISO 8601 datetime of `LastDeactivatedTime`. |
-| `last_fire` | added | ISO 8601 datetime of `LastFireTime` — last turret discharge. |
+| `last_fire` | added | ISO 8601 datetime of `LastFireTime`, last turret discharge. |
 | `last_reload` | added | ISO 8601 datetime of `LastLongReloadStartTime`. |
 | `last_fuel_check` | added | ISO 8601 datetime of `LastCheckedFuelTime`. |
-| `pin_code` | added | `CurrentPinCode` — the active PIN code on the structure as a single integer. Falls back to the first non-zero entry of the legacy `CurrentPinCodes` array (always zero on every observed save). Pruned when `0`. **Sensitive credential** — exposed for tribe-admin auditing; downstream UIs should gate this behind admin-only views. |
+| `pin_code` | added | `CurrentPinCode`, the active PIN code on the structure as a single integer. Falls back to the first non-zero entry of the legacy `CurrentPinCodes` array (always zero on every observed save). Pruned when `0`. **Sensitive credential**, exposed for tribe-admin auditing; downstream UIs should gate this behind admin-only views. |
 
 #### `ASV_MapStructures` schema
 
@@ -399,18 +399,48 @@ For the richest output, hand `export_players` **both** — assemble a wrapper fo
 | `lat`, `lon`, `ccc` | legacy | location via `MapConfig` |
 | `inventory` | legacy | inventory items (only meaningful for beaver dams / dropped supply crates) |
 
-### Cluster-uploaded creatures
+### Cluster-uploaded creatures and items
 
-To match the legacy exporter's behaviour of including cluster-uploaded tames (creatures stored in obelisk/cloud-inventory files), pass the cluster directory to `export_all` / `export_to_files`:
+Pass the cluster directory to `export_all` / `export_to_files` to fold cluster data into the per-map output:
 
 ```python
 export_to_files(save, "output/", map_config, cluster="path/to/cluster")
 # or equivalently:
 data = export_all(save, map_config, cluster="path/to/cluster")
-# data["ASV_Tamed"] now includes both world tames and cluster uploads.
+# data["ASV_Tamed"]   - now includes cluster cryopod tames (cryo=True)
+# data["ASV_Players"] - each player's inventory now contains their
+#                       uploaded items (entries tagged "uploaded": true),
+#                       matched by cloud-file stem (xuid) ==
+#                       Profile.unique_id.
 ```
 
-Pre-loaded `CloudInventory` instances also work (`cluster=[inv1, inv2, ...]`). The low-level helper `export_cluster_uploads(cluster_invs, map_config)` is still available if you need cluster-only output.
+Cluster items are spliced into the owning player's `inventory`; no separate `ASV_ClusterItems` file is emitted. The match works because every cluster file is named after the owning player's Steam id / platform UUID, which is the same value as `Profile.unique_id`.
+
+Pre-loaded `CloudInventory` instances also work (`cluster=[inv1, inv2, ...]`).
+
+### Standalone cloud-inventory inspection
+
+For staff tools that need to inspect a single user's obelisk / cluster file in isolation (no worldsave context, no per-player matching), use `export_cloud_inventory`:
+
+```python
+from arkparser import CloudInventory, export_cloud_inventory
+
+cloud = CloudInventory.load("/cluster/2533274802706466")  # ASE xuid
+# or
+cloud = CloudInventory.load("/cluster/000297eb6c36484ab95c75d7bbbc8629")  # ASA UUID
+
+data = export_cloud_inventory(cloud)
+# {
+#   "ASV_Tamed": [ ... every dino, cryopod-embedded or otherwise ... ],
+#   "ASV_Items": [ ... every uploaded item, snake_case flat stats ... ],
+# }
+```
+
+Each `ASV_Items` entry carries `itemId`, `qty`, `blueprint`, `id` (combined ItemID1_ItemID2), `upload_time` (ISO 8601 with UTC offset), and item-class-specific stats (`durability_max`, `damage`, `armor`, `hypo`, `hyper`, `crafter`, `crafter_tribe`, `skill_bonus`, `loaded_ammo`, `quality`, `rating`, `c0`..`c5` paint regions, `drop_location`, `egg_*` for fertilized eggs, `dino_*` for cryopod items, etc). Default / unset fields are filtered, NaN floats dropped, `"Unknown"` crafter strings nulled.
+
+The low-level helpers are also available:
+- `export_cluster_uploads(cluster_invs, map_config=None) -> list[dict]` — tamed-shape records (incl. cryopod-as-item dinos) across the supplied cloud files
+- `export_cluster_items(cluster_invs) -> list[dict]` — every uploaded item across the supplied cloud files
 
 ## Package Structure
 
@@ -559,14 +589,16 @@ All four expose `from_*` constructors and `to_dict()` for serialization.
 |---|---|---|
 | `export_tamed(save, map_config=None)` | `list[dict]` | `ASV_Tamed` records |
 | `export_wild(save, map_config=None)` | `list[dict]` | `ASV_Wild` records |
-| `export_players(save, map_config=None)` | `list[dict]` | `ASV_Players` records (from Profile parsers) |
+| `export_players(save, map_config=None, cluster_inventories=None)` | `list[dict]` | `ASV_Players` records (from Profile parsers). Pass `cluster_inventories` to splice each player's uploaded items into their `inventory` (entries tagged `uploaded: true`, matched by xuid stem == `Profile.unique_id`) |
 | `export_tribes(save)` | `list[dict]` | `ASV_Tribes` records |
 | `export_structures(save, map_config=None)` | `list[dict]` | `ASV_Structures` records |
 | `export_tribe_logs(save)` | `list[dict]` | `ASV_TribeLogs` records |
 | `export_map_structures(save, map_config=None)` | `list[dict]` | `ASV_MapStructures` records |
-| `export_all(save, map_config=None)` | `dict[str, list[dict]]` | All seven exports keyed by ASV filename stem |
-| `export_cluster_uploads(cluster_inventories, map_config=None)` | `list[dict]` | Tamed-shape records for creatures stored in cluster `CloudInventory` files (decoded from `ArkTamedDinosData[].DinoData` blobs) |
-| `export_to_files(save, output_dir, map_config=None, wrap=True)` | `list[Path]` | Writes each export to `<dir>/<ASV_Name>.json`. `wrap=True` (default) emits the legacy `{map, day, time, data}` envelope; `wrap=False` writes the flat list |
+| `export_all(save, map_config=None, cluster=None)` | `dict[str, list[dict]]` | All seven exports keyed by ASV filename stem. `cluster` accepts a directory path or pre-loaded `CloudInventory` iterable; splices cluster tames into `ASV_Tamed` and cluster items into `ASV_Players[i].inventory` |
+| `export_cluster_uploads(cluster_inventories, map_config=None)` | `list[dict]` | Tamed-shape records for creatures stored in cluster `CloudInventory` files (decoded from `ArkTamedDinosData[].DinoData` blobs and `ArkItems[].CustomItemDatas` cryopod blobs) |
+| `export_cluster_items(cluster_inventories)` | `list[dict]` | Every uploaded item across the supplied cloud files, snake_case flat stats included |
+| `export_cloud_inventory(cloud, map_config=None)` | `dict[str, list[dict]]` | Standalone inspection of a single `CloudInventory`. Returns `{"ASV_Tamed": [...], "ASV_Items": [...]}` for staff tools that need to see one user's obelisk file without worldsave context |
+| `export_to_files(save, output_dir, map_config=None, wrap=True, cluster=None, compact=False)` | `list[Path]` | Writes each export to `<dir>/<ASV_Name>.json`. `wrap=True` (default) emits the legacy `{map, day, time, data}` envelope; `wrap=False` writes the flat list |
 
 Schema policy:
 
@@ -614,7 +646,26 @@ Schema policy:
 | World Save | Binary file | SQLite database |
 | Compression | None | zlib + custom RLE |
 
-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.
+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.
+
+### 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.
+
+What is **NOT yet extracted** from ASA cryopod blobs:
+
+- `DinoID1` / `DinoID2` (and therefore `id` / `dinoid`)
+- `TamingTeamID` / `TargetingTeam` (and therefore `tribeid`)
+- `TamerString`, `OwningPlayerID`, `OwningPlayerName`
+- `TamedOnServerName`, `UploadedFromServerName`
+- `BaseCharacterLevel` vs `ExtraCharacterLevel` split (only the displayed total surfaces)
+- Mutation counts, imprint quality, ancestors, behavioural toggles, etc.
+
+ASA cryopod records therefore come back with `tribeid: 0`, `tamer: ""`, `dinoid: "0"`, `imprint: 0.0` on the otherwise-rich tamed schema. The compressed property block at the C#-reported `PropertyOffset + 1` decompresses cleanly through both zlib and the custom RLE (matching `AsaCompressedData.cs` byte-for-byte), and the surrounding `AsaGameObject` headers parse correctly, but the property-list bytes that follow do **not** form valid name-table references under any alignment we tried (including the layout `AsaPropertyRegistry.ReadProperty` uses). The legacy AsaSavegameToolkit wraps `ReadProperties` in a swallowing try/catch (`AsaGameObject.cs:178-193`), so it is plausible that **no current open-source tool extracts this data** either.
+
+**ASE cryopod records are fully populated** via the in-place property-list blob, `from_cryopod_bytes` surfaces every legacy ASV_Tamed field.
+
+If you crack the ASA cryopod block format (e.g. via UE5 source-level RE on `UPropertySerializer` for these compressed stores, or a working reference output to byte-diff against), please open a PR, the bytes are correctly decompressed and exposed in `WorldSave.iter_cryopod_creatures()`, only the property reader is missing.
 
 ## Testing