arkparser 0.7.5__tar.gz → 0.9.0__tar.gz

{arkparser-0.7.5 → arkparser-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.7.5
+Version: 0.9.0
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -133,6 +133,27 @@ print(f"Parse errors: {save.parse_error_count}")
 print(f"Is ASA: {save.is_asa}")
 ```
 
+### Player/tribe data packed in the save (ASA)
+
+Some ASA servers (Nitrado observed) write no `.arkprofile` / `.arktribe` files.
+The same files are packed inside the `.ark` instead. Read them and attach them
+the same way you would attach sidecar files:
+
+```python
+from arkparser import WorldSave, export_all
+
+save = WorldSave.load("path/to/Ragnarok_WP.ark", lazy_properties=True)
+store = save.read_embedded_store()
+save.profiles, save.tribes = store.profiles, store.tribes
+data = export_all(save)
+```
+
+`EmbeddedStore` holds `profiles`, `tribes`, `superseded_profiles` /
+`superseded_tribes` (old copies the game leaves behind, skipped), and
+`errors` (one line per skipped entry; a bad entry never fails the load). Saves
+from servers that write sidecar files return an empty store. Not run by
+`load()`, so it costs nothing unless called.
+
 ### Low-memory parsing (large saves)
 
 By default every object's property block is parsed up front, which on a busy
@@ -577,6 +598,7 @@ Key methods:
 | `get_object_by_guid(guid)` | `GameObject \| None` | Lookup by GUID (ASA) |
 | `get_actor_location(guid)` | `LocationData \| None` | Actor location by GUID (ASA) |
 | `iter_cryopod_creatures()` | `Iterator[(GameObject, CryopodCreature)]` | Walk filled cryopods |
+| `read_embedded_store()` | `EmbeddedStore` | Player and tribe files packed inside an ASA save (servers that write no `.arkprofile` / `.arktribe`); see "Player/tribe data packed in the save" |
 
 ### Game Objects
 

{arkparser-0.7.5 → arkparser-0.9.0}/README.md

@@ -99,6 +99,27 @@ print(f"Parse errors: {save.parse_error_count}")
 print(f"Is ASA: {save.is_asa}")
 ```
 
+### Player/tribe data packed in the save (ASA)
+
+Some ASA servers (Nitrado observed) write no `.arkprofile` / `.arktribe` files.
+The same files are packed inside the `.ark` instead. Read them and attach them
+the same way you would attach sidecar files:
+
+```python
+from arkparser import WorldSave, export_all
+
+save = WorldSave.load("path/to/Ragnarok_WP.ark", lazy_properties=True)
+store = save.read_embedded_store()
+save.profiles, save.tribes = store.profiles, store.tribes
+data = export_all(save)
+```
+
+`EmbeddedStore` holds `profiles`, `tribes`, `superseded_profiles` /
+`superseded_tribes` (old copies the game leaves behind, skipped), and
+`errors` (one line per skipped entry; a bad entry never fails the load). Saves
+from servers that write sidecar files return an empty store. Not run by
+`load()`, so it costs nothing unless called.
+
 ### Low-memory parsing (large saves)
 
 By default every object's property block is parsed up front, which on a busy
@@ -543,6 +564,7 @@ Key methods:
 | `get_object_by_guid(guid)` | `GameObject \| None` | Lookup by GUID (ASA) |
 | `get_actor_location(guid)` | `LocationData \| None` | Actor location by GUID (ASA) |
 | `iter_cryopod_creatures()` | `Iterator[(GameObject, CryopodCreature)]` | Walk filled cryopods |
+| `read_embedded_store()` | `EmbeddedStore` | Player and tribe files packed inside an ASA save (servers that write no `.arkprofile` / `.arktribe`); see "Player/tribe data packed in the save" |
 
 ### Game Objects
 

{arkparser-0.7.5 → arkparser-0.9.0}/arkparser/__init__.py

@@ -48,7 +48,7 @@ from arkparser.export import (
     export_tribes,
     export_wild,
 )
-from arkparser.files import CloudInventory, Profile, Tribe, WorldSave
+from arkparser.files import CloudInventory, EmbeddedStore, Profile, Tribe, WorldSave
 from arkparser.game_objects import GameObject, GameObjectContainer, LocationData
 
 # Convenience alias - users may know this as "Obelisk" from the game
@@ -61,6 +61,7 @@ __all__ = [
     "CloudInventory",
     "Obelisk",
     "WorldSave",
+    "EmbeddedStore",
     # Cloud-inventory data models
     "UploadedCreature",
     "UploadedItem",
@@ -95,4 +96,4 @@ __all__ = [
     "ArkParseError",
 ]
 
-__version__ = "0.7.5"
+__version__ = "0.9.0"

{arkparser-0.7.5 → arkparser-0.9.0}/arkparser/export.py

@@ -326,6 +326,18 @@ LEGACY_TRIBE_KEYS: frozenset[str] = frozenset(
         "dataFile",
     }
 )
+# Tribe-record keys that must always emit, even when null/zero. The three
+# last_member_login fields have "null means cannot tell" semantics and a real
+# zero value (login within the final in-game second before the snapshot), so
+# _compact must never prune them. Not part of LEGACY_TRIBE_KEYS: that set
+# names the ASVExport parity contract and stays legacy-only.
+TRIBE_KEEP_KEYS: frozenset[str] = LEGACY_TRIBE_KEYS | frozenset(
+    {
+        "last_member_login",
+        "last_member_login_player_id",
+        "last_member_login_game_seconds",
+    }
+)
 LEGACY_STRUCT_KEYS: frozenset[str] = frozenset(
     {
         "id",
@@ -2436,50 +2448,89 @@ def _tribe_file_date(tribe: t.Any, save: t.Any) -> dt.datetime | None:
     return getattr(save, "file_mtime", None) if save is not None else None
 
 
-def _tribe_active_iso(
-    file_date: t.Any,
+def _tribe_last_login(
     member_ids: t.Iterable[int],
     profile_active: dict[int, dt.datetime],
-) -> str | None:
-    """Legacy ContentTribe.LastActive (ContentTribe.cs:35-49): the max of the
-    tribe file date and the members' last-active datetimes, discarding values
-    in the future. Tribe-log "Day N" stamps are game-calendar time, not real
-    seconds, so they cannot be converted with the save anchor and are unused.
-
-    Returns ``None`` when no past candidate exists.
+    profile_login_raw: dict[int, float],
+    game_time: float,
+) -> tuple[str | None, int | None, int | None]:
+    """Game-domain last-login rollup over a tribe's allocated members.
+
+    Winner is the argmax of raw ``LastLoginTime`` restricted to
+    ``login <= game_time``: profiles keep saving after the world snapshot, so
+    logins can exceed the world's game clock; those are dropped, never
+    clamped. Selection and filtering both run in the game-time domain, so the
+    result never depends on any file mtime (the defect that ruins the legacy
+    ``active`` as an inactivity signal).
+
+    Returns ``(anchored_iso, player_id, game_seconds)``, all ``None`` when no
+    member passes. ``anchored_iso`` alone may be ``None`` with the other two
+    set, when the save lacks the mtime anchor. ``game_seconds`` is
+    ``int(game_time - login)``: a floored, non-negative JSON int.
+
+    Cluster profiles are out of scope by construction: nothing puts a
+    foreign-map Profile into ``save.profiles``, so every candidate here lives
+    on this map's game clock. No defensive logic needed.
     """
-    assert isinstance(profile_active, dict), "profile_active must be a dict"
-    candidates: list[dt.datetime] = []
-    if isinstance(file_date, dt.datetime):
-        candidates.append(file_date if file_date.tzinfo else file_date.astimezone())
+    assert isinstance(profile_login_raw, dict), "profile_login_raw must be a dict"
+    if game_time <= 0:
+        return None, None, None
+    best_pid: int | None = None
+    best_raw = float("-inf")
     for i, pid in enumerate(member_ids):
         assert i < _MAX_TRIBE_MEMBERS, "tribe member list exceeded bound"
-        active = profile_active.get(_int(pid))
-        if active is not None:
-            candidates.append(active if active.tzinfo else active.astimezone())
-    now = dt.datetime.now(dt.timezone.utc)
-    past = [c for c in candidates if c <= now]
-    if not past:
+        raw = profile_login_raw.get(_int(pid))
+        if raw is None or raw > game_time or raw <= best_raw:
+            continue
+        best_pid = _int(pid)
+        best_raw = raw
+    if best_pid is None:
+        return None, None, None
+    seconds = int(game_time - best_raw)
+    assert seconds >= 0, "game_seconds must be non-negative after the future filter"
+    anchored = profile_active.get(best_pid)
+    iso = anchored.isoformat() if anchored is not None else None
+    return iso, best_pid, seconds
+
+
+def _file_date_iso(value: t.Any) -> str | None:
+    """ISO 8601 for a tribe file date, dropping future values (clock skew,
+    bad rsync). Non-datetime input yields ``None``."""
+    if not isinstance(value, dt.datetime):
         return None
-    return max(past).isoformat()
+    aware = value if value.tzinfo else value.astimezone()
+    assert aware.tzinfo is not None, "file date must be timezone-aware here"
+    now = dt.datetime.now(dt.timezone.utc)
+    assert now.tzinfo is not None, "now must be timezone-aware"
+    return aware.isoformat() if aware <= now else None
 
 
-def _profile_actives(profiles: list[Profile], save: t.Any) -> dict[int, dt.datetime]:
-    """``player_id -> last-active datetime`` for tribe activity rollups.
+def _profile_actives(
+    profiles: list[Profile], save: t.Any
+) -> tuple[dict[int, dt.datetime], dict[int, float]]:
+    """Per-player last-login maps for tribe activity rollups.
 
-    Mirrors legacy ContentPlayer.LastActiveDateTime: the profile's
-    LastLoginTime converted through the save anchor.
+    Returns ``(anchored, raw)``: ``anchored`` is ``player_id -> LastLoginTime``
+    converted through the save anchor (legacy ContentPlayer.LastActiveDateTime,
+    inherits .ark mtime error); ``raw`` is ``player_id -> LastLoginTime`` as
+    in-game seconds, untouched by any filesystem state. One pass over
+    ``profiles`` fills both.
     """
     assert isinstance(profiles, list), "profiles must be a list"
-    out: dict[int, dt.datetime] = {}
+    anchored: dict[int, dt.datetime] = {}
+    raw: dict[int, float] = {}
     for prof in profiles:
         pid = _int(prof.player_id)
         if not pid:
             continue
+        login = _float(prof.last_login_time)
+        if login > 0:
+            raw[pid] = login
         active = _approx_real_datetime(prof.last_login_time, save)
         if active is not None:
-            out[pid] = active
-    return out
+            anchored[pid] = active
+    assert len(anchored) <= len(profiles) and len(raw) <= len(profiles), "rollup maps exceed input"
+    return anchored, raw
 
 
 def _build_profile_index(save: t.Any) -> dict[int, Profile]:
@@ -2785,7 +2836,7 @@ def _assemble_tribes(save: t.Any) -> dict[str, t.Any]:
                 member_name.setdefault(pid, mname)
     file_tribe_ids = set(rich) | {_UNCLAIMED_TRIBE_ID, _ABANDONED_TRIBE_ID}
     profiles = _profile_entries(save)
-    profile_active = _profile_actives(profiles, save)
+    profile_active, profile_login_raw = _profile_actives(profiles, save)
     profile_tribeid, players_by_tribe = _allocate_profiles(
         profiles, file_tribe_ids, member_index, tribe_members
     )
@@ -2814,6 +2865,8 @@ def _assemble_tribes(save: t.Any) -> dict[str, t.Any]:
         "counts": counts,
         "profile_index": profile_index,
         "profile_active": profile_active,
+        "profile_login_raw": profile_login_raw,
+        "game_time": _float(getattr(save, "game_time", 0.0)),
         "players_by_tribe": players_by_tribe,
         "profile_tribeid": profile_tribeid,
         "member_stubs": member_stubs,
@@ -2862,18 +2915,26 @@ def _tribe_record(tid: int, a: dict[str, t.Any]) -> dict[str, t.Any]:
 
     File-backed tribes reuse the rich record (dataFile/owner/alliances) but
     have ``players``/``members`` overridden to the allocated-player set so
-    they match the legacy writer (which counts allocated profiles, not the raw
-    member list). Synthesized stubs carry id + name + world-derived counts.
-    ``active`` finalizes here for both shapes: max of the tribe file date and
-    the allocated members' last-active times (legacy ContentTribe.LastActive).
+    they match the legacy writer. ``active`` is the anchored last member
+    login when one exists, else the tribe file date (spec D1-b; deliberate
+    deviation from legacy ContentTribe.LastActive, which was the file mtime
+    on every file-backed tribe). The three ``last_member_login*`` fields are
+    the mtime-immune signal and always emit, null meaning "cannot tell".
     """
+    assert isinstance(a, dict), "assembled tribes must be a dict"
     players = a["players_by_tribe"].get(tid, [])
+    iso, login_pid, game_seconds = _tribe_last_login(
+        players, a["profile_active"], a["profile_login_raw"], a["game_time"]
+    )
     base = a["rich"].get(tid)
     if base is not None:
         rec = dict(base)
         rec["players"] = len(players)
         rec["members"] = _members_for(tid, a)
-        rec["active"] = _tribe_active_iso(rec.get("active"), players, a["profile_active"])
+        rec["active"] = iso if iso is not None else _file_date_iso(rec.get("active"))
+        rec["last_member_login"] = iso
+        rec["last_member_login_player_id"] = login_pid
+        rec["last_member_login_game_seconds"] = game_seconds
         return rec
     c = a["counts"].get(tid, {})
     data: dict[str, t.Any] = {
@@ -2884,10 +2945,13 @@ def _tribe_record(tid: int, a: dict[str, t.Any]) -> dict[str, t.Any]:
         "tames": c.get("tames", 0),
         "uploadedTames": 0,
         "structures": c.get("structures", 0),
-        "active": _tribe_active_iso(None, players, a["profile_active"]),
+        "active": iso,
         "dataFile": "",
+        "last_member_login": iso,
+        "last_member_login_player_id": login_pid,
+        "last_member_login_game_seconds": game_seconds,
     }
-    return _compact(data, LEGACY_TRIBE_KEYS)
+    return _compact(data, TRIBE_KEEP_KEYS)
 
 
 def export_tribes(save: t.Any) -> list[dict[str, t.Any]]:

{arkparser-0.7.5 → arkparser-0.9.0}/arkparser/files/__init__.py

@@ -12,6 +12,7 @@ All parsers support both ASE and ASA formats with automatic detection.
 
 from .base import ArkFile
 from .cloud_inventory import CloudInventory
+from .embedded_store import EmbeddedStore
 from .profile import Profile
 from .tribe import Tribe
 from .world_save import WorldSave
@@ -22,4 +23,5 @@ __all__ = [
     "Tribe",
     "CloudInventory",
     "WorldSave",
+    "EmbeddedStore",
 ]

arkparser-0.9.0/arkparser/files/embedded_store.py

@@ -0,0 +1,261 @@
+"""
+Player and tribe store packed inside an ASA world save.
+
+Some ASA servers (Nitrado observed) never write ``.arkprofile`` / ``.arktribe``
+files. The same files are packed into the save's ``custom`` table under the
+``GameModeCustomBytes`` key instead. Servers that do write the files leave that
+row at a few dozen bytes.
+
+Blob layout (int32 little-endian)::
+
+    Int32  format                     # 1
+    repeat (tribes, then profiles):
+      Int32  section_size             # bytes of packed files that follow
+      Int32  count                    # size 0 + count 0 = terminator, ends the blob
+      Bytes  files[section_size]      # complete .arktribe / .arkprofile files
+      count x { Bytes(8) key, Int32 offset, Int32 size }
+
+The store is append-style: each save writes a fresh copy of a changed tribe or
+profile and zeroes the old copy's key. Only entries with a non-zero key are
+current. Each packed file is byte-identical in format to a sidecar file, so it
+loads with ``Tribe.load(bytes)`` / ``Profile.load(bytes)`` unchanged.
+
+Pieces are read with ``substr()`` slices so a large store never sits in memory
+whole: the index first, then one current file at a time.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import struct
+import typing as t
+from dataclasses import dataclass, field
+
+from ..common.exceptions import CorruptDataError
+from ..game_objects.game_object import MAX_OBJECT_COUNT
+from .profile import Profile
+from .tribe import Tribe
+
+logger = logging.getLogger(__name__)
+
+STORE_KEY = "GameModeCustomBytes"
+STORE_FORMAT = 1
+NO_STORE_FORMAT = 0
+# Tribes + profiles + one spare for a future section type.
+MAX_SECTIONS = 3
+INDEX_ENTRY = struct.Struct("<8sii")
+ZERO_KEY = b"\x00" * 8
+# Where the class-name string sits in a v7 packed file: version, two header
+# ints, object count, then the first object's 16-byte GUID.
+CLASS_NAME_OFFSET = 32
+MAX_CLASS_NAME = 256
+
+_SIZE_SQL = "SELECT length(value) FROM custom WHERE key = ?"
+_SLICE_SQL = "SELECT substr(value, ?, ?) FROM custom WHERE key = ?"
+
+
+@dataclass
+class EmbeddedStore:
+    """Current profiles and tribes read out of a save's packed store.
+
+    Attributes:
+        profiles: One ``Profile`` per player (latest copy).
+        tribes: One ``Tribe`` per tribe (latest copy).
+        superseded_profiles: Old profile copies skipped (zero key).
+        superseded_tribes: Old tribe copies skipped (zero key).
+        errors: Problems found, one line each. A bad entry is skipped and the
+            rest still load; a bad layout empties the result.
+    """
+
+    profiles: list[Profile] = field(default_factory=list)
+    tribes: list[Tribe] = field(default_factory=list)
+    superseded_profiles: int = 0
+    superseded_tribes: int = 0
+    errors: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class StoreSection:
+    """One section's location in the blob plus its raw index entries."""
+
+    data_start: int
+    data_size: int
+    entries: list[tuple[bytes, int, int]]
+
+
+class BlobSlicer:
+    """Reads byte ranges of the store row without loading the whole value."""
+
+    def __init__(self, conn: sqlite3.Connection, size: int) -> None:
+        assert size >= 0, "negative blob size"
+        self.conn = conn
+        self.size = size
+
+    def read(self, offset: int, length: int) -> bytes:
+        """Return ``length`` bytes at 0-based ``offset``, or raise if out of range."""
+        if offset < 0 or length < 0 or offset + length > self.size:
+            raise CorruptDataError(
+                f"store read {offset}+{length} past blob end {self.size}"
+            )
+        if length == 0:
+            return b""
+        row = self.conn.execute(_SLICE_SQL, (offset + 1, length, STORE_KEY)).fetchone()
+        data = bytes(row[0]) if row is not None and row[0] is not None else b""
+        if len(data) != length:
+            raise CorruptDataError(f"store read {offset}+{length} returned {len(data)} bytes")
+        return data
+
+    def read_int32_pair(self, offset: int) -> tuple[int, int]:
+        """Read two little-endian int32 values at ``offset``."""
+        first, second = struct.unpack("<2i", self.read(offset, 8))
+        return first, second
+
+
+def load_embedded_store(conn: sqlite3.Connection) -> EmbeddedStore:
+    """Read the packed profile/tribe store from an open ASA save connection.
+
+    Pre: ``conn`` is an open connection to an ASA save (has a ``custom``
+    table). Post: returns the current entries; an absent or near-empty store
+    returns an empty result with no errors, and a malformed layout returns an
+    empty result with one error line. Never raises for bad store data.
+    """
+    assert conn is not None, "connection required"
+    row = conn.execute(_SIZE_SQL, (STORE_KEY,)).fetchone()
+    size = int(row[0]) if row is not None and row[0] is not None else 0
+    store = EmbeddedStore()
+    if size <= 8:
+        return store
+    slicer = BlobSlicer(conn, size)
+    # Servers that write sidecar files leave this row all zeros (20-28 bytes
+    # observed), so format 0 means "no store", not a malformed one.
+    if struct.unpack("<i", slicer.read(0, 4))[0] == NO_STORE_FORMAT:
+        return store
+    try:
+        sections = read_sections(slicer)
+    except CorruptDataError as exc:
+        store.errors.append(f"store layout: {exc}")
+        return store
+    for number, section in enumerate(sections):
+        load_section(slicer, section, number, store)
+    assert len(store.profiles) + len(store.tribes) <= MAX_OBJECT_COUNT, "store overflow"
+    return store
+
+
+def read_sections(slicer: BlobSlicer) -> list[StoreSection]:
+    """Walk the blob's section headers and index tables.
+
+    Pre: blob is longer than 8 bytes. Post: returns every section up to the
+    terminator, with bounds checked; raises ``CorruptDataError`` on any
+    impossible count, size, or a missing terminator.
+    """
+    assert slicer.size > 8, "store too small to hold a section"
+    fmt = struct.unpack("<i", slicer.read(0, 4))[0]
+    if fmt != STORE_FORMAT:
+        raise CorruptDataError(f"unknown store format {fmt}")
+    sections: list[StoreSection] = []
+    pos = 4
+    for _ in range(MAX_SECTIONS + 1):
+        data_size, count = slicer.read_int32_pair(pos)
+        pos += 8
+        if data_size == 0 and count == 0:
+            assert pos <= slicer.size, "terminator past blob end"
+            return sections
+        if data_size < 0 or not 0 <= count <= MAX_OBJECT_COUNT:
+            raise CorruptDataError(f"section size {data_size} / count {count} out of range")
+        if len(sections) == MAX_SECTIONS:
+            raise CorruptDataError(f"more than {MAX_SECTIONS} sections")
+        index_start = pos + data_size
+        raw_index = slicer.read(index_start, count * INDEX_ENTRY.size)
+        entries = [tuple(e) for e in INDEX_ENTRY.iter_unpack(raw_index)]
+        sections.append(StoreSection(pos, data_size, t.cast(list[tuple[bytes, int, int]], entries)))
+        pos = index_start + count * INDEX_ENTRY.size
+    raise CorruptDataError("no section terminator")
+
+
+def entry_in_bounds(section: StoreSection, offset: int, size: int) -> bool:
+    """True when an index entry's file lies inside its section's data."""
+    assert section.data_size >= 0, "negative section size"
+    return 0 <= offset and 0 < size and offset + size <= section.data_size
+
+
+def section_kind(slicer: BlobSlicer, section: StoreSection) -> type[Profile] | type[Tribe] | None:
+    """Classify a section by the class name in its first in-bounds file.
+
+    Pre: section bounds already validated. Post: ``Tribe``, ``Profile``, or
+    ``None`` when no entry names a known class.
+    """
+    assert section.entries is not None, "section has no index"
+    for _, offset, size in section.entries:
+        if not entry_in_bounds(section, offset, size) or size < CLASS_NAME_OFFSET + 4:
+            continue
+        head = slicer.read(section.data_start + offset, min(size, CLASS_NAME_OFFSET + 4 + MAX_CLASS_NAME))
+        length = struct.unpack_from("<i", head, CLASS_NAME_OFFSET)[0]
+        name = head[CLASS_NAME_OFFSET + 4 : CLASS_NAME_OFFSET + 4 + max(0, length)]
+        if Tribe.MAIN_CLASS_NAME.encode() in name:
+            return Tribe
+        if Profile.MAIN_CLASS_NAME.encode() in name:
+            return Profile
+        return None
+    return None
+
+
+def load_section(slicer: BlobSlicer, section: StoreSection, number: int, store: EmbeddedStore) -> None:
+    """Load the current entries of one section into ``store``.
+
+    Pre: ``section`` came from :func:`read_sections`. Post: current files are
+    parsed and de-duplicated by id (latest in index order wins); superseded
+    copies are counted; per-entry failures are recorded, never raised.
+    """
+    assert number >= 0, "negative section number"
+    kind = section_kind(slicer, section)
+    if kind is None:
+        store.errors.append(f"section {number}: unknown content, skipped")
+        return
+    label = "tribe" if kind is Tribe else "profile"
+    latest: dict[int, Profile | Tribe] = {}
+    superseded = 0
+    for i, (key, offset, size) in enumerate(section.entries):
+        if key == ZERO_KEY:
+            superseded += 1
+            continue
+        loaded = load_entry(slicer, section, kind, offset, size)
+        if isinstance(loaded, str):
+            store.errors.append(f"{label} #{i}: {loaded}")
+            continue
+        ident = loaded.tribe_id if isinstance(loaded, Tribe) else loaded.player_id
+        latest[ident if isinstance(ident, int) else -1 - i] = loaded
+    if kind is Tribe:
+        store.tribes.extend(t.cast(list[Tribe], list(latest.values())))
+        store.superseded_tribes += superseded
+    else:
+        store.profiles.extend(t.cast(list[Profile], list(latest.values())))
+        store.superseded_profiles += superseded
+    assert superseded <= len(section.entries), "superseded count exceeds entries"
+
+
+def load_entry(
+    slicer: BlobSlicer,
+    section: StoreSection,
+    kind: type[Profile] | type[Tribe],
+    offset: int,
+    size: int,
+) -> Profile | Tribe | str:
+    """Parse one packed file; return the object or an error string.
+
+    Pre: ``kind`` is ``Profile`` or ``Tribe``. Post: never raises for bad
+    entry data; out-of-bounds entries, unknown versions, and parse failures
+    come back as a one-line reason.
+    """
+    assert kind in (Profile, Tribe), "unsupported entry kind"
+    if not entry_in_bounds(section, offset, size) or size < 4:
+        return f"offset {offset} size {size} outside section of {section.data_size} bytes"
+    raw = slicer.read(section.data_start + offset, size)
+    version = struct.unpack_from("<i", raw, 0)[0]
+    if version not in kind.VALID_VERSIONS:
+        return f"unsupported file version {version}"
+    try:
+        return kind.load(raw)
+    except Exception as exc:  # noqa: BLE001 - one bad entry must not sink the store
+        logger.debug("Embedded %s entry failed to parse", kind.__name__, exc_info=True)
+        return f"{type(exc).__name__}: {exc}"

{arkparser-0.7.5 → arkparser-0.9.0}/arkparser/files/world_save.py

@@ -40,6 +40,7 @@ from ..game_objects.container import GameObjectContainer
 from ..game_objects.game_object import MAX_OBJECT_COUNT, GameObject
 from ..game_objects.location import LocationData
 from ..properties.registry import read_properties, read_properties_partial
+from .embedded_store import EmbeddedStore, load_embedded_store
 
 logger = logging.getLogger(__name__)
 
@@ -171,6 +172,9 @@ class WorldSave:
     # matching the legacy ContentContainer.GetApproxDateTimeOf formula:
     # real = file_mtime + (object_time - game_time).
     file_mtime: dt.datetime | None = None
+    # Path the save was loaded from (None when loaded from bytes). Lets
+    # read_embedded_store reopen an eagerly loaded ASA save's database.
+    source_path: Path | None = None
 
     # ASE-specific
     embedded_data: list[EmbeddedData] = field(default_factory=list)
@@ -324,6 +328,7 @@ class WorldSave:
                 reader = BinaryReader.from_file(path)
             save = cls._parse_ase(reader, load_properties, lazy_properties)
         save.file_mtime = mtime
+        save.source_path = path
         return save
 
     # ------------------------------------------------------------------
@@ -499,6 +504,33 @@ class WorldSave:
             if cryo is not None:
                 yield obj, cryo
 
+    def read_embedded_store(self) -> EmbeddedStore:
+        """Read the player/tribe files packed inside an ASA save.
+
+        Some ASA servers write no ``.arkprofile`` / ``.arktribe`` files and
+        pack them into the save instead (see ``embedded_store``). Not run by
+        :meth:`load`; callers that want the data ask for it, so load cost is
+        unchanged for everyone else.
+
+        Pre: the save was loaded from a path (ASA) or is ASE. Post: returns
+        the current profiles and tribes; ASE saves and saves without a store
+        return an empty :class:`EmbeddedStore`. Reuses the lazy connection
+        when present, otherwise opens and closes a read-only one.
+        """
+        if not self.is_asa:
+            return EmbeddedStore()
+        if self._lazy_conn is not None:
+            return load_embedded_store(self._lazy_conn)
+        assert self.source_path is not None, "ASA saves always load from a path"
+        uri = self.source_path.resolve().as_uri() + "?mode=ro"
+        conn = sqlite3.connect(uri, uri=True)
+        try:
+            store = load_embedded_store(conn)
+        finally:
+            conn.close()
+        assert isinstance(store, EmbeddedStore), "store loader returned wrong type"
+        return store
+
     # ------------------------------------------------------------------
     # Properties
     # ------------------------------------------------------------------