feat(cp1): port MotiveGridGame turn loop into proteus.grid

proteus/grid/game.py

@@ -0,0 +1,259 @@
+"""MotiveGridGame — the shared per-turn game loop for the motive_grid family.
+
+``MotiveGridGame`` subclasses ``proteus.arc_grid.ARCBaseGame``.  It owns the
+turn loop and delegates all scenario-specific behaviour (level construction,
+threat motion, elimination, answer keys) to an injected :class:`Scenario`.
+
+One ``perform_action`` call drives exactly one turn (the engine calls
+``step()`` repeatedly until ``complete_action()``; this game completes the
+action in a single ``step``).  The public surface is
+:meth:`apply_motive_action`, which accepts a plain action string so callers
+(the future ``MotiveGridModule``) never touch the ``GameAction`` enums.
+
+See ``docs/superpowers/specs/2026-06-01-motive-grid-design.md`` §3.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from proteus.arc_grid import (
+    ARCBaseGame,
+    ActionInput,
+    Camera,
+    GameAction,
+    GameState,
+    Sprite,
+)
+
+if TYPE_CHECKING:
+    from .scenario import Scenario
+
+# Action string -> (dx, dy) grid delta.  y grows downward (arc_grid convention).
+_DIRECTION_DELTAS: dict[str, tuple[int, int]] = {
+    "up": (0, -1),
+    "down": (0, 1),
+    "left": (-1, 0),
+    "right": (1, 0),
+    "stay": (0, 0),
+}
+
+# Action string -> engine GameAction (per spec §3: up/down/left/right =
+# ACTION1..4, stay = ACTION5).
+_ACTION_TO_GAMEACTION: dict[str, GameAction] = {
+    "up": GameAction.ACTION1,
+    "down": GameAction.ACTION2,
+    "left": GameAction.ACTION3,
+    "right": GameAction.ACTION4,
+    "stay": GameAction.ACTION5,
+}
+
+# Reverse map: engine GameAction -> action string, for step() dispatch.
+_GAMEACTION_TO_ACTION: dict[GameAction, str] = {
+    v: k for k, v in _ACTION_TO_GAMEACTION.items()
+}
+
+# Sprite names the scenario contract relies on.
+FOCAL_NAME = "focal"
+PREDATOR_NAME = "predator"
+
+
+class MotiveGridGame(ARCBaseGame):
+    """Shared turn loop for motive_grid scenarios.
+
+    The game is constructed with a concrete :class:`Scenario`, builds its world
+    via ``scenario.build_level``, and runs each turn through :meth:`step`:
+
+        1. Move the focal sprite (internal-wall collision or an off-grid target
+           keeps it in place).
+        2. ``scenario.advance_threat`` moves the predator/NPCs.
+        3. If ``scenario.check_elimination`` -> :meth:`lose`.
+        4. Else if the step budget is exhausted -> :meth:`win`.
+        5. ``complete_action`` ends the turn.
+
+    Boundary handling: arc_grid enforces no world border, so the framework
+    guards the grid edge for the focal agent itself.  Every scenario uses
+    ``camera == grid_size`` with no panning, so a focal move whose target cell
+    falls outside ``[0, width) x [0, height)`` is rejected (see
+    :meth:`within_bounds`).  Internal walls (dead-ends, obstacles) are still
+    handled by ``try_move_sprite``.  Scenarios therefore need not ring the grid
+    with perimeter walls, but DO own their own threat sprites' bounds.
+    """
+
+    def __init__(
+        self,
+        scenario: Scenario,
+        rng: random.Random,
+        difficulty,
+        max_steps: int,
+    ) -> None:
+        """Initialize the game from a scenario.
+
+        Args:
+            scenario: The injected scenario driving world/threat/answer-key
+                behaviour.
+            rng: Seeded RNG, threaded into level construction and threat
+                tie-breaks for determinism.
+            difficulty: Session difficulty (passed through to the scenario).
+            max_steps: Survival budget; surviving this many played turns wins.
+        """
+        level = scenario.build_level(rng)
+        width, height = scenario.grid_size
+        camera = Camera(width=width, height=height)
+
+        # Direction actions (1..5) only; placeable/click action 6 is unused.
+        super().__init__(
+            game_id=scenario.task_name,
+            levels=[level],
+            camera=camera,
+            available_actions=[1, 2, 3, 4, 5],
+        )
+
+        self.scenario = scenario
+        self.rng = rng
+        self.difficulty = difficulty
+        self.max_steps = max_steps
+        self.step_count = 0
+
+    # ------------------------------------------------------------------ #
+    # Public turn surface
+    # ------------------------------------------------------------------ #
+    def apply_motive_action(self, action: str):
+        """Play one turn from a plain action string.
+
+        Wraps the action string in an ``ActionInput`` and drives one turn via
+        the engine's ``perform_action`` (which calls :meth:`step`).  This is the
+        public surface so callers never build ``GameAction`` enums themselves.
+
+        Args:
+            action: One of ``"up"``, ``"down"``, ``"left"``, ``"right"``,
+                ``"stay"``.
+
+        Returns:
+            The ``FrameData`` returned by ``perform_action``.
+
+        Raises:
+            ValueError: If *action* is not a recognised direction string.
+        """
+        if action not in _ACTION_TO_GAMEACTION:
+            valid = ", ".join(_ACTION_TO_GAMEACTION)
+            raise ValueError(f"Unknown action '{action}'. Valid: {valid}")
+        action_input = ActionInput(id=_ACTION_TO_GAMEACTION[action])
+        return self.perform_action(action_input)
+
+    def step(self) -> None:
+        """Resolve a single turn (one focal move + threat advance + outcome).
+
+        Reads the pending engine action, moves the focal sprite, advances the
+        threat, then checks for elimination or survival.  Always completes the
+        action so the engine loop terminates after one step.
+        """
+        action = _GAMEACTION_TO_ACTION.get(self._action.id, "stay")
+        dx, dy = _DIRECTION_DELTAS[action]
+
+        focal = self.focal_sprite
+        if (
+            focal is not None
+            and (dx != 0 or dy != 0)
+            and self.within_bounds(focal.x + dx, focal.y + dy)
+        ):
+            # arc_grid has no implicit world border: try_move_sprite reverts
+            # only on sprite collision, so the framework guards the grid edge
+            # itself.  Internal walls are still handled by try_move_sprite.
+            self.try_move_sprite(focal, dx, dy)
+
+        self.scenario.advance_threat(self)
+
+        self.step_count += 1
+
+        if self.scenario.check_elimination(self):
+            self.lose()
+        elif self.step_count >= self.max_steps:
+            self.win()
+
+        self.complete_action()
+
+    # ------------------------------------------------------------------ #
+    # Sprite / state accessors for scenarios
+    # ------------------------------------------------------------------ #
+    def within_bounds(self, x: int, y: int) -> bool:
+        """Return True if cell ``(x, y)`` lies inside the scenario grid.
+
+        Every motive_grid scenario uses ``camera == grid_size`` with no
+        panning, so the grid is the world.  A move whose target cell falls
+        outside ``[0, width) x [0, height)`` is rejected, keeping sprites
+        on-screen without each scenario needing a perimeter wall.  Public so a
+        scenario's ``advance_threat`` hook can reuse it to keep its own threat
+        sprites on-grid (the framework only guards the focal agent).
+
+        Args:
+            x: Grid column (cell x-coordinate).
+            y: Grid row (cell y-coordinate).
+        """
+        width, height = self.scenario.grid_size
+        return 0 <= x < width and 0 <= y < height
+
+    def get_sprite(self, name: str) -> Sprite | None:
+        """Return the first sprite with *name*, or ``None`` if absent.
+
+        Args:
+            name: The sprite name to look up on the current level.
+
+        Returns:
+            The matching :class:`~proteus.arc_grid.Sprite`, or ``None``.
+        """
+        sprites = self.current_level.get_sprites_by_name(name)
+        return sprites[0] if sprites else None
+
+    @property
+    def focal_sprite(self) -> Sprite | None:
+        """The model-controlled focal sprite (``name="focal"``)."""
+        return self.get_sprite(FOCAL_NAME)
+
+    @property
+    def predator_sprite(self) -> Sprite | None:
+        """The threat/predator sprite (``name="predator"``)."""
+        return self.get_sprite(PREDATOR_NAME)
+
+    @property
+    def eliminated(self) -> bool:
+        """Whether the focal agent has been eliminated (game over)."""
+        return self._state == GameState.GAME_OVER
+
+    @property
+    def survived(self) -> bool:
+        """Whether the focal agent survived the full step budget (win)."""
+        return self._state == GameState.WIN
+
+    def current_grid(self) -> np.ndarray:
+        """Render the current world at native resolution (for ASCII).
+
+        Returns the native ``width x height`` palette array (e.g. ``(8, 8)`` for
+        an 8x8 grid), one palette index per cell, which ``ascii_view`` converts
+        to text.  This is distinct from :meth:`current_frame`, which returns the
+        64x64 upscaled render used for PNG/debug output.
+
+        We deliberately call the arc_grid-internal ``camera._raw_render`` here:
+        it is the correct native-resolution accessor (``render`` always upscales
+        to 64x64). No public native-resolution accessor exists.
+
+        Returns:
+            A ``(height, width)`` numpy array of palette indices at native grid
+            resolution.
+        """
+        return self.camera._raw_render(self.current_level.get_sprites())
+
+    def current_frame(self) -> np.ndarray:
+        """Render the current world as a 64x64 numpy palette frame.
+
+        The ASCII conversion (palette index -> symbol via ``scenario.legend``)
+        lives in the later ``ascii_view`` module; this exposes the raw frame
+        for it to consume.
+
+        Returns:
+            A ``(64, 64)`` numpy array of palette indices.
+        """
+        return self.camera.render(self.current_level.get_sprites())

tests/grid/test_game_import.py

@@ -0,0 +1,10 @@
+def test_game_module_imports_and_action_maps_are_consistent():
+    from proteus.grid.game import (
+        MotiveGridGame,
+        _DIRECTION_DELTAS,
+        _ACTION_TO_GAMEACTION,
+        _GAMEACTION_TO_ACTION,
+    )
+    # Every action has a delta and a GameAction, and the reverse map is exact.
+    assert set(_DIRECTION_DELTAS) == set(_ACTION_TO_GAMEACTION)
+    assert _GAMEACTION_TO_ACTION == {v: k for k, v in _ACTION_TO_GAMEACTION.items()}