arkparser 0.5.0__tar.gz → 0.5.4__tar.gz

{arkparser-0.5.0 → arkparser-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.5.0
+Version: 0.5.4
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT

{arkparser-0.5.0 → arkparser-0.5.4}/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.5.0"
+"""
+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.4"

{arkparser-0.5.0 → arkparser-0.5.4}/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.5.0 → arkparser-0.5.4}/arkparser/data_models.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import logging
 import math
+import re
 import typing as t
 from dataclasses import dataclass, field
 
@@ -18,6 +19,26 @@ from .properties.registry import read_properties
 
 logger = logging.getLogger(__name__)
 
+# 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
+# discards this instance int32, so non-cryo tames never carry it. Strip it to
+# match the canonical class name ("Raptor_Character_BP_C") and legacy parity.
+_INSTANCE_SUFFIX_RE = re.compile(r"_\d+$")
+
+
+def _strip_instance_suffix(class_name: str) -> str:
+    """Drop a trailing ``_<digits>`` actor-instance suffix from a class name.
+
+    Pre: ``class_name`` is a str. Post: returns the same string with at most one
+    trailing ``_<digits>`` group removed. Legit variant suffixes (``_Aberrant_C``,
+    ``_Fire_C``) end in a letter, so they are never touched.
+    """
+    assert isinstance(class_name, str), "class_name must be str"
+    stripped = _INSTANCE_SUFFIX_RE.sub("", class_name)
+    assert len(stripped) <= len(class_name), "strip must not grow the string"
+    return stripped
+
 
 def _finite(value: t.Any, default: float) -> float:
     """Coerce to a finite float; NaN / inf / non-numeric collapse to ``default``.
@@ -514,7 +535,7 @@ class CryopodCreature:
             # Parse strings - need at least 3 for basic info
             strings = normalize_indexed_list(custom_data.get("CustomDataStrings"))
             if len(strings) >= 3:
-                cryo.class_name = strings[0]  # e.g., "Raptor_Character_BP_C_2145673735"
+                cryo.class_name = _strip_instance_suffix(strings[0])  # raw: "Raptor_Character_BP_C_2145673735"
                 display_name = strings[1]  # e.g., "bluey - Lvl 228 (Raptor)"
                 colors_str = strings[2]  # e.g., "2,2,2,2,2,2,"
 
@@ -602,7 +623,9 @@ class CryopodCreature:
             if soft_classes:
                 first_class = soft_classes[0]
                 if isinstance(first_class, dict):
-                    cryo.class_name = first_class.get("name", cryo.class_name)
+                    cryo.class_name = _strip_instance_suffix(
+                        first_class.get("name", cryo.class_name)
+                    )
 
             # Populate raw creature_props / status_props so the export
             # pipeline's _SyntheticGameObject adapter (which calls

{arkparser-0.5.0 → arkparser-0.5.4}/arkparser/export.py

@@ -32,6 +32,7 @@ Performance:
 from __future__ import annotations
 
 import datetime as dt
+import itertools
 import json
 import logging
 import math
@@ -1366,13 +1367,21 @@ def export_tamed(save: t.Any, map_config: MapConfig | None = None) -> list[dict[
     (b) every cryopod-embedded tame, with the latter carrying ``cryo=True``
     and inheriting the cryopod item's world location for GPS fields.
     """
+    return list(_iter_tamed(save, map_config))
+
+
+def _iter_tamed(save: t.Any, map_config: MapConfig | None) -> t.Iterator[dict[str, t.Any]]:
+    """Yield ASV_Tamed records one at a time (see :func:`export_tamed`).
+
+    Generator form so :func:`export_to_files` can stream each record to disk
+    and release it instead of materializing the whole list (the list is the
+    dominant export-time allocation on large PvE saves).
+    """
     objects = _world_objects(save, "get_tamed_creatures", "tamed_objects")
     lookup = _save_lookup(save)
-    results: list[dict[str, t.Any]] = [
-        _tamed_dict(obj, _status_for(obj, lookup), lookup, map_config, save) for obj in objects
-    ]
-    results.extend(_export_world_cryopods(save, map_config))
-    return results
+    for obj in objects:
+        yield _tamed_dict(obj, _status_for(obj, lookup), lookup, map_config, save)
+    yield from _export_world_cryopods(save, map_config)
 
 
 def _build_item_owner_lookup(save: t.Any, lookup: dict[t.Any, t.Any]) -> dict[t.Any, dict[str, t.Any]]:
@@ -1820,10 +1829,16 @@ def _wild_dict(
 
 
 def export_wild(save: t.Any, map_config: MapConfig | None = None) -> list[dict[str, t.Any]]:
+    return list(_iter_wild(save, map_config))
+
+
+def _iter_wild(save: t.Any, map_config: MapConfig | None) -> t.Iterator[dict[str, t.Any]]:
+    """Yield ASV_Wild records one at a time (streaming form of export_wild)."""
     objects = _world_objects(save, "get_wild_creatures", "wild_objects")
     is_asa = bool(getattr(save, "is_asa", False))
     lookup = _save_lookup(save)
-    return [_wild_dict(obj, _status_for(obj, lookup), map_config, is_asa) for obj in objects]
+    for obj in objects:
+        yield _wild_dict(obj, _status_for(obj, lookup), map_config, is_asa)
 
 
 def _player_from_profile(
@@ -2073,6 +2088,15 @@ def export_players(
     map_config: MapConfig | None = None,
     cluster_inventories: t.Iterable[CloudInventory] | None = None,
 ) -> list[dict[str, t.Any]]:
+    return list(_iter_players(save, map_config, cluster_inventories))
+
+
+def _iter_players(
+    save: t.Any,
+    map_config: MapConfig | None,
+    cluster_inventories: t.Iterable[CloudInventory] | None,
+) -> t.Iterator[dict[str, t.Any]]:
+    """Yield ASV_Players records one at a time (streaming form of export_players)."""
     profiles = _collection(save, "profiles", Profile)
     lookup = _save_lookup(save)
     pawn_status_by_id = _player_status_by_data_id(save, lookup)
@@ -2083,7 +2107,6 @@ def export_players(
     allocation = _assemble_tribes(save)
     profile_tribeid = allocation["profile_tribeid"]
     tribe_names = allocation["names"]
-    results: list[dict[str, t.Any]] = []
     for entry in profiles:
         record, join_keys = _player_record_for(entry, save, pawn_status_by_id, lookup, map_config)
         if record is None:
@@ -2100,11 +2123,10 @@ def export_players(
                 inv_list = []
                 record["inventory"] = inv_list
             inv_list.extend(spliced)
-        results.append(record)
+        yield record
     # Tribe members with no .arkprofile surface as stub players (legacy +N).
     for tid, pid, name in allocation["member_stubs"]:
-        results.append(_member_stub_player(tid, pid, name, tribe_names.get(tid, "")))
-    return results
+        yield _member_stub_player(tid, pid, name, tribe_names.get(tid, ""))
 
 
 def _strip_rich_color(msg: str) -> str:
@@ -2761,20 +2783,23 @@ def _structure_dict(
 
 
 def export_structures(save: t.Any, map_config: MapConfig | None = None) -> list[dict[str, t.Any]]:
+    return list(_iter_structures(save, map_config))
+
+
+def _iter_structures(save: t.Any, map_config: MapConfig | None) -> t.Iterator[dict[str, t.Any]]:
+    """Yield ASV_Structures records one at a time (streaming form of export_structures)."""
     objects = _world_objects(save, "get_structures", "structure_objects")
     lookup = _save_lookup(save)
     # Reuse the assembled tribe-name map so a structure's ``tribe`` resolves to
     # the same name the tribes export uses (file TribeName / stub OwnerName).
     tribe_names = _assemble_tribes(save)["names"]
-    results: list[dict[str, t.Any]] = []
     for obj in objects:
         team = _int(_prop(obj, "TargetingTeam"))
         if team < _PLAYER_TEAM_THRESHOLD and _is_excluded_abandoned(getattr(obj, "class_name", "") or ""):
             # Unowned map element / crate / debug actor: legacy drops these
             # from ASV_Structures (surfaced via ASV_MapStructures instead).
             continue
-        results.append(_structure_dict(obj, save, lookup, map_config, tribe_names))
-    return results
+        yield _structure_dict(obj, save, lookup, map_config, tribe_names)
 
 
 # Mirrors C# ContentContainer.cs:846. Order matters: first match wins.
@@ -2810,10 +2835,14 @@ def export_map_structures(
     save: t.Any,
     map_config: MapConfig | None = None,
 ) -> list[dict[str, t.Any]]:
+    return list(_iter_map_structures(save, map_config))
+
+
+def _iter_map_structures(save: t.Any, map_config: MapConfig | None) -> t.Iterator[dict[str, t.Any]]:
+    """Yield ASV_MapStructures records one at a time (streaming form of export_map_structures)."""
     objects = getattr(save, "objects", None) or []
-    all_objs = list(objects.values()) if isinstance(objects, dict) else list(objects)
+    all_objs = objects.values() if isinstance(objects, dict) else objects
     lookup = _save_lookup(save)
-    results: list[dict[str, t.Any]] = []
     for obj in all_objs:
         cn = getattr(obj, "class_name", "") or ""
         label = _asv_map_struct_label(cn)
@@ -2829,8 +2858,7 @@ def export_map_structures(
             "inventory": _inventory_items(obj, lookup),
         }
         data.update(_gps_payload(obj, map_config))
-        results.append(data)
-    return results
+        yield data
 
 
 # Legacy ASVExport.exe filenames. Single canonical schema.
@@ -2845,12 +2873,8 @@ _EXPORT_NAMES: dict[str, str] = {
 }
 
 
-def _wrap_with_meta(
-    data: list[dict[str, t.Any]],
-    save: t.Any,
-    map_config: MapConfig | None = None,
-) -> dict[str, t.Any]:
-    """Wrap a payload in legacy ``{map, day, time, data}`` envelope."""
+def _meta_head(save: t.Any, map_config: MapConfig | None = None) -> dict[str, t.Any]:
+    """Return the legacy envelope head ``{map, day, time}`` (no ``data`` key)."""
     map_name = getattr(map_config, "name", "") if map_config is not None else ""
     day = 0
     time_str = "00:00"
@@ -2859,7 +2883,74 @@ def _wrap_with_meta(
         day = int(game_time // 86400)
         rem = int(game_time % 86400)
         time_str = f"{rem // 3600:02d}:{(rem % 3600) // 60:02d}"
-    return {"map": map_name, "day": day, "time": time_str, "data": data}
+    return {"map": map_name, "day": day, "time": time_str}
+
+
+def _wrap_with_meta(
+    data: list[dict[str, t.Any]],
+    save: t.Any,
+    map_config: MapConfig | None = None,
+) -> dict[str, t.Any]:
+    """Wrap a payload in the legacy ``{map, day, time, data}`` envelope.
+
+    Retained for callers that already hold a materialized list (e.g. the
+    validation harness diffing against legacy). :func:`export_to_files`
+    streams via :func:`_stream_dump` instead and does not use this.
+    """
+    return {**_meta_head(save, map_config), "data": data}
+
+
+def _stream_dump(
+    fh: t.TextIO,
+    head: dict[str, t.Any] | None,
+    records: t.Iterable[dict[str, t.Any]],
+    dump_kwargs: dict[str, t.Any],
+) -> None:
+    """Stream a JSON array to ``fh``, one record at a time.
+
+    Writes a bare ``[records...]`` array when ``head`` is ``None``, otherwise
+    splices the records into ``head`` under a ``"data"`` key
+    (``{..head.., "data": [records...]}``). Each record is encoded and written
+    individually, then released — the full record list never co-resides in
+    memory. The result round-trips identically (at the value level) to
+    ``json.dump(head | {"data": list(records)}, fh, **dump_kwargs)``; only
+    insignificant whitespace differs.
+
+    Pre-conditions: ``records`` is a finite iterable of JSON-serializable
+    dicts; ``dump_kwargs`` carries the same ``indent`` / ``separators`` /
+    ``default`` used elsewhere. Post-conditions: ``fh`` holds one complete,
+    valid JSON document.
+    """
+    indent = dump_kwargs.get("indent")
+    rec_kwargs: dict[str, t.Any] = {"default": dump_kwargs.get("default", str)}
+    if indent:
+        rec_kwargs["indent"] = indent
+    else:
+        rec_kwargs["separators"] = (",", ":")
+    nl = "\n" if indent else ""
+    if head is not None:
+        head_json = json.dumps(head, **rec_kwargs)
+        assert head_json.endswith("}"), "envelope head must serialize to a JSON object"
+        # Splice the data array in just before the head object's closing brace
+        # (indented dumps leave a trailing "\n}", compact a bare "}").
+        fh.write(head_json[: -2 if indent else -1])
+        fh.write(f',{nl}{" " * indent}"data": [' if indent else ',"data":[')
+        rec_pad = " " * (indent * 2) if indent else ""
+        close_pad = " " * indent if indent else ""
+    else:
+        fh.write("[")
+        rec_pad = " " * indent if indent else ""
+        close_pad = ""
+    first = True
+    for rec in records:
+        chunk = json.dumps(rec, **rec_kwargs)
+        if indent:
+            chunk = rec_pad + chunk.replace("\n", "\n" + rec_pad)
+        fh.write(("" if first else ",") + nl + chunk)
+        first = False
+    fh.write("]" if first else nl + close_pad + "]")
+    if head is not None:
+        fh.write(nl + "}")
 
 
 def _load_cluster_inventories(
@@ -2909,18 +3000,33 @@ def export_all(
     Note: returns flat lists per type (not the legacy ``{map, day, time, data}``
     envelope). ``export_to_files`` adds the envelope when writing.
     """
+    return {name: list(records) for name, records in _iter_exports(save, map_config, cluster)}
+
+
+def _iter_exports(
+    save: t.Any,
+    map_config: MapConfig | None,
+    cluster: str | Path | t.Iterable[CloudInventory] | None,
+) -> t.Iterator[tuple[str, t.Iterable[dict[str, t.Any]]]]:
+    """Yield ``(ASV_name, record_iterable)`` one export type at a time.
+
+    The heavy types (tamed / wild / players / structures / map_structures)
+    yield **lazy generators** so :func:`export_to_files` can stream each
+    record to disk and release it — the full per-type list never
+    materializes (it is the dominant export-time allocation on large PvE
+    saves). The small types (tribes / tribe_logs) stay eager lists.
+    :func:`export_all` wraps each iterable in ``list()`` for callers that
+    want every record in memory.
+    """
     cluster_invs = _load_cluster_inventories(cluster)
     cluster_tamed = export_cluster_uploads(cluster_invs, map_config) if cluster_invs else []
-    tamed = export_tamed(save, map_config) + cluster_tamed
-    return {
-        _EXPORT_NAMES["tamed"]: tamed,
-        _EXPORT_NAMES["wild"]: export_wild(save, map_config),
-        _EXPORT_NAMES["players"]: export_players(save, map_config, cluster_invs or None),
-        _EXPORT_NAMES["tribes"]: export_tribes(save),
-        _EXPORT_NAMES["structures"]: export_structures(save, map_config),
-        _EXPORT_NAMES["tribe_logs"]: export_tribe_logs(save),
-        _EXPORT_NAMES["map_structures"]: export_map_structures(save, map_config),
-    }
+    yield _EXPORT_NAMES["tamed"], itertools.chain(_iter_tamed(save, map_config), cluster_tamed)
+    yield _EXPORT_NAMES["wild"], _iter_wild(save, map_config)
+    yield _EXPORT_NAMES["players"], _iter_players(save, map_config, cluster_invs or None)
+    yield _EXPORT_NAMES["tribes"], export_tribes(save)
+    yield _EXPORT_NAMES["structures"], _iter_structures(save, map_config)
+    yield _EXPORT_NAMES["tribe_logs"], export_tribe_logs(save)
+    yield _EXPORT_NAMES["map_structures"], _iter_map_structures(save, map_config)
 
 
 def export_to_files(
@@ -2952,9 +3058,15 @@ def export_to_files(
         dump_kwargs: dict[str, t.Any] = {"separators": (",", ":"), "default": str}
     else:
         dump_kwargs = {"indent": 2, "default": str}
-    for name, data in export_all(save, map_config, cluster=cluster).items():
-        payload: t.Any = _wrap_with_meta(data, save, map_config) if wrap else data
+    # Stream each export type record-by-record straight to its file: a record
+    # is built, encoded, written, then released. The full per-type list never
+    # materializes and no whole-file JSON string is built — both were the
+    # measured peak-RAM drivers on large PvE saves (the structures list alone
+    # was hundreds of MB of nested inventory dicts).
+    head = _meta_head(save, map_config) if wrap else None
+    for name, records in _iter_exports(save, map_config, cluster):
         path = out / f"{name}.json"
-        path.write_text(json.dumps(payload, **dump_kwargs), encoding="utf-8")
+        with path.open("w", encoding="utf-8") as fh:
+            _stream_dump(fh, head, records, dump_kwargs)
         created.append(path)
     return created

{arkparser-0.5.0 → arkparser-0.5.4}/arkparser/game_objects/game_object.py

@@ -64,23 +64,34 @@ class GameObject:
     parent: GameObject | None = field(default=None, repr=False)
     components: dict[str, GameObject] = field(default_factory=dict, repr=False)
 
-    # Lazy property index: name -> {index: Property}. Built on first lookup,
-    # invalidated by setting to None when properties is mutated.
-    _prop_index: dict[str, dict[int, "Property"]] | None = field(default=None, repr=False, compare=False)
+    # Lazy property index: name -> Property (single-index, the common case) OR
+    # name -> {index: Property} (only when a name carries >1 distinct index).
+    # Storing the bare Property for single-index names avoids allocating one
+    # inner dict per (object, name): on a 300k-object save that was ~5.4M dicts
+    # / ~600 MB of pure index overhead built during export. Built on first
+    # lookup, invalidated by setting to None when properties is mutated.
+    _prop_index: dict[str, "Property | dict[int, Property]"] | None = field(
+        default=None, repr=False, compare=False
+    )
 
-    def _build_prop_index(self) -> dict[str, dict[int, "Property"]]:
-        idx: dict[str, dict[int, "Property"]] = {}
+    def _build_prop_index(self) -> dict[str, "Property | dict[int, Property]"]:
+        # First-writer wins, matching legacy C# GetPropertyValue
+        # (IPropertyContainer.cs:45) which returns the first (name, index)
+        # match. _serialize_properties keeps all occurrences in the additive
+        # `properties` dict; lookups intentionally mirror legacy here. Do not
+        # switch to last-wins.
+        idx: dict[str, "Property | dict[int, Property]"] = {}
         for prop in self.properties:
-            bucket = idx.get(prop.name)
-            if bucket is None:
-                idx[prop.name] = {prop.index: prop}
-            else:
-                # First-writer wins, matching legacy C# GetPropertyValue
-                # (IPropertyContainer.cs:45) which returns the first (name,
-                # index) match. _serialize_properties keeps all occurrences in
-                # the additive `properties` dict; lookups intentionally mirror
-                # legacy here. Do not switch to last-wins.
-                bucket.setdefault(prop.index, prop)
+            existing = idx.get(prop.name)
+            if existing is None:
+                idx[prop.name] = prop  # common case: store the bare Property
+            elif isinstance(existing, dict):
+                existing.setdefault(prop.index, prop)
+            elif existing.index != prop.index:
+                # Second distinct index for this name: promote to a dict.
+                # `existing` first preserves first-writer iteration order.
+                idx[prop.name] = {existing.index: existing, prop.index: prop}
+            # else: duplicate (name, index) -> keep first-writer `existing`.
         self._prop_index = idx
         return idx
 
@@ -108,11 +119,16 @@ class GameObject:
         """Get a property by name and optional index (None = first by insertion)."""
         idx = self._prop_index if self._prop_index is not None else self._build_prop_index()
         bucket = idx.get(name)
-        if not bucket:
+        if bucket is None:
             return None
-        if index is None:
-            return next(iter(bucket.values()))
-        return bucket.get(index)
+        if isinstance(bucket, dict):
+            if index is None:
+                return next(iter(bucket.values()))
+            return bucket.get(index)
+        # Single-index bucket: the bare Property.
+        if index is None or bucket.index == index:
+            return bucket
+        return None
 
     def get_property_value(self, name: str, default: t.Any = None, index: int | None = None) -> t.Any:
         """Get a property value by name (returns default if missing)."""
@@ -123,7 +139,11 @@ class GameObject:
         """Get all properties with the given name (any index)."""
         idx = self._prop_index if self._prop_index is not None else self._build_prop_index()
         bucket = idx.get(name)
-        return list(bucket.values()) if bucket else []
+        if bucket is None:
+            return []
+        if isinstance(bucket, dict):
+            return list(bucket.values())
+        return [bucket]
 
     def has_property(self, name: str) -> bool:
         """Check if this object has a property with the given name."""