tilemap-parser 4.2.3__tar.gz → 4.2.5__tar.gz

{tilemap_parser-4.2.3 → tilemap_parser-4.2.5}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tilemap-parser"
-version = "4.2.3"
+version = "4.2.5"
 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.3 → tilemap_parser-4.2.5}/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.3 → tilemap_parser-4.2.5}/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.3 → tilemap_parser-4.2.5}/src/tilemap_parser/runtime/area_node.py

@@ -8,11 +8,18 @@ from ..parser.node_parse import ParsedNode
 
 
 class AreaNode:
-    def __init__(self, parsed: ParsedNode) -> None:
+    def __init__(self, parsed: ParsedNode, render_scale: float = 1.0) -> None:
         self.node_id = parsed.node_id
         self.name = parsed.name
         self.node_type = parsed.node_type
-        self._rect = Rect(parsed.area.x, parsed.area.y, parsed.area.w, parsed.area.h)
+        self.render_scale = render_scale
+        rs = render_scale
+        self._rect = Rect(
+            int(parsed.area.x * rs),
+            int(parsed.area.y * rs),
+            int(parsed.area.w * rs),
+            int(parsed.area.h * rs),
+        )
         self.layer_name = parsed.layer_name
         self.properties = dict(parsed.properties)
         self.group = parsed.group

{tilemap_parser-4.2.3 → tilemap_parser-4.2.5}/src/tilemap_parser/runtime/map_loader.py

@@ -109,7 +109,11 @@ class TilemapData:
         origin_offset = _normalize_origin(parsed)
         result = cls(parsed, surfaces, resolved_paths, warnings, map_path=p)
         result.origin_offset = origin_offset
-        result.area_nodes = [AreaNode(n) for n in parsed.nodes if n.node_type == "area"]
+        result.area_nodes = [
+            AreaNode(n, render_scale=result.render_scale)
+            for n in parsed.nodes
+            if n.node_type == "area"
+        ]
         result.particle_emitters = [
             ParticleEmitterNode(n) for n in parsed.nodes if n.node_type == "particle_emitter"
         ]
@@ -275,8 +279,8 @@ class TilemapData:
         return self.get_tile_surface(tile.ttype, tile.variant)
 
     def get_object_surface_by_id(
-        self, layer_id_or_name: Union[int, str], object_id: int, *, copy_surface: bool = True
-    ) -> Optional[Tuple[Surface, int, int]]:
+        self, layer_id_or_name: Union[int, str], object_id: int, *, copy_surface: bool = True, scaled: bool = False
+    ) -> Optional[Tuple[Surface, float, float]]:
         layer = self.get_layer(layer_id_or_name)
         if layer is None or layer.layer_type != "object":
             return None
@@ -286,19 +290,31 @@ class TilemapData:
         surf = self.get_object_surface(obj, copy_surface=copy_surface)
         if surf is None:
             return None
-        return surf, obj.area.x, obj.area.y
+        rs = self.render_scale if scaled else 1.0
+        x = obj.area.x * rs
+        y = obj.area.y * rs
+        if scaled and rs != 1.0:
+            w, h = surf.get_size()
+            surf = pygame.transform.scale(surf, (int(w * rs), int(h * rs)))
+        return surf, x, y
 
     def get_object_surfaces(
-        self, layer_id_or_name: Union[int, str], *, copy_surface: bool = True
-    ) -> List[Tuple[Surface, int, int, int]]:
+        self, layer_id_or_name: Union[int, str], *, copy_surface: bool = True, scaled: bool = False
+    ) -> List[Tuple[Surface, float, float, int]]:
         layer = self.get_layer(layer_id_or_name)
         if layer is None or layer.layer_type != "object":
             return []
-        result: List[Tuple[Surface, int, int, int]] = []
+        result: List[Tuple[Surface, float, float, int]] = []
+        rs = self.render_scale if scaled else 1.0
         for oid, obj in layer.objects.items():
             surf = self.get_object_surface(obj, copy_surface=copy_surface)
             if surf is not None:
-                result.append((surf, obj.area.x, obj.area.y, oid))
+                x = obj.area.x * rs
+                y = obj.area.y * rs
+                if scaled and rs != 1.0:
+                    w, h = surf.get_size()
+                    surf = pygame.transform.scale(surf, (int(w * rs), int(h * rs)))
+                result.append((surf, x, y, oid))
         return result
 
     def get_tileset_animation(self, ttype: int) -> Optional[dict]:

{tilemap_parser-4.2.3 → tilemap_parser-4.2.5}/src/tilemap_parser/runtime/map_object.py

@@ -56,26 +56,40 @@ class MapObject:
         "collision_shapes",
         "collision_layer",
         "collision_mask",
+        "y_sort_origin",
     )
 
     def __init__(
         self,
         x: float,
         y: float,
-        surface: Surface,
-        collision_shape: CollisionPolygon,
+        surface: Optional[Surface] = None,
+        collision_shape: Optional[CollisionPolygon] = None,
         *,
         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
         self.surface = surface
-        self.collision_shapes = collision_shapes or [collision_shape]
-        self.collision_shape = self.collision_shapes[0]
+        if collision_shapes is not None:
+            self.collision_shapes = collision_shapes
+            self.collision_shape = collision_shapes[0] if collision_shapes else None
+        elif collision_shape is not None:
+            self.collision_shapes = [collision_shape]
+            self.collision_shape = collision_shape
+        else:
+            self.collision_shapes = []
+            self.collision_shape = None
         self.collision_layer = collision_layer
         self.collision_mask = collision_mask
+        self.y_sort_origin = y_sort_origin
+
+    @property
+    def has_collision(self) -> bool:
+        return len(self.collision_shapes) > 0
 
 
 def _resolve_object_collision_filename(tileset_path: Union[str, Path]) -> str:
@@ -91,8 +105,9 @@ def load_map_objects(
     collision_dir: Union[str, Path],
     *,
     cache: Optional[CollisionCache] = None,
+    require_collision: bool = True,
 ) -> List[MapObject]:
-    """Load all collidable objects from a tilemap.
+    """Load objects from a tilemap.
 
     Iterates every object layer in *tilemap_data*, resolves the
     corresponding ``.object_collision.json`` from *collision_dir*, and
@@ -126,13 +141,12 @@ def load_map_objects(
             files (typically ``<map_path>/collision/``).
         cache: Optional :class:`CollisionCache` for caching parsed
             collision data across calls.
+        require_collision: If True (default), only objects with matching
+            collision regions are returned. If False, visual-only objects
+            without collision are also included.
 
     Returns:
-        List of :class:`MapObject` instances, one per map object that
-        has both a valid surface and a matching collision region.
-        When a region contains multiple collision polygons, all shapes
-        are preserved in :attr:`MapObject.collision_shapes` and the
-        collision system checks each shape pair during narrowphase.
+        List of :class:`MapObject` instances.
     """
     collision_dir = Path(collision_dir)
     objects: List[MapObject] = []
@@ -164,6 +178,16 @@ def load_map_objects(
 
             collision_data = loaded_collision[ttype]
             if collision_data is None:
+                if require_collision:
+                    continue
+                game_obj = MapObject(
+                    x=x,
+                    y=y,
+                    surface=surf,
+                    collision_shape=None,
+                    collision_shapes=[],
+                )
+                objects.append(game_obj)
                 continue
 
             world_shapes = []
@@ -177,6 +201,16 @@ def load_map_objects(
                 oy = region.region_rect[1] * rs
                 world_shapes.extend(shape.transform(ox, oy, rs) for shape in region.shapes)
             if not world_shapes:
+                if require_collision:
+                    continue
+                game_obj = MapObject(
+                    x=x,
+                    y=y,
+                    surface=surf,
+                    collision_shape=None,
+                    collision_shapes=[],
+                )
+                objects.append(game_obj)
                 continue
 
             game_obj = MapObject(

{tilemap_parser-4.2.3 → tilemap_parser-4.2.5}/src/tilemap_parser/runtime/protocols.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
-from typing import Protocol, Union
+from typing import Protocol
+
+import pygame
+from pygame import Surface
 
 from ..parser.collision import (
     CapsuleShape,
@@ -10,6 +13,12 @@ from ..parser.collision import (
 )
 
 
+class ExtraObject(Protocol):
+    surface: Surface | None
+    x: float
+    y: float
+
+
 class ICollidable(Protocol):
     """Base protocol for anything with a world position and collision shape.
 
@@ -25,4 +34,4 @@ class ICollidable(Protocol):
 
     x: float
     y: float
-    collision_shape: Union[RectangleShape, CircleShape, CapsuleShape, CollisionPolygon]
+    collision_shape: RectangleShape | CircleShape | CapsuleShape | CollisionPolygon

{tilemap_parser-4.2.3 → tilemap_parser-4.2.5}/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.3 → tilemap_parser-4.2.5}/src/tilemap_parser.egg-info/PKG-INFO

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

@@ -44,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.3 → tilemap_parser-4.2.5}/tests/test_map_loader.py

@@ -346,3 +346,102 @@ class TestNodeLoading:
         assert pe.config.lifetime_min == 0.5
         assert pe.config.lifetime_max == 2.0
         assert pe.config.gravity_y == 30.0
+
+    def test_get_object_surfaces_scaled(self, map_data):
+        _, data_dir, _, _ = map_data
+        # Create map with render_scale = 2.0 and object layer
+        map_path = data_dir / "test_map_obj.json"
+        payload = {
+            "meta": {
+                "tile_size": "16;16",
+                "map_size": "10;10",
+                "version": "1.1",
+                "render_scale": 2.0,
+            },
+            "resources": {"tilesets": [{"path": "../assets/tileset.png", "type": "object"}]},
+            "project_state": {"rules": [], "groups": []},
+            "data": {
+                "ongrid": {},
+                "layers": [
+                    {
+                        "name": "Obj",
+                        "type": "object",
+                        "visible": True,
+                        "locked": False,
+                        "opacity": 1.0,
+                        "z_index": 0,
+                        "properties": {},
+                        "tiles": {},
+                        "objects": {
+                            "1": {
+                                "area": {"x": 32, "y": 64, "w": 16, "h": 16},
+                                "ttype": 0,
+                                "tileset_type": "object",
+                                "variant": 0,
+                                "properties": {},
+                            }
+                        },
+                    }
+                ],
+            },
+        }
+        with open(map_path, "w") as f:
+            json.dump(payload, f, indent=2)
+
+        td = TilemapData.load(map_path)
+        # Unscaled
+        unscaled = td.get_object_surfaces("Obj", scaled=False)
+        assert len(unscaled) == 1
+        surf_u, x_u, y_u, _ = unscaled[0]
+        assert (x_u, y_u) == (32, 64)
+        assert surf_u.get_size() == (16, 16)
+
+        # Scaled
+        scaled = td.get_object_surfaces("Obj", scaled=True)
+        assert len(scaled) == 1
+        surf_s, x_s, y_s, _ = scaled[0]
+        assert (x_s, y_s) == (64, 128)
+        assert surf_s.get_size() == (32, 32)
+
+    def test_area_node_scaled(self, map_data):
+        _, data_dir, _, _ = map_data
+        map_path = data_dir / "test_map_scaled_nodes.json"
+        payload = {
+            "meta": {
+                "tile_size": "16;16",
+                "map_size": "10;10",
+                "version": "1.1",
+                "render_scale": 3.0,
+            },
+            "resources": {"tilesets": [{"path": "../assets/tileset.png", "type": "tile"}]},
+            "project_state": {"rules": [], "groups": []},
+            "data": {"ongrid": {}, "layers": []},
+        }
+        with open(map_path, "w") as f:
+            json.dump(payload, f, indent=2)
+
+        nodes_path = data_dir / "test_map_scaled_nodes.nodes.json"
+        nodes_payload = {
+            "nodes": [
+                {
+                    "node_id": "area_1",
+                    "name": "Zone",
+                    "node_type": "area",
+                    "area": {"x": 10, "y": 20, "w": 30, "h": 40},
+                    "layer_name": "main",
+                    "properties": {},
+                    "group": "",
+                }
+            ],
+            "groups": [],
+        }
+        with open(nodes_path, "w") as f:
+            json.dump(nodes_payload, f, indent=2)
+
+        td = TilemapData.load(map_path)
+        assert len(td.area_nodes) == 1
+        an = td.area_nodes[0]
+        assert an.rect == pygame.Rect(30, 60, 90, 120)
+
+
+

{tilemap_parser-4.2.3 → tilemap_parser-4.2.5}/tests/test_map_object.py

@@ -1299,4 +1299,26 @@ class TestLoadMapObjects:
             objects = load_map_objects(td, collision_dir)
             assert objects == []
 
+    def test_load_visual_only_objects(self, map_no_collision_file):
+        td, collision_dir = map_no_collision_file
+        # With require_collision=False, objects without collision files are returned
+        objects = load_map_objects(td, collision_dir, require_collision=False)
+        assert len(objects) == 1
+        obj = objects[0]
+        assert obj.has_collision is False
+        assert obj.collision_shape is None
+        assert obj.collision_shapes == []
+        assert isinstance(obj.surface, pygame.Surface)
+
+    def test_map_object_optional_collision(self):
+        surf = pygame.Surface((16, 16))
+        obj = MapObject(x=10, y=20, surface=surf)
+        assert obj.x == 10
+        assert obj.y == 20
+        assert obj.surface is surf
+        assert obj.collision_shape is None
+        assert obj.collision_shapes == []
+        assert obj.has_collision is False
+
+
 

tilemap_parser-4.2.5/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