arkparser 0.1.0__py3-none-any.whl

arkparser/models/item.py

@@ -0,0 +1,207 @@
+"""
+Item model class - Inventory items.
+
+Wraps GameObject with intuitive attribute access for item data.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Item:
+    """
+    An inventory item.
+
+    Wraps a GameObject representing an item with intuitive property access.
+
+    Attributes:
+        class_name: Blueprint class name.
+        name: Custom name (if renamed).
+        quantity: Stack quantity.
+        quality: Item quality/tier.
+        durability: Current durability.
+        is_blueprint: True if this is a blueprint.
+        is_engram: True if this is an engram.
+
+    Example:
+        >>> item = Item.from_game_object(obj)
+        >>> print(f"{item.class_name} x{item.quantity}")
+        >>> if item.is_blueprint:
+        ...     print("  (Blueprint)")
+    """
+
+    _game_object: t.Any = field(default=None, repr=False)
+
+    @classmethod
+    def from_game_object(cls, game_object: t.Any) -> Item:
+        """
+        Create an Item from a GameObject.
+
+        Args:
+            game_object: The item's game object.
+
+        Returns:
+            An Item instance.
+        """
+        return cls(_game_object=game_object)
+
+    @property
+    def class_name(self) -> str:
+        """Blueprint class name."""
+        return self._game_object.class_name if self._game_object else ""
+
+    @property
+    def guid(self) -> str:
+        """Unique identifier (ASA only)."""
+        return self._game_object.guid if self._game_object else ""
+
+    @property
+    def name(self) -> str:
+        """Custom name (if renamed by player)."""
+        if not self._game_object:
+            return ""
+        return self._game_object.get_property_value("CustomItemName", default="") or ""
+
+    @property
+    def description(self) -> str:
+        """Custom description (if modified)."""
+        if not self._game_object:
+            return ""
+        return self._game_object.get_property_value("CustomItemDescription", default="") or ""
+
+    @property
+    def quantity(self) -> int:
+        """Stack quantity."""
+        if not self._game_object:
+            return 1
+        val = self._game_object.get_property_value("ItemQuantity", default=1)
+        return int(val) if val else 1
+
+    @property
+    def quality(self) -> float:
+        """Item quality rating."""
+        if not self._game_object:
+            return 0.0
+        val = self._game_object.get_property_value("ItemRating", default=0.0)
+        return float(val) if val else 0.0
+
+    @property
+    def quality_index(self) -> int:
+        """
+        Quality tier index.
+
+        0 = Primitive, 1 = Ramshackle, 2 = Apprentice,
+        3 = Journeyman, 4 = Mastercraft, 5 = Ascendant
+        """
+        if not self._game_object:
+            return 0
+        val = self._game_object.get_property_value("ItemQualityIndex", default=0)
+        return int(val) if val else 0
+
+    @property
+    def quality_name(self) -> str:
+        """Quality tier name."""
+        names = [
+            "Primitive",
+            "Ramshackle",
+            "Apprentice",
+            "Journeyman",
+            "Mastercraft",
+            "Ascendant",
+        ]
+        idx = self.quality_index
+        return names[idx] if 0 <= idx < len(names) else "Unknown"
+
+    @property
+    def durability(self) -> float:
+        """Current durability."""
+        if not self._game_object:
+            return 0.0
+        val = self._game_object.get_property_value("SavedDurability", default=0.0)
+        return float(val) if val else 0.0
+
+    @property
+    def is_blueprint(self) -> bool:
+        """True if this is a blueprint."""
+        if not self._game_object:
+            return False
+        return self._game_object.get_property_value("bIsBlueprint", default=False)
+
+    @property
+    def is_engram(self) -> bool:
+        """True if this is an engram."""
+        if not self._game_object:
+            return False
+        return self._game_object.get_property_value("bIsEngram", default=False)
+
+    @property
+    def is_equipped(self) -> bool:
+        """True if currently equipped."""
+        if not self._game_object:
+            return False
+        return self._game_object.get_property_value("bIsEquipped", default=False)
+
+    @property
+    def stat_values(self) -> list[int]:
+        """
+        Item stat values (for armor, weapons, etc.).
+
+        Returns:
+            List of stat modifier values.
+        """
+        if not self._game_object:
+            return []
+        values = []
+        for i in range(8):
+            val = self._game_object.get_property_value("ItemStatValues", index=i, default=0)
+            values.append(int(val) if val else 0)
+        return values
+
+    @property
+    def crafting_skill_bonus(self) -> float:
+        """Crafting skill bonus applied during crafting."""
+        if not self._game_object:
+            return 0.0
+        val = self._game_object.get_property_value("CraftingSkillBonusMultiplier", default=0.0)
+        return float(val) if val else 0.0
+
+    def get_property(self, name: str, index: int = 0, default: t.Any = None) -> t.Any:
+        """
+        Get a raw property value from the underlying game object.
+
+        Args:
+            name: Property name.
+            index: Array index for repeated properties.
+            default: Value to return if not found.
+
+        Returns:
+            The property value.
+        """
+        if self._game_object:
+            return self._game_object.get_property_value(name, default=default, index=index)
+        return default
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Convert to dictionary."""
+        result: dict[str, t.Any] = {
+            "class_name": self.class_name,
+            "guid": self.guid,
+            "quantity": self.quantity,
+            "quality": self.quality,
+            "quality_name": self.quality_name,
+            "is_blueprint": self.is_blueprint,
+        }
+        if self.name:
+            result["name"] = self.name
+        if self.durability:
+            result["durability"] = self.durability
+        return result
+
+    def __repr__(self) -> str:
+        name = self.name or self.class_name
+        if self.quantity > 1:
+            return f"Item({name!r}, quantity={self.quantity})"
+        return f"Item({name!r})"

arkparser/models/player.py

@@ -0,0 +1,263 @@
+"""
+Player model class - ARK player/profile data.
+
+Wraps profile data with intuitive attribute access.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass, field
+
+from .stats import CreatureStats, Location
+
+
+@dataclass
+class Player:
+    """
+    An ARK player character.
+
+    Wraps profile and character data with intuitive property access.
+
+    Attributes:
+        name: Player character name.
+        level: Character level.
+        experience: Experience points.
+        tribe_id: Tribe ID the player belongs to.
+        tribe_name: Name of the player's tribe.
+        stats: Player stat points.
+
+    Example:
+        >>> player = Player.from_game_object(obj, status_obj)
+        >>> print(f"{player.name} - Level {player.level}")
+        >>> print(f"Health: {player.stats.health}")
+    """
+
+    _game_object: t.Any = field(default=None, repr=False)
+    _status_object: t.Any = field(default=None, repr=False)
+
+    # Cached values
+    _stats: CreatureStats | None = field(default=None, repr=False)
+
+    @classmethod
+    def from_game_object(
+        cls,
+        game_object: t.Any,
+        status_object: t.Any = None,
+    ) -> Player:
+        """
+        Create a Player from a GameObject.
+
+        Args:
+            game_object: The player's main game object.
+            status_object: The player's status component (for stats).
+
+        Returns:
+            A Player instance.
+        """
+        return cls(_game_object=game_object, _status_object=status_object)
+
+    @property
+    def guid(self) -> str:
+        """Unique identifier (ASA only)."""
+        return self._game_object.guid if self._game_object else ""
+
+    @property
+    def player_id(self) -> int:
+        """Player data ID (unique per player)."""
+        if not self._game_object:
+            return 0
+        val = self._game_object.get_property_value("PlayerDataID", default=0)
+        return int(val) if val else 0
+
+    @property
+    def name(self) -> str:
+        """Player character name."""
+        if not self._game_object:
+            return ""
+        return self._game_object.get_property_value("PlayerName", default="") or ""
+
+    @property
+    def steam_name(self) -> str:
+        """Steam/platform username."""
+        if not self._game_object:
+            return ""
+        return self._game_object.get_property_value("PlatformProfileName", default="") or ""
+
+    @property
+    def tribe_id(self) -> int:
+        """Tribe ID the player belongs to."""
+        if not self._game_object:
+            return 0
+        val = self._game_object.get_property_value("TribeID", default=0)
+        return int(val) if val else 0
+
+    @property
+    def tribe_name(self) -> str:
+        """Name of the player's tribe."""
+        if not self._game_object:
+            return ""
+        return self._game_object.get_property_value("TribeName", default="") or ""
+
+    @property
+    def is_female(self) -> bool:
+        """True if the character is female."""
+        if not self._game_object:
+            return False
+        return self._game_object.get_property_value("bIsFemale", default=False)
+
+    @property
+    def gender(self) -> str:
+        """Gender as string ('Female' or 'Male')."""
+        return "Female" if self.is_female else "Male"
+
+    @property
+    def base_level(self) -> int:
+        """Base character level."""
+        if self._status_object:
+            return self._status_object.get_property_value("BaseCharacterLevel", default=1)
+        return 1
+
+    @property
+    def extra_level(self) -> int:
+        """Extra levels (ascension levels, etc.)."""
+        if self._status_object:
+            val = self._status_object.get_property_value("ExtraCharacterLevel", default=0)
+            return int(val) if val else 0
+        return 0
+
+    @property
+    def level(self) -> int:
+        """Total character level."""
+        return self.base_level + self.extra_level
+
+    @property
+    def experience(self) -> float:
+        """Current experience points."""
+        if self._status_object:
+            val = self._status_object.get_property_value("ExperiencePoints", default=0.0)
+            return float(val) if val else 0.0
+        return 0.0
+
+    @property
+    def stats(self) -> CreatureStats:
+        """
+        Player stat points.
+
+        Uses the same 12-stat system as creatures.
+        """
+        if self._stats is None:
+            points = []
+            if self._status_object:
+                for i in range(12):
+                    val = self._status_object.get_property_value("NumberOfLevelUpPointsApplied", index=i, default=0)
+                    points.append(int(val) if val else 0)
+            self._stats = CreatureStats.from_array(points)
+        return self._stats
+
+    @property
+    def engram_points(self) -> int:
+        """Total engram points available."""
+        if not self._game_object:
+            return 0
+        val = self._game_object.get_property_value("TotalEngramPoints", default=0)
+        return int(val) if val else 0
+
+    @property
+    def location(self) -> Location | None:
+        """World position and rotation."""
+        if self._game_object and self._game_object.location:
+            loc = self._game_object.location
+            return Location(
+                x=loc.x,
+                y=loc.y,
+                z=loc.z,
+                pitch=getattr(loc, "pitch", 0.0),
+                yaw=getattr(loc, "yaw", 0.0),
+                roll=getattr(loc, "roll", 0.0),
+            )
+        return None
+
+    @property
+    def last_server(self) -> str:
+        """Last server the player was on."""
+        if not self._game_object:
+            return ""
+        return self._game_object.get_property_value("LastServerSavedOn", default="") or ""
+
+    @property
+    def steam_id(self) -> str:
+        """Steam/platform unique ID (from UniqueID or file)."""
+        if not self._game_object:
+            return ""
+        val = self._game_object.get_property_value("UniqueID", default="")
+        if val:
+            return str(val)
+        return ""
+
+    @property
+    def data_file(self) -> str:
+        """Profile data file name (e.g., '2535445137750472.arkprofile')."""
+        sid = self.steam_id
+        if sid:
+            return f"{sid}.arkprofile"
+        pid = self.player_id
+        if pid:
+            return f"{pid}.arkprofile"
+        return ""
+
+    def get_property(self, name: str, index: int = 0, default: t.Any = None) -> t.Any:
+        """
+        Get a raw property value from the underlying game object.
+
+        Args:
+            name: Property name.
+            index: Array index for repeated properties.
+            default: Value to return if not found.
+
+        Returns:
+            The property value.
+        """
+        if self._game_object:
+            return self._game_object.get_property_value(name, default=default, index=index)
+        return default
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Convert to dictionary matching C# ASV_Players export format."""
+        result: dict[str, t.Any] = {
+            "playerid": self.player_id,
+            "steam": self.steam_name,
+            "name": self.name,
+            "tribeid": self.tribe_id,
+            "tribe": self.tribe_name,
+            "sex": self.gender,
+            "lvl": self.level,
+            # Flat stat fields matching C# export
+            "hp": self.stats.health,
+            "stam": self.stats.stamina,
+            "melee": self.stats.melee,
+            "weight": self.stats.weight,
+            "speed": self.stats.speed,
+            "food": self.stats.food,
+            "water": self.stats.water,
+            "oxy": self.stats.oxygen,
+            "craft": self.stats.crafting,
+            "fort": self.stats.fortitude,
+            "stats": self.stats.to_dict(),
+            "engram_points": self.engram_points,
+        }
+        if self.steam_id:
+            result["steamid"] = self.steam_id
+        if self.data_file:
+            result["dataFile"] = self.data_file
+        if self.location:
+            result["location"] = self.location.to_dict()
+            result["ccc"] = self.location.ccc
+            if self.location.latitude is not None:
+                result["lat"] = self.location.latitude
+            if self.location.longitude is not None:
+                result["lon"] = self.location.longitude
+        return result
+
+    def __repr__(self) -> str:
+        return f"Player({self.name!r}, level={self.level})"

arkparser/models/stats.py

@@ -0,0 +1,226 @@
+"""
+Stats helper classes for creatures and players.
+
+Provides named attribute access to the 12 ARK stat indices.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass, field
+
+if t.TYPE_CHECKING:
+    from arkparser.common.map_config import MapConfig
+
+
+@dataclass
+class CreatureStats:
+    """
+    Creature stats with named attribute access.
+
+    ARK uses 12 stat indices. This class provides friendly access:
+    - Index 0: Health
+    - Index 1: Stamina
+    - Index 2: Torpidity
+    - Index 3: Oxygen
+    - Index 4: Food
+    - Index 5: Water
+    - Index 6: Temperature
+    - Index 7: Weight
+    - Index 8: Melee Damage
+    - Index 9: Movement Speed
+    - Index 10: Fortitude
+    - Index 11: Crafting Skill
+
+    Attributes:
+        health: Health stat points.
+        stamina: Stamina stat points.
+        torpidity: Torpidity stat points.
+        oxygen: Oxygen stat points.
+        food: Food stat points.
+        water: Water stat points.
+        temperature: Temperature stat points.
+        weight: Weight stat points.
+        melee: Melee damage stat points.
+        speed: Movement speed stat points.
+        fortitude: Fortitude stat points.
+        crafting: Crafting skill stat points.
+    """
+
+    health: int = 0
+    stamina: int = 0
+    torpidity: int = 0
+    oxygen: int = 0
+    food: int = 0
+    water: int = 0
+    temperature: int = 0
+    weight: int = 0
+    melee: int = 0
+    speed: int = 0
+    fortitude: int = 0
+    crafting: int = 0
+
+    @classmethod
+    def from_array(cls, points: list[int] | None) -> CreatureStats:
+        """
+        Create from an array of stat points.
+
+        Args:
+            points: Array of 12 stat point values (can be None or shorter).
+
+        Returns:
+            CreatureStats instance with the stat values.
+        """
+        if points is None:
+            return cls()
+
+        pts = list(points) + [0] * (12 - len(points)) if len(points) < 12 else points
+
+        return cls(
+            health=pts[0],
+            stamina=pts[1],
+            torpidity=pts[2],
+            oxygen=pts[3],
+            food=pts[4],
+            water=pts[5],
+            temperature=pts[6],
+            weight=pts[7],
+            melee=pts[8],
+            speed=pts[9],
+            fortitude=pts[10],
+            crafting=pts[11],
+        )
+
+    def to_array(self) -> list[int]:
+        """Convert to array format."""
+        return [
+            self.health,
+            self.stamina,
+            self.torpidity,
+            self.oxygen,
+            self.food,
+            self.water,
+            self.temperature,
+            self.weight,
+            self.melee,
+            self.speed,
+            self.fortitude,
+            self.crafting,
+        ]
+
+    @property
+    def total(self) -> int:
+        """Total stat points (excluding torpidity)."""
+        return self.health + self.stamina + self.oxygen + self.food + self.water + self.weight + self.melee + self.speed
+
+    def to_dict(self) -> dict[str, int]:
+        """Convert to dictionary."""
+        return {
+            "health": self.health,
+            "stamina": self.stamina,
+            "torpidity": self.torpidity,
+            "oxygen": self.oxygen,
+            "food": self.food,
+            "water": self.water,
+            "temperature": self.temperature,
+            "weight": self.weight,
+            "melee": self.melee,
+            "speed": self.speed,
+            "fortitude": self.fortitude,
+            "crafting": self.crafting,
+        }
+
+
+@dataclass
+class Location:
+    """
+    3D position with optional rotation and GPS conversion.
+
+    Attributes:
+        x: X coordinate (UE world space).
+        y: Y coordinate (UE world space).
+        z: Z coordinate (UE world space).
+        pitch: Pitch rotation.
+        yaw: Yaw rotation.
+        roll: 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
+    _map_config: MapConfig | None = field(default=None, repr=False, compare=False)
+
+    def with_map(self, map_config: MapConfig) -> Location:
+        """
+        Return a new Location with a map config attached for GPS conversion.
+
+        Args:
+            map_config: The map configuration to use.
+
+        Returns:
+            A new Location with GPS conversion enabled.
+        """
+        return Location(
+            x=self.x,
+            y=self.y,
+            z=self.z,
+            pitch=self.pitch,
+            yaw=self.yaw,
+            roll=self.roll,
+            _map_config=map_config,
+        )
+
+    @property
+    def latitude(self) -> float | None:
+        """
+        Latitude coordinate (requires map configuration).
+
+        Set via ``with_map()`` or by passing map_config to the savegame parser.
+
+        Formula: lat_shift + (y / lat_div)
+        """
+        if self._map_config is None:
+            return None
+        return self._map_config.ue_to_lat(self.y)
+
+    @property
+    def longitude(self) -> float | None:
+        """
+        Longitude coordinate (requires map configuration).
+
+        Set via ``with_map()`` or by passing map_config to the savegame parser.
+
+        Formula: lon_shift + (x / lon_div)
+        """
+        if self._map_config is None:
+            return None
+        return self._map_config.ue_to_lon(self.x)
+
+    @property
+    def ccc(self) -> str:
+        """
+        CCC string (cheat setplayerpos format).
+
+        Returns:
+            Space-separated "x y z" coordinate string.
+        """
+        return f"{self.x} {self.y} {self.z}"
+
+    def to_dict(self) -> dict[str, float]:
+        """Convert to dictionary."""
+        result: dict[str, float] = {
+            "x": self.x,
+            "y": self.y,
+            "z": self.z,
+            "pitch": self.pitch,
+            "yaw": self.yaw,
+            "roll": self.roll,
+        }
+        if self.latitude is not None:
+            result["lat"] = self.latitude
+        if self.longitude is not None:
+            result["lon"] = self.longitude
+        return result