arkparse 0.5.1__tar.gz → 0.5.2__tar.gz

{arkparse-0.5.1 → arkparse-0.5.2}/.gitignore

@@ -188,5 +188,6 @@ temp
 .venv**
 arkparse-fast-core/**
 /arkparse-fast-core
-
-**.zip
+.serena/
+**.zip
+.claude/

{arkparse-0.5.1 → arkparse-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparse
-Version: 0.5.1
+Version: 0.5.2
 Summary: A package to parse and modify ark save files
 Project-URL: Homepage, https://github.com/VincentHenauGithub/ark-save-parser
 Author-email: Vincent Henau <vincent.henau.github@gmail.com>

{arkparse-0.5.1 → arkparse-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arkparse"
-version = "0.5.1"
+version = "0.5.2"
 dependencies = [
     "rcon>=2.4.9",
     "numpy>=2.3.2",

{arkparse-0.5.1 → arkparse-0.5.2}/src/arkparse/logging/ark_save_logger.py

@@ -52,6 +52,16 @@ class ArkSaveLogger:
     # Use _get_struct_path() for thread-safe access
     current_struct_path = []
     _allow_invalid_objects = None
+    # Governs mod-namespace objects (not /Game/ or /Script/). Defaults to True
+    # (skip & continue) for backward compatibility; set to False to hard-fail.
+    _allow_invalid_mod_objects = None
+    # Optional callback invoked when an object fails to parse. Signature:
+    #   (obj_uuid, class_name, byte_buffer, error) -> None
+    # Used by tooling (e.g. the testbench) to capture failing objects for debug.
+    _object_failure_handler = None
+    # Optional callback invoked on a (non-fatal) struct size mismatch. Signature:
+    #   (struct_type, data_size, start_position, end_position, byte_buffer) -> None
+    _struct_mismatch_handler = None
     _worker_logging_enabled = None  # Whether logging is enabled in worker threads
     _file = ""
     _byte_buffer = None
@@ -140,10 +150,13 @@ class ArkSaveLogger:
                 }
                 ArkSaveLogger._file_viewer_enabled = True
                 ArkSaveLogger._worker_logging_enabled = False
+                ArkSaveLogger._allow_invalid_objects = True
+                ArkSaveLogger._allow_invalid_mod_objects = True
                 config = {
                     "levels": ArkSaveLogger._log_level_states,
                     "fve": False,
                     "allow_invalid": True,
+                    "allow_invalid_mod": True,
                     "worker_logging": False
                 }
                 write_config_file(ArkSaveLogger.__LOG_CONFIG_FILE_NAME, config)
@@ -151,6 +164,7 @@ class ArkSaveLogger:
                 ArkSaveLogger._log_level_states = config["levels"]
                 ArkSaveLogger._file_viewer_enabled = config["fve"]
                 ArkSaveLogger._allow_invalid_objects = config["allow_invalid"]
+                ArkSaveLogger._allow_invalid_mod_objects = config.get("allow_invalid_mod", True)
                 ArkSaveLogger._worker_logging_enabled = config.get("worker_logging", False)
             # Update cached parser_log state for fast checks
             ArkSaveLogger._parser_log_enabled = (
@@ -220,6 +234,69 @@ class ArkSaveLogger:
             global_config["allow_invalid"] = state
             write_config_file(ArkSaveLogger.__LOG_CONFIG_FILE_NAME, global_config)
 
+    @staticmethod
+    def allow_invalid_mod_objects(state: bool = True, set_globally: bool = False):
+        """Governs parsing failures for mod-namespace objects (anything whose
+        class is not under /Game/ or /Script/). When False, such failures are
+        reraised instead of skipped. Defaults to True (skip & continue)."""
+        if ArkSaveLogger._allow_invalid_mod_objects is None:
+            ArkSaveLogger.__init_config()
+
+        ArkSaveLogger._allow_invalid_mod_objects = state
+
+        if set_globally:
+            global_config = read_config_file(ArkSaveLogger.__LOG_CONFIG_FILE_NAME)
+            global_config["allow_invalid_mod"] = state
+            write_config_file(ArkSaveLogger.__LOG_CONFIG_FILE_NAME, global_config)
+
+    @staticmethod
+    def set_object_failure_handler(handler):
+        """Register a callback invoked whenever an object fails to parse.
+
+        The handler receives ``(obj_uuid, class_name, byte_buffer, error)``. Pass
+        ``None`` to clear it. Exceptions raised by the handler are swallowed so
+        debug tooling can never break parsing. Intended for capturing failing
+        objects (binary + structured dump) for offline debugging.
+        """
+        ArkSaveLogger._object_failure_handler = handler
+
+    @staticmethod
+    def _notify_object_failure(obj_uuid, class_name, byte_buffer, error, **kwargs):
+        """Forward a parse failure to the registered handler.
+
+        ``kwargs`` carries optional context (e.g. ``kind`` of "game"/"archive" and
+        a ``reload_hint`` dict) so the handler can capture and reload different
+        object types appropriately. Handlers should accept ``**kwargs``.
+        """
+        handler = ArkSaveLogger._object_failure_handler
+        if handler is None:
+            return
+        try:
+            handler(obj_uuid, class_name, byte_buffer, error, **kwargs)
+        except Exception as e:  # never let debug tooling break parsing
+            ArkSaveLogger.warning_log(f"object_failure_handler raised: {e}")
+
+    @staticmethod
+    def set_struct_mismatch_handler(handler):
+        """Register a callback invoked on a non-fatal struct size mismatch (a
+        struct parsed as a property list that didn't consume exactly data_size).
+
+        The handler receives ``(struct_type, data_size, start_position,
+        end_position, byte_buffer)``. Pass ``None`` to clear it. Exceptions are
+        swallowed. Intended for debug tooling to record under-/over-read structs.
+        """
+        ArkSaveLogger._struct_mismatch_handler = handler
+
+    @staticmethod
+    def _notify_struct_mismatch(struct_type, data_size, start_position, end_position, byte_buffer):
+        handler = ArkSaveLogger._struct_mismatch_handler
+        if handler is None:
+            return
+        try:
+            handler(struct_type, data_size, start_position, end_position, byte_buffer)
+        except Exception as e:  # never let debug tooling break parsing
+            ArkSaveLogger.warning_log(f"struct_mismatch_handler raised: {e}")
+
     @staticmethod
     def enable_worker_logging(state: bool = True, set_globally: bool = False):
         """Enable or disable logging in parallel worker threads.

{arkparse-0.5.1 → arkparse-0.5.2}/src/arkparse/parsing/ark_archive.py

@@ -73,6 +73,12 @@ class ArkArchive:
             except Exception as e:
                 ArkSaveLogger.error_log(f"Error reading properties for object \'{obj.class_name}\' at {self.data.get_position()}: {e}")
                 self.data.structured_print()
+                # Notify any registered debug handler (e.g. the testbench dumper).
+                # Archives reload from their raw bytes via ArkArchive(data, from_store).
+                ArkSaveLogger._notify_object_failure(
+                    None, obj.class_name, self.data, e,
+                    kind="archive", reload_hint={"from_store": from_store},
+                )
                 raise e
             ArkSaveLogger.exit_struct()
 

{arkparse-0.5.1 → arkparse-0.5.2}/src/arkparse/parsing/ark_property.py

@@ -173,7 +173,7 @@ class ArkProperty:
     # Public API
     # ---------------------------------------------------------------------------------------------
     @staticmethod
-    def read_property(byte_buffer: "ArkBinaryParser", in_array: bool = False) -> Optional["ArkProperty"]:
+    def read_property(byte_buffer: "ArkBinaryParser", in_array: bool = False, struct_end: int = -1) -> Optional["ArkProperty"]:
         name_position = byte_buffer.get_position()
         value_position = 0
         byte_buffer.save_context.generate_unknown = True
@@ -185,7 +185,12 @@ class ArkProperty:
             ArkSaveLogger.parser_log("Exiting struct (None marker) (pos = " + str(byte_buffer.get_position()) + " (hex: " + hex(byte_buffer.get_position()) + "))")
             ArkSaveLogger.exit_struct()
 
-            if byte_buffer.size() - byte_buffer.position >= 4 and byte_buffer.peek_int() == 0:
+            # Only skip the 4 trailing zeros if we haven't already reached the
+            # declared struct boundary. When struct_end is known and we're right
+            # at it, those zeros belong to the outer stream, not this struct.
+            if (struct_end == -1 or byte_buffer.position < struct_end) \
+                    and byte_buffer.size() - byte_buffer.position >= 4 \
+                    and byte_buffer.peek_int() == 0:
                 byte_buffer.skip_bytes(4)
             return None
 
@@ -291,6 +296,18 @@ class ArkProperty:
         if key_type == ArkValueType.Struct:
             value_type = bb.read_name()
         else:
+            if key_type == ArkValueType.Byte:
+                # Enum-keyed map (e.g. TMap<TEnumAsByte<EFoo>, ...>): the key's
+                # enum type is serialized as a descriptor block before the value
+                # type: [enum name][int][enum path][int]. Consume it so the value
+                # type is read from the correct offset.
+                enum_key_type = bb.read_name()
+                bb.read_int()
+                enum_key_path = bb.read_name()
+                bb.read_int()
+                ArkSaveLogger.parser_log(
+                    f"Enum-keyed map: enum={enum_key_type} ({enum_key_path})"
+                )
             value_type = bb.read_value_type_by_name()
             struct_names = bb.read_int()
             if struct_names > 0:
@@ -342,7 +359,13 @@ class ArkProperty:
     @staticmethod
     def read_struct_map(key_type: ArkValueType, bb: "ArkBinaryParser", map_name: str) -> "ArkProperty":
         props: List[ArkProperty] = []
-        key_name = ArkProperty.read_property_value(key_type, bb)
+        if key_type == ArkValueType.Byte:
+            # Enum-keyed map entry: the key is the enum value name (e.g.
+            # E_ActorType_AAT::NewEnumerator0), serialized as a name reference
+            # rather than a single byte.
+            key_name = bb.read_name()
+        else:
+            key_name = ArkProperty.read_property_value(key_type, bb)
         with log_block(f"Map({key_name}:{map_name})"):
             while bb.has_more():
                 p = ArkProperty.read_property(bb)
@@ -511,7 +534,12 @@ class ArkProperty:
         ark_struct_type = ArkStructType.from_type_name(struct_type)
         
         if (ark_struct_type is not None) or in_array:
-            if in_array and bb.peek_name() == "None":
+            # Known fixed-layout structs (LinearColor/Vector/Color/...) are packed
+            # primitives with no None terminator. In archive parsing there is no name
+            # table, so peek_name() falls back to read_string() and would mis-read their
+            # packed float bytes as a string length, overflowing the buffer. Skip the
+            # None probe for these and let the dedicated reader consume the exact bytes.
+            if in_array and ark_struct_type not in _STRUCT_READERS and bb.peek_name() == "None":
                 ArkSaveLogger.parser_log("Exiting struct (None marker)")
                 return bb.read_name()
             if data_size <= 4:
@@ -536,19 +564,21 @@ class ArkProperty:
         ArkSaveLogger.parser_log(f"Reading struct {struct_type} with data size {data_size} as property list at position {bb.get_position()}")
         # Fallback: struct as property list
         position = bb.get_position()
-        props = ArkProperty.read_struct_properties(bb)
+        props = ArkProperty.read_struct_properties(bb, struct_end=position + data_size)
         if bb.get_position() != position + data_size and not in_array:
             ArkSaveLogger.warning_log(f"WARNING: Struct reading position mismatch for type {struct_type}")
             ArkSaveLogger.warning_log(
                 f"StructType: {struct_type}, DataSize: {data_size}, Position: {position}, CurrentPosition: {bb.get_position()}"
             )
+            # Notify any registered debug handler (e.g. the testbench recorder).
+            ArkSaveLogger._notify_struct_mismatch(struct_type, data_size, position, bb.get_position(), bb)
             bb.set_position(position + data_size)
         return props
 
     @staticmethod
-    def read_struct_properties(bb: "ArkBinaryParser") -> ArkPropertyContainer:
+    def read_struct_properties(bb: "ArkBinaryParser", struct_end: int = -1) -> ArkPropertyContainer:
         props: List[ArkProperty] = []
-        struct_property = ArkProperty.read_property(bb)
+        struct_property = ArkProperty.read_property(bb, struct_end=struct_end)
         if struct_property is not None:
             ArkSaveLogger.parser_log(
                 f"Struct properties: {struct_property.name} {struct_property.type} {struct_property.value}"
@@ -556,7 +586,7 @@ class ArkProperty:
         while struct_property:
             props.append(struct_property)
             if bb.has_more():
-                struct_property = ArkProperty.read_property(bb)
+                struct_property = ArkProperty.read_property(bb, struct_end=struct_end)
                 if struct_property is not None:
                     ArkSaveLogger.parser_log(
                         f"Struct properties: {struct_property.name} {struct_property.type} {struct_property.value}"

{arkparse-0.5.1 → arkparse-0.5.2}/src/arkparse/parsing/struct/ark_custom_item_data.py

@@ -92,7 +92,19 @@ class ArkCustomItemData:
         #         ark_binary_data.validate_uint32(0)
         #         self.skins.append([bp, shorthand])
 
-        ark_binary_data.validate_name("None")        
+        ark_binary_data.validate_name("None")
+
+        # Some modded CustomItemData (e.g. the Cryopods mod) append extra empty
+        # trailing sections, each serialized as a [uint32 0][None] pair. Vanilla
+        # data has none of these, so this loop is a no-op there; the next array
+        # element starts with a real name ("CustomDataBytes") whose first 4 bytes
+        # are non-zero, which stops the loop.
+        while (ark_binary_data.size() - ark_binary_data.position) >= 12 \
+                and ark_binary_data.peek_int() == 0 \
+                and ark_binary_data.peek_name(4) == "None":
+            ark_binary_data.read_uint32()   # 0
+            ark_binary_data.read_name()     # None
+            ArkSaveLogger.parser_log("Consumed trailing [0][None] padding in CustomItemData")
 
         ArkSaveLogger.parser_log(f"CustomItemData of type {self.custom_data_name} read successfully, total size: {total_size} bytes")
         for string in self.strings:
@@ -335,10 +347,17 @@ class ArkCustomItemData:
         nr_of_items = ark_binary_data.read_uint32()
         soft_classes = []
 
-        while ark_binary_data.peek_int() != 0:
-            obj_name = ark_binary_data.read_name()
-            soft_classes.append(obj_name)
-        ark_binary_data.validate_uint32(0)
+        # Each soft-class entry is an FSoftObjectPath.
+        # - With name table (game saves): single FName (name_id + always_zero) + SubPathString.
+        # - Without name table (archives, UE 5.5): FTopLevelAssetPath — PackageName string
+        #   + AssetName string — followed by SubPathString.
+        has_name_table = ark_binary_data.save_context.has_name_table()
+        for _ in range(nr_of_items):
+            pkg_name = ark_binary_data.read_name()    # PackageName (or full path when name table)
+            if not has_name_table:
+                ark_binary_data.read_name()           # AssetName (archives only)
+            ark_binary_data.read_string()             # SubPathString (usually empty)
+            soft_classes.append(pkg_name)
 
         return soft_classes
 

{arkparse-0.5.1 → arkparse-0.5.2}/src/arkparse/saves/save_connection.py

@@ -609,10 +609,17 @@ class SaveConnection:
                 ArkSaveLogger.warning_log(f"Error parsing object {obj_uuid} of type {class_name}, skipping...")
             else:
                 byte_buffer.structured_print(to_default_file=True)
+                if ArkSaveLogger._allow_invalid_mod_objects is False:
+                    byte_buffer.find_names(type=2)
+                    ArkSaveLogger.error_log(f"Error parsing mod object {obj_uuid} of type {class_name}: {e}")
+                    reraise = True
                 ArkSaveLogger.warning_log(f"Error parsing non-standard object of type {class_name}")
 
                 # input("Press Enter to continue...")
 
+            # Notify any registered debug handler (e.g. the testbench dumper).
+            ArkSaveLogger._notify_object_failure(obj_uuid, class_name, byte_buffer, e, kind="game")
+
             SaveConnection.failed_parses[class_name] = SaveConnection.failed_parses.get(class_name, 0) + 1
             ArkSaveLogger.warning_log(f"Failed parses for this class: {SaveConnection.failed_parses[class_name]}")