talespire-encoding 1.2.2__py3-none-any.whl

talespire_encoding-1.2.2.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: talespire-encoding
+Version: 1.2.2
+Summary: Encoding and decoding tools for TaleSpire data
+Author: Baldrax
+License: MIT
+Project-URL: Homepage, https://github.com/Baldrax/TaleSpire-Encoding-Python
+Project-URL: Repository, https://github.com/Baldrax/TaleSpire-Encoding-Python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# TaleSpire-Encoding-Python
+Encoding/Decoding tools for TaleSpire
+
+This repository is just getting started.
+
+It currently contains two encoding types:
+- Slabs (v1, v2)
+- Creature Blueprints (v1, v2)
+
+## Installation:
+With pip you can install specific releases.
+```
+pip install git+https://github.com/Baldrax/TaleSpire-Encoding-Python.git@vX.X.X
+```
+Replace the version with the version you want to install:
+- [Latest Releases](https://github.com/Baldrax/TaleSpire-Encoding-Python/releases)
+
+## Slabs Example usage:
+```python
+from ts_encoding.slab import TSSlab
+
+example_slab_code = ("H4sIAAAAAAAACjv369xFJgZGBgYGgUWHGX9Pme/S4z7T7pZ"
+                     "doRonUGwCSIKhgRFMS0L4DTwMDCcYwOIsDBDADOZLQsRB8g"
+                     "xQPgOcDwD7jJ0vaAAAAA==")
+
+slab = TSSlab()
+slab.decode_slab(example_slab_code)
+
+# The slab contents are now in a dictionary `slab.data`
+from pprint import pprint
+pprint(slab.data)
+
+"""
+{'layout_count': 1,
+ 'layouts': [{'instance_count': 9,
+              'instances': [{'degrees': 90.0,
+                             'pos_x': 0.0,
+                             'pos_y': 0.0,
+                             'pos_z': 4.0},
+                            {'degrees': 0.0,
+                             'pos_x': 4.0,
+                             'pos_y': 0.0,
+                             'pos_z': 4.0},
+                            {'degrees': 0.0,
+                             'pos_x': 2.0,
+                             'pos_y': 0.0,
+                             'pos_z': 4.0},
+                            {'degrees': 270.0,
+                             'pos_x': 0.0,
+                             'pos_y': 0.0,
+                             'pos_z': 2.0},
+                            {'degrees': 180.0,
+                             'pos_x': 0.0,
+                             'pos_y': 0.0,
+                             'pos_z': 0.0},
+                            {'degrees': 0.0,
+                             'pos_x': 4.0,
+                             'pos_y': 0.0,
+                             'pos_z': 2.0},
+                            {'degrees': 0.0,
+                             'pos_x': 2.0,
+                             'pos_y': 0.0,
+                             'pos_z': 2.0},
+                            {'degrees': 0.0,
+                             'pos_x': 4.0,
+                             'pos_y': 0.0,
+                             'pos_z': 0.0},
+                            {'degrees': 0.0,
+                             'pos_x': 2.0,
+                             'pos_y': 0.0,
+                             'pos_z': 0.0}],
+              'reserved': 0,
+              'uuid': '01c3a210-94fb-449f-8c47-993eda3e7126'}],
+ 'magic_num': 3520002766,
+ 'num_creatures': 0,
+ 'version': 2}
+"""
+
+# To encode the data
+new_slab_code = slab.encode_slab()
+# The new_slab_code can be pasted into TaleSpire
+
+# To create the data start a new TSSlab and edit the data dictionary.
+# Each uuid is a new layout in the dictionary it is currently up to you
+#  to format the dictionary properly so that it encodes correctly.
+# In future versions there may be tools to help build the layouts.
+
+# Here is an example of creating a single grass tile
+new_slab = TSSlab()
+new_slab.data["layout_count"] = 1
+grass_layout = {
+    "instance_count": 1, # The number of grass tiles
+    "instances": [{
+        "degrees": 0.0, # Yaw rotation in degrees 0-360 it is up to you to give valid values
+        "pos_x": 0.0, # X position within slab
+        "pos_y": 0.0, # Y position within slab
+        "pos_z": 0.0}], # Z position within slab
+    "reserved": 0, # Always set to 0
+    "uuid": "01c3a210-94fb-449f-8c47-993eda3e7126" # Asset UUID
+}
+new_slab.data["layouts"].append(grass_layout)
+new_slab_code = new_slab.encode_slab()
+
+# You can paste that new_slab_code into TaleSpire to see your grass tile
+```
+
+## Creature Blueprint Example usage:
+```python
+from ts_encoding.creature_bp import TSCreature
+from pprint import pprint
+
+url_from_TS = ("talespire://creature-blueprint/"
+              "AgAMV2hpdGUgTWVlcGxlAQAAACMAYnI6MDAwMDAwMDAwMDAwMDAwMD"
+              "AwMDAwMDAwMDQ3MDQxMDABAAAAAI49u_vNJQRDrZctETEJKR8ABAAA"
+              "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgQQAAIEEAACBBAAAgQQ"
+              "AAIEEAACBBAAAgQQAAIEEAACBBAAAgQQAAIEEAACBBAAAgQQAAIEEA"
+              "ACBBAAAgQQAAIEEAACBBAAAA")
+
+bp = TSCreature()
+bp.decode_url(url_from_TS)
+pprint(bp.data)
+
+# You can change any of the data in `bp.data`
+bp.data["name"] = "New Name"
+bp.data["stats"][0] = {"max": 100.0, "value": 100.0}  # Changes hp to 100
+
+# To re-encode the data
+new_url = bp.encode_url()
+
+print(new_url)  # You can copy/paste this new URL into TaleSpire
+```

talespire_encoding-1.2.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+ts_encoding/__init__.py,sha256=9V8f47HbY_y2d0P7ilE4n0chgE4e2UKuOuL9MDwwzVs,322
+ts_encoding/assets.py,sha256=7jtDLbvZcpj0Ka0Jng0SmiN07vaTAPuSTT5Vbz0-b4A,5216
+ts_encoding/common.py,sha256=vTNXa2gYU7ib0yXtu1oO_aIwMmLTk9KequcwzLSGiTk,6745
+ts_encoding/creature_bp.py,sha256=_fISg6jayCxrkX6eW038Gn5c9hLgNO9Qkh5lYd3eFlU,13745
+ts_encoding/exceptions.py,sha256=E13sbDOaK8iUBUjMsn_oKPPyYOVjeevY9qu8iihgwwQ,892
+ts_encoding/slab.py,sha256=uv6f-9owrPm4Y2f-tcDBrIv5eIIEomrMPGU7lgqyDFA,9708
+ts_encoding/slab_testing.py,sha256=sumuW0h9PzpUZfOOMpIy118_EJJNwE0QXfIPEif8klM,18552
+talespire_encoding-1.2.2.dist-info/METADATA,sha256=01fx0BOEwVDiluN_9VNOs5-w6h3QLPkQrew6yHXh3PE,5186
+talespire_encoding-1.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+talespire_encoding-1.2.2.dist-info/top_level.txt,sha256=CrhA5IN_Ee5Brotf1rSdvULycalNETRGm2coN5quVbA,12
+talespire_encoding-1.2.2.dist-info/RECORD,,

talespire_encoding-1.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

talespire_encoding-1.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+ts_encoding

ts_encoding/__init__.py

@@ -0,0 +1,17 @@
+__version__ = "1.2.2"
+
+from .exceptions import (
+    SlabExceedsSizeLimit,
+    BadSlabCode,
+    UnsupportedSlabVersion,
+    InvalidTaleSpireDirectory,
+    InvalidAssetType
+)
+
+__all__ = [
+    "SlabExceedsSizeLimit",
+    "BadSlabCode",
+    "UnsupportedSlabVersion",
+    "InvalidTaleSpireDirectory",
+    "InvalidAssetType"
+]

ts_encoding/assets.py

@@ -0,0 +1,152 @@
+"""
+Tools for reading in TaleSpire assets.
+These require a path to a valid TaleSpire install.
+It utilizes the `index.json` files within the installed location to get asset information.
+"""
+from __future__ import annotations
+
+import json
+
+from pathlib import Path
+
+from ts_encoding import InvalidTaleSpireDirectory, InvalidAssetType
+
+
+def get_asset_index_paths(ts_basedir: Path | str) -> list[Path]:
+    """
+    Given the base TaleSpire Directory get a list of all the paths to index.json files.
+
+    Args:
+        ts_basedir: The base directory that TaleSpire is installed in.
+    """
+    ts_base_path = Path(str(ts_basedir))
+    taleweaver_dir = ts_base_path / "Taleweaver"
+
+    if taleweaver_dir.is_dir():
+        return list(taleweaver_dir.rglob("index.json"))
+    else:
+        raise InvalidTaleSpireDirectory(f"The supplied TaleSpire directory is not valid:\n\t{ts_base_path}")
+
+
+def read_index_file(index_file: Path | str) -> dict:
+    """
+    Read in the given index file and return it as a dictionary.
+
+    Args:
+        index_file: The TaleSpire index.json file to be read.
+    """
+    index_file_path = Path(str(index_file))
+    with index_file_path.open("r", encoding="utf-8") as f:
+        index_dict = json.load(f)
+
+    return index_dict
+
+
+def get_index_dicts(ts_basedir: Path | str) -> dict:
+    """
+    Given the base TaleSpire directory return a dictionary containing
+    all the content pack asset indexes as dictionaries.
+
+    Args:
+        ts_basedir: The base directory that TaleSpire is installed in.
+    """
+    index_files = get_asset_index_paths(ts_basedir)
+
+    index_dicts = {}
+
+    for index_file in index_files:
+        index_dict = read_index_file(index_file)
+        index_name = index_dict["Name"]
+        index_dicts[index_name] = {"path": str(index_file), "index": index_dict}
+
+    return index_dicts
+
+
+class TSAssetLib:
+
+    # This is the default list of asset loaded as well as the valid types excepted.
+    default_asset_filter = ["Tiles", "Props", "Creatures", "Music"]
+
+    def __init__(self, ts_basedir, asset_filter: list[str] | None = None):
+        """
+        TaleSpire Asset Library
+        This reads in all the TaleSpire assets and stores them both in index form and by UUID.
+
+        A filter can be set to limit what types of assets are stored.
+        Valid types are: ["Tiles", "Props", "Creatures", "Music"]
+        The default is all asset types.
+
+        Args:
+            ts_basedir: The base directory that TaleSpire is installed in.
+            asset_filter: A list of asset types to use as a filter.
+        """
+        self.index_dicts = get_index_dicts(ts_basedir)
+        self.asset_filter = asset_filter if asset_filter else self.default_asset_filter
+        self.index_names = list(self.index_dicts.keys())
+        self.asset_uuid_dict: dict[str, TSAsset] = {}
+        self._build_asset_uuid_dict()
+
+    def _build_asset_uuid_dict(self) -> None:
+        for index_name in self.index_names:
+            index_path = Path(self.index_dicts[index_name]["path"])
+            index_dict = self.index_dicts[index_name]["index"]
+
+            icon_atlases = []
+            for atlas_entry in index_dict["IconsAtlases"]:
+                icon_atlases.append(atlas_entry["Path"])
+
+            for asset_type in self.asset_filter:
+                asset_type = asset_type.title()
+                if asset_type not in self.default_asset_filter:
+                    raise InvalidAssetType(
+                        f"Invalid Asset Filter: {asset_type}\nValid types are: {self.default_asset_filter}"
+                    )
+
+                for asset_dict in self.index_dicts[index_name]["index"][asset_type]:
+                    if "Icon" in asset_dict:
+                        asset = TSIconAsset(asset_dict, asset_type)
+                        atlas_index = asset_dict["Icon"]["AtlasIndex"]
+                        asset.icon_atlas = str(index_path.parent / icon_atlases[atlas_index])
+                    else:
+                        asset = TSAsset(asset_dict, asset_type)
+
+                    self.asset_uuid_dict[asset.id] = asset
+
+    def asset(self, asset_uuid: str) -> TSAsset:
+        """
+        Given a UUID return the asset.
+
+        Args:
+            asset_uuid: The TaleSpire asset UUID
+        """
+        asset = self.asset_uuid_dict.get(asset_uuid, None)
+        return asset
+
+    def assets(self) -> list[TSAsset]:
+        """Returns a list of all the assets in the library."""
+        return list(self.asset_uuid_dict.values())
+
+
+class TSAsset:
+
+    def __init__(self, asset_dict, asset_type):
+        self.asset_dict = asset_dict
+        self.asset_type = asset_type
+        self.id = asset_dict["Id"].lower()
+        self.name = asset_dict["Name"]
+        self.deprecated = asset_dict["IsDeprecated"] == 1
+
+
+class TSIconAsset(TSAsset):
+
+    def __init__(self, asset_dict, asset_type):
+        super().__init__(asset_dict, asset_type)
+        self.icon_atlas_index = asset_dict["Icon"]["AtlasIndex"]
+        self.icon_atlas = ""
+        atlas_region = asset_dict["Icon"]["Region"]
+        self.atlas_region = (
+            atlas_region["x"],
+            atlas_region["y"],
+            atlas_region["width"],
+            atlas_region["height"]
+        )

ts_encoding/common.py

@@ -0,0 +1,210 @@
+"""
+Base TS Encoding classes and functions for use in the specific encoders.
+
+URL Schemes are documented here:
+https://talespire.com/url-scheme
+
+Standard Byte order is little-endian
+"""
+import base64
+import struct
+import uuid
+
+
+class TSCodingBase:
+    """
+    A Base Class to Decode and Encode a TaleSpire content.
+
+    For Decoding:
+    The class stores the binary data and an offset which represents the current position/index we are at in the
+    binary data. Each unpack method then increments the offset by the proper amount so we can decode the next
+    step without having to feed in the offset index.
+    """
+
+    def __init__(self):
+        self.data = {}
+        self._init_data()
+        self._version = 0
+        self._encode_version = 2
+        self._code = None
+        self._binary_data = None
+        self._offset = 0
+
+    def _init_data(self) -> None:
+        """
+        This is intended to be overridden by the subclass.
+        The data dictionary should be initialized to a default state declaring all the data needed.
+        """
+        self.data = {
+            "version": 1,
+        }
+
+    def _decode(self) -> None:
+        """
+        Preps self._code into self._binary_data then runs self._decode_steps()
+        It is up to the subclass to set self._code
+        """
+        self._binary_data = base64.b64decode(self._code)  # Decode the encoded string into binary data
+        self._offset = 0  # Reset the offset index of the binary data
+        self._decode_steps()
+
+    def _decode_steps(self) -> None:
+        """
+        This is meant to be overridden by the subclass.
+        Keep these steps as simple as possible, 1 or 2 lines or break them out into another method.
+        When the steps are complete all the binary data should be unpacked into `self.data`
+        """
+        pass
+
+    def _encode(self) -> None:
+        """
+        Resets self._binary_data, runs self._encode_steps and encodes the new binary data to self._code
+        It is up to the subclass to reveal self._code to the user or application.
+        """
+        self._binary_data = bytearray()
+        self._encode_steps()
+        self._code = base64.b64encode(self._binary_data)
+
+    def _encode_steps(self) -> None:
+        """
+        This is meant to be overridden by the subclass.
+        Keep these steps as simple as possible, 1 or 2 lines or break them out into another method.
+        When the steps are complete everything in `self.data` should be packed into `self._binary_data`
+        """
+        pass
+
+    def _unpack_u8(self) -> int:
+        """Unpacks a u8 - Unsigned 8-bit integer (1 byte)"""
+        result, = struct.unpack_from("<B", self._binary_data, self._offset)
+        self._offset += 1
+        return result
+
+    def _unpack_u16(self) -> int:
+        """Unpacks a u16 - Unsigned Short Integer (2 bytes)"""
+        result, = struct.unpack_from("<H", self._binary_data, self._offset)
+        self._offset += 2
+        return result
+
+    def _unpack_u32(self) -> int:
+        """Unpacks a u32 - Unsigned 32-bit Integer (4 bytes)"""
+        result, = struct.unpack_from("<I", self._binary_data, self._offset)
+        self._offset += 4
+        return result
+
+    def _unpack_u64(self) -> int:
+        """Unpacks a u64 - Unsigned 64-bit integer (8 bytes)"""
+        result, = struct.unpack_from("<Q", self._binary_data, self._offset)
+        self._offset += 8
+        return result
+
+    def _unpack_utf8(self, num_bytes: int) -> str:
+        """
+        Unpacks a UTF-8 string of fixed length.
+
+        Args:
+            num_bytes (int): Number of bytes to read from the stream.
+
+        Returns:
+            str: Decoded UTF-8 string
+        """
+        result, = struct.unpack_from(f"<{num_bytes}s", self._binary_data, self._offset)
+        self._offset += num_bytes
+        return result
+
+    def _unpack_i32(self) -> int:
+        """Unpacks an i32 - Signed 32-bit integer (4 bytes)"""
+        result, = struct.unpack_from("<i", self._binary_data, self._offset)
+        self._offset += 4
+        return result
+
+    def _unpack_uuid(self) -> str:
+        """Unpacks a UUID - 128-bit identifier (16 bytes)"""
+        result, = struct.unpack_from(f"16s", self._binary_data, self._offset)
+        self._offset += 16
+        return str(uuid.UUID(bytes=result))
+
+    def _unpack_slab_uuid(self) -> str:
+        """Unpacks a slab UUID - 128-bit identifier (16 bytes, mixed-endian layout)"""
+        fields = struct.unpack_from("<IHH8B", self._binary_data, self._offset)
+        self._offset += 16
+        asset_uuid = uuid.UUID(
+            fields=(
+                fields[0],
+                fields[1],
+                fields[2],
+                fields[3],
+                fields[4],
+                int.from_bytes(fields[5:], byteorder="big")
+            )
+        )
+        return str(asset_uuid)
+
+    def _pack_u8(self, value: int) -> None:
+        """
+        Packs a u8 - Unsigned 8-bit integer (1 byte)
+
+        Args:
+            value: The integer value to pack.
+        """
+        self._binary_data.extend(struct.pack("<B", value))
+
+    def _pack_u16(self, value: int) -> None:
+        """
+        Packs a u16 - Unsigned 16-bit integer (2 bytes)
+
+        Args:
+            value: The integer value to pack.
+        """
+        self._binary_data.extend(struct.pack("<H", value))
+
+    def _pack_u32(self, value: int) -> None:
+        """
+        Packs a u32 - Unsigned 32-bit integer (4 bytes)
+
+        Args:
+            value: The integer value to pack.
+        """
+        self._binary_data.extend(struct.pack("<I", value))
+
+    def _pack_u64(self, value: int) -> None:
+        """
+        Packs a u64 - Unsigned 64-bit Integer (8 bytes)
+
+        Args:
+            value: The integer value to pack.
+        """
+        self._binary_data.extend(struct.pack("<Q", value))
+
+    def _pack_uuid(self, uuid_str: str) -> None:
+        """
+        Packs a UUID - 128-bit identifier (16 bytes)
+
+        Args:
+            uuid_str: The UUID string.
+        """
+        self._binary_data.extend(uuid.UUID(uuid_str).bytes)
+
+    def _pack_slab_uuid(self, uuid_str: str):
+        """
+        Packs a Slab UUID - 128-bit identifier (16 bytes, mixed-endian layout)
+
+        Args:
+            uuid_str: The UUID String.
+        """
+        fields = uuid.UUID(uuid_str).fields
+
+        node_bytes = fields[5].to_bytes(6, byteorder="big")
+
+        self._binary_data.extend(struct.pack(
+            "<IHH8B",
+            fields[0], fields[1], fields[2], fields[3], fields[4], *node_bytes
+        ))
+
+    def _pack_i32(self, value: int):
+        """
+        Packs an i32 - Signed 32-bit integer (4 bytes)
+
+        Args:
+            value: The integer to pack.
+        """
+        self._binary_data.extend(struct.pack("<i", value))