Keep cheaper root distances and traversal when adding destinations

Author: antonsoo

CHANGELOG.md

@@ -8,7 +8,7 @@ This project adheres to [Semantic Versioning](https://semver.org/) since version
 
 ### Fixed
 
-- Adding a root to an already resolved `tcod.path.Pathfinder` no longer leaves a stale predecessor which can cause cyclic paths after resolving again.
+- Adding a root to an already resolved `tcod.path.Pathfinder` resets its predecessor only when its value improves the current distance. This prevents cyclic paths while preserving routes to cheaper roots.
 
 ## [21.2.1] - 2026-06-04
 

tcod/path.py

@@ -1212,13 +1212,16 @@ def add_root(self, index: tuple[int, ...], value: int = 0) -> None:
 
         `value` is the distance to use for this root.  Zero is typical, but
         if multiple roots are added they can be given different weights.
+        The root is ignored if `value` is not less than its current distance.
         """
         index = tuple(index)  # Check for bad input.
         if self._order == "F":  # Convert to ij indexing order.
             index = index[::-1]
         if len(index) != self._distance.ndim:
             msg = f"Index must be {self._distance.ndim} items, got {index!r}"
             raise TypeError(msg)
+        if value >= self._distance[index]:
+            return
         self._distance[index] = value
         self._travel[index] = index
         self._update_heuristic(None)

tests/test_path.py

@@ -40,3 +40,44 @@ def test_add_root_after_resolve(shape: tuple[int, ...], order: str, value: int)
         assert root in (origin, new_root)
         root_value = value if root == new_root else 0
         assert len(path) - 1 + root_value == expected[index]
+
+
+@pytest.mark.parametrize("shape", [(4, 7), (3, 4, 7)])
+@pytest.mark.parametrize("order", ["C", "F"])
+@pytest.mark.parametrize("first_value", [-5, 3])
+@pytest.mark.parametrize("relative_value", [-1, 0, 1, 20])
+@pytest.mark.parametrize("partial", [False, True])
+def test_add_root_preserves_better_distances(
+    shape: tuple[int, ...], order: str, first_value: int, relative_value: int, partial: bool
+) -> None:
+    graph = tcod.path.CustomGraph(shape, order=order)
+    cost = np.ones(shape, dtype=np.int8)
+    for axis in range(len(shape)):
+        for direction in (-1, 1):
+            edge = [0] * len(shape)
+            edge[axis] = direction
+            graph.add_edge(tuple(edge), cost=cost)
+    pathfinder = tcod.path.Pathfinder(graph)
+    origin = (0,) * len(shape)
+    new_root = tuple(size // 2 for size in shape)
+    pathfinder.add_root(origin, value=first_value)
+    pathfinder.resolve(new_root if partial else None)
+    old_distances = pathfinder.distance.copy()
+    old_traversal = pathfinder.traversal.copy()
+    old_path = pathfinder.path_from(new_root).copy()
+    value = int(old_distances[new_root]) + relative_value
+    pathfinder.add_root(new_root, value=value)
+    if relative_value >= 0:
+        np.testing.assert_array_equal(pathfinder.distance, old_distances)
+        np.testing.assert_array_equal(pathfinder.traversal, old_traversal)
+        np.testing.assert_array_equal(pathfinder.path_from(new_root), old_path)
+    else:
+        assert pathfinder.distance[new_root] == value
+        np.testing.assert_array_equal(pathfinder.path_from(new_root), [new_root])
+    pathfinder.resolve()
+    coordinates = np.indices(shape)
+    expected = np.minimum(
+        first_value + coordinates.sum(axis=0),
+        value + sum(abs(new_root[axis] - coordinates[axis]) for axis in range(len(shape))),
+    )
+    np.testing.assert_array_equal(pathfinder.distance, expected)