arkparser 0.1.3__tar.gz → 0.1.4__tar.gz

{arkparser-0.1.3 → arkparser-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.1.3
+Version: 0.1.4
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -97,7 +97,7 @@ A pure-Python library for parsing ARK: Survival Evolved (ASE) and ARK: Survival
 
 ## Features
 
-- **Player Profiles** (`.arkprofile`): character name, level, stats, engrams
+- **Player Profiles** (`.arkprofile`): platform gamertag, character name, level, stats, engrams
 - **Tribe Data** (`.arktribe`): members, ranks, logs, alliances
 - **Cloud Inventory / Obelisk**: uploaded creatures, items, cryopod contents
 - **World Saves** (`.ark`): full map state, including creatures, structures, items, and players
@@ -122,7 +122,8 @@ from arkparser import Profile
 
 profile = Profile.load("path/to/player.arkprofile")  # auto-detects ASE/ASA
 
-print(profile.player_name)         # "SomePlayer"
+print(profile.player_name)         # Platform gamertag / display name
+print(profile.character_name)      # In-game character name
 print(profile.level)               # 105
 print(profile.tribe_id)            # 1729028872
 print(profile.engram_blueprints)   # ["EngramEntry_Campfire_C", ...]
@@ -258,11 +259,13 @@ All file parsers support `load(source)` which accepts `str`, `Path`, or `bytes`
 
 | Property | Type | Description |
 |---|---|---|
-| `player_name` | `str \| None` | Character name |
+| `player_name` | `str \| None` | Platform gamertag / display name |
+| `character_name` | `str \| None` | In-game character name, falling back to `player_name` when absent |
 | `player_id` | `int \| None` | Unique player ID |
 | `unique_id` | `str \| None` | Platform ID (Steam/Xbox numeric ID) |
 | `tribe_id` | `int \| None` | Tribe ID (handles ASE `TribeId` / ASA `TribeID`) |
 | `tribe_name` | `str \| None` | Always `None`; tribe name is not stored in profiles |
+| `is_female` | `bool \| None` | Parsed gender flag (`True` = female, `False` = male, `None` = absent) |
 | `level` | `int` | Current level (`ExtraCharacterLevel + 1`) |
 | `experience` | `float` | Total XP |
 | `total_engram_points` | `int` | Engram points spent |

{arkparser-0.1.3 → arkparser-0.1.4}/README.md

@@ -63,7 +63,7 @@ A pure-Python library for parsing ARK: Survival Evolved (ASE) and ARK: Survival
 
 ## Features
 
-- **Player Profiles** (`.arkprofile`): character name, level, stats, engrams
+- **Player Profiles** (`.arkprofile`): platform gamertag, character name, level, stats, engrams
 - **Tribe Data** (`.arktribe`): members, ranks, logs, alliances
 - **Cloud Inventory / Obelisk**: uploaded creatures, items, cryopod contents
 - **World Saves** (`.ark`): full map state, including creatures, structures, items, and players
@@ -88,7 +88,8 @@ from arkparser import Profile
 
 profile = Profile.load("path/to/player.arkprofile")  # auto-detects ASE/ASA
 
-print(profile.player_name)         # "SomePlayer"
+print(profile.player_name)         # Platform gamertag / display name
+print(profile.character_name)      # In-game character name
 print(profile.level)               # 105
 print(profile.tribe_id)            # 1729028872
 print(profile.engram_blueprints)   # ["EngramEntry_Campfire_C", ...]
@@ -224,11 +225,13 @@ All file parsers support `load(source)` which accepts `str`, `Path`, or `bytes`
 
 | Property | Type | Description |
 |---|---|---|
-| `player_name` | `str \| None` | Character name |
+| `player_name` | `str \| None` | Platform gamertag / display name |
+| `character_name` | `str \| None` | In-game character name, falling back to `player_name` when absent |
 | `player_id` | `int \| None` | Unique player ID |
 | `unique_id` | `str \| None` | Platform ID (Steam/Xbox numeric ID) |
 | `tribe_id` | `int \| None` | Tribe ID (handles ASE `TribeId` / ASA `TribeID`) |
 | `tribe_name` | `str \| None` | Always `None`; tribe name is not stored in profiles |
+| `is_female` | `bool \| None` | Parsed gender flag (`True` = female, `False` = male, `None` = absent) |
 | `level` | `int` | Current level (`ExtraCharacterLevel + 1`) |
 | `experience` | `float` | Total XP |
 | `total_engram_points` | `int` | Engram points spent |

{arkparser-0.1.3 → arkparser-0.1.4}/arkparser/__init__.py

@@ -16,7 +16,8 @@ Example usage:
     >>>
     >>> # Load a player profile
     >>> profile = Profile.load("path/to/profile.arkprofile")
-    >>> print(f"Player: {profile.player_name}")
+    >>> print(f"Gamertag: {profile.player_name}")
+    >>> print(f"Character: {profile.character_name}")
     >>>
     >>> # Load tribe data
     >>> tribe = Tribe.load("path/to/tribe.arktribe")

{arkparser-0.1.3 → arkparser-0.1.4}/arkparser/export.py

@@ -521,13 +521,23 @@ def _export_profile_parser(profile: Profile) -> dict[str, t.Any]:
     }
     steam_id = profile.unique_id or ""
 
+    # The C# reference treats these as two distinct names:
+    #   Name (ContentPlayer.cs:77)         -> platform gamertag (PlayerName field)
+    #   CharacterName (ContentPlayer.cs:86) -> in-game name (PlayerCharacterName field)
+    # Export contract mirrors that split: ``steam`` = gamertag, ``name`` =
+    # in-game character name. Falls back to the gamertag if the character
+    # config struct is absent (matches the C# `?? Name` fallback).
+    gamertag = profile.player_name or ""
+    character_name = profile.character_name or gamertag
+    is_female = profile.is_female
+
     result: dict[str, t.Any] = {
         "playerid": profile.player_id or 0,
-        "steam": "",
-        "name": profile.player_name or "",
+        "steam": gamertag,
+        "name": character_name,
         "tribeid": profile.tribe_id or 0,
         "tribe": profile.tribe_name or "",
-        "sex": "",
+        "sex": "Female" if is_female is True else "Male",
         "lvl": profile.level,
         "hp": stats["health"],
         "stam": stats["stamina"],

{arkparser-0.1.3 → arkparser-0.1.4}/arkparser/files/profile.py

@@ -2,7 +2,7 @@
 Player profile parser for .arkprofile files.
 
 Profile files contain player character data including:
-- Character name and stats
+- Platform gamertag and character name
 - Level and experience
 - Engrams learned
 - Inventory items (if saved)
@@ -28,7 +28,8 @@ class Profile(ArkFile):
 
     Example usage:
         >>> profile = Profile.load("examples/ase/map_save/2533274977850953.arkprofile")
-        >>> print(f"Player: {profile.player_name}")
+        >>> print(f"Gamertag: {profile.player_name}")
+        >>> print(f"Character: {profile.character_name}")
         >>> print(f"Level: {profile.level}")
     """
 
@@ -70,9 +71,53 @@ class Profile(ArkFile):
 
     @property
     def player_name(self) -> str | None:
-        """Get the player's character name."""
+        """Get the player's platform gamertag (Steam / Xbox / PSN display name).
+
+        Note: despite the historical name, this is NOT the in-game character
+        name. For that, use ``character_name``. The C# reference (ContentPlayer.cs
+        line 77) reads this same ``PlayerName`` field into its ``Name`` property.
+        """
         return self._player_data.get("PlayerName")
 
+    @property
+    def character_name(self) -> str | None:
+        """Get the player's in-game character name.
+
+        Purpose: returns the name the player chose when creating their
+        character (e.g. "Alex"), distinct from the platform gamertag (e.g.
+        "Itz0Alex") which ``player_name`` returns.
+        Preconditions: profile file is loaded; ``_player_data`` is accessible.
+        Postconditions: returns ``MyPlayerCharacterConfig.PlayerCharacterName``
+        when present, including empty-string values, falling back to
+        ``player_name`` (gamertag) only when the config field is absent -
+        matches the C# reference behavior
+        (ContentPlayer.cs line 86: ``CharacterName = playerConfig.GetPropertyValue<string>("PlayerCharacterName") ?? Name;``).
+        Side effects: none.
+        Failure modes: returns ``None`` only when both the config struct and
+        ``PlayerName`` are missing.
+        """
+        config = self._player_data.get("MyPlayerCharacterConfig")
+        if isinstance(config, dict):
+            character_name = config.get("PlayerCharacterName")
+            if character_name is not None:
+                return character_name
+        return self.player_name
+
+    @property
+    def is_female(self) -> bool | None:
+        """Get the player's character gender (True = female, False = male, None = unknown).
+
+        Same nested location as ``character_name``: read from
+        ``MyPlayerCharacterConfig.bIsFemale``. Returns None when the config
+        struct is absent (treat as gender unknown / default male in display code).
+        """
+        config = self._player_data.get("MyPlayerCharacterConfig")
+        if isinstance(config, dict):
+            value = config.get("bIsFemale")
+            if value is not None:
+                return bool(value)
+        return None
+
     @property
     def player_id(self) -> int | None:
         """Get the player's unique ID."""
@@ -202,10 +247,12 @@ class Profile(ArkFile):
         base_dict.update(
             {
                 "player_name": self.player_name,
+                "character_name": self.character_name,
                 "player_id": self.player_id,
                 "unique_id": self.unique_id,
                 "tribe_id": self.tribe_id,
                 "tribe_name": self.tribe_name,
+                "is_female": self.is_female,
                 "experience": self.experience,
                 "total_engram_points": self.total_engram_points,
             }

{arkparser-0.1.3 → arkparser-0.1.4}/arkparser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.1.3
+Version: 0.1.4
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -97,7 +97,7 @@ A pure-Python library for parsing ARK: Survival Evolved (ASE) and ARK: Survival
 
 ## Features
 
-- **Player Profiles** (`.arkprofile`): character name, level, stats, engrams
+- **Player Profiles** (`.arkprofile`): platform gamertag, character name, level, stats, engrams
 - **Tribe Data** (`.arktribe`): members, ranks, logs, alliances
 - **Cloud Inventory / Obelisk**: uploaded creatures, items, cryopod contents
 - **World Saves** (`.ark`): full map state, including creatures, structures, items, and players
@@ -122,7 +122,8 @@ from arkparser import Profile
 
 profile = Profile.load("path/to/player.arkprofile")  # auto-detects ASE/ASA
 
-print(profile.player_name)         # "SomePlayer"
+print(profile.player_name)         # Platform gamertag / display name
+print(profile.character_name)      # In-game character name
 print(profile.level)               # 105
 print(profile.tribe_id)            # 1729028872
 print(profile.engram_blueprints)   # ["EngramEntry_Campfire_C", ...]
@@ -258,11 +259,13 @@ All file parsers support `load(source)` which accepts `str`, `Path`, or `bytes`
 
 | Property | Type | Description |
 |---|---|---|
-| `player_name` | `str \| None` | Character name |
+| `player_name` | `str \| None` | Platform gamertag / display name |
+| `character_name` | `str \| None` | In-game character name, falling back to `player_name` when absent |
 | `player_id` | `int \| None` | Unique player ID |
 | `unique_id` | `str \| None` | Platform ID (Steam/Xbox numeric ID) |
 | `tribe_id` | `int \| None` | Tribe ID (handles ASE `TribeId` / ASA `TribeID`) |
 | `tribe_name` | `str \| None` | Always `None`; tribe name is not stored in profiles |
+| `is_female` | `bool \| None` | Parsed gender flag (`True` = female, `False` = male, `None` = absent) |
 | `level` | `int` | Current level (`ExtraCharacterLevel + 1`) |
 | `experience` | `float` | Total XP |
 | `total_engram_points` | `int` | Engram points spent |

{arkparser-0.1.3 → arkparser-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arkparser"
-version = "0.1.3"
+version = "0.1.4"
 description = "Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files"
 readme = "README.md"
 license = "MIT"

{arkparser-0.1.3 → arkparser-0.1.4}/tests/test_export.py

@@ -46,7 +46,9 @@ def test_export_players_uses_profile_parser(ase_profile_path: Path) -> None:
     profile = Profile.load(ase_profile_path)
     exported = export_players(type("Holder", (), {"profiles": [profile]})())
     assert exported[0]["playerid"] == profile.player_id
-    assert exported[0]["name"] == profile.player_name
+    assert exported[0]["steam"] == profile.player_name
+    assert exported[0]["name"] == profile.character_name
+    assert exported[0]["sex"] == ("Female" if profile.is_female else "Male")
     assert exported[0]["tribeid"] == profile.tribe_id
 
 

{arkparser-0.1.3 → arkparser-0.1.4}/tests/test_profile.py

@@ -29,6 +29,17 @@ class TestASEProfile:
         assert isinstance(profile.player_name, str)
         assert len(profile.player_name) > 0
 
+    def test_ase_character_name(self, ase_profile_path: Path) -> None:
+        """ASE profile should expose the in-game character name separately."""
+        profile = Profile.load(ase_profile_path)
+        assert profile.character_name == "neg"
+        assert profile.character_name != profile.player_name
+
+    def test_ase_is_female(self, ase_profile_path: Path) -> None:
+        """ASE profile should expose the parsed gender flag when present."""
+        profile = Profile.load(ase_profile_path)
+        assert profile.is_female is True
+
     def test_ase_player_id(self, ase_profile_path: Path) -> None:
         """ASE profile should have a numeric player ID."""
         profile = Profile.load(ase_profile_path)
@@ -47,6 +58,8 @@ class TestASEProfile:
         d = profile.to_dict()
         assert isinstance(d, dict)
         assert "player_name" in d
+        assert d["character_name"] == profile.character_name
+        assert d["is_female"] is True
         assert "player_id" in d
 
 
@@ -70,6 +83,16 @@ class TestASAProfile:
         assert isinstance(profile.player_name, str)
         assert len(profile.player_name) > 0
 
+    def test_asa_character_name_falls_back_to_player_name(self, asa_profile_path: Path) -> None:
+        """ASA profile should fall back to the platform name when character config is absent."""
+        profile = Profile.load(asa_profile_path)
+        assert profile.character_name == profile.player_name
+
+    def test_asa_is_female_can_be_unknown(self, asa_profile_path: Path) -> None:
+        """ASA profile should return None when the gender flag is absent."""
+        profile = Profile.load(asa_profile_path)
+        assert profile.is_female is None
+
     def test_asa_player_id(self, asa_profile_path: Path) -> None:
         """ASA profile should have a numeric player ID."""
         profile = Profile.load(asa_profile_path)
@@ -88,6 +111,8 @@ class TestASAProfile:
         d = profile.to_dict()
         assert isinstance(d, dict)
         assert "player_name" in d
+        assert d["character_name"] == profile.character_name
+        assert d["is_female"] is None
         assert "player_id" in d
 
     def test_asa_engram_blueprints(self, asa_profile_path: Path) -> None: