tilemap-parser 4.2.2__tar.gz → 4.2.4__tar.gz

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 4.2.2
+Version: 4.2.4
 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-4.2.2 → tilemap_parser-4.2.4}/pyproject.toml

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

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser/__init__.py

@@ -20,6 +20,7 @@ __all__ = [
     "CollisionPolygon",
     "CollisionResult",
     "CollisionRunner",
+    "ICollidable",
     "ICollidableObject",
     "ICollidableSprite",
     "LayerRenderStats",

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser/parser/map_parse.py

@@ -159,6 +159,8 @@ class ParsedLayer:
     locked: bool
     opacity: float
     z_index: int
+    y_sort: bool = False
+    y_sort_origin: int = 0
     properties: JsonDict = field(default_factory=dict)
     tiles: Dict[Point, ParsedTile] = field(default_factory=dict)
     objects: Dict[int, ParsedObject] = field(default_factory=dict)
@@ -285,6 +287,8 @@ def _parse_layer(layer_obj: JsonDict, layer_id: int, ctx: str) -> ParsedLayer:
         locked=_coerce_bool(layer_obj.get("locked", False), f"{ctx}.locked"),
         opacity=_coerce_float(layer_obj.get("opacity", 1.0), f"{ctx}.opacity"),
         z_index=_coerce_int(layer_obj.get("z_index", layer_id), f"{ctx}.z_index"),
+        y_sort=_coerce_bool(layer_obj.get("y_sort", False), f"{ctx}.y_sort"),
+        y_sort_origin=layer_obj.get("y_sort_origin", 0),
         properties=_optional_dict(layer_obj.get("properties"), f"{ctx}.properties")
         or {},
     )
@@ -409,6 +413,7 @@ def _expand_ongrid_to_layer(data_obj: JsonDict, ctx: str) -> List[ParsedLayer]:
         locked=False,
         opacity=1.0,
         z_index=0,
+        y_sort=False, y_sort_origin=0,
         properties={},
     )
     for loc_str, tile_data in raw_ongrid.items():

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser/parser/tmx_converter.py

@@ -268,6 +268,7 @@ def _parse_tile_layer(
         locked=False,
         opacity=opacity,
         z_index=0,
+        y_sort=False, y_sort_origin=0,
     )
 
     layer.properties = _parse_properties(layer_elem)

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser/runtime/__init__.py

@@ -18,6 +18,7 @@ from .tile_collision import (
     MovementMode,
     rect_vs_tilemap,
 )
+from .protocols import ICollidable
 from .map_loader import TilemapData, load_map
 from .object_collision import (
     CollisionHit,
@@ -45,6 +46,7 @@ __all__ = [
     "CollisionHit",
     "CollisionResult",
     "CollisionRunner",
+    "ICollidable",
     "ICollidableObject",
     "ICollidableSprite",
     "LayerRenderStats",

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser/runtime/map_object.py

@@ -56,6 +56,7 @@ class MapObject:
         "collision_shapes",
         "collision_layer",
         "collision_mask",
+        "y_sort_origin",
     )
 
     def __init__(
@@ -68,6 +69,7 @@ class MapObject:
         collision_shapes: Optional[List[CollisionPolygon]] = None,
         collision_layer: int = 1,
         collision_mask: int = 0xFFFFFFFF,
+        y_sort_origin: Optional[int] = None,
     ) -> None:
         self.x = x
         self.y = y
@@ -76,6 +78,7 @@ class MapObject:
         self.collision_shape = self.collision_shapes[0]
         self.collision_layer = collision_layer
         self.collision_mask = collision_mask
+        self.y_sort_origin = y_sort_origin
 
 
 def _resolve_object_collision_filename(tileset_path: Union[str, Path]) -> str:

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser/runtime/object_collision.py

@@ -33,27 +33,20 @@ from ..utils.geometry import (
     rect_vs_circle,
     rect_vs_rect,
 )
+from .protocols import ICollidable
 
 
-class ICollidableObject(Protocol):
+class ICollidableObject(ICollidable, Protocol):
     """
     Protocol for objects that can collide.
 
-    Required attributes:
-        x: World X position
-        y: World Y position
-        collision_shape: Shape for collision
-            (RectangleShape, CircleShape, CapsuleShape, or CollisionPolygon)
+    All required attributes (x, y, collision_shape) are inherited from ICollidable.
 
     Optional attributes (with defaults):
         collision_layer: Layer this object is on (default: 1)
         collision_mask: Layers to collide with (default: 0xFFFFFFFF)
     """
 
-    x: float
-    y: float
-    collision_shape: Union[RectangleShape, CircleShape, CapsuleShape, CollisionPolygon]
-
 
 @dataclass(slots=True)
 class CollisionHit:

tilemap_parser-4.2.4/src/tilemap_parser/runtime/protocols.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+import pygame
+from pygame import Surface
+
+from ..parser.collision import (
+    CapsuleShape,
+    CircleShape,
+    CollisionPolygon,
+    RectangleShape,
+)
+
+
+class ExtraObject(Protocol):
+    surface: Surface | None
+    x: float
+    y: float
+
+
+class ICollidable(Protocol):
+    """Base protocol for anything with a world position and collision shape.
+
+    This is the minimal interface for participating in collision detection.
+    All collidable protocols (ICollidableSprite, ICollidableObject) extend this.
+
+    Required attributes:
+        x (float): World X position
+        y (float): World Y position
+        collision_shape: Shape used for collision detection
+            (RectangleShape, CircleShape, CapsuleShape, or CollisionPolygon)
+    """
+
+    x: float
+    y: float
+    collision_shape: RectangleShape | CircleShape | CapsuleShape | CollisionPolygon

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser/runtime/renderer.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
-from typing import Dict, List, Optional, Tuple, Union
 
 import pygame
 from pygame import Rect, Surface, transform
 
 from .map_loader import TilemapData
+from .protocols import ExtraObject
 
 CHUNK_SIZE = 32
 
@@ -19,19 +20,15 @@ class LayerRenderStats:
 
 
 class TileLayerRenderer:
-    def __init__(
-        self, data: TilemapData, *, include_hidden_layers: bool = False
-    ) -> None:
+    def __init__(self, data: TilemapData, *, include_hidden_layers: bool = False) -> None:
         self.data = data
-        self.tile_layers = data.get_tile_layers_dict(
-            include_hidden=include_hidden_layers
-        )
+        self.tile_layers = data.get_tile_layers_dict(include_hidden=include_hidden_layers)
         self._sorted_layer_ids = sorted(
             self.tile_layers.keys(),
             key=lambda lid: (self.tile_layers[lid].z_index, lid),
         )
 
-        self._variant_cache: Dict[Tuple[int, int], Optional[Surface]] = {}
+        self._variant_cache: dict[tuple[int, int], Surface | None] = {}
 
         self._tile_w, self._tile_h = data.tile_size
         self._rs = data.render_scale
@@ -45,7 +42,7 @@ class TileLayerRenderer:
                 f"got tile_size=({self._tile_w}, {self._tile_h}) render_scale={self._rs}"
             )
 
-        self._tileset_animations: Dict[int, dict] = {}
+        self._tileset_animations: dict[int, dict] = {}
         for ts_idx, ts in enumerate(data.parsed.tilesets):
             if ts.animation is not None:
                 self._tileset_animations[ts_idx] = {
@@ -56,9 +53,9 @@ class TileLayerRenderer:
                     "animation_mode": ts.animation.animation_mode,
                 }
 
-        self._layer_chunks: Dict[int, Dict[Tuple[int, int], List[Tuple[int, int]]]] = {}
+        self._layer_chunks: dict[int, dict[tuple[int, int], list[tuple[int, int]]]] = {}
         for layer_id, layer in self.tile_layers.items():
-            chunks: Dict[Tuple[int, int], List[Tuple[int, int]]] = {}
+            chunks: dict[tuple[int, int], list[tuple[int, int]]] = {}
             for (x, y), tile in layer.tiles.items():
                 if not isinstance(tile.ttype, int):
                     continue
@@ -69,10 +66,10 @@ class TileLayerRenderer:
                 chunks[chunk_key].append((x, y))
             self._layer_chunks[layer_id] = chunks
 
-    def get_layer_dict(self) -> Dict[int, object]:
+    def get_layer_dict(self) -> dict[int, object]:
         return dict(self.tile_layers)
 
-    def _get_cached_variant(self, ttype: int, variant: int) -> Optional[Surface]:
+    def _get_cached_variant(self, ttype: int, variant: int) -> Surface | None:
         key = (ttype, variant)
         if key not in self._variant_cache:
             cell = self.data.get_tile_surface(ttype, variant, copy_surface=True)
@@ -121,17 +118,21 @@ class TileLayerRenderer:
     def render(
         self,
         target: Surface,
-        camera_xy: Union[Tuple[float, float], Tuple[int, int]] = (0, 0),
-        viewport_size: Optional[Tuple[int, int]] = None,
+        camera_xy: tuple[float, float] | tuple[int, int] = (0, 0),
+        viewport_size: tuple[int, int] | None = None,
         *,
-        current_time_ms: Optional[float] = None,
+        extra_objects: Sequence[ExtraObject] | None = None,
+        current_time_ms: float | None = None,
     ) -> LayerRenderStats:
-        """Render visible tile layers.
+        """Render visible tile layers, optionally merged with extra objects.
+
+        When *extra_objects* is provided, each item must have ``surface``,
+        ``x``, and ``y`` attributes (duck-typed). Extras are blitted after
+        all tile layers, preserving caller order.
 
-        Note: ``skipped_tiles`` is a debugging indicator, not a whole-map
-        accumulated count. It tracks null surfaces and invalid tiles within
-        the active chunk range — enough to spot rendering issues without
-        the cost of a full scan.
+        Tiles are blitted per layer in natural chunk order.  When
+        ``layer.y_sort`` is enabled, tiles within each chunk are sorted by
+        their tile-space Y coordinate before blitting.
         """
         cam_x, cam_y = float(camera_xy[0]), float(camera_xy[1])
         if viewport_size is None:
@@ -171,11 +172,14 @@ class TileLayerRenderer:
                     if not chunk:
                         continue
 
-                    for x, y in chunk:
+                    tile_iter = chunk
+                    if layer.y_sort:
+                        origin = layer.y_sort_origin
+                        tile_iter = sorted(chunk, key=lambda p: p[1] * self._eff_h + origin)
+
+                    for x, y in tile_iter:
                         tile = layer.tiles[(x, y)]
-                        display_variant = self._compute_display_variant(
-                            tile.variant, tile.ttype, x, y, time_ms
-                        )
+                        display_variant = self._compute_display_variant(tile.variant, tile.ttype, x, y, time_ms)
                         cell = self._get_cached_variant(tile.ttype, display_variant)
                         if cell is None:
                             skipped += 1
@@ -187,6 +191,15 @@ class TileLayerRenderer:
                         )
                         drawn += 1
 
-        return LayerRenderStats(
-            drawn_tiles=drawn, skipped_tiles=skipped, visible_layers=visible_layers
-        )
+        if extra_objects:
+            for obj in extra_objects:
+                surf = obj.surface
+                if surf is None:
+                    continue
+                target.blit(surf, (obj.x - cam_x, obj.y - cam_y))
+
+        return LayerRenderStats(drawn_tiles=drawn, skipped_tiles=skipped, visible_layers=visible_layers)
+
+    @property
+    def sorted_layer_ids(self) -> list[int]:
+        return list(self._sorted_layer_ids)

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser/runtime/tile_collision.py

@@ -23,12 +23,13 @@ from ..parser.collision import (
     RectangleShape,
     TilesetCollision,
 )
+from .protocols import ICollidable
 
 Point = Tuple[float, float]
 Vector2 = Tuple[float, float]
 
 
-class ICollidableSprite(Protocol):
+class ICollidableSprite(ICollidable, Protocol):
     """
     Interface that any sprite/character class must implement to use collision runners.
 
@@ -303,7 +304,7 @@ def _circle_polygon_collision_offset(
     return False
 
 
-def get_shape_bounds(sprite: ICollidableSprite) -> Tuple[float, float, float, float]:
+def get_shape_bounds(sprite: ICollidable) -> Tuple[float, float, float, float]:
     """Get AABB bounds for sprite (left, top, right, bottom)"""
     shape = sprite.collision_shape
     if isinstance(shape, RectangleShape):
@@ -328,7 +329,7 @@ def get_shape_bounds(sprite: ICollidableSprite) -> Tuple[float, float, float, fl
 
 
 def check_sprite_polygon_collision(
-    sprite: ICollidableSprite, polygon: CollisionPolygon
+    sprite: ICollidable, polygon: CollisionPolygon
 ) -> bool:
     """Check if sprite collides with a world-space polygon (legacy / public API)."""
     shape = sprite.collision_shape
@@ -349,7 +350,7 @@ def check_sprite_polygon_collision(
 
 
 def _check_sprite_polygon_offset(
-    sprite: ICollidableSprite,
+    sprite: ICollidable,
     polygon: CollisionPolygon,
     ox: float,
     oy: float,
@@ -489,7 +490,7 @@ class CollisionRunner:
         self,
         tileset_collision: TilesetCollision,
         tile_map: dict,
-        sprite: ICollidableSprite,
+        sprite: ICollidable,
         margin: int = 1,
     ) -> List[CollisionPolygon]:
         """
@@ -529,7 +530,7 @@ class CollisionRunner:
 
     def _collides_at(
         self,
-        sprite: ICollidableSprite,
+        sprite: ICollidable,
         tileset_collision: TilesetCollision,
         tile_map: dict,
         margin: int = 1,
@@ -567,7 +568,7 @@ class CollisionRunner:
 
     def _first_colliding_shape(
         self,
-        sprite: ICollidableSprite,
+        sprite: ICollidable,
         tileset_collision: TilesetCollision,
         tile_map: dict,
         margin: int = 1,
@@ -603,7 +604,7 @@ class CollisionRunner:
 
     def move_and_slide(
         self,
-        sprite: ICollidableSprite,
+        sprite: ICollidable,
         tileset_collision: TilesetCollision,
         tile_map: dict,
         delta_x: float,
@@ -729,7 +730,7 @@ class CollisionRunner:
 
     def _get_collision_normal_from_motion(
         self,
-        sprite: ICollidableSprite,
+        sprite: ICollidable,
         polygon: CollisionPolygon,
         ox: float,
         oy: float,
@@ -1745,7 +1746,7 @@ class CollisionRunner:
 
     def move_rpg(
         self,
-        sprite: ICollidableSprite,
+        sprite: ICollidable,
         tileset_collision: TilesetCollision,
         tile_map: dict,
         delta_x: float,
@@ -1814,7 +1815,7 @@ class CollisionRunner:
 
     def move(
         self,
-        sprite: ICollidableSprite,
+        sprite: ICollidable,
         tileset_collision: TilesetCollision,
         tile_map: dict,
         delta_x: float = 0.0,

{tilemap_parser-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 4.2.2
+Version: 4.2.4
 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-4.2.2 → tilemap_parser-4.2.4}/src/tilemap_parser.egg-info/SOURCES.txt

@@ -24,6 +24,7 @@ src/tilemap_parser/runtime/map_loader.py
 src/tilemap_parser/runtime/map_object.py
 src/tilemap_parser/runtime/object_collision.py
 src/tilemap_parser/runtime/particles.py
+src/tilemap_parser/runtime/protocols.py
 src/tilemap_parser/runtime/renderer.py
 src/tilemap_parser/runtime/tile_collision.py
 src/tilemap_parser/utils/__init__.py
@@ -43,4 +44,5 @@ tests/test_object_surfaces.py
 tests/test_particle_emitter.py
 tests/test_render_scale.py
 tests/test_tile_collision.py
+tests/test_tile_layer_renderer_y_sort.py
 tests/test_tmx_converter.py

tilemap_parser-4.2.4/tests/test_tile_layer_renderer_y_sort.py

@@ -0,0 +1,348 @@
+"""
+Tests for TileLayerRenderer y-sort and extra_objects.
+
+Covers:
+- y_sort read from parsed layer data
+- y-major iteration when layer.y_sort=True
+- extra_objects merged and sorted by (z_index, y)
+- Duck-typed extra objects (surface, x, y only)
+- Smoke test: render with extra_objects does not crash, stats correct
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+import pygame
+import pytest
+from pygame import Surface
+
+from tilemap_parser.parser.map_parse import (
+    ParsedLayer,
+    ParsedMeta,
+    ParsedMap,
+    _parse_layer,
+)
+from tilemap_parser.runtime.map_loader import TilemapData
+from tilemap_parser.runtime.renderer import TileLayerRenderer
+
+
+# ---------------------------------------------------------------------------
+# ParsedLayer y_sort field
+# ---------------------------------------------------------------------------
+
+
+class TestParsedLayerYSort:
+    def test_default_is_false(self):
+        """y_sort defaults to False when not present in data."""
+        d = {
+            "name": "test",
+            "type": "tile",
+            "visible": True,
+            "locked": False,
+            "opacity": 1.0,
+            "z_index": 0,
+        }
+        layer = _parse_layer(d, 0, "test")
+        assert layer.y_sort is False
+
+    def test_reads_true(self):
+        d = {
+            "name": "test",
+            "type": "tile",
+            "visible": True,
+            "locked": False,
+            "opacity": 1.0,
+            "z_index": 0,
+            "y_sort": True,
+        }
+        layer = _parse_layer(d, 0, "test")
+        assert layer.y_sort is True
+
+    def test_reads_false_explicit(self):
+        d = {
+            "name": "test",
+            "type": "tile",
+            "visible": True,
+            "locked": False,
+            "opacity": 1.0,
+            "z_index": 0,
+            "y_sort": False,
+        }
+        layer = _parse_layer(d, 0, "test")
+        assert layer.y_sort is False
+
+    def test_y_sort_origin_defaults_to_zero(self):
+        d = {"name": "test", "type": "tile", "visible": True, "locked": False, "opacity": 1.0, "z_index": 0}
+        layer = _parse_layer(d, 0, "test")
+        assert layer.y_sort_origin == 0
+
+    def test_y_sort_origin_reads_from_json(self):
+        d = {"name": "test", "type": "tile", "visible": True, "locked": False, "opacity": 1.0, "z_index": 0, "y_sort_origin": 16}
+        layer = _parse_layer(d, 0, "test")
+        assert layer.y_sort_origin == 16
+
+
+# ---------------------------------------------------------------------------
+# Helpers — minimal map for renderer tests
+# ---------------------------------------------------------------------------
+
+
+def _dummy_tileset_surface(w=16, h=16) -> Surface:
+    """Create a solid-colour surface to serve as a tileset cell."""
+    surf = Surface((w, h))
+    surf.fill((200, 100, 50))
+    return surf
+
+
+class DummyVisual:
+    """Minimal duck-typed visual — surface, x, y, optional z_index."""
+
+    __slots__ = ("surface", "x", "y", "z_index")
+
+    def __init__(self, surface, x, y, z_index=0):
+        self.surface = surface
+        self.x = x
+        self.y = y
+        self.z_index = z_index
+
+    def __repr__(self):
+        return f"DummyVisual(x={self.x}, y={self.y}, z={self.z_index})"
+
+
+def _make_tile(pos, ttype=0, variant=0):
+    from tilemap_parser.parser.map_parse import ParsedTile
+
+    return ParsedTile(pos=pos, ttype=ttype, variant=variant, gid=None, properties=None)
+
+
+def _make_map_data(layers, tile_size=(16, 16)) -> TilemapData:
+    """Build a TilemapData from a list of ParsedLayer objects."""
+    from pathlib import Path
+    from tilemap_parser.parser.map_parse import ParsedTileset
+
+    meta = ParsedMeta(
+        tile_size=tile_size,
+        map_size=(10, 10),
+        initial_map_size=(10, 10),
+        zoom_level=1.0,
+        scroll=(0, 0),
+        version="1.1",
+        render_scale=1.0,
+    )
+    mock_map = object.__new__(ParsedMap)
+    mock_map.meta = meta
+    mock_map.layers = layers
+    mock_map.tilesets = [ParsedTileset(path="dummy.png", type="tile")]
+    tw, th = tile_size
+    resolved_paths = [Path("dummy.png")]
+    return TilemapData(mock_map, [_dummy_tileset_surface(tw, th)], resolved_paths, [])
+
+
+# ---------------------------------------------------------------------------
+# TileLayerRenderer — extra_objects
+# ---------------------------------------------------------------------------
+
+
+class TestExtraObjects:
+    def make_map_data(self) -> TilemapData:
+        """Minimal 1-layer map with a single tile at (0,0)."""
+        layer = ParsedLayer(
+            id=0,
+            name="Ground",
+            layer_type="tile",
+            visible=True,
+            locked=False,
+            opacity=1.0,
+            z_index=0,
+        )
+        layer.tiles[(0, 0)] = _make_tile((0, 0))
+        return _make_map_data([layer])
+
+    def test_extra_objects_smoke(self):
+        """Render with extra_objects does not crash."""
+        data = self.make_map_data()
+        renderer = TileLayerRenderer(data)
+        target = Surface((100, 100))
+        objs = [DummyVisual(_dummy_tileset_surface(), 10, 20)]
+        stats = renderer.render(target, (0, 0), extra_objects=objs)
+        assert stats.drawn_tiles == 1
+        assert stats.visible_layers == 1
+
+    def test_extra_objects_merged_into_drawn_count(self):
+        """drawn_tiles only counts tiles, not extras (unchanged stat)."""
+        data = self.make_map_data()
+        renderer = TileLayerRenderer(data)
+        target = Surface((100, 100))
+        objs = [DummyVisual(_dummy_tileset_surface(), 10, 20)]
+        stats = renderer.render(target, (0, 0), extra_objects=objs)
+        assert stats.drawn_tiles == 1  # extras not counted here
+
+    def test_multiple_extra_objects(self):
+        """Multiple extra objects all blit without error."""
+        data = self.make_map_data()
+        renderer = TileLayerRenderer(data)
+        target = Surface((200, 200))
+        objs = [
+            DummyVisual(_dummy_tileset_surface(), 10, 20, z_index=0),
+            DummyVisual(_dummy_tileset_surface(), 30, 40, z_index=1),
+            DummyVisual(_dummy_tileset_surface(), 50, 60, z_index=0),
+        ]
+        renderer.render(target, (0, 0), extra_objects=objs)
+        # no crash is the assertion
+
+    def test_duck_typed_minimal(self):
+        """Object with only surface/x/y works (no z_index)."""
+        data = self.make_map_data()
+        renderer = TileLayerRenderer(data)
+        target = Surface((100, 100))
+
+        class MinimalVisual:
+            def __init__(self):
+                self.surface = _dummy_tileset_surface()
+                self.x = 5
+                self.y = 15
+
+        renderer.render(target, (0, 0), extra_objects=[MinimalVisual()])
+
+    def test_extra_object_with_none_surface_skipped(self):
+        """Objects with surface=None are silently skipped."""
+        data = self.make_map_data()
+        renderer = TileLayerRenderer(data)
+        target = Surface((100, 100))
+
+        class NoneSurfaceVisual:
+            def __init__(self):
+                self.surface = None
+                self.x = 0
+                self.y = 0
+
+        renderer.render(target, (0, 0), extra_objects=[NoneSurfaceVisual()])
+
+    def test_render_without_extra_objects_still_works(self):
+        """Calling render() without extra_objects is unchanged."""
+        data = self.make_map_data()
+        renderer = TileLayerRenderer(data)
+        target = Surface((100, 100))
+        stats = renderer.render(target, (0, 0))
+        assert stats.drawn_tiles == 1
+        assert stats.visible_layers == 1
+
+
+# ---------------------------------------------------------------------------
+# TileLayerRenderer — y_sort iteration
+# ---------------------------------------------------------------------------
+
+
+class _SpySurface(pygame.Surface):
+    """Records (dest_x, dest_y) for each blit call."""
+
+    def __init__(self, size):
+        super().__init__(size)
+        self.blit_calls: list[tuple[float, float]] = []
+
+    def blit(self, source, dest, *args, **kwargs):
+        if isinstance(dest, tuple):
+            self.blit_calls.append((float(dest[0]), float(dest[1])))
+        else:
+            self.blit_calls.append((float(dest.x), float(dest.y)))
+        return super().blit(source, dest, *args, **kwargs)
+
+
+class TestLayerYSort:
+    """Verify that y_sort changes iteration order within a chunk."""
+
+    def make_map_data_two_tiles(self, y_sort: bool = True) -> TilemapData:
+        """One layer with two tiles at different Y positions."""
+        layer = ParsedLayer(
+            id=0,
+            name="Bushes",
+            layer_type="tile",
+            visible=True,
+            locked=False,
+            opacity=1.0,
+            z_index=0,
+            y_sort=y_sort,
+        )
+        layer.tiles[(0, 0)] = _make_tile((0, 0))
+        layer.tiles[(0, 5)] = _make_tile((0, 5))
+        return _make_map_data([layer])
+
+    def test_y_sort_layer_does_not_crash(self):
+        """Layer with y_sort=True renders without error."""
+        data = self.make_map_data_two_tiles()
+        renderer = TileLayerRenderer(data)
+        target = Surface((200, 200))
+        stats = renderer.render(target, (0, 0))
+        assert stats.drawn_tiles == 2
+
+    def test_y_major_order(self):
+        """y-sort within a chunk produces y-major iteration."""
+        data = self.make_map_data_two_tiles(y_sort=True)
+        renderer = TileLayerRenderer(data)
+        target = _SpySurface((200, 200))
+        renderer.render(target, (0, 0))
+        ys = [y for _, y in target.blit_calls]
+        assert ys == sorted(ys)
+
+    def test_no_ysort_preserves_input_order(self):
+        """Without y-sort the chunk iteration is insertion order."""
+        data = self.make_map_data_two_tiles(y_sort=False)
+        renderer = TileLayerRenderer(data)
+        target = _SpySurface((200, 200))
+        renderer.render(target, (0, 0))
+        ef = 16
+        assert target.blit_calls == [(0.0, 0.0), (0.0, 5.0 * ef)]
+
+    def test_y_sort_origin_shifts_sort_order(self):
+        """y_sort_origin offsets the Y used for sorting."""
+        layer = ParsedLayer(
+            id=0, name="test", layer_type="tile", visible=True,
+            locked=False, opacity=1.0, z_index=0,
+            y_sort=True, y_sort_origin=32,
+        )
+        layer.tiles[(0, 0)] = _make_tile((0, 0))
+        layer.tiles[(0, 1)] = _make_tile((0, 1))
+        data = _make_map_data([layer])
+        renderer = TileLayerRenderer(data)
+        target = _SpySurface((200, 200))
+        renderer.render(target, (0, 0))
+        ef = 16
+        assert target.blit_calls == [(0.0, 0.0), (0.0, 1.0 * ef)]
+
+
+# ---------------------------------------------------------------------------
+# Integration — combined y_sort + extra_objects
+# ---------------------------------------------------------------------------
+
+
+class TestIntegration:
+    def test_y_sort_with_extra_objects(self):
+        """y_sort layer renders tiles first, then extras in caller order."""
+        layer = ParsedLayer(
+            id=0,
+            name="Bushes",
+            layer_type="tile",
+            visible=True,
+            locked=False,
+            opacity=1.0,
+            z_index=0,
+            y_sort=True,
+        )
+        layer.tiles[(0, 0)] = _make_tile((0, 0))
+        layer.tiles[(0, 5)] = _make_tile((0, 5))
+        data = _make_map_data([layer])
+        renderer = TileLayerRenderer(data)
+        target = _SpySurface((200, 200))
+        ef = 16
+        objs = [
+            DummyVisual(_dummy_tileset_surface(), 5, 25),
+            DummyVisual(_dummy_tileset_surface(), 5, 3),
+        ]
+        renderer.render(target, (0, 0), extra_objects=objs)
+        assert len(target.blit_calls) == 4
+        assert target.blit_calls[0] == (0.0, 0.0)  # tile y=0
+        assert target.blit_calls[1] == (0.0, 5.0 * ef)  # tile y=5
+        assert target.blit_calls[2] == (5.0, 25.0)  # extra in caller order
+        assert target.blit_calls[3] == (5.0, 3.0)  # extra in caller order