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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tilemap-parser"
-version = "5.0.4"
+version = "5.1.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.0.4 → tilemap_parser-5.1.0}/src/tilemap_parser/runtime/movement/platformer.py

@@ -8,6 +8,7 @@ from ...parser.collision import TilesetCollision
 from ..polygon_query import _check_sprite_polygon_offset, get_shape_bounds
 from ..protocols import ICollidableSprite
 from ..world import PhysicsWorld
+from .queries import _resolve_tile_data
 from .types import CollisionResult, Vector2
 
 
@@ -118,9 +119,7 @@ def move_platformer(
     for tile_y in range(min_tile_y, max_tile_y + 1):
         for tile_x in range(min_tile_x, max_tile_x + 1):
             tile_id = tile_map.get((tile_x, tile_y))
-            if tile_id is None:
-                continue
-            tile_data = tileset_collision.tiles.get(tile_id)
+            tile_data = _resolve_tile_data(world, tileset_collision, tile_id)
             if tile_data is None:
                 continue
             ox = tile_x * tw

{tilemap_parser-5.0.4 → tilemap_parser-5.1.0}/src/tilemap_parser/runtime/movement/queries.py

@@ -4,12 +4,31 @@ from __future__ import annotations
 
 import math
 
-from ...parser.collision import CollisionPolygon, TilesetCollision
+from ...parser.collision import CollisionPolygon, TileCollisionData, TilesetCollision
 from ..collision.hit import should_collide
 from ..polygon_query import _check_sprite_polygon_offset, get_shape_bounds
 from ..protocols import ICollidable, ICollidableSprite
 
 
+def _resolve_tile_data(
+    world,
+    tileset_collision: TilesetCollision,
+    tile_id: int | None,
+) -> TileCollisionData | None:
+    """Fetch collision data for *tile_id*, GID-routed when a world is attached.
+
+    With an attached world built via ``from_map(..., use_gids=True)`` the id
+    is range-routed against the map's grid resources (decoration tilesets can
+    never alias into the collision owner's local keys).  Without a world the
+    historic literal lookup applies.
+    """
+    if tile_id is None:
+        return None
+    if world is not None:
+        return world.resolve_collision(tile_id)
+    return tileset_collision.tiles.get(tile_id)
+
+
 def _collides_at(
     self,
     sprite: ICollidable,
@@ -35,9 +54,7 @@ def _collides_at(
     for tile_y in range(min_tile_y, max_tile_y + 1):
         for tile_x in range(min_tile_x, max_tile_x + 1):
             tile_id = tile_map.get((tile_x, tile_y))
-            if tile_id is None:
-                continue
-            tile_data = tileset_collision.tiles.get(tile_id)
+            tile_data = _resolve_tile_data(world, tileset_collision, tile_id)
             if tile_data is None:
                 continue
             ox = tile_x * tw
@@ -72,9 +89,7 @@ def _first_colliding_shape(
     for tile_y in range(min_tile_y, max_tile_y + 1):
         for tile_x in range(min_tile_x, max_tile_x + 1):
             tile_id = tile_map.get((tile_x, tile_y))
-            if tile_id is None:
-                continue
-            tile_data = tileset_collision.tiles.get(tile_id)
+            tile_data = _resolve_tile_data(world, tileset_collision, tile_id)
             if tile_data is None:
                 continue
             ox = tile_x * tw
@@ -113,9 +128,7 @@ def _collides_at_platformer(
     for tile_y in range(min_tile_y, max_tile_y + 1):
         for tile_x in range(min_tile_x, max_tile_x + 1):
             tile_id = tile_map.get((tile_x, tile_y))
-            if tile_id is None:
-                continue
-            tile_data = tileset_collision.tiles.get(tile_id)
+            tile_data = _resolve_tile_data(world, tileset_collision, tile_id)
             if tile_data is None:
                 continue
             ox = tile_x * tw
@@ -218,9 +231,7 @@ def _find_walkable_ground_y(
     for tile_y in range(min_tile_y, max_tile_y + 1):
         for tile_x in range(min_tile_x, max_tile_x + 1):
             tile_id = tile_map.get((tile_x, tile_y))
-            if tile_id is None:
-                continue
-            tile_data = tileset_collision.tiles.get(tile_id)
+            tile_data = _resolve_tile_data(world, tileset_collision, tile_id)
             if tile_data is None:
                 continue
             ox = tile_x * tw

{tilemap_parser-5.0.4 → tilemap_parser-5.1.0}/src/tilemap_parser/runtime/movement/runner.py

@@ -151,13 +151,19 @@ class CollisionRunner:
         tile_x, tile_y = self.get_tile_at(world_x, world_y)
         tile_id = tile_map.get((tile_x, tile_y))
 
-        if tile_id is None or not tileset_collision.has_collision(tile_id):
+        world = self._resolve_world(None)
+        tile_data = queries._resolve_tile_data(world, tileset_collision, tile_id)
+        if tile_data is None:
             return []
 
         tile_world_x = tile_x * self._eff_tw
         tile_world_y = tile_y * self._eff_th
 
-        return tileset_collision.get_world_shapes(tile_id, tile_world_x, tile_world_y, self.render_scale)
+        return [
+            shape.transform(tile_world_x, tile_world_y, self.render_scale)
+            for shape in tile_data.shapes
+            if shape.is_valid()
+        ]
 
     def get_nearby_tile_shapes(
         self,
@@ -182,12 +188,11 @@ class CollisionRunner:
         max_tile_y = int(bottom // th) + margin
 
         shapes = []
+        world = self._resolve_world(None)
         for tile_y in range(min_tile_y, max_tile_y + 1):
             for tile_x in range(min_tile_x, max_tile_x + 1):
                 tile_id = tile_map.get((tile_x, tile_y))
-                if tile_id is None:
-                    continue
-                tile_data = tileset_collision.tiles.get(tile_id)
+                tile_data = queries._resolve_tile_data(world, tileset_collision, tile_id)
                 if tile_data is None:
                     continue
                 tile_world_x = tile_x * tw

{tilemap_parser-5.0.4 → tilemap_parser-5.1.0}/src/tilemap_parser/runtime/navigation/nav_grid.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import math
 from typing import Dict, List, Optional, Tuple
 
-from ...parser.collision import TilesetCollision
+from ...parser.collision import TileCollisionData, TilesetCollision
 
 
 class NavGrid:
@@ -15,14 +15,15 @@ class NavGrid:
     """
 
     __slots__ = (
-        "tile_map",
-        "tileset_collision",
-        "tile_size",
-        "_eff_tw",
         "_eff_th",
-        "_width",
+        "_eff_tw",
+        "_gid_resolver",
         "_height",
         "_walkable",
+        "_width",
+        "tile_map",
+        "tile_size",
+        "tileset_collision",
     )
 
     def __init__(
@@ -32,9 +33,14 @@ class NavGrid:
         tile_size: Tuple[int, int],
         render_scale: float = 1.0,
         map_size: Optional[Tuple[int, int]] = None,
+        gid_resolver=None,
     ) -> None:
         self.tile_map = tile_map
         self.tileset_collision = tileset_collision
+        # Optional callable (int) -> TileCollisionData | None.  Pass
+        # ``physics_world.resolve_collision`` for GID-routed maps so ids from
+        # non-collidable grid tilesets resolve to None instead of aliasing.
+        self._gid_resolver = gid_resolver
         self.tile_size = tile_size
         self._eff_tw = tile_size[0] * render_scale
         self._eff_th = tile_size[1] * render_scale
@@ -52,11 +58,15 @@ class NavGrid:
 
         self._walkable = [[self._is_tile_walkable(x, y) for x in range(self._width)] for y in range(self._height)]
 
-    def _is_tile_walkable(self, tx: int, ty: int) -> bool:
-        tile_id = self.tile_map.get((tx, ty))
+    def _resolve(self, tile_id):
         if tile_id is None:
-            return True
-        tile_data = self.tileset_collision.tiles.get(tile_id)
+            return None
+        if self._gid_resolver is not None:
+            return self._gid_resolver(tile_id)
+        return self.tileset_collision.tiles.get(tile_id)
+
+    def _is_tile_walkable(self, tx: int, ty: int) -> bool:
+        tile_data = self._resolve(self.tile_map.get((tx, ty)))
         if tile_data is None:
             return True
         for poly in tile_data.shapes:
@@ -78,10 +88,7 @@ class NavGrid:
         return self._walkable[ty][tx]
 
     def is_one_way(self, tx: int, ty: int) -> bool:
-        tile_id = self.tile_map.get((tx, ty))
-        if tile_id is None:
-            return False
-        tile_data = self.tileset_collision.tiles.get(tile_id)
+        tile_data = self._resolve(self.tile_map.get((tx, ty)))
         if tile_data is None:
             return False
         has_one_way = False
@@ -104,6 +111,10 @@ class NavGrid:
         new._width = self._width
         new._height = self._height
         new._walkable = [row[:] for row in self._walkable]
+        # _gid_resolver lives in __slots__: dropping it here made every
+        # derived grid raise AttributeError once _resolve() ran (e.g. via
+        # is_one_way), and silently lost GID routing before that.
+        new._gid_resolver = self._gid_resolver
         return new
 
     def erode(self, margin: float) -> NavGrid:
@@ -155,16 +166,31 @@ class NavGrid:
         sprite_height: Optional[float] = None,
         render_scale: float = 1.0,
         map_size: Optional[Tuple[int, int]] = None,
-        cache: Optional[Dict[float, NavGrid]] = None,
+        cache: Optional[dict[tuple[float, bool], NavGrid]] = None,
+        gid_resolver=None,
     ) -> NavGrid:
+        """Build (or fetch from *cache*) an eroded grid for one entity size.
+
+        The cache is scoped to a single map/routing context and is keyed by
+        ``(margin, resolver_is_literal)`` so literal and GID-routed grids can
+        never cross-contaminate through a shared cache dict.
+        """
         tw = tile_size[0] * render_scale
         size = max(sprite_width, sprite_height if sprite_height is not None else sprite_width)
         margin = (size / 2.0) / tw
-        if cache is not None and margin in cache:
-            return cache[margin]
-        nav = cls(tile_map, tileset_collision, tile_size, render_scale, map_size).erode(margin)
+        key = (margin, gid_resolver is None)
+        if cache is not None and key in cache:
+            return cache[key]
+        nav = cls(
+            tile_map,
+            tileset_collision,
+            tile_size,
+            render_scale,
+            map_size,
+            gid_resolver=gid_resolver,
+        ).erode(margin)
         if cache is not None:
-            cache[margin] = nav
+            cache[key] = nav
         return nav
 
     def get_neighbors(self, tx: int, ty: int, *, diagonals: bool = False) -> List[Tuple[int, int]]:

{tilemap_parser-5.0.4 → tilemap_parser-5.1.0}/src/tilemap_parser/runtime/world.py

@@ -9,14 +9,18 @@ resolves movement against the world's tiles AND bodies uniformly.
 
 from __future__ import annotations
 
-from typing import Dict, List, Optional, Tuple
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
 
-from ..parser.collision import TilesetCollision
+from ..parser.collision import TileCollisionData, TilesetCollision
 from .body import Body
 from .collision.hit import check_collision
 from .map_loader import TilemapData
 from .protocols import ICollidable
 
+if TYPE_CHECKING:  # pragma: no cover
+    from ..parser.map_parse import ParsedTileset
+
 
 class PhysicsWorld:
     """A space containing a tile layer and solid bodies."""
@@ -45,6 +49,11 @@ class PhysicsWorld:
         self.tile_size = tuple(tile_size)
         self.render_scale = render_scale
         self.bodies: List[Body] = []
+        # GID routing (see `resolve_collision`): (firstgid, tile_count, stem)
+        # for every *grid* resource of the source map, plus the stem that the
+        # single collision file belongs to.  Empty => literal local lookups.
+        self._grid_ranges: List[Tuple[int, int, str]] = []
+        self._collision_owner_stem: Optional[str] = None
         if self.tile_map and self.tileset_collision is None:
             raise ValueError(
                 "tile_map requires tileset_collision: a world with solid "
@@ -91,12 +100,68 @@ class PhysicsWorld:
                 "tiles cannot resolve movement without collision data"
             )
         world.tileset_collision = tileset_collision
+        if use_gids:
+            world._capture_grid_ownership(tilemap_data, tileset_collision)
         return world
 
-    # ------------------------------------------------------------------
-    # Body management
-    # ------------------------------------------------------------------
+ 
+    def _capture_grid_ownership(
+        self, map_data: TilemapData, tileset_collision: TilesetCollision
+    ) -> None:
+        """Record every grid resource's GID range and the collision owner.
 
+        Only ``type=="tile"`` resources participate; object tilesets are
+        never part of the physics grid.  Routing activates only when the
+        collision file's ``tileset_name`` stem-matches one of them —
+        otherwise lookups stay literal (legacy / pre-merged files).
+        """
+        owner = tileset_collision.tileset_name
+        ranges: List[Tuple[int, int, str]] = []
+        matched: Optional[str] = None
+        for ts in map_data.parsed.tilesets:
+            if getattr(ts, "type", "tile") != "tile":
+                continue
+            stem = Path(ts.path).stem
+            ranges.append((ts.firstgid, ts.tile_count, stem))
+            if stem == owner and matched is None:
+                matched = stem
+        if matched is not None:
+            self._grid_ranges = ranges
+            self._collision_owner_stem = matched
+
+    def resolve_collision(self, tile_id: int) -> Optional[TileCollisionData]:
+        """Resolve a possibly-global tile id to its collision data.
+
+        With GID routing active (``from_map(..., use_gids=True)`` plus a
+        stem-matched collision file):
+
+        1. find the grid resource whose ``[firstgid, firstgid+count)``
+           window contains *tile_id*;
+        2. if that resource is **not** the collision owner → ``None``
+           (decoration grids are never solid, no cross-set aliasing);
+        3. else translate ``tile_id - firstgid`` to the local key.
+
+        Without routing (literal mode, or a pre-merged GID-keyed
+        collision), falls back to a plain dictionary lookup — identical
+        to historic behaviour.
+        """
+        if self._grid_ranges and self.tileset_collision is not None:
+            for firstgid, count, stem in self._grid_ranges:
+                if firstgid <= tile_id < firstgid + count:
+                    if stem != self._collision_owner_stem:
+                        return None
+                    return self.tileset_collision.tiles.get(tile_id - firstgid)
+            return None
+        if self.tileset_collision is None:
+            return None
+        return self.tileset_collision.tiles.get(tile_id)
+
+    def has_collision_gid(self, tile_id: int) -> bool:
+        """Convenience boolean form of :meth:`resolve_collision`."""
+        data = self.resolve_collision(tile_id)
+        return data is not None and data.has_collision()
+
+    # body
     def add_body(self, body: Body) -> None:
         """Add a body to the world.  Adding the same body twice is a no-op."""
         if body not in self.bodies:

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

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

@@ -54,6 +54,7 @@ tests/test_camera.py
 tests/test_collision.py
 tests/test_geometry.py
 tests/test_gid_collision.py
+tests/test_gid_routing.py
 tests/test_integration_animation.py
 tests/test_integration_collision.py
 tests/test_integration_map_loader.py

tilemap_parser-5.1.0/tests/test_gid_routing.py

@@ -0,0 +1,293 @@
+"""GID range-routing tests: single grid collision file, multi-tileset maps.
+
+Regression ground: with ``use_gids=True`` and a collision file whose
+``firstgid != 0``, literal lookups silently missed (e.g. only 1 of many
+collidable tiles resolved).  Naive per-lookup offset subtraction also aliases:
+a decoration grid whose GID window lands inside the owner's *local*
+key space (e.g. gid ``1813 - 90 = 1723``) would become falsely solid
+the moment the owner gains that local key.
+
+Routing must therefore resolve ownership against the map's grid
+resource table BEFORE translating.
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from tilemap_parser.parser.collision import (
+    CollisionPolygon,
+    TileCollisionData,
+    TilesetCollision,
+)
+from tilemap_parser.runtime.navigation.nav_grid import NavGrid
+from tilemap_parser.runtime.world import PhysicsWorld
+
+# ---------------------------------------------------------------------------
+# builders
+# ---------------------------------------------------------------------------
+
+def solid(x=8.0, y=8.0):
+    return CollisionPolygon(vertices=[(0, 0), (x, 0), (x, y), (0, y)])
+
+
+def make_col(name: str, keys: dict[int, list]) -> TilesetCollision:
+    return TilesetCollision(
+        tileset_name=name,
+        tile_size=(8, 8),
+        tiles={k: TileCollisionData(tile_id=k, shapes=v) for k, v in keys.items()},
+    )
+
+
+def stamp(world: PhysicsWorld, ranges, owner_stem: str | None) -> None:
+    """Simulate what from_map captures from map_data.parsed.tilesets."""
+    world._grid_ranges = list(ranges)
+    world._collision_owner_stem = owner_stem
+
+
+
+RANGES = [
+    (0, 90, "cave"),          # decoration grid
+    (90, 1750, "tileset"),    # collision owner
+    (1840, 56, "cave_hole"),  # decoration grid
+    (1896, 1296, "bg"),       # decoration grid
+]
+COL_KEYS = {1: [solid()], 2: [solid()], 575: [solid()], 981: [solid()]}
+
+
+@pytest.fixture()
+def routed_world() -> PhysicsWorld:
+    w = PhysicsWorld(
+        tile_map={(0, 6): 92, (3, 6): 1813},
+        tileset_collision=make_col("tileset", COL_KEYS),
+        tile_size=(8, 8),
+        render_scale=3.0,
+    )
+    stamp(w, RANGES, "tileset")
+    return w
+
+
+class TestRoutingMatrix:
+    def test_owner_gid_translates_to_local(self, routed_world):
+        assert routed_world.resolve_collision(92) is not None      # local 2
+        assert routed_world.has_collision_gid(92) is True
+
+    def test_decoration_grid_never_solids__alias_regression(self, routed_world):
+        # gid 1813 belongs to cave_hole; naive `gid-90` would hit local 1723.
+        assert routed_world.resolve_collision(1813) is None
+        assert routed_world.has_collision_gid(1813) is False
+
+    def test_other_owner_windows_rejected(self, routed_world):
+        assert routed_world.resolve_collision(5) is None           # cave window
+        assert routed_world.resolve_collision(1900) is None        # bg window
+        assert routed_world.resolve_collision(1840 + 4) is None    # hole window
+
+    def test_unmapped_gap_is_none(self, routed_world):
+        # 90+1750+56+1296 == 3192: first id past every grid window
+        assert routed_world.resolve_collision(3192) is None
+        assert routed_world.resolve_collision(5000) is None
+
+    def test_owner_local_keys_without_collision_shapes(self, routed_world):
+        # owner-local 50 exists as a gid but has no entry -> None, not crash
+        assert routed_world.resolve_collision(90 + 50) is None
+
+    def test_boundary_edges(self, routed_world):
+        assert routed_world.resolve_collision(89) is None           # last cave gid
+        # inclusive owner lower edge: local 0 exists in the window but has no
+        # collision entry -> None (must not fall through to another range)
+        assert routed_world.resolve_collision(90) is None
+        assert routed_world.resolve_collision(90 + 1749) is None    # last owner gid, keyless
+
+
+class TestLiteralFallback:
+    def test_no_routing_keeps_literal_lookup(self):
+        w = PhysicsWorld(
+            tile_map={(0, 0): 2},
+            tileset_collision=make_col("tileset", COL_KEYS),
+            tile_size=(8, 8),
+        )
+        assert w._grid_ranges == []
+        assert w.resolve_collision(2) is not None
+        assert w.has_collision_gid(2) is True
+
+    def test_merged_gid_keyed_file_stays_literal(self):
+        # merge() output: keys ARE gids, no stem match possible
+        merged = make_col("merged", {92: [solid()]})
+        w = PhysicsWorld(
+            tile_map={(0, 6): 92}, tileset_collision=merged, tile_size=(8, 8)
+        )
+        stamp(w, [], None)
+        assert w.resolve_collision(92) is not None
+
+
+class TestFromMapCapture:
+    def _payload(self, tmp: Path):
+        (tmp / "a.png").write_bytes(b"x")  # existence not required (skip_missing_images)
+        (tmp / "b.png").write_bytes(b"x")
+        return {
+            "meta": {
+                "tile_size": "8;8",
+                "map_size": "4;4",
+                "offset": "0;0",
+                "render_scale": 1.0,
+                "version": "1.1",
+            },
+            "resources": {
+                "tilesets": [
+                    {"path": str(tmp / "a.png"), "type": "tile", "tile_count": 4, "firstgid": 0},
+                    {"path": str(tmp / "b.png"), "type": "tile", "tile_count": 4, "firstgid": 4},
+                    {"path": str(tmp / "c.png"), "type": "object", "tile_count": 2, "firstgid": 8},
+                ]
+            },
+            "project_state": {"rules": []},
+            "data": {
+                "layers": [
+                    {
+                        "name": "L", "type": "tile", "visible": True,
+                        "tiles": {
+                            "0;0": {"pos": "0;0", "ttype": 1, "variant": 0, "gid": 4},
+                            "1;0": {"pos": "1;0", "ttype": 0, "variant": 1, "gid": 1},
+                        },
+                    }
+                ]
+            },
+        }
+
+    def test_from_map_auto_captures_owner_and_routes(self, tmp_path):
+        from tilemap_parser.runtime.map_loader import load_map
+
+        payload_path = tmp_path / "m.json"
+        payload_path.write_text(json.dumps(self._payload(tmp_path)))
+
+        map_data = load_map(payload_path)
+        col = make_col("b", {0: [solid()]})  # local-keyed file for resource b
+
+        world = PhysicsWorld.from_map(map_data, col, use_gids=True)
+
+        # gid 4 -> owner b -> local 0 -> solid; gid 1 -> owner a -> decor
+        assert world.has_collision_gid(4) is True
+        assert world.has_collision_gid(1) is False
+        # object resource c never participates even though its window follows
+        assert world.resolve_collision(8) is None
+
+    def test_from_map_literal_mode_untouched(self, tmp_path):
+        from tilemap_parser.runtime.map_loader import load_map
+
+        payload_path = tmp_path / "m.json"
+        payload_path.write_text(json.dumps(self._payload(tmp_path)))
+        map_data = load_map(payload_path)
+        col = make_col("b", {0: [solid(), solid()]})
+
+        world = PhysicsWorld.from_map(map_data, col, use_gids=False)
+        assert world._grid_ranges == []
+        assert world.resolve_collision(0) is not None  # literal local id
+
+
+# ---------------------------------------------------------------------------
+# NavGrid resolver propagation (copy / erode / for_entity)
+# ---------------------------------------------------------------------------
+
+class TestNavGridResolverPropagation:
+    def _world(self):
+        world = PhysicsWorld(
+            tile_map={(0, 6): 92, (3, 6): 1813},
+            tileset_collision=make_col("tileset", COL_KEYS),
+            tile_size=(8, 8),
+        )
+        stamp(world, RANGES, "tileset")
+        return world
+
+    def test_copy_preserves_resolver_and_does_not_crash(self):
+        w = self._world()
+        base = NavGrid(w.tile_map, w.tileset_collision, w.tile_size, gid_resolver=w.resolve_collision)
+
+        derived = base.copy()  # used to lack the slot entirely
+        assert derived._gid_resolver is not None
+
+        # is_one_way hits _resolve(): raised AttributeError on copies before
+        derived.is_one_way(0, 6)
+        # routed semantics survive the copy: owner solid, decoration not
+        assert derived.is_solid(0, 6) is True    # gid 92 -> owner local 2
+        assert derived.is_solid(3, 6) is False   # gid 1813 -> other grid resource
+
+        eroded = base.erode(1.0)
+        eroded.is_one_way(0, 6)
+        assert eroded._gid_resolver is not None
+
+    def test_literal_grid_unchanged_without_resolver(self):
+        grid = NavGrid({(0, 0): 2}, make_col("t", COL_KEYS), (8, 8))
+        assert grid.copy()._gid_resolver is None
+        assert grid.is_solid(0, 0) is True       # literal local key 2
+        grid.is_one_way(0, 0)                    # must not raise
+
+    def test_cache_keys_separate_resolver_modes(self):
+        w = self._world()
+        cache: dict = {}
+
+        literal = NavGrid.for_entity(
+            w.tile_map, w.tileset_collision, w.tile_size,
+            sprite_width=10.0, sprite_height=10.0, cache=cache,
+        )
+        routed = NavGrid.for_entity(
+            w.tile_map, w.tileset_collision, w.tile_size,
+            sprite_width=10.0, sprite_height=10.0, cache=cache,
+            gid_resolver=w.resolve_collision,
+        )
+
+        assert len(cache) == 2, "modes must occupy distinct cache slots"
+        assert literal is not routed
+        assert literal._gid_resolver is None
+        assert routed._gid_resolver is not None
+        # same inputs, different semantics: owner tile solid only when routed
+        assert literal.is_solid(0, 6) is False   # literal lookup of gid 92 misses
+        assert routed.is_solid(0, 6) is True     # routed resolves to local 2
+
+    def test_cache_reuses_entry_within_same_mode(self):
+        w = self._world()
+        cache: dict = {}
+        a = NavGrid.for_entity(
+            w.tile_map, w.tileset_collision, w.tile_size,
+            sprite_width=16.0, cache=cache, gid_resolver=w.resolve_collision,
+        )
+        b = NavGrid.for_entity(
+            w.tile_map, w.tileset_collision, w.tile_size,
+            sprite_width=16.0, cache=cache, gid_resolver=w.resolve_collision,
+        )
+        assert a is b, "same margin + same mode must hit the cached grid"
+
+        lit_a = NavGrid.for_entity(
+            w.tile_map, w.tileset_collision, w.tile_size,
+            sprite_width=16.0, cache=cache,
+        )
+        lit_b = NavGrid.for_entity(
+            w.tile_map, w.tileset_collision, w.tile_size,
+            sprite_width=16.0, cache=cache,
+        )
+        assert lit_a is lit_b and lit_a is not a
+        assert len(cache) == 2
+
+    def test_for_entity_forwards_resolver(self):
+        w = self._world()
+        grid = NavGrid.for_entity(
+            w.tile_map,
+            w.tileset_collision,
+            w.tile_size,
+            sprite_width=10.0,
+            sprite_height=10.0,
+            gid_resolver=w.resolve_collision,
+        )
+        assert grid._gid_resolver is not None
+        # owner tile stays solid under entity clearance; decoration never was
+        assert grid.is_solid(0, 6) is True
+        assert grid.is_solid(3, 6) is False
+
+        # parity: identical construction without a resolver would alias the
+        # decoration gid into local 1723 (keyless today, so also False) --
+        # assert via direct literal probe that routing, not luck, decides.
+        literal = NavGrid.for_entity(
+            w.tile_map, w.tileset_collision, w.tile_size, sprite_width=10.0
+        )
+        assert literal._gid_resolver is None
+        assert literal.is_solid(0, 6) is False   # literal lookup of gid 92 misses
+        assert grid.is_solid(0, 6) is True       # routed lookup resolves it