tilemap-parser 1.0.1__tar.gz → 1.1.1__tar.gz

{tilemap_parser-1.0.1/src/tilemap_parser.egg-info → tilemap_parser-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 1.0.1
+Version: 1.1.1
 Summary: Standalone parser/loader for tilemap-editor JSON maps and sprite animation JSON.
 Author: tilemap parser contributors
 Classifier: Programming Language :: Python :: 3

{tilemap_parser-1.0.1 → tilemap_parser-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tilemap-parser"
-version = "1.0.1"
+version = "1.1.1"
 description = "Standalone parser/loader for tilemap-editor JSON maps and sprite animation JSON."
 readme = "README.md"
 requires-python = ">=3.10"

{tilemap_parser-1.0.1 → tilemap_parser-1.1.1}/src/tilemap_parser/__init__.py

@@ -10,6 +10,30 @@ from .animation import (
     parse_animation_file,
     parse_animation_json,
 )
+from .collision import (
+    CapsuleShape,
+    CharacterCollision,
+    CircleShape,
+    CollisionCache,
+    CollisionParseError,
+    CollisionPolygon,
+    RectangleShape,
+    TileCollisionData,
+    TilesetCollision,
+    clear_collision_cache,
+    get_cached_character_collision,
+    get_cached_tileset_collision,
+    load_character_collision,
+    load_tileset_collision,
+    parse_character_collision,
+    parse_tileset_collision,
+)
+from .collision_runner import (
+    CollisionResult,
+    CollisionRunner,
+    ICollidableSprite,
+    MovementMode,
+)
 from .map_loader import TilemapData, load_map
 from .map_parse import (
     MapParseError,
@@ -36,8 +60,18 @@ __all__ = [
     "AnimationMarker",
     "AnimationParseError",
     "AnimationPlayer",
+    "CapsuleShape",
+    "CharacterCollision",
+    "CircleShape",
+    "CollisionCache",
+    "CollisionParseError",
+    "CollisionPolygon",
+    "CollisionResult",
+    "CollisionRunner",
+    "ICollidableSprite",
     "LayerRenderStats",
     "MapParseError",
+    "MovementMode",
     "ParsedAutotileGroup",
     "ParsedAutotileRule",
     "ParsedLayer",
@@ -48,14 +82,24 @@ __all__ = [
     "ParsedProjectState",
     "ParsedTile",
     "ParsedTileset",
+    "RectangleShape",
     "SpriteAnimationSet",
+    "TileCollisionData",
     "TileLayerRenderer",
+    "TilesetCollision",
     "TilemapData",
+    "clear_collision_cache",
+    "get_cached_character_collision",
+    "get_cached_tileset_collision",
+    "load_character_collision",
     "load_map",
+    "load_tileset_collision",
     "parse_animation_dict",
     "parse_animation_file",
     "parse_animation_json",
+    "parse_character_collision",
     "parse_map_dict",
     "parse_map_file",
     "parse_map_json",
+    "parse_tileset_collision",
 ]

tilemap_parser-1.1.1/src/tilemap_parser/collision.py

@@ -0,0 +1,344 @@
+"""
+Collision data parser and runtime utilities for tilemap collision systems.
+
+This module provides parsers for both tileset collision (polygon-based) and
+character collision (geometric shapes) data generated by the tilemap editor.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+JsonDict = Dict[str, Any]
+Point = Tuple[float, float]
+IntPoint = Tuple[int, int]
+
+
+class CollisionParseError(ValueError):
+    """Raised when collision data cannot be parsed"""
+    pass
+
+
+@dataclass
+class CollisionPolygon:
+    """Polygon collision shape for a tile"""
+
+    vertices: List[Point]
+    one_way: bool = False
+
+    def transform(self, tile_x: float, tile_y: float) -> "CollisionPolygon":
+        """Transform polygon to world space coordinates"""
+        world_vertices = [(tile_x + vx, tile_y + vy) for vx, vy in self.vertices]
+        return CollisionPolygon(vertices=world_vertices, one_way=self.one_way)
+
+    def is_valid(self) -> bool:
+        """Check if polygon has at least 3 vertices"""
+        return len(self.vertices) >= 3
+
+
+@dataclass
+class TileCollisionData:
+    """Collision data for a single tile"""
+
+    tile_id: int
+    shapes: List[CollisionPolygon] = field(default_factory=list)
+
+    def has_collision(self) -> bool:
+        """Check if tile has any valid collision shapes"""
+        return any(shape.is_valid() for shape in self.shapes)
+
+
+@dataclass
+class TilesetCollision:
+    """Complete collision data for a tileset"""
+
+    tileset_name: str
+    tile_size: IntPoint
+    tiles: Dict[int, TileCollisionData] = field(default_factory=dict)
+
+    def get_tile_collision(self, tile_id: int) -> Optional[TileCollisionData]:
+        """Get collision data for a specific tile"""
+        return self.tiles.get(tile_id)
+
+    def has_collision(self, tile_id: int) -> bool:
+        """Check if tile has collision data"""
+        tile_data = self.get_tile_collision(tile_id)
+        return tile_data is not None and tile_data.has_collision()
+
+    def get_world_shapes(
+        self, tile_id: int, tile_x: float, tile_y: float
+    ) -> List[CollisionPolygon]:
+        """Get collision shapes transformed to world space"""
+        tile_data = self.get_tile_collision(tile_id)
+        if not tile_data:
+            return []
+        return [shape.transform(tile_x, tile_y) for shape in tile_data.shapes]
+
+
+@dataclass
+class RectangleShape:
+    """Rectangle collision shape"""
+
+    width: float
+    height: float
+    offset: Point = (0.0, 0.0)
+
+    def get_bounds(self, x: float, y: float) -> Tuple[float, float, float, float]:
+        """Get AABB bounds in world space (left, top, right, bottom)"""
+        left = x + self.offset[0]
+        top = y + self.offset[1]
+        return (left, top, left + self.width, top + self.height)
+
+
+@dataclass
+class CircleShape:
+    """Circle collision shape"""
+
+    radius: float
+    offset: Point = (0.0, 0.0)
+
+    def get_center(self, x: float, y: float) -> Point:
+        """Get center position in world space"""
+        return (x + self.offset[0], y + self.offset[1])
+
+
+@dataclass
+class CapsuleShape:
+    """Capsule collision shape (vertical orientation)"""
+
+    radius: float
+    height: float
+    offset: Point = (0.0, 0.0)
+
+    def get_top_center(self, x: float, y: float) -> Point:
+        """Get top circle center in world space"""
+        return (x + self.offset[0], y + self.offset[1])
+
+    def get_bottom_center(self, x: float, y: float) -> Point:
+        """Get bottom circle center in world space"""
+        return (x + self.offset[0], y + self.offset[1] + self.height)
+
+
+CharacterShapeType = Union[RectangleShape, CircleShape, CapsuleShape]
+
+
+@dataclass
+class CharacterCollision:
+    """Complete collision data for a character sprite"""
+
+    name: str
+    shape: CharacterShapeType
+    properties: Dict[str, Any] = field(default_factory=dict)
+
+
+def parse_tileset_collision(data: JsonDict) -> TilesetCollision:
+    """
+    Parse tileset collision data from dictionary.
+
+    Args:
+        data: Dictionary loaded from .collision.json file
+
+    Returns:
+        TilesetCollision object
+
+    Raises:
+        CollisionParseError: If data format is invalid
+    """
+    try:
+        tileset_name = data["tileset_name"]
+        tile_size_raw = data["tile_size"]
+        tile_size = (int(tile_size_raw[0]), int(tile_size_raw[1]))
+
+        tiles: Dict[int, TileCollisionData] = {}
+        tiles_data = data.get("tiles", {})
+
+        for tile_id_str, tile_data in tiles_data.items():
+            tile_id = int(tile_id_str)
+            shapes: List[CollisionPolygon] = []
+
+            for shape_data in tile_data.get("shapes", []):
+                vertices = [tuple(v) for v in shape_data["vertices"]]
+                one_way = shape_data.get("one_way", False)
+                shapes.append(CollisionPolygon(vertices=vertices, one_way=one_way))
+
+            tiles[tile_id] = TileCollisionData(tile_id=tile_id, shapes=shapes)
+
+        return TilesetCollision(
+            tileset_name=tileset_name, tile_size=tile_size, tiles=tiles
+        )
+    except (KeyError, ValueError, TypeError) as e:
+        raise CollisionParseError(f"Invalid tileset collision data: {e}") from e
+
+
+def parse_character_collision(data: JsonDict) -> CharacterCollision:
+    """
+    Parse character collision data from dictionary.
+
+    Args:
+        data: Dictionary loaded from .collision.json file
+
+    Returns:
+        CharacterCollision object
+
+    Raises:
+        CollisionParseError: If data format is invalid
+    """
+    try:
+        name = data["name"]
+        shape_data = data["shape"]
+        shape_type = shape_data["type"]
+        offset = tuple(shape_data.get("offset", (0.0, 0.0)))
+
+        if shape_type == "rectangle":
+            shape = RectangleShape(
+                width=float(shape_data["width"]),
+                height=float(shape_data["height"]),
+                offset=offset,
+            )
+        elif shape_type == "circle":
+            shape = CircleShape(radius=float(shape_data["radius"]), offset=offset)
+        elif shape_type == "capsule":
+            shape = CapsuleShape(
+                radius=float(shape_data["radius"]),
+                height=float(shape_data["height"]),
+                offset=offset,
+            )
+        else:
+            raise CollisionParseError(f"Unknown shape type: {shape_type}")
+
+        properties = data.get("properties", {})
+
+        return CharacterCollision(name=name, shape=shape, properties=properties)
+    except (KeyError, ValueError, TypeError) as e:
+        raise CollisionParseError(f"Invalid character collision data: {e}") from e
+
+
+def load_tileset_collision(
+    tileset_path: Union[str, Path],
+) -> Optional[TilesetCollision]:
+    """
+    Load tileset collision data from file.
+
+    Args:
+        tileset_path: Path to tileset image file
+
+    Returns:
+        TilesetCollision object or None if collision file doesn't exist
+
+    Raises:
+        CollisionParseError: If collision file exists but is invalid
+    """
+    tileset_path = Path(tileset_path)
+    collision_path = tileset_path.with_suffix(".collision.json")
+
+    if not collision_path.exists():
+        return None
+
+    try:
+        with open(collision_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return parse_tileset_collision(data)
+    except (OSError, json.JSONDecodeError) as e:
+        raise CollisionParseError(f"Cannot load {collision_path}: {e}") from e
+
+
+def load_character_collision(
+    sprite_path: Union[str, Path],
+) -> Optional[CharacterCollision]:
+    """
+    Load character collision data from file.
+
+    Args:
+        sprite_path: Path to character sprite image file
+
+    Returns:
+        CharacterCollision object or None if collision file doesn't exist
+
+    Raises:
+        CollisionParseError: If collision file exists but is invalid
+    """
+    sprite_path = Path(sprite_path)
+    collision_path = sprite_path.with_suffix(".collision.json")
+
+    if not collision_path.exists():
+        return None
+
+    try:
+        with open(collision_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return parse_character_collision(data)
+    except (OSError, json.JSONDecodeError) as e:
+        raise CollisionParseError(f"Cannot load {collision_path}: {e}") from e
+
+
+class CollisionCache:
+    """
+    Optimized collision data cache with fast lookups.
+
+    Caches parsed collision data to avoid repeated file I/O and parsing.
+    Useful for runtime performance in game engines.
+    """
+
+    def __init__(self):
+        self._tileset_cache: Dict[str, Optional[TilesetCollision]] = {}
+        self._character_cache: Dict[str, Optional[CharacterCollision]] = {}
+
+    def get_tileset_collision(
+        self, tileset_path: Union[str, Path]
+    ) -> Optional[TilesetCollision]:
+        """Get tileset collision data (cached)"""
+        key = str(Path(tileset_path).resolve())
+
+        if key not in self._tileset_cache:
+            self._tileset_cache[key] = load_tileset_collision(tileset_path)
+
+        return self._tileset_cache[key]
+
+    def get_character_collision(
+        self, sprite_path: Union[str, Path]
+    ) -> Optional[CharacterCollision]:
+        """Get character collision data (cached)"""
+        key = str(Path(sprite_path).resolve())
+
+        if key not in self._character_cache:
+            self._character_cache[key] = load_character_collision(sprite_path)
+
+        return self._character_cache[key]
+
+    def clear(self):
+        """Clear all cached collision data"""
+        self._tileset_cache.clear()
+        self._character_cache.clear()
+
+    def preload_tileset(self, tileset_path: Union[str, Path]):
+        """Preload tileset collision data into cache"""
+        self.get_tileset_collision(tileset_path)
+
+    def preload_character(self, sprite_path: Union[str, Path]):
+        """Preload character collision data into cache"""
+        self.get_character_collision(sprite_path)
+
+
+_global_cache = CollisionCache()
+
+
+def get_cached_tileset_collision(
+    tileset_path: Union[str, Path],
+) -> Optional[TilesetCollision]:
+    """Get tileset collision using global cache"""
+    return _global_cache.get_tileset_collision(tileset_path)
+
+
+def get_cached_character_collision(
+    sprite_path: Union[str, Path],
+) -> Optional[CharacterCollision]:
+    """Get character collision using global cache"""
+    return _global_cache.get_character_collision(sprite_path)
+
+
+def clear_collision_cache():
+    """Clear global collision cache"""
+    _global_cache.clear()