arkparser 0.1.0__py3-none-any.whl

arkparser/game_objects/__init__.py

@@ -0,0 +1,32 @@
+"""
+ARK Game Objects.
+
+This module provides classes for representing game objects from ARK save files.
+
+Game objects are the fundamental entities - creatures, items, structures, players,
+and other game entities.
+
+Usage:
+    from arkparser.game_objects import GameObject, GameObjectContainer, LocationData
+
+    # Read objects from binary
+    objects = read_object_list(reader, is_asa=False)
+
+    # Create a container for lookup
+    container = GameObjectContainer(objects=objects)
+    container.build_relationships()
+
+    # Find creatures
+    creatures = container.get_creatures()
+"""
+
+from .container import GameObjectContainer
+from .game_object import GameObject, read_object_list
+from .location import LocationData
+
+__all__ = [
+    "LocationData",
+    "GameObject",
+    "GameObjectContainer",
+    "read_object_list",
+]

arkparser/game_objects/container.py

@@ -0,0 +1,180 @@
+"""
+Game Object Container.
+
+A container for game objects that provides lookup and relationship management.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass, field
+
+from .game_object import GameObject
+
+if t.TYPE_CHECKING:
+    from ..common.binary_reader import BinaryReader
+
+
+@dataclass
+class GameObjectContainer:
+    """
+    Container for a collection of game objects.
+
+    Provides methods for looking up objects by ID, class name, or name,
+    and manages parent/component relationships.
+    """
+
+    objects: list[GameObject] = field(default_factory=list)
+
+    # Lookup caches (built on demand)
+    _by_guid: dict[str, GameObject] = field(default_factory=dict, repr=False)
+    _by_class: dict[str, list[GameObject]] = field(default_factory=dict, repr=False)
+    _by_name: dict[str, GameObject] = field(default_factory=dict, repr=False)
+
+    def __len__(self) -> int:
+        return len(self.objects)
+
+    def __iter__(self) -> t.Iterator[GameObject]:
+        return iter(self.objects)
+
+    def __getitem__(self, index: int) -> GameObject:
+        return self.objects[index]
+
+    def add(self, obj: GameObject) -> None:
+        """Add an object to the container."""
+        self.objects.append(obj)
+        self._invalidate_caches()
+
+    def _invalidate_caches(self) -> None:
+        """Clear lookup caches."""
+        self._by_guid.clear()
+        self._by_class.clear()
+        self._by_name.clear()
+
+    def _build_caches(self) -> None:
+        """Build lookup caches if empty."""
+        if not self._by_guid and self.objects:
+            for obj in self.objects:
+                if obj.guid:
+                    self._by_guid[obj.guid] = obj
+                if obj.class_name:
+                    if obj.class_name not in self._by_class:
+                        self._by_class[obj.class_name] = []
+                    self._by_class[obj.class_name].append(obj)
+                if obj.primary_name:
+                    self._by_name[obj.primary_name] = obj
+
+    def get_by_id(self, obj_id: int) -> GameObject | None:
+        """Get object by ID."""
+        if 0 <= obj_id < len(self.objects):
+            return self.objects[obj_id]
+        return None
+
+    def get_by_guid(self, guid: str) -> GameObject | None:
+        """Get object by GUID."""
+        self._build_caches()
+        return self._by_guid.get(guid)
+
+    def get_by_name(self, name: str) -> GameObject | None:
+        """Get object by primary name."""
+        self._build_caches()
+        return self._by_name.get(name)
+
+    def get_by_class(self, class_name: str) -> list[GameObject]:
+        """Get all objects with the given class name."""
+        self._build_caches()
+        return self._by_class.get(class_name, [])
+
+    def find_by_class_pattern(self, pattern: str) -> list[GameObject]:
+        """Find objects whose class name contains the pattern."""
+        return [obj for obj in self.objects if pattern in obj.class_name]
+
+    def build_relationships(self) -> None:
+        """
+        Build parent/component relationships between objects.
+
+        Components have multiple names - the last name references the parent.
+        """
+        self._build_caches()
+
+        for obj in self.objects:
+            if obj.has_parent_names:
+                # This is a component - find its parent
+                parent_name = obj.names[-1]  # Last name is parent reference
+                parent = self.get_by_name(parent_name)
+                if parent:
+                    parent.add_component(obj)
+
+    # Class name patterns that are never structures
+    _NON_STRUCTURE_PATTERNS: t.ClassVar[tuple[str, ...]] = (
+        "_Character_BP",
+        "DinoCharacter",
+        "PlayerPawn",
+        "Buff_",
+        "PrimalBuff",
+        "Weap",
+        "StatusComponent",
+        "Inventory",
+        "DroppedItem",
+        "DeathItemCache",
+        "NPCZone",
+        "DinoDropInventory",
+    )
+
+    def get_creatures(self) -> list[GameObject]:
+        """Get all creature objects (tamed and wild)."""
+        return [
+            obj for obj in self.objects
+            if "_Character_BP" in obj.class_name or "DinoCharacter" in obj.class_name
+        ]
+
+    def get_items(self) -> list[GameObject]:
+        """Get all item objects."""
+        return [obj for obj in self.objects if obj.is_item]
+
+    def get_structures(self) -> list[GameObject]:
+        """Get all tribe-owned placed structures."""
+        results: list[GameObject] = []
+        for obj in self.objects:
+            cn = obj.class_name
+            if obj.get_property_value("TargetingTeam") is None:
+                continue
+            if obj.get_property_value("DinoID1") is not None:
+                continue
+            if any(pat in cn for pat in self._NON_STRUCTURE_PATTERNS):
+                continue
+            results.append(obj)
+        return results
+
+    def get_player_pawns(self) -> list[GameObject]:
+        """Get player character objects on the map."""
+        return [obj for obj in self.objects if "PlayerPawn" in obj.class_name]
+
+    def get_players(self) -> list[GameObject]:
+        """Get all player data objects."""
+        return self.get_by_class("PrimalPlayerData") + self.find_by_class_pattern("PlayerPawnTest")
+
+    def load_all_properties(
+        self,
+        reader: BinaryReader,
+        properties_block_offset: int,
+        is_asa: bool = False,
+    ) -> None:
+        """
+        Load properties for all objects.
+
+        Args:
+            reader: Binary reader.
+            properties_block_offset: Base offset of properties block.
+            is_asa: True for ASA format.
+        """
+        for i, obj in enumerate(self.objects):
+            next_obj = self.objects[i + 1] if i + 1 < len(self.objects) else None
+            obj.load_properties(reader, properties_block_offset, is_asa, next_obj)
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "count": len(self.objects),
+            "objects": [obj.to_dict() for obj in self.objects],
+        }

arkparser/game_objects/game_object.py

@@ -0,0 +1,273 @@
+"""
+Game Object.
+
+The core entity class for all objects in ARK save files.
+Game objects represent creatures, items, structures, players, and other entities.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass, field
+
+from .location import LocationData
+
+if t.TYPE_CHECKING:
+    from ..common.binary_reader import BinaryReader
+    from ..properties.base import Property
+
+
+@dataclass
+class GameObject:
+    """
+    A game object from an ARK save file.
+
+    Game objects are the fundamental entities in ARK saves. They represent
+    creatures, items, structures, players, and other game entities.
+
+    Attributes:
+        id: Object index/ID within the save file.
+        guid: 16-byte GUID (ASA only, empty string for ASE).
+        class_name: The UE4 class name (e.g., "Dodo_Character_BP_C").
+        is_item: True if this is an item/blueprint/engram.
+        names: List of ArkNames (usually 1 for actors, 2 for components).
+        from_data_file: True if loaded from external data file.
+        data_file_index: Index of the external data file.
+        location: Position and rotation data (if has_location is True).
+        properties_offset: Offset to property data in the save file.
+        properties: List of parsed properties.
+        extra_data: Additional data after properties (type depends on structGuid).
+    """
+
+    id: int = 0
+    guid: str = ""
+    class_name: str = ""
+    is_item: bool = False
+    names: list[str] = field(default_factory=list)
+    from_data_file: bool = False
+    data_file_index: int = 0
+    location: LocationData | None = None
+    properties_offset: int = 0
+    properties: list[Property] = field(default_factory=list)
+    extra_data: bytes | None = None
+
+    # Parent/component relationships (set after loading)
+    parent: GameObject | None = field(default=None, repr=False)
+    components: dict[str, GameObject] = field(default_factory=dict, repr=False)
+
+    @property
+    def has_location(self) -> bool:
+        """True if this object has location data."""
+        return self.location is not None
+
+    @property
+    def primary_name(self) -> str | None:
+        """The primary name of this object (first in names list)."""
+        return self.names[0] if self.names else None
+
+    @property
+    def parent_names(self) -> list[str]:
+        """Parent names (all names after the first)."""
+        return self.names[1:] if len(self.names) > 1 else []
+
+    @property
+    def has_parent_names(self) -> bool:
+        """True if this object has parent names (component)."""
+        return len(self.names) > 1
+
+    def get_property(self, name: str, index: int | None = None) -> Property | None:
+        """
+        Get a property by name and optional index.
+
+        Args:
+            name: Property name to find.
+            index: Property index (for arrays with same name). If None, returns first match.
+
+        Returns:
+            The Property object, or None if not found.
+        """
+        for prop in self.properties:
+            if prop.name == name:
+                if index is None or prop.index == index:
+                    return prop
+        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.
+
+        Args:
+            name: Property name to find.
+            default: Default value if property not found.
+            index: Property index (for arrays with same name). If None, returns first match.
+
+        Returns:
+            The property value, or the default if not found.
+        """
+        prop = self.get_property(name, index)
+        return prop.value if prop is not None else default
+
+    def get_properties_by_name(self, name: str) -> list[Property]:
+        """Get all properties with the given name (any index)."""
+        return [p for p in self.properties if p.name == name]
+
+    def has_property(self, name: str) -> bool:
+        """Check if this object has a property with the given name."""
+        return any(p.name == name for p in self.properties)
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Convert to dictionary for serialization."""
+        result: dict[str, t.Any] = {
+            "id": self.id,
+            "class_name": self.class_name,
+        }
+
+        if self.guid:
+            result["guid"] = self.guid
+        if self.is_item:
+            result["is_item"] = True
+        if self.names:
+            result["names"] = self.names
+        if self.from_data_file:
+            result["from_data_file"] = True
+            result["data_file_index"] = self.data_file_index
+        if self.location:
+            result["location"] = self.location.to_dict()
+
+        # Convert properties to dict
+        props: dict[str, t.Any] = {}
+        for prop in self.properties:
+            if prop.name in props:
+                existing = props[prop.name]
+                if isinstance(existing, list):
+                    existing.append(prop.value)
+                else:
+                    props[prop.name] = [existing, prop.value]
+            else:
+                props[prop.name] = prop.value
+        if props:
+            result["properties"] = props
+
+        return result
+
+    @classmethod
+    def read_header(
+        cls,
+        reader: BinaryReader,
+        obj_id: int,
+        is_asa: bool = False,
+    ) -> GameObject:
+        """
+        Read the object header (not properties).
+
+        Properties are loaded separately via load_properties().
+
+        Args:
+            reader: Binary reader positioned at object header.
+            obj_id: Object ID/index.
+            is_asa: True for ASA format.
+
+        Returns:
+            GameObject with header data populated.
+        """
+        obj = cls(id=obj_id)
+
+        # Read GUID (16 bytes) - always present, but all zeros in ASE
+        guid = reader.read_guid()
+        obj.guid = str(guid) if any(b != 0 for b in guid.bytes) else ""
+
+        # Read class name
+        obj.class_name = reader.read_string()
+
+        # Is item flag (UInt32 bool)
+        obj.is_item = reader.read_uint32() != 0
+
+        # Read names
+        name_count = reader.read_int32()
+        obj.names = [reader.read_string() for _ in range(name_count)]
+
+        # From data file flag
+        obj.from_data_file = reader.read_uint32() != 0
+        obj.data_file_index = reader.read_int32()
+
+        # Location data
+        has_location = reader.read_uint32() != 0
+        if has_location:
+            obj.location = LocationData.read(reader, is_asa)
+
+        # Properties offset
+        obj.properties_offset = reader.read_int32()
+
+        # Unknown int (should be 0)
+        _unknown = reader.read_int32()
+
+        return obj
+
+    def load_properties(
+        self,
+        reader: BinaryReader,
+        properties_block_offset: int,
+        is_asa: bool = False,
+        next_object: GameObject | None = None,
+        name_table: list[str] | None = None,
+    ) -> None:
+        """
+        Load properties for this object.
+
+        Args:
+            reader: Binary reader.
+            properties_block_offset: Base offset of the properties block.
+            is_asa: True for ASA format.
+            next_object: Next object (to determine property block end).
+            name_table: Optional name table for world saves (version 6+).
+        """
+        from ..properties.registry import read_properties
+
+        # Calculate absolute offset
+        offset = properties_block_offset + self.properties_offset
+
+        # Seek to properties
+        reader.position = offset
+
+        # Read properties
+        self.properties = read_properties(reader, is_asa, name_table=name_table)
+
+        # Any remaining data before next object is extra data
+        if next_object is not None:
+            next_offset = properties_block_offset + next_object.properties_offset
+            remaining = next_offset - reader.position
+            if remaining > 0:
+                self.extra_data = reader.read_bytes(remaining)
+
+    def add_component(self, component: GameObject) -> None:
+        """Add a component to this object."""
+        if component.primary_name:
+            self.components[component.primary_name] = component
+            component.parent = self
+
+
+def read_object_list(
+    reader: BinaryReader,
+    is_asa: bool = False,
+) -> list[GameObject]:
+    """
+    Read a list of game objects from the archive.
+
+    This reads only the object headers. Properties must be loaded
+    separately using load_properties().
+
+    Args:
+        reader: Binary reader positioned at object count.
+        is_asa: True for ASA format.
+
+    Returns:
+        List of GameObject instances with headers populated.
+    """
+    count = reader.read_int32()
+    objects: list[GameObject] = []
+
+    for i in range(count):
+        obj = GameObject.read_header(reader, i, is_asa)
+        objects.append(obj)
+
+    return objects

arkparser/game_objects/location.py

@@ -0,0 +1,87 @@
+"""
+Location Data.
+
+Position and rotation data for game objects.
+ASE uses floats (4 bytes each), ASA uses doubles (8 bytes each).
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass
+
+if t.TYPE_CHECKING:
+    from ..common.binary_reader import BinaryReader
+
+
+@dataclass
+class LocationData:
+    """
+    Position and rotation data for a game object.
+
+    Contains 6 values: x, y, z position and pitch, yaw, roll rotation.
+    """
+
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+    pitch: float = 0.0
+    yaw: float = 0.0
+    roll: float = 0.0
+
+    @property
+    def position(self) -> tuple[float, float, float]:
+        """Get position as (x, y, z) tuple."""
+        return (self.x, self.y, self.z)
+
+    @property
+    def rotation(self) -> tuple[float, float, float]:
+        """Get rotation as (pitch, yaw, roll) tuple."""
+        return (self.pitch, self.yaw, self.roll)
+
+    def to_dict(self) -> dict[str, float]:
+        """Convert to dictionary."""
+        return {
+            "x": self.x,
+            "y": self.y,
+            "z": self.z,
+            "pitch": self.pitch,
+            "yaw": self.yaw,
+            "roll": self.roll,
+        }
+
+    @classmethod
+    def read(cls, reader: BinaryReader, is_asa: bool = False) -> LocationData:
+        """
+        Read location data from the archive.
+
+        Args:
+            reader: Binary reader positioned at location data.
+            is_asa: True for ASA format (doubles), False for ASE (floats).
+
+        Returns:
+            LocationData instance.
+        """
+        if is_asa:
+            return cls(
+                x=reader.read_double(),
+                y=reader.read_double(),
+                z=reader.read_double(),
+                pitch=reader.read_double(),
+                yaw=reader.read_double(),
+                roll=reader.read_double(),
+            )
+        else:
+            return cls(
+                x=reader.read_float(),
+                y=reader.read_float(),
+                z=reader.read_float(),
+                pitch=reader.read_float(),
+                yaw=reader.read_float(),
+                roll=reader.read_float(),
+            )
+
+    @classmethod
+    def size(cls, is_asa: bool = False) -> int:
+        """Get the byte size of location data."""
+        return 48 if is_asa else 24  # 6 doubles vs 6 floats

arkparser/models/__init__.py

@@ -0,0 +1,29 @@
+"""
+ARK save parser game object models.
+
+Provides higher-level model classes wrapping raw GameObjects
+with intuitive property access for common ARK save data.
+"""
+
+from arkparser.models.character import Character
+from arkparser.models.creature import Creature, TamedCreature, WildCreature
+from arkparser.models.item import Item
+from arkparser.models.player import Player
+from arkparser.models.stats import CreatureStats, Location
+from arkparser.models.structure import Structure
+from arkparser.models.tribe import Tribe, TribeLogEntry, TribeMember
+
+__all__ = [
+    "CreatureStats",
+    "Location",
+    "Creature",
+    "TamedCreature",
+    "WildCreature",
+    "Item",
+    "Player",
+    "Tribe",
+    "TribeMember",
+    "TribeLogEntry",
+    "Structure",
+    "Character",
+]