arkparser 0.1.0__py3-none-any.whl

arkparser/properties/registry.py

@@ -0,0 +1,236 @@
+"""
+Property Registry - Type Dispatch for Property Reading.
+
+This module provides the central registry for reading properties from binary data.
+It dispatches to the appropriate property class based on the type name in the header.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from ..common.binary_reader import BinaryReader
+from ..common.exceptions import UnknownPropertyError
+from .base import NameTable, Property, PropertyHeader, read_property_header
+from .byte_property import ByteProperty
+from .compound import ArrayProperty, MapProperty, StructProperty
+from .primitives import (
+    BoolProperty,
+    DoubleProperty,
+    FloatProperty,
+    Int8Property,
+    Int16Property,
+    Int64Property,
+    IntProperty,
+    NameProperty,
+    ObjectProperty,
+    SoftObjectProperty,
+    StrProperty,
+    UInt16Property,
+    UInt32Property,
+    UInt64Property,
+)
+
+# Type alias for property reader functions
+PropertyReader = t.Callable[[BinaryReader, PropertyHeader, bool], Property]
+
+
+# Registry mapping type names to their reader classes
+PROPERTY_REGISTRY: dict[str, type[Property]] = {
+    # Numeric properties
+    "Int8Property": Int8Property,
+    "Int16Property": Int16Property,
+    "IntProperty": IntProperty,
+    "Int64Property": Int64Property,
+    "UInt16Property": UInt16Property,
+    "UInt32Property": UInt32Property,
+    "UInt64Property": UInt64Property,
+    "FloatProperty": FloatProperty,
+    "DoubleProperty": DoubleProperty,
+    # Boolean
+    "BoolProperty": BoolProperty,
+    # String/Name
+    "StrProperty": StrProperty,
+    "NameProperty": NameProperty,
+    # Object reference
+    "ObjectProperty": ObjectProperty,
+    # Soft object reference (asset paths)
+    "SoftObjectProperty": SoftObjectProperty,
+    # Byte (can be raw or enum)
+    "ByteProperty": ByteProperty,
+    # Compound types
+    "ArrayProperty": ArrayProperty,
+    "StructProperty": StructProperty,
+    "MapProperty": MapProperty,
+}
+
+
+def read_property(
+    reader: BinaryReader,
+    is_asa: bool = False,
+    name_table: NameTable = None,
+    worldsave_format: bool = False,
+) -> Property | None:
+    """
+    Read a single property from the binary reader.
+
+    Reads the property header, then dispatches to the appropriate
+    property type's read method.
+
+    Args:
+        reader: The binary reader positioned at the property header.
+        is_asa: True for ASA format, False for ASE.
+        name_table: Optional name table for world saves.
+                   - list: ASE format (1-based index)
+                   - dict: ASA format (hash key)
+        worldsave_format: True for ASA WorldSave SQLite object format.
+
+    Returns:
+        The parsed Property object, or None if the terminating "None" property
+        was encountered.
+
+    Raises:
+        UnknownPropertyError: If the property type is not recognized.
+    """
+    header = read_property_header(reader, is_asa, name_table=name_table, worldsave_format=worldsave_format)
+
+    # Check for terminator (read_property_header returns None for "None")
+    if header is None:
+        return None
+
+    # Look up the property type in the registry
+    property_class = PROPERTY_REGISTRY.get(header.type_name)
+
+    if property_class is None:
+        raise UnknownPropertyError(
+            property_type=header.type_name,
+            position=reader.position,
+        )
+
+    # Read the property value
+    # In WorldSave format, all properties need the flag and name_table
+    if worldsave_format:
+        return property_class.read(reader, header, is_asa, name_table=name_table, worldsave_format=worldsave_format)
+    elif header.type_name in (
+        "ArrayProperty",
+        "StructProperty",
+        "MapProperty",
+        "ByteProperty",
+        "NameProperty",
+        "ObjectProperty",
+    ):
+        # These types need name_table even in non-worldsave mode
+        return property_class.read(reader, header, is_asa, name_table=name_table, worldsave_format=worldsave_format)
+    else:
+        return property_class.read(reader, header, is_asa)
+
+
+def read_properties(
+    reader: BinaryReader,
+    is_asa: bool = False,
+    name_table: NameTable = None,
+    worldsave_format: bool = False,
+) -> list[Property]:
+    """
+    Read all properties until the "None" terminator.
+
+    This reads properties in a loop until encountering a property
+    named "None", which signals the end of the property list.
+
+    Args:
+        reader: The binary reader positioned at the first property.
+        is_asa: True for ASA format, False for ASE.
+        name_table: Optional name table for world saves.
+                   - list: ASE format (1-based index)
+                   - dict: ASA format (hash key)
+        worldsave_format: True for ASA WorldSave SQLite object format.
+
+    Returns:
+        List of parsed Property objects.
+
+    Raises:
+        UnknownPropertyError: If any property type is not recognized.
+    """
+    properties: list[Property] = []
+
+    while True:
+        prop = read_property(reader, is_asa, name_table=name_table, worldsave_format=worldsave_format)
+        if prop is None:
+            break
+        properties.append(prop)
+
+    return properties
+
+
+def read_properties_as_dict(
+    reader: BinaryReader,
+    is_asa: bool = False,
+) -> dict[str, Property | list[Property]]:
+    """
+    Read all properties and return as a dictionary.
+
+    Properties with the same name (different indices) are grouped into lists.
+
+    Args:
+        reader: The binary reader positioned at the first property.
+        is_asa: True for ASA format, False for ASE.
+
+    Returns:
+        Dictionary mapping property names to Property objects or lists of them.
+    """
+    properties = read_properties(reader, is_asa)
+    result: dict[str, Property | list[Property]] = {}
+
+    for prop in properties:
+        if prop.name in result:
+            existing = result[prop.name]
+            if isinstance(existing, list):
+                existing.append(prop)
+            else:
+                result[prop.name] = [existing, prop]
+        else:
+            result[prop.name] = prop
+
+    return result
+
+
+def get_property_value(
+    properties: dict[str, Property | list[Property]],
+    name: str,
+    default: t.Any = None,
+    index: int | None = None,
+) -> t.Any:
+    """
+    Get a property value from a properties dictionary.
+
+    Helper function for easily extracting values from parsed properties.
+
+    Args:
+        properties: Dictionary of properties from read_properties_as_dict.
+        name: The property name to look up.
+        default: Default value if property not found.
+        index: Specific index to retrieve if there are multiple properties
+               with the same name. None returns the first/only one.
+
+    Returns:
+        The property value, or the default if not found.
+    """
+    if name not in properties:
+        return default
+
+    prop_or_list = properties[name]
+
+    if isinstance(prop_or_list, list):
+        if index is not None:
+            # Find the property with the matching index
+            for prop in prop_or_list:
+                if prop.index == index:
+                    return prop.value
+            return default
+        else:
+            # Return the first one
+            return prop_or_list[0].value if prop_or_list else default
+    else:
+        if index is not None and prop_or_list.index != index:
+            return default
+        return prop_or_list.value

arkparser/structs/__init__.py

@@ -0,0 +1,60 @@
+"""
+ARK Struct System.
+
+This module provides struct types for structured data within properties.
+
+Structs come in two forms:
+1. Native structs: Fixed binary format (Vector, Color, etc.)
+2. Property-based structs: List of properties terminated by "None"
+
+Usage:
+    from arkparser.structs import read_struct, Vector, Color
+
+    # Read a struct by type name
+    struct = read_struct(reader, "Vector", is_asa=False)
+
+    # Access struct data
+    if isinstance(struct, Vector):
+        print(f"Position: ({struct.x}, {struct.y}, {struct.z})")
+"""
+
+from .base import NativeStruct, Struct
+from .colors import Color, LinearColor
+from .misc import CustomItemDataRef, Guid, UniqueNetIdRepl
+from .property_list import StructPropertyList
+from .registry import (
+    ARRAY_NAME_TO_STRUCT_TYPE,
+    STRUCT_REGISTRY,
+    get_array_struct_type,
+    is_native_struct,
+    read_struct,
+)
+from .vectors import IntPoint, IntVector, Quat, Rotator, Vector, Vector2D
+
+__all__ = [
+    # Base
+    "Struct",
+    "NativeStruct",
+    # Vectors
+    "Vector",
+    "Vector2D",
+    "Rotator",
+    "Quat",
+    "IntPoint",
+    "IntVector",
+    # Colors
+    "Color",
+    "LinearColor",
+    # Misc
+    "UniqueNetIdRepl",
+    "Guid",
+    "CustomItemDataRef",
+    # Property-based
+    "StructPropertyList",
+    # Registry
+    "STRUCT_REGISTRY",
+    "ARRAY_NAME_TO_STRUCT_TYPE",
+    "read_struct",
+    "is_native_struct",
+    "get_array_struct_type",
+]

arkparser/structs/base.py

@@ -0,0 +1,63 @@
+"""
+Struct Base Classes.
+
+Structs in ARK save files come in two forms:
+1. Native structs: Fixed binary format, known by struct type name
+2. Property-based structs: List of properties terminated by "None"
+
+This module provides the abstract base class and common types.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+if t.TYPE_CHECKING:
+    from ..common.binary_reader import BinaryReader
+
+
+class Struct(ABC):
+    """
+    Abstract base class for all struct types.
+
+    Structs are typed data containers used within StructProperty values.
+    """
+
+    @property
+    @abstractmethod
+    def struct_type(self) -> str:
+        """The struct type name (e.g., 'Vector', 'Color')."""
+        ...
+
+    @property
+    @abstractmethod
+    def is_native(self) -> bool:
+        """True if this is a native (fixed format) struct."""
+        ...
+
+    @abstractmethod
+    def to_dict(self) -> dict[str, t.Any]:
+        """Convert the struct to a dictionary for serialization."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def read(cls, reader: BinaryReader, is_asa: bool = False, **kwargs: t.Any) -> Struct:
+        """Read the struct from binary data."""
+        ...
+
+
+@dataclass
+class NativeStruct(Struct):
+    """
+    Base class for native structs with fixed binary formats.
+
+    Native structs have a known, fixed structure that doesn't use the
+    property system. Examples: Vector, Rotator, Color, etc.
+    """
+
+    @property
+    def is_native(self) -> bool:
+        return True

arkparser/structs/colors.py

@@ -0,0 +1,108 @@
+"""
+Color Structs.
+
+Color-related native structs for storing RGBA color values.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass
+
+from .base import NativeStruct
+
+if t.TYPE_CHECKING:
+    from ..common.binary_reader import BinaryReader
+
+
+@dataclass
+class Color(NativeStruct):
+    """
+    BGRA Color (8-bit per channel).
+
+    Format: b, g, r, a as UInt8 (4 bytes total).
+    Note: Byte order is BGRA, not RGBA!
+    """
+
+    b: int = 0
+    g: int = 0
+    r: int = 0
+    a: int = 255
+
+    @property
+    def struct_type(self) -> str:
+        return "Color"
+
+    def to_dict(self) -> dict[str, int]:
+        return {"r": self.r, "g": self.g, "b": self.b, "a": self.a}
+
+    @property
+    def rgba(self) -> tuple[int, int, int, int]:
+        """Get color as (r, g, b, a) tuple."""
+        return (self.r, self.g, self.b, self.a)
+
+    @property
+    def hex(self) -> str:
+        """Get color as hex string (#RRGGBB or #RRGGBBAA)."""
+        if self.a == 255:
+            return f"#{self.r:02x}{self.g:02x}{self.b:02x}"
+        return f"#{self.r:02x}{self.g:02x}{self.b:02x}{self.a:02x}"
+
+    @classmethod
+    def read(cls, reader: BinaryReader, is_asa: bool = False, **kwargs: t.Any) -> Color:
+        """Read a Color from the archive."""
+        return cls(
+            b=reader.read_uint8(),
+            g=reader.read_uint8(),
+            r=reader.read_uint8(),
+            a=reader.read_uint8(),
+        )
+
+
+@dataclass
+class LinearColor(NativeStruct):
+    """
+    Linear RGBA Color (32-bit float per channel).
+
+    Format: r, g, b, a as Float (16 bytes total).
+    Values are typically in range [0.0, 1.0] but can exceed for HDR.
+    """
+
+    r: float = 0.0
+    g: float = 0.0
+    b: float = 0.0
+    a: float = 1.0
+
+    @property
+    def struct_type(self) -> str:
+        return "LinearColor"
+
+    def to_dict(self) -> dict[str, float]:
+        return {"r": self.r, "g": self.g, "b": self.b, "a": self.a}
+
+    def to_color(self) -> Color:
+        """Convert to 8-bit Color (clamped to 0-255)."""
+        return Color(
+            r=max(0, min(255, int(self.r * 255))),
+            g=max(0, min(255, int(self.g * 255))),
+            b=max(0, min(255, int(self.b * 255))),
+            a=max(0, min(255, int(self.a * 255))),
+        )
+
+    @classmethod
+    def read(cls, reader: BinaryReader, is_asa: bool = False, **kwargs: t.Any) -> LinearColor:
+        """Read a LinearColor from the archive.
+
+        Args:
+            reader: Binary reader positioned at the struct data.
+            is_asa: True for ASA format.
+
+        Note: For ASA indexed struct properties, the array index prefix is
+        already handled by the struct registry before this method is called.
+        """
+        return cls(
+            r=reader.read_float(),
+            g=reader.read_float(),
+            b=reader.read_float(),
+            a=reader.read_float(),
+        )

arkparser/structs/misc.py

@@ -0,0 +1,133 @@
+"""
+Miscellaneous Native Structs.
+
+Various native structs that don't fit into other categories.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass
+
+from .base import NativeStruct
+
+if t.TYPE_CHECKING:
+    from ..common.binary_reader import BinaryReader
+
+
+@dataclass
+class UniqueNetIdRepl(NativeStruct):
+    """
+    Unique Network ID for player identification.
+
+    Used for Steam IDs and other platform identifiers.
+
+    ASE Format:
+        - Int32 unknown
+        - String net_id (e.g., "2533274977850953" for Xbox)
+
+    ASA Format:
+        - Byte unknown
+        - String value_type (platform, e.g., "RedpointEOS")
+        - Byte length
+        - Bytes value (raw ID bytes, converted to hex string)
+    """
+
+    unknown: int = 0
+    net_id: str = ""
+    value_type: str = ""  # ASA only: platform type like "RedpointEOS"
+
+    @property
+    def struct_type(self) -> str:
+        return "UniqueNetIdRepl"
+
+    def to_dict(self) -> dict[str, t.Any]:
+        result = {"unknown": self.unknown, "net_id": self.net_id}
+        if self.value_type:
+            result["value_type"] = self.value_type
+        return result
+
+    @property
+    def steam_id(self) -> str | None:
+        """Extract Steam ID if this is a Steam network ID."""
+        if self.net_id.startswith("steam:"):
+            return self.net_id[6:]
+        return self.net_id if self.net_id else None
+
+    @classmethod
+    def read(cls, reader: BinaryReader, is_asa: bool = False, **kwargs: t.Any) -> UniqueNetIdRepl:
+        """Read a UniqueNetIdRepl from the archive."""
+        if is_asa:
+            # ASA format: byte unknown + string value_type + byte length + bytes value
+            unknown = reader.read_uint8()
+            value_type = reader.read_string()
+            length = reader.read_uint8()
+            value_bytes = reader.read_bytes(length)
+            net_id = value_bytes.hex()
+            return cls(unknown=unknown, net_id=net_id, value_type=value_type)
+        else:
+            # ASE format: int32 unknown + string net_id
+            unknown = reader.read_int32()
+            net_id = reader.read_string()
+            return cls(unknown=unknown, net_id=net_id)
+
+
+@dataclass
+class Guid(NativeStruct):
+    """
+    GUID/UUID structure.
+
+    16-byte globally unique identifier.
+    """
+
+    value: str = ""  # Stored as hex string
+
+    @property
+    def struct_type(self) -> str:
+        return "Guid"
+
+    def to_dict(self) -> dict[str, str]:
+        return {"guid": self.value}
+
+    @classmethod
+    def read(cls, reader: BinaryReader, is_asa: bool = False, **kwargs: t.Any) -> Guid:
+        """Read a Guid from the archive."""
+        guid_value = reader.read_guid()
+        return cls(value=str(guid_value))
+
+
+@dataclass
+class CustomItemDataRef(NativeStruct):
+    """
+    Reference to custom item data.
+
+    Used for storing references to item-specific custom data.
+    Format: 4 x Int32 values (16 bytes)
+    """
+
+    value1: int = 0
+    value2: int = 0
+    value3: int = 0
+    value4: int = 0
+
+    @property
+    def struct_type(self) -> str:
+        return "CustomItemDataRef"
+
+    def to_dict(self) -> dict[str, int]:
+        return {
+            "value1": self.value1,
+            "value2": self.value2,
+            "value3": self.value3,
+            "value4": self.value4,
+        }
+
+    @classmethod
+    def read(cls, reader: BinaryReader, is_asa: bool = False, **kwargs: t.Any) -> CustomItemDataRef:
+        """Read a CustomItemDataRef from the archive."""
+        return cls(
+            value1=reader.read_int32(),
+            value2=reader.read_int32(),
+            value3=reader.read_int32(),
+            value4=reader.read_int32(),
+        )

arkparser/structs/property_list.py

@@ -0,0 +1,101 @@
+"""
+Property-Based Struct.
+
+This struct type contains a list of properties rather than a fixed binary format.
+It's used for complex game objects and custom data structures.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass, field
+
+from .base import Struct
+
+if t.TYPE_CHECKING:
+    from ..common.binary_reader import BinaryReader
+    from ..properties.base import Property
+
+
+@dataclass
+class StructPropertyList(Struct):
+    """
+    A struct that contains a list of properties.
+
+    This is the fallback for any struct type that isn't a known native type.
+    The properties are read until a "None" terminator is encountered.
+    """
+
+    _struct_type: str = "PropertyList"
+    properties: list[Property] = field(default_factory=list)
+
+    @property
+    def struct_type(self) -> str:
+        return self._struct_type
+
+    @property
+    def is_native(self) -> bool:
+        return False
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Convert properties to a dictionary."""
+        result: dict[str, t.Any] = {}
+        for prop in self.properties:
+            if prop.name in result:
+                # Handle duplicate property names (array-like)
+                existing = result[prop.name]
+                if isinstance(existing, list):
+                    existing.append(prop.value)
+                else:
+                    result[prop.name] = [existing, prop.value]
+            else:
+                result[prop.name] = prop.value
+        return result
+
+    def get_property(self, name: str, index: int = 0) -> Property | None:
+        """Get a property by name and optional index."""
+        for prop in self.properties:
+            if prop.name == name and prop.index == index:
+                return prop
+        return None
+
+    def get_value(self, name: str, default: t.Any = None, index: int = 0) -> t.Any:
+        """Get a property value by name."""
+        prop = self.get_property(name, index)
+        return prop.value if prop else default
+
+    @classmethod
+    def read(
+        cls,
+        reader: BinaryReader,
+        is_asa: bool = False,
+        struct_type: str = "PropertyList",
+        name_table: list[str] | None = None,
+        worldsave_format: bool = False,
+    ) -> StructPropertyList:
+        """
+        Read a property-based struct from the archive.
+
+        Note: This imports the registry at runtime to avoid circular imports.
+
+        Args:
+            reader: The binary reader.
+            is_asa: True for ASA format.
+            struct_type: The struct type name.
+            name_table: Optional name table for world saves (version 6+).
+            worldsave_format: True for ASA WorldSave SQLite object format.
+        """
+        # Import here to avoid circular dependency
+        from ..properties.registry import read_properties
+
+        # Note: For ASA, the extra_byte that precedes struct data is read by the
+        # calling code (StructProperty.read or ArrayProperty.read), not here.
+        # We just read the properties directly.
+
+        properties = read_properties(
+            reader,
+            is_asa,
+            name_table=name_table,
+            worldsave_format=worldsave_format,
+        )
+        return cls(_struct_type=struct_type, properties=properties)