tilemap-parser 5.1.0__tar.gz → 5.2.0__tar.gz

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 5.1.0
+Version: 5.2.0
 Summary: Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime.
 Author: tilemap parser contributors
 License:                     GNU GENERAL PUBLIC LICENSE

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tilemap-parser"
-version = "5.1.0"
+version = "5.2.0"
 description = "Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime."
 readme = "pypi-readme.md"
 requires-python = ">=3.10"

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/src/tilemap_parser/__init__.py

@@ -10,6 +10,7 @@ __all__ = [
     "AnimationParseError",
     "AnimationPlayer",
     "AreaNode",
+    "BackgroundLayer",
     "CapsuleShape",
     "CharacterCollision",
     "CircleShape",
@@ -26,6 +27,7 @@ __all__ = [
     "LayerRenderStats",
     "MapParseError",
     "MovementMode",
+    "ObjectAnimation",
     "ObjectCollisionData",
     "ObjectCollisionManager",
     "ObjectCollisionRegionData",

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/src/tilemap_parser/parser/__init__.py

@@ -30,6 +30,7 @@ from .collision_loader import (
 )
 from .map_parse import (
     MapParseError,
+    ObjectAnimation,
     ParsedAutotileGroup,
     ParsedAutotileRule,
     ParsedLayer,
@@ -72,6 +73,7 @@ __all__ = [
     "CollisionParseError",
     "CollisionPolygon",
     "MapParseError",
+    "ObjectAnimation",
     "ObjectCollisionData",
     "ObjectCollisionRegionData",
     "ParsedAutotileGroup",

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/src/tilemap_parser/parser/map_parse.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import math
 import re
 import string
 from dataclasses import dataclass, field
@@ -121,6 +122,20 @@ class ParsedObjectArea:
     h: int
 
 
+@dataclass
+class ObjectAnimation:
+    frame_count: int
+    frame_duration_ms: float
+    speed: float = 1.0
+    loop: bool = True
+    animation_mode: str = "default"
+    random_phase: bool = False
+    frames: List[int] = field(default_factory=list)
+    frame_stride: int = 1
+    frame_w: Optional[int] = None
+    frame_h: Optional[int] = None
+
+
 @dataclass
 class ParsedObject:
     area: ParsedObjectArea
@@ -128,15 +143,18 @@ class ParsedObject:
     tileset_type: str
     variant: int
     properties: Optional[JsonDict] = None
+    animation: Optional[ObjectAnimation] = None
 
 
 @dataclass
 class TilesetAnimation:
     frame_count: int
     frame_duration_ms: float
-    frame_stride: int
+    frame_stride: int = 1
     loop: bool = True
     animation_mode: str = "default"
+    frame_w: Optional[int] = None
+    frame_h: Optional[int] = None
 
 
 @dataclass
@@ -166,6 +184,8 @@ class ParsedLayer:
     objects: Dict[int, ParsedObject] = field(default_factory=dict)
     next_object_id: Optional[int] = None
     ttypes: set[int] = field(default_factory=set)
+    image_path: Optional[str] = None
+    image_rect: Optional[Tuple[int, int, int, int]] = None
 
 
 @dataclass
@@ -256,6 +276,47 @@ def _parse_object_area(area_obj: JsonDict, ctx: str) -> ParsedObjectArea:
     )
 
 
+def _parse_object_animation(anim_obj: JsonDict, ctx: str) -> ObjectAnimation:
+    frame_count = _coerce_int(anim_obj.get("frame_count"), f"{ctx}.frame_count")
+    if frame_count < 1:
+        raise MapParseError(_ctx(f"{ctx}.frame_count", "must be >= 1"))
+    frame_duration_ms = _coerce_float(
+        anim_obj.get("frame_duration_ms"), f"{ctx}.frame_duration_ms"
+    )
+    if not math.isfinite(frame_duration_ms) or frame_duration_ms <= 0:
+        raise MapParseError(_ctx(f"{ctx}.frame_duration_ms", "must be > 0 and finite"))
+    frames_raw = anim_obj.get("frames")
+    frames: List[int] = []
+    if frames_raw is not None:
+        frames_list = _require_list(frames_raw, f"{ctx}.frames")
+        if len(frames_list) != frame_count:
+            raise MapParseError(
+                _ctx(
+                    f"{ctx}.frames",
+                    f"must contain exactly {frame_count} entries (got {len(frames_list)})",
+                )
+            )
+        frames = [_coerce_int(f, f"{ctx}.frames[{i}]") for i, f in enumerate(frames_list)]
+        for i, frame_idx in enumerate(frames):
+            if frame_idx < 0:
+                raise MapParseError(
+                    _ctx(f"{ctx}.frames[{i}]", f"must be non-negative (got {frame_idx})")
+                )
+    return ObjectAnimation(
+        frame_count=frame_count,
+        frame_duration_ms=frame_duration_ms,
+        speed=_coerce_float(anim_obj.get("speed", 1.0), f"{ctx}.speed"),
+        loop=_coerce_bool(anim_obj.get("loop", True), f"{ctx}.loop"),
+        animation_mode=_require_str(
+            anim_obj.get("animation_mode", "default"), f"{ctx}.animation_mode"
+        ),
+        random_phase=_coerce_bool(
+            anim_obj.get("random_phase", False), f"{ctx}.random_phase"
+        ),
+        frames=frames,
+    )
+
+
 def _parse_objects(objs_obj: JsonDict, ctx: str) -> Dict[int, ParsedObject]:
     result: Dict[int, ParsedObject] = {}
     for key, value in objs_obj.items():
@@ -269,12 +330,22 @@ def _parse_objects(objs_obj: JsonDict, ctx: str) -> Dict[int, ParsedObject]:
         )
         variant = _coerce_int(obj_dict.get("variant"), f"{ctx}.{key}.variant")
         props = _optional_dict(obj_dict.get("properties"), f"{ctx}.{key}.properties")
+        animation_raw = obj_dict.get("animation")
+        animation = (
+            _parse_object_animation(
+                _require_dict(animation_raw, f"{ctx}.{key}.animation"),
+                f"{ctx}.{key}.animation",
+            )
+            if animation_raw is not None
+            else None
+        )
         result[oid] = ParsedObject(
             area=area,
             ttype=ttype,
             tileset_type=tileset_type,
             variant=variant,
             properties=props,
+            animation=animation,
         )
     return result
 
@@ -308,6 +379,24 @@ def _parse_layer(layer_obj: JsonDict, layer_id: int, ctx: str) -> ParsedLayer:
             layer.next_object_id = _coerce_int(
                 layer_obj["next_object_id"], f"{ctx}.next_object_id"
             )
+
+    image_path_raw = layer_obj.get("image_path")
+    if image_path_raw is not None:
+        layer.image_path = _require_str(image_path_raw, f"{ctx}.image_path")
+        # Normalize background/background_layer types with images to "image" type
+        if layer.layer_type in ("background", "background_layer"):
+            layer.layer_type = "image"
+
+    image_rect_raw = layer_obj.get("image_rect")
+    if image_rect_raw is not None:
+        rect_obj = _require_dict(image_rect_raw, f"{ctx}.image_rect")
+        layer.image_rect = (
+            _coerce_int(rect_obj.get("x"), f"{ctx}.image_rect.x"),
+            _coerce_int(rect_obj.get("y"), f"{ctx}.image_rect.y"),
+            _coerce_int(rect_obj.get("w"), f"{ctx}.image_rect.w"),
+            _coerce_int(rect_obj.get("h"), f"{ctx}.image_rect.h"),
+        )
+
     return layer
 
 
@@ -380,12 +469,28 @@ def _parse_tilesets_list(tilesets_raw: List[Any], ctx: str) -> List[ParsedTilese
         animation_raw = ts_obj.get("animation")
         if animation_raw is not None:
             anim_obj = _require_dict(animation_raw, f"{ctx}[{i}].animation")
+            frame_stride_raw = anim_obj.get("frame_stride")
+            frame_stride = (
+                _coerce_int(frame_stride_raw, f"{ctx}[{i}].animation.frame_stride")
+                if frame_stride_raw is not None
+                else 1
+            )
+            frame_w_raw = anim_obj.get("frame_w")
+            frame_h_raw = anim_obj.get("frame_h")
+            frame_count = _coerce_int(anim_obj.get("frame_count"), f"{ctx}[{i}].animation.frame_count")
+            frame_duration_ms = _coerce_float(anim_obj.get("frame_duration_ms"), f"{ctx}[{i}].animation.frame_duration_ms")
+            if frame_count < 1:
+                raise MapParseError(_ctx(f"{ctx}[{i}].animation.frame_count", "must be >= 1"))
+            if not math.isfinite(frame_duration_ms) or frame_duration_ms <= 0:
+                raise MapParseError(_ctx(f"{ctx}[{i}].animation.frame_duration_ms", "must be > 0 and finite"))
             animation = TilesetAnimation(
-                frame_count=_coerce_int(anim_obj.get("frame_count"), f"{ctx}[{i}].animation.frame_count"),
-                frame_duration_ms=_coerce_float(anim_obj.get("frame_duration_ms"), f"{ctx}[{i}].animation.frame_duration_ms"),
-                frame_stride=_coerce_int(anim_obj.get("frame_stride"), f"{ctx}[{i}].animation.frame_stride"),
+                frame_count=frame_count,
+                frame_duration_ms=frame_duration_ms,
+                frame_stride=frame_stride,
                 loop=_coerce_bool(anim_obj.get("loop", True), f"{ctx}[{i}].animation.loop"),
                 animation_mode=_require_str(anim_obj.get("animation_mode", "default"), f"{ctx}[{i}].animation.animation_mode"),
+                frame_w=_coerce_int(frame_w_raw, f"{ctx}[{i}].animation.frame_w") if frame_w_raw is not None else None,
+                frame_h=_coerce_int(frame_h_raw, f"{ctx}[{i}].animation.frame_h") if frame_h_raw is not None else None,
             )
         out.append(
             ParsedTileset(

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/src/tilemap_parser/runtime/__init__.py

@@ -16,7 +16,7 @@ from .map_object import MapObject, load_map_objects
 from .movement import CollisionResult, CollisionRunner, MovementMode
 from .polygon_query import rect_vs_tilemap
 from .protocols import ICollidable, ICollidableObject, ICollidableSprite
-from .map_loader import TilemapData, load_map
+from .map_loader import BackgroundLayer, TilemapData, load_map
 from .collision import (
     CollisionHit,
     ObjectCollisionManager,
@@ -43,6 +43,7 @@ from .particles import (
 __all__ = [
     "AnimationPlayer",
     "AreaNode",
+    "BackgroundLayer",
     "Body",
     "Camera",
     "CollisionCache",

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/src/tilemap_parser/runtime/map_loader.py

@@ -4,12 +4,20 @@ import json
 import math
 from copy import deepcopy
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Dict, List, Literal, Optional, Tuple, TypedDict, Union
 
 import pygame
 from pygame import Rect, Surface
 
-from ..parser.map_parse import MapParseError, ParsedLayer, ParsedMap, ParsedObject, ParsedTile, parse_map_file
+from ..parser.map_parse import (
+    MapParseError,
+    ObjectAnimation,
+    ParsedLayer,
+    ParsedMap,
+    ParsedObject,
+    ParsedTile,
+    parse_map_file,
+)
 from ..parser.node_parse import parse_nodes_dict
 from .area_node import AreaNode
 from .particles import ParticleEmitterNode
@@ -17,6 +25,31 @@ from .particles import ParticleEmitterNode
 PathLike = Union[str, Path]
 
 
+class BackgroundLayer:
+    __slots__ = ("image_path", "image_rect", "surface")
+
+    def __init__(
+        self,
+        image_path: str,
+        image_rect: tuple[int, int, int, int] | None,
+        surface: Surface | None,
+    ) -> None:
+        self.image_path = image_path
+        self.image_rect = image_rect
+        self.surface = surface
+
+
+# Public return for get_object_animation (exposed, not internal ObjectAnimation)
+class AnimData(TypedDict, total=True):
+    frames: List[Surface]
+    properties: Dict[str, object]
+    frame_duration_ms: float
+    loop: bool
+    animation_mode: Literal["default", "random_start_times"]
+    frame_w: int
+    frame_h: int
+
+
 class TilemapData:
     def __init__(
         self,
@@ -36,6 +69,7 @@ class TilemapData:
         self.origin_offset = (0, 0)
         self.area_nodes: List[AreaNode] = []
         self.particle_emitters: List[ParticleEmitterNode] = []
+        self.background_layer: Optional[BackgroundLayer] = None
         self._tw, self._th = parsed.meta.tile_size
         self._build_path_index()
         self._normalize_tile_ttypes()
@@ -117,6 +151,35 @@ class TilemapData:
         result.particle_emitters = [
             ParticleEmitterNode(n) for n in parsed.nodes if n.node_type == "particle_emitter"
         ]
+
+        for layer in parsed.layers:
+            if layer.image_path is not None and layer.layer_type == "image":
+                bg_path = _resolve_resource_path(layer.image_path, map_dir, extra_search_base)
+                bg_surface: Optional[Surface] = None
+                if bg_path.is_file():
+                    try:
+                        bg_surface = pygame.image.load(str(bg_path))
+                        try:
+                            bg_surface = bg_surface.convert_alpha()
+                        except pygame.error:
+                            pass
+                    except pygame.error as e:
+                        msg = f"Background layer image load failed: {e}"
+                        warnings.append(msg)
+                        if not skip_missing_images:
+                            raise MapParseError(msg) from e
+                else:
+                    msg = f"Background layer image not found: {layer.image_path!r} -> {bg_path}"
+                    warnings.append(msg)
+                    if not skip_missing_images:
+                        raise MapParseError(msg)
+                result.background_layer = BackgroundLayer(
+                    image_path=layer.image_path,
+                    image_rect=layer.image_rect,
+                    surface=bg_surface,
+                )
+                break
+
         return result
 
     def _build_path_index(self) -> None:
@@ -327,9 +390,98 @@ class TilemapData:
                     "frame_stride": anim.frame_stride,
                     "loop": anim.loop,
                     "animation_mode": anim.animation_mode,
+                    "frame_w": anim.frame_w,
+                    "frame_h": anim.frame_h,
                 }
         return None
 
+    def get_object_animation(self, obj: ParsedObject, render_scale: float = 1.0) -> Optional[AnimData]:
+        """Return effective object animation as ``AnimData`` or ``None``.
+
+        When per-object ``animation`` is ``None``, falls back to the object's
+        tileset ``ParsedTileset.animation`` (shared strip). ``render_scale``
+        scales both ``frames`` and ``frame_w/h`` in the returned dict
+        (default ``1.0`` leaves at source resolution). No ``Surface`` overload -
+        single dict with ``frames`` + ``properties`` + ``loop``/``duration``/``mode``/``w/h``.
+        """
+        if not isinstance(render_scale, (int, float)) or not math.isfinite(render_scale) or render_scale <= 0:
+            raise ValueError(f"render_scale must be finite and > 0, got {render_scale!r}")
+        # effective animation (per-object or tileset fallback) - internal ObjectAnimationData
+        anim_data: Optional[ObjectAnimation] = obj.animation  # internal, keep frame_count
+        if anim_data is None:
+            t_anim = self.get_tileset_animation(obj.ttype)
+            if t_anim is None:
+                return None
+            anim_data = ObjectAnimation(
+                frame_count=t_anim["frame_count"],
+                frame_duration_ms=t_anim["frame_duration_ms"],
+                loop=t_anim.get("loop", True),
+                animation_mode=t_anim.get("animation_mode", "default"),
+                frames=[],
+                frame_stride=t_anim.get("frame_stride", 1),
+                frame_w=t_anim.get("frame_w"),
+                frame_h=t_anim.get("frame_h"),
+            )
+        if obj.ttype < 0 or obj.ttype >= len(self.surfaces):
+            return None
+        source = self.surfaces[obj.ttype]
+        if source is None:
+            return None
+        # frame dimensions - prefer animation's w/h, else area, else tile_size, scaled by render_scale
+        fw = getattr(anim_data, "frame_w", None)
+        if fw is None:
+            fw = obj.area.w if obj.area.w > 0 else self._tw
+        fh = getattr(anim_data, "frame_h", None)
+        if fh is None:
+            fh = obj.area.h if obj.area.h > 0 else self._th
+        if fw <= 0 or fh <= 0:
+            return None
+        # apply render_scale to dimensions
+        if render_scale != 1.0:
+            fw = int(fw * render_scale)
+            fh = int(fh * render_scale)
+        # cols based on original fw before scale for correct slicing
+        orig_fw = getattr(anim_data, "frame_w", None)
+        if orig_fw is None:
+            orig_fw = obj.area.w if obj.area.w > 0 else self._tw
+        if orig_fw is None or orig_fw <= 0:
+            orig_fw = fw
+        cols = max(1, source.get_width() // orig_fw) if render_scale != 1.0 else max(1, source.get_width() // fw)
+        if anim_data.frames:
+            frame_indices = anim_data.frames
+        else:
+            stride = getattr(anim_data, "frame_stride", 1)
+            if stride is None or stride <= 0:
+                stride = 1
+            if stride == 1:
+                frame_indices = list(range(anim_data.frame_count))
+            else:
+                frame_indices = [i * stride for i in range(anim_data.frame_count)]
+        frames: List[Surface] = []
+        for fi in frame_indices:
+            col = fi % cols
+            row = fi // cols
+            src_fw = getattr(anim_data, "frame_w", None) or (obj.area.w if obj.area.w > 0 else self._tw)
+            src_fh = getattr(anim_data, "frame_h", None) or (obj.area.h if obj.area.h > 0 else self._th)
+            src = Rect(col * src_fw, row * src_fh, src_fw, src_fh)
+            if not source.get_rect().contains(src):
+                surf = Surface((src_fw, src_fh), pygame.SRCALPHA)
+            else:
+                cell = source.subsurface(src)
+                surf = cell.copy()
+            if render_scale != 1.0:
+                surf = pygame.transform.scale(surf, (fw, fh))
+            frames.append(surf)
+        return {
+            "frames": frames,
+            "properties": dict(obj.properties) if obj.properties else {},
+            "frame_duration_ms": float(anim_data.frame_duration_ms),
+            "loop": bool(anim_data.loop),
+            "animation_mode": str(anim_data.animation_mode),
+            "frame_w": fw,
+            "frame_h": fh,
+        }
+
 
 def _variant_surface(
     surf: Surface,

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/src/tilemap_parser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 5.1.0
+Version: 5.2.0
 Summary: Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime.
 Author: tilemap parser contributors
 License:                     GNU GENERAL PUBLIC LICENSE

{tilemap_parser-5.1.0 → tilemap_parser-5.2.0}/src/tilemap_parser.egg-info/SOURCES.txt

@@ -49,6 +49,7 @@ src/tilemap_parser/runtime/navigation/path_follower.py
 src/tilemap_parser/runtime/navigation/pathfinder.py
 src/tilemap_parser/utils/__init__.py
 src/tilemap_parser/utils/geometry.py
+tests/test_background_layer.py
 tests/test_body.py
 tests/test_camera.py
 tests/test_collision.py
@@ -62,6 +63,7 @@ tests/test_map_loader.py
 tests/test_map_object.py
 tests/test_move_grounded.py
 tests/test_navigation.py
+tests/test_object_animation.py
 tests/test_object_collision.py
 tests/test_object_surfaces.py
 tests/test_particle_emitter.py