arkparser 0.1.0__py3-none-any.whl

arkparser/common/map_config.py

@@ -0,0 +1,166 @@
+"""
+Map configuration for UE coordinate to GPS lat/lon conversion.
+
+Formula (from C# reference):
+    latitude  = lat_shift + (y / lat_div)
+    longitude = lon_shift + (x / lon_div)
+
+Where x, y are Unreal Engine world coordinates.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass
+
+
+@dataclass
+class MapConfig:
+    """
+    Configuration for a specific ARK map.
+
+    Used to convert Unreal Engine coordinates to GPS lat/lon.
+
+    Attributes:
+        name: Human-readable map name.
+        filename: Save file name (e.g., "theisland.ark").
+        lat_shift: Latitude origin offset.
+        lat_div: Latitude divisor (scale).
+        lon_shift: Longitude origin offset.
+        lon_div: Longitude divisor (scale).
+    """
+
+    name: str
+    filename: str
+    lat_shift: float = 50.0
+    lat_div: float = 8000.0
+    lon_shift: float = 50.0
+    lon_div: float = 8000.0
+
+    def ue_to_lat(self, y: float) -> float:
+        """Convert UE Y coordinate to latitude."""
+        return self.lat_shift + (y / self.lat_div)
+
+    def ue_to_lon(self, x: float) -> float:
+        """Convert UE X coordinate to longitude."""
+        return self.lon_shift + (x / self.lon_div)
+
+    def ue_to_gps(self, x: float, y: float) -> tuple[float, float]:
+        """
+        Convert UE coordinates to GPS (latitude, longitude).
+
+        Returns:
+            Tuple of (latitude, longitude).
+        """
+        return (self.ue_to_lat(y), self.ue_to_lon(x))
+
+    def ccc_string(self, x: float, y: float, z: float) -> str:
+        """Format coordinates as a cheat setplayerpos string."""
+        return f"{x} {y} {z}"
+
+
+# ============================================================================
+# Built-in map configurations from C# ArkViewer maps.json
+# ============================================================================
+
+# fmt: off
+_MAP_CONFIGS: list[MapConfig] = [
+    # Official ASE Maps
+    MapConfig("The Island (Evolved)", "theisland.ark", 50.0, 8000.0, 50.0, 8000.0),
+    MapConfig("Scorched Earth", "scorchedearth_p.ark", 50.0, 8000.0, 50.0, 8000.0),
+    MapConfig("Aberration (Evolved)", "aberration_p.ark", 50.0, 8000.0, 50.0, 8000.0),
+    MapConfig("Extinction (Evolved)", "extinction.ark", 50.0, 8000.0, 50.0, 8000.0),
+    MapConfig("The Center (Evolved)", "thecenter.ark", 30.34223747253418, 9584.0, 55.10416793823242, 9600.0),
+    MapConfig("Ragnarok", "ragnarok.ark", 50.009388, 13100.0, 50.009388, 13100.0),
+    MapConfig("Valguero", "valguero_p.ark", 50.0, 8161.0, 50.0, 8161.0),
+    MapConfig("Crystal Isles", "crystalisles.ark", 48.687, 15882.02, 49.9481, 16988.76),
+    MapConfig("Genesis", "genesis.ark", 50.0, 10500.0, 50.0, 10500.0),
+    MapConfig("Genesis 2", "gen2.ark", 49.6, 14500.0, 49.6, 14500.0),
+    MapConfig("Lost Island", "lostisland.ark", 51.6, 15300.0, 49.0, 15300.0),
+    MapConfig("Fjordur", "fjordur.ark", 50.0, 7140.0, 50.0, 7140.0),
+
+    # Official ASA Maps
+    MapConfig("The Island (Ascended)", "theisland_wp.ark", 50.0, 6850.0, 50.0, 6850.0),
+    MapConfig("The Center (Ascended)", "thecenter_wp.ark", 32.5, 10380.52, 50.5, 10374.29),
+    MapConfig("Scorched Earth (Ascended)", "scorchedearth_wp.ark", 50.0, 8000.0, 50.0, 8000.0),
+    MapConfig("Aberration (Ascended)", "aberration_wp.ark", 50.0, 8000.0, 50.0, 8000.0),
+    MapConfig("Extinction (Ascended)", "extinction_wp.ark", 50.0, 6850.0, 50.0, 6850.0),
+    MapConfig("Ragnarok (Ascended)", "ragnarok_wp.ark", 50.009388, 13100.0, 50.009388, 13100.0),
+    MapConfig("Valguero (Ascended)", "valguero_wp.ark", 50.0, 8161.0, 50.0, 8161.0),
+
+    # Community / Modded Maps
+    MapConfig("Astral ARK", "astralark.ark", 50.0, 2000.0, 50.0, 2000.0),
+    MapConfig("Hope", "hope.ark", 50.0, 6850.0, 50.0, 6850.0),
+    MapConfig("Tunguska", "tunguska_p.ark", 46.8, 14000.0, 49.29, 13300.0),
+    MapConfig("Caballus", "caballus_p.ark", 50.0, 8125.0, 50.0, 8125.0),
+    MapConfig("Tiamat Prime", "tiamatprime.ark", 50.0, 8000.0, 50.0, 8000.0),
+    MapConfig("Glacius", "glacius_p.ark", 50.0, 16250.0, 50.0, 16250.0),
+    MapConfig("Antartika", "antartika.ark", 50.0, 8000.0, 50.0, 8000.0),
+    MapConfig("Amissa (Evolved)", "amissa.ark", 49.9, 10900.0, 49.9, 10850.0),
+    MapConfig("Amissa (Ascended)", "amissa_wp.ark", 46.9, 11375.0, 48.1, 11400.0),
+    MapConfig("Olympus", "olympus.ark", 0.0, 8130.0, 0.0, 8130.0),
+    MapConfig("Ebenus Astrum", "ebenusastrum.ark", 52.9, 8650.0, 25.0, 18500.0),
+    MapConfig("ARKForum Event Map", "arkforum_eventmap.ark", 50.0, 1500.0, 50.0, 1500.0),
+    MapConfig("The Volcano", "thevolcano.ark", 50.0, 9200.0, 50.0, 9200.0),
+    MapConfig("The Earrion", "earrion_p.ark", 50.0, 6250.0, 50.0, 6250.0),
+    MapConfig("Alemia", "Alemia_P.ark", 50.0, 8150.0, 50.0, 8150.0),
+    MapConfig("Velius", "Velius_P.ark", 50.0, 8575.0, 50.0, 8575.0),
+    MapConfig("Svartalfheim (Evolved)", "Svartalfheim.ark", 50.0, 4065.0, 50.0, 4065.0),
+    MapConfig("Svartalfheim (Ascended)", "Svartalfheim_WP.ark", 50.0, 4055.0, 50.0, 4055.0),
+    MapConfig("TaeniaStella", "TaeniaStella.ark", 48.9, 15500.0, 48.9, 15500.0),
+    MapConfig("Forglar (Ascended)", "forglar_wp.ark", 61.4, 7150.0, 69.8, 7945.0),
+    MapConfig("Insaluna (Ascended)", "insaluna_wp.ark", 50.0, 9400.0, 50.0, 9400.0),
+    MapConfig("Temptress Lagoon (Ascended)", "temptress_wp.ark", 50.0, 8150.0, 50.0, 8150.0),
+    MapConfig("Reverence (Ascended)", "reverence_wp.ark", 50.0, 8125.0, 50.0, 8125.0),
+    MapConfig("Nyrandil (Ascended)", "nyrandil.ark", 50.0, 8175.0, 50.0, 8175.0),
+    MapConfig("Astraeos (Ascended)", "astraeos_wp.ark", 50.0, 16000.0, 50.0, 16000.0),
+    MapConfig("Gun Smoke", "gunsmoke.ark", 12.1, 7900.0, 10.8, 7850.0),
+    MapConfig("Fjell", "viking_p.ark", 50.0, 7140.0, 50.0, 7140.0),
+]
+# fmt: on
+
+# Build lookup by filename (case-insensitive)
+_MAP_BY_FILENAME: dict[str, MapConfig] = {cfg.filename.lower(): cfg for cfg in _MAP_CONFIGS}
+
+# Default config for unknown maps
+DEFAULT_MAP_CONFIG = MapConfig("Unknown", "unknown.ark", 50.0, 8000.0, 50.0, 8000.0)
+
+
+def get_map_config(filename: str) -> MapConfig:
+    """
+    Get map configuration by save filename.
+
+    Args:
+        filename: The save file name (e.g., "ragnarok.ark").
+
+    Returns:
+        MapConfig for the map, or DEFAULT_MAP_CONFIG if not found.
+    """
+    return _MAP_BY_FILENAME.get(filename.lower(), DEFAULT_MAP_CONFIG)
+
+
+def get_map_config_by_name(name: str) -> MapConfig:
+    """
+    Get map configuration by display name (case-insensitive partial match).
+
+    Args:
+        name: Map display name or partial match (e.g., "Ragnarok", "The Island").
+
+    Returns:
+        MapConfig for the map, or DEFAULT_MAP_CONFIG if not found.
+    """
+    name_lower = name.lower()
+    for cfg in _MAP_CONFIGS:
+        if name_lower in cfg.name.lower():
+            return cfg
+    return DEFAULT_MAP_CONFIG
+
+
+def list_maps() -> list[MapConfig]:
+    """
+    Get all available map configurations.
+
+    Returns:
+        List of all registered MapConfig instances.
+    """
+    return list(_MAP_CONFIGS)

arkparser/common/types.py

@@ -0,0 +1,249 @@
+"""
+Core ARK Types.
+
+This module defines the fundamental types used throughout ARK save files:
+- ArkName: Unreal Engine's FName type (name + instance index)
+- ObjectReference: References to other game objects
+
+These types mirror Unreal Engine 4's serialization format.
+"""
+
+from __future__ import annotations
+
+import re
+import typing as t
+from dataclasses import dataclass
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+# The "None" name is used as a terminator in property lists
+NAME_NONE = "None"
+
+
+# =============================================================================
+# ArkName (FName)
+# =============================================================================
+
+# Pattern to extract instance index from name strings like "MyName_5"
+_NAME_INDEX_PATTERN = re.compile(r"^(.+)_(\d+)$")
+
+
+@dataclass(frozen=True, slots=True)
+class ArkName:
+    """
+    Unreal Engine FName type.
+
+    FNames consist of a base name and an instance index. They're used
+    extensively for property names, class names, and identifiers.
+
+    Format in files:
+        - Without name table: String with optional "_N" suffix
+        - With name table: Int32 index + Int32 instance
+
+    Instance numbering:
+        - Instance 0 = no suffix (or first occurrence)
+        - Instance 1 = "_0" suffix
+        - Instance 2 = "_1" suffix
+        - etc.
+
+    Examples:
+        >>> ArkName.from_string("Health")
+        ArkName(name='Health', instance=0)
+
+        >>> ArkName.from_string("MyDino_5")
+        ArkName(name='MyDino', instance=6)  # instance = parsed + 1
+
+        >>> str(ArkName("MyDino", 6))
+        'MyDino_5'
+
+    Attributes:
+        name: The base name string.
+        instance: The instance index (0 = no suffix).
+    """
+
+    name: str
+    instance: int = 0
+
+    def __str__(self) -> str:
+        """Convert to string representation."""
+        if self.instance == 0:
+            return self.name
+        return f"{self.name}_{self.instance - 1}"
+
+    def __repr__(self) -> str:
+        """Detailed representation for debugging."""
+        if self.instance == 0:
+            return f"ArkName({self.name!r})"
+        return f"ArkName({self.name!r}, instance={self.instance})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality with another ArkName."""
+        if isinstance(other, ArkName):
+            return self.name == other.name and self.instance == other.instance
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        """Hash for use in dicts/sets."""
+        return hash((self.name, self.instance))
+
+    @property
+    def is_none(self) -> bool:
+        """Check if this is the 'None' terminator name."""
+        return self.name == NAME_NONE and self.instance == 0
+
+    @classmethod
+    def from_string(cls, value: str) -> ArkName:
+        """
+        Parse an ArkName from a string.
+
+        Handles the "_N" suffix convention:
+        - "Health" -> ArkName("Health", 0)
+        - "MyDino_0" -> ArkName("MyDino", 1)
+        - "Item_5" -> ArkName("Item", 6)
+
+        Args:
+            value: The string to parse.
+
+        Returns:
+            An ArkName instance.
+        """
+        if not value:
+            return cls("", 0)
+
+        match = _NAME_INDEX_PATTERN.match(value)
+        if match:
+            name = match.group(1)
+            index = int(match.group(2))
+            return cls(name, index + 1)
+
+        return cls(value, 0)
+
+    @classmethod
+    def from_parts(cls, name: str, instance: int) -> ArkName:
+        """
+        Create an ArkName from separate name and instance.
+
+        Used when reading from a name table where name and instance
+        are stored separately.
+
+        Args:
+            name: The base name.
+            instance: The instance index.
+
+        Returns:
+            An ArkName instance.
+        """
+        return cls(name, instance)
+
+    @classmethod
+    def none(cls) -> ArkName:
+        """Return the 'None' terminator name."""
+        return cls(NAME_NONE, 0)
+
+
+# =============================================================================
+# ObjectReference
+# =============================================================================
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectReference:
+    """
+    Reference to another game object.
+
+    Objects in ARK save files can reference each other. The format differs
+    between ASE and ASA:
+
+    ASE format:
+        - Int32 type (0 = index, 1 = name)
+        - If type 0: Int32 object index
+        - If type 1: ArkName
+
+    ASA format:
+        - Int16 isName flag
+        - If isName = 0: 16-byte GUID
+        - If isName = 1: ArkName
+
+    Attributes:
+        object_id: The object index (ASE) or None.
+        object_guid: The object GUID as hex string (ASA) or None.
+        object_name: The object name (when referencing by name) or None.
+        is_null: True if this is a null reference.
+    """
+
+    object_id: int | None = None
+    object_guid: str | None = None
+    object_name: ArkName | None = None
+
+    @property
+    def is_null(self) -> bool:
+        """Check if this is a null/empty reference."""
+        return self.object_id is None and self.object_guid is None and self.object_name is None
+
+    @property
+    def is_id_reference(self) -> bool:
+        """Check if this references by ID (ASE style)."""
+        return self.object_id is not None
+
+    @property
+    def is_guid_reference(self) -> bool:
+        """Check if this references by GUID (ASA style)."""
+        return self.object_guid is not None
+
+    @property
+    def is_name_reference(self) -> bool:
+        """Check if this references by name."""
+        return self.object_name is not None
+
+    @classmethod
+    def null(cls) -> ObjectReference:
+        """Create a null reference."""
+        return cls()
+
+    @classmethod
+    def from_id(cls, object_id: int) -> ObjectReference:
+        """Create a reference from an object ID (ASE)."""
+        return cls(object_id=object_id)
+
+    @classmethod
+    def from_guid(cls, guid: str) -> ObjectReference:
+        """Create a reference from a GUID string (ASA)."""
+        return cls(object_guid=guid)
+
+    @classmethod
+    def from_name(cls, name: ArkName) -> ObjectReference:
+        """Create a reference from an object name."""
+        return cls(object_name=name)
+
+    def __str__(self) -> str:
+        """String representation."""
+        if self.is_null:
+            return "ObjectReference(null)"
+        if self.object_id is not None:
+            return f"ObjectReference(id={self.object_id})"
+        if self.object_guid is not None:
+            return f"ObjectReference(guid={self.object_guid})"
+        if self.object_name is not None:
+            return f"ObjectReference(name={self.object_name})"
+        return "ObjectReference()"
+
+
+# =============================================================================
+# Type Aliases
+# =============================================================================
+
+# For type hints in generic contexts
+PropertyValue = t.Union[
+    int,
+    float,
+    bool,
+    str,
+    bytes,
+    ArkName,
+    ObjectReference,
+    list[t.Any],
+    dict[str, t.Any],
+    None,
+]

arkparser/common/version_detection.py

@@ -0,0 +1,195 @@
+"""
+ARK File Format Detection.
+
+Detects whether an ARK save file is in ASE or ASA format based on
+header information. This allows the parser to automatically choose
+the correct parsing strategy.
+
+Detection Strategy for profiles/tribes/cloud data:
+    1. Read the version number from the file header (Int32)
+    2. Version 7+ is always ASA
+    3. For versions 1-6, check for a GUID at bytes 8-24:
+       - All zeros = ASE
+       - Non-zero = ASA (uses GUIDs for object identification)
+
+World saves (.ark files) have different headers:
+    - ASE: Int16 version at offset 0 (typically 5-7)
+    - ASA: SQLite database format
+"""
+
+from __future__ import annotations
+
+import typing as t
+from enum import Enum
+from pathlib import Path
+
+
+class ArkFileFormat(Enum):
+    """
+    ARK save file format types.
+
+    ASE (ARK: Survival Evolved):
+        - Save format versions 5-6
+        - Uses floats for vectors
+        - Object references by index
+
+    ASA (ARK: Survival Ascended):
+        - Save format version 7+
+        - Uses doubles for vectors
+        - Object references by GUID
+        - World saves use SQLite database format
+    """
+
+    ASE = "ASE"
+    ASA = "ASA"
+    UNKNOWN = "UNKNOWN"
+
+
+class ArkFileType(Enum):
+    """
+    ARK save file types based on extension and content.
+    """
+
+    PROFILE = "profile"  # .arkprofile
+    TRIBE = "tribe"  # .arktribe
+    CLOUD_INVENTORY = "cloud_inventory"  # No extension (obelisk data)
+    WORLD_SAVE = "world_save"  # .ark
+    UNKNOWN = "unknown"
+
+
+def detect_file_type(source: bytes | str | Path) -> ArkFileType:
+    """
+    Detect the type of ARK save file based on extension.
+
+    Args:
+        source: File path string, Path object, or bytes (for bytes, returns UNKNOWN).
+
+    Returns:
+        The detected file type.
+
+    Example:
+        >>> detect_file_type("player.arkprofile")
+        ArkFileType.PROFILE
+    """
+    if isinstance(source, bytes):
+        return ArkFileType.UNKNOWN
+
+    path = Path(source)
+    suffix = path.suffix.lower()
+
+    if suffix == ".arkprofile":
+        return ArkFileType.PROFILE
+    elif suffix == ".arktribe":
+        return ArkFileType.TRIBE
+    elif suffix == ".ark":
+        return ArkFileType.WORLD_SAVE
+    elif suffix == "":
+        # No extension - likely cloud inventory / obelisk data
+        return ArkFileType.CLOUD_INVENTORY
+
+    return ArkFileType.UNKNOWN
+
+
+def detect_format(source: bytes | str | Path) -> ArkFileFormat:
+    """
+    Detect the format of an ARK save file.
+
+    Automatically determines whether a file uses ASE or ASA format
+    by examining the file header. Works for:
+    - .arkprofile (player profiles)
+    - .arktribe (tribe data)
+    - Cloud/obelisk data (no extension)
+    - .ark world saves
+
+    Args:
+        source: Raw bytes, file path string, or Path object.
+
+    Returns:
+        ArkFileFormat.ASE, ArkFileFormat.ASA, or ArkFileFormat.UNKNOWN.
+
+    Example:
+        >>> format = detect_format("examples/ase/map_save/1446520645.arktribe")
+        >>> print(format)
+        ArkFileFormat.ASE
+    """
+    # Load data if given a path
+    path: Path | None = None
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        if not path.exists() or path.stat().st_size == 0:
+            return ArkFileFormat.UNKNOWN
+        data = path.read_bytes()
+    else:
+        data = source
+
+    # Need at least some bytes to detect
+    if len(data) < 24:
+        return ArkFileFormat.UNKNOWN
+
+    # Check for SQLite header (ASA world saves)
+    if data[:16] == b"SQLite format 3\x00":
+        return ArkFileFormat.ASA
+
+    # Check if this is a world save by file extension
+    is_world_save = path is not None and path.suffix.lower() == ".ark"
+
+    if is_world_save:
+        # World saves use Int16 version at offset 0
+        int16_version = int.from_bytes(data[0:2], "little", signed=True)
+        # ASE world saves have versions 5-12
+        if 5 <= int16_version <= 12:
+            return ArkFileFormat.ASE
+        return ArkFileFormat.UNKNOWN
+
+    # For profiles/tribes/cloud data, version is Int32
+    version = int.from_bytes(data[0:4], "little", signed=True)
+
+    # Version 7+ is ASA for profiles/tribes/cloud
+    if version >= 7:
+        return ArkFileFormat.ASA
+
+    # For versions 1-6, check for GUID at bytes 8-24
+    # ASE files have all zeros here; ASA files have a non-zero GUID
+    if 1 <= version <= 6:
+        guid_bytes = data[8:24]
+        has_guid = any(b != 0 for b in guid_bytes)
+        return ArkFileFormat.ASA if has_guid else ArkFileFormat.ASE
+
+    return ArkFileFormat.UNKNOWN
+
+
+def get_save_version(source: bytes | str | Path) -> int:
+    """
+    Read the save version number from a file header.
+
+    For profiles/tribes/cloud data, this reads an Int32.
+    For world saves, this reads an Int16.
+
+    Args:
+        source: Raw bytes, file path string, or Path object.
+
+    Returns:
+        The version number, or -1 if the file is invalid.
+    """
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        if not path.exists() or path.stat().st_size == 0:
+            return -1
+        data = path.read_bytes()
+    else:
+        data = source
+
+    if len(data) < 4:
+        return -1
+
+    # Check for SQLite (ASA world save)
+    if data[:16] == b"SQLite format 3\x00":
+        return -1  # SQLite doesn't have a simple version
+
+    # Check if it looks like a world save (Int16 version 5-9)
+    int16_version = int.from_bytes(data[0:2], "little", signed=True)
+    if 5 <= int16_version <= 9:
+        return int16_version
+
+    # Otherwise read as Int32
+    return int.from_bytes(data[0:4], "little", signed=True)