python-gameplay-nav-stuck-loops

Answer

Root cause: the controller held buttons far too long (PRESS_FRAMES=120 ≈ 2s at 60fps), so every doorway was overshot; the coarse block classifier stamped Pallet Town's north map-edge transition row (tile y<=2) as a wall and routed the agent into a wall-bang loop; and the name-entry state machine could press A while the END cursor was selected, hard-locking the session.

Fix 1 — Short-tap movement (no more overshoot):

# config.py — before: 120-frame holds / 300-frame strides overshot doors
PRESS_FRAMES = 120
STEP_FORWARD  = 300

# config.py — after: one-tap presses, quick re-observation
PRESS_FRAMES = 5
STEP_FORWARD  = 15

def _execute_move(self, direction: str):
    """Tap, don't hold: short press then re-read the map state."""
    for _ in range(PRESS_FRAMES):
        self.emu.press(direction)
        self.emu.advance(1)
    self.emu.release(direction)
    self.emu.advance(STEP_FORWARD)   # let the new tile settle before pathing

Fix 2 — Map-edge exits are transitions, not walls:

MAP_EDGE_EXIT_ROW = 2  # tiles y<=2 are transition rows (Pallet north -> Route 1)

def _blocked_spatial_directions(self, tile: dict) -> set[str]:
    """Blocked set for pathing. Discards the coarse classifier's 'wall'
    stamp on map-edge exit rows so the agent walks north instead of
    banging against an invisible barrier."""
    blocked: set[str] = set()
    tx, ty = tile["x"], tile["y"]
    for d, nid in tile.get("neighbors", {}).items():
        if nid is None or self._is_wall(nid):
            if d == "n" and ty <= MAP_EDGE_EXIT_ROW:
                continue            # north map-edge exit: open
            blocked.add(d)
    return blocked

Fix 3 — Coordinate-aware button hints (fixes name-entry END cursor):

def _suggested_map_action(self, obs: dict) -> str:
    """Choose presses from where the player actually is. Prevents both the
    name-entry END-cursor lock and wall-banging."""
    map_id  = obs["map_id"]
    tx, ty  = obs["tile"]["x"], obs["tile"]["y"]
    blocked = self._blocked_spatial_directions(obs["tile"])

    # name-entry: only A on letter rows; back out (B) on the END row
    if obs["state"] == "NAME_ENTRY":
        if obs["cursor_row"] != NAME_ENTRY_END_ROW:
            return "a"
        return "b"

    # north map-edge exit (Pallet Town -> Route 1)
    if ty <= MAP_EDGE_EXIT_ROW and "n" not in blocked:
        return "up"

    # doorway: align to door tile center, then confirm with A (Oak's Lab)
    door = obs.get("door")
    if door:
        if tx < door["x"]: return "right"
        if tx > door["x"]: return "left"
        if ty < door["y"]: return "down"
        if ty > door["y"]: return "up"
        return "a"

    # generic pathing toward target, honoring blocked directions
    dx, dy = obs["target"]["x"] - tx, obs["target"]["y"] - ty
    if abs(dx) >= abs(dy):
        if dx > 0 and "e" not in blocked: return "right"
        if dx < 0 and "w" not in blocked: return "left"
    if dy < 0 and "n" not in blocked: return "up"
    return "down"

Fix 4 — Recovery resets sticky press counters:

def _reset_recovery_trackers(self):
    """On entering recovery, clear accumulated counters so a stale
    a_press_count can never fire a phantom END/START confirmation."""
    self.a_press_count = 0
    self.b_press_count = 0
    self.stuck_cycles  = 0
    self.last_action   = None

def _on_stuck(self, obs):
    if self.stuck_cycles >= STUCK_THRESHOLD:
        self._enter_recovery()
        self._reset_recovery_trackers()   # <- was missing; a_press_count kept counting