feat(pack_evade): observational food cells (near focal + behind predator) + wall/food prompt

proteus/grid/scenarios/pack_evade.py

@@ -28,6 +28,7 @@ BACKGROUND_IDX = 5  # arc_grid Camera default background
 FOCAL_IDX = 1
 PREDATOR_IDX = 2
 WALL_IDX = 3        # matches predator_evade + COLOR_MAP gray
+FOOD_IDX = 14       # COLOR_MAP green; observational food cells
 
 _GRID = (64, 64)
 _FOCAL_START = (5, 30)      # 3x3 -> footprint x[5,8) y[30,33), center (6,31)
@@ -54,6 +55,17 @@ _SPAWN_RECTS = (
     (_PREDATOR_START[0], _PREDATOR_START[1], _PREDATOR_START[0] + 4, _PREDATOR_START[1] + 4),
 )
 
+# Extra (beyond the two mandatory) observational food cells per difficulty.
+_FOOD_EXTRAS = {
+    Difficulty.EASY: 1, Difficulty.MEDIUM: 2, Difficulty.HARD: 3, Difficulty.EXPERT: 3,
+}
+_FOCAL_CENTER = (_FOCAL_START[0] + 1, _FOCAL_START[1] + 1)      # 3x3 center
+_PREDATOR_CENTER = (_PREDATOR_START[0] + 2, _PREDATOR_START[1] + 2)  # 5x5 center
+
+
+def _sign(v: int) -> int:
+    return (v > 0) - (v < 0)
+
 
 def _axis_gap(a0: int, a1: int, b0: int, b1: int) -> int:
     """Free cells between inclusive intervals [a0,a1] and [b0,b1]; -1 if overlap."""
@@ -102,22 +114,27 @@ class PackEvade(Scenario):
     task_name: str = "pack_evade"
     grid_size: tuple[int, int] = _GRID
     rules_text: str = (
-        "You control agent A, a 3x3 block, on a 64x64 open field (no walls). A "
-        "5x5 predator B hunts you, moving one cell toward you every turn. You are "
-        "eaten if B's block touches (overlaps) yours. Stay as far from B as you "
-        "can. Actions: up, down, left, right, stay (up decreases the row, down "
-        "increases it; left/right move along the column)."
+        "You control agent A, a 3x3 block, on a 64x64 field laced with impassable "
+        "wall blocks (your 3x3 body cannot overlap a wall). A 5x5 predator B hunts "
+        "you, moving one cell toward you every turn. You are eaten if B's block "
+        "touches (overlaps) yours. Food cells (1x1) are scattered on the field — "
+        "one near you and one behind the predator — they are edible context. Stay "
+        "as far from B as you can. Actions: up, down, left, right, stay (up "
+        "decreases the row, down increases it; left/right move along the column)."
     )
     memory_brief: str = (
-        "PRACTICE / MEMORY RUN. You are A (3x3) on a 64x64 open field. A 5x5 "
-        "predator B hunts you, stepping one cell toward you each turn; you are "
-        "eaten if its block overlaps yours. Keep maximum distance. End your reply "
-        "with a line: ACTION: <one of up, down, left, right, stay>"
+        "PRACTICE / MEMORY RUN. You are A (3x3) on a 64x64 field laced with "
+        "impassable wall blocks (you cannot overlap a wall). A 5x5 predator B "
+        "hunts you, stepping one cell toward you each turn; you are eaten if its "
+        "block overlaps yours. Food cells (1x1) are scattered — one near you and "
+        "one behind the predator — they are edible context. Keep maximum distance. "
+        "End your reply with a line: ACTION: <one of up, down, left, right, stay>"
     )
 
     # ------------------------------------------------------------------ #
     _wall_rects: list[tuple[int, int, int, int]] = []
     _wall_cells: frozenset[tuple[int, int]] = frozenset()
+    _food_cells: list[tuple[int, int]] = []
 
     def build_level(self, rng: random.Random, difficulty: Difficulty) -> Level:
         self.grid_size = _GRID
@@ -125,6 +142,7 @@ class PackEvade(Scenario):
         self._wall_cells = frozenset(
             c for r in self._wall_rects for c in _rect_cells(r)
         )
+        self._food_cells = self._generate_food(rng, difficulty)
         focal = Sprite(
             pixels=[[FOCAL_IDX] * 3 for _ in range(3)],
             name="focal", x=_FOCAL_START[0], y=_FOCAL_START[1],
@@ -135,6 +153,13 @@ class PackEvade(Scenario):
             name="predator", x=_PREDATOR_START[0], y=_PREDATOR_START[1],
             blocking=BlockingMode.NOT_BLOCKED,
         )
+        food = [
+            Sprite(
+                pixels=[[FOOD_IDX]], name="food", x=fx, y=fy,
+                blocking=BlockingMode.NOT_BLOCKED,
+            )
+            for (fx, fy) in self._food_cells
+        ]
         walls = [
             Sprite(
                 pixels=[[WALL_IDX] * (x1 - x0 + 1) for _ in range(y1 - y0 + 1)],
@@ -142,7 +167,65 @@ class PackEvade(Scenario):
             )
             for (x0, y0, x1, y1) in self._wall_rects
         ]
-        return Level(sprites=[focal, predator, *walls])
+        # Food drawn before focal/predator so the agents render on top of it.
+        return Level(sprites=[*walls, *food, focal, predator])
+
+    def _generate_food(
+        self, rng: random.Random, difficulty: Difficulty
+    ) -> list[tuple[int, int]]:
+        """Observational 1x1 food: one near focal, one behind the predator, + extras.
+
+        Deterministic from *rng*. All cells are on-grid, off walls, off both spawn
+        footprints, and distinct. 'Behind the predator' is the cell beyond the
+        predator along the focal->predator direction (so reaching it courts the
+        predator); 'near focal' is a close free cell.
+        """
+        w, h = _GRID
+        blocked = set(self._wall_cells)
+        for (x0, y0, x1, y1) in _SPAWN_RECTS:
+            for x in range(x0, x1 + 1):
+                for y in range(y0, y1 + 1):
+                    blocked.add((x, y))
+        food: list[tuple[int, int]] = []
+
+        def free(c: tuple[int, int]) -> bool:
+            return (
+                _MARGIN <= c[0] < w - _MARGIN and _MARGIN <= c[1] < h - _MARGIN
+                and c not in blocked and c not in food
+            )
+
+        def nearest_free(target: tuple[int, int], rmin: int = 0):
+            for r in range(rmin, max(w, h)):
+                ring = []
+                for dx in range(-r, r + 1):
+                    for dy in range(-r, r + 1):
+                        if max(abs(dx), abs(dy)) != r:
+                            continue
+                        ring.append((target[0] + dx, target[1] + dy))
+                rng.shuffle(ring)
+                for c in ring:
+                    if free(c):
+                        return c
+            return None
+
+        near = nearest_free(_FOCAL_CENTER, rmin=3)
+        if near:
+            food.append(near)
+        dx, dy = _sign(_PREDATOR_CENTER[0] - _FOCAL_CENTER[0]), _sign(_PREDATOR_CENTER[1] - _FOCAL_CENTER[1])
+        behind_seed = (_PREDATOR_CENTER[0] + 4 * dx, _PREDATOR_CENTER[1] + 4 * dy)
+        behind = nearest_free(behind_seed)
+        if behind:
+            food.append(behind)
+        for _ in range(_FOOD_EXTRAS.get(difficulty, 2)):
+            for _attempt in range(200):
+                c = (rng.randint(_MARGIN, w - 1 - _MARGIN), rng.randint(_MARGIN, h - 1 - _MARGIN))
+                if free(c):
+                    food.append(c)
+                    break
+        return food
+
+    def food_cells(self) -> list[tuple[int, int]]:
+        return list(self._food_cells)
 
     def _generate_walls(
         self, rng: random.Random, difficulty: Difficulty
@@ -318,7 +401,10 @@ class PackEvade(Scenario):
         )
 
     def legend(self) -> dict[int, str]:
-        return {BACKGROUND_IDX: ".", FOCAL_IDX: "A", PREDATOR_IDX: "B", WALL_IDX: "#"}
+        return {
+            BACKGROUND_IDX: ".", FOCAL_IDX: "A", PREDATOR_IDX: "B",
+            WALL_IDX: "#", FOOD_IDX: "F",
+        }
 
     def render_frame(self, game: MotiveGridGame) -> str:
         """Compact open-field observation (no 4096-char ASCII map)."""
@@ -339,6 +425,12 @@ class PackEvade(Scenario):
                 "Walls (blocked rectangles, inclusive (x0,y0)-(x1,y1)): " + rects + "."
             )
             lines.append("Your 3x3 body cannot overlap these.")
+        if self._food_cells:
+            cells = "; ".join(f"({x},{y})" for (x, y) in self._food_cells)
+            lines.append(
+                "Food (1x1 edible cells, one near you and one behind the predator): "
+                + cells + "."
+            )
         return "\n".join(lines)
 
     def wall_rects(self) -> list[tuple[int, int, int, int]]:

tests/grid/test_pack_evade_food.py

@@ -0,0 +1,56 @@
+"""Observational food cells for pack_evade (1x1, near focal + behind predator)."""
+from __future__ import annotations
+
+import random
+
+import proteus.grid  # noqa: F401  (registers scenarios)
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
+from proteus.grid.scenario import get_scenario
+
+
+def _scn(seed=7, diff=Difficulty.MEDIUM):
+    scn = get_scenario("pack_evade")()
+    game = MotiveGridGame(scn, random.Random(seed), diff, max_steps=20)
+    return scn, game
+
+
+def test_food_generated_with_mandatory_cells():
+    scn, _ = _scn(seed=7)
+    food = scn._food_cells
+    w, h = scn.grid_size
+    assert len(food) >= 2
+    assert len(set(food)) == len(food)                       # distinct
+    for (x, y) in food:
+        assert 0 <= x < w and 0 <= y < h
+        assert (x, y) not in scn._wall_cells                 # never on a wall
+    # one near the focal spawn center (6,31)
+    assert any(abs(x - 6) + abs(y - 31) <= 12 for (x, y) in food), "food near focal"
+    # one behind the predator: focal is west (x~6), predator east (x[54,59)),
+    # so 'behind' is further east (x >= 59).
+    assert any(x >= 59 for (x, y) in food), "food behind predator (east)"
+
+
+def test_food_deterministic():
+    a, _ = _scn(seed=7)
+    b, _ = _scn(seed=7)
+    assert a._food_cells == b._food_cells
+
+
+def test_food_in_legend_and_food_cells_hook():
+    scn, _ = _scn(seed=7)
+    assert scn.legend().get(14) == "F"
+    assert scn.food_cells() == scn._food_cells
+    assert scn.food_cells()  # non-empty
+
+
+def test_food_named_in_observation():
+    scn, game = _scn(seed=7)
+    frame = scn.render_frame(game)
+    assert "Food" in frame
+
+
+def test_food_count_scales_with_difficulty():
+    e, _ = _scn(seed=7, diff=Difficulty.EASY)
+    hard, _ = _scn(seed=7, diff=Difficulty.HARD)
+    assert len(hard._food_cells) >= len(e._food_cells)