synth-ai 0.2.13.dev1__py3-none-any.whl → 0.2.14__py3-none-any.whl

examples/task_apps/dev/pokemon_emerald/external/pokeagent-speedrun/utils/map_stitcher.py

@@ -0,0 +1,1763 @@
+#!/usr/bin/env python3
+"""
+Map Stitching System for Pokemon Emerald
+
+Connects previously seen map areas with warps and transitions to create
+a unified world map showing connections between routes, towns, and buildings.
+"""
+
+import json
+import logging
+import os
+from typing import Dict, List, Tuple, Optional, Set, Any
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from pokemon_env.enums import MapLocation, MetatileBehavior
+from utils import state_formatter
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class WarpConnection:
+    """Represents a connection between two map areas"""
+    from_map_id: int  # (map_bank << 8) | map_number
+    to_map_id: int
+    from_position: Tuple[int, int]  # Player position when warp triggered
+    to_position: Tuple[int, int]    # Player position after warp
+    warp_type: str  # "door", "stairs", "exit", "route_transition"
+    direction: str  # "north", "south", "east", "west", "up", "down"
+    
+    def get_reverse_connection(self) -> 'WarpConnection':
+        """Get the reverse direction of this warp"""
+        reverse_dirs = {
+            "north": "south", "south": "north",
+            "east": "west", "west": "east", 
+            "up": "down", "down": "up"
+        }
+        return WarpConnection(
+            from_map_id=self.to_map_id,
+            to_map_id=self.from_map_id,
+            from_position=self.to_position,
+            to_position=self.from_position,
+            warp_type=self.warp_type,
+            direction=reverse_dirs.get(self.direction, "unknown")
+        )
+
+@dataclass
+class MapArea:
+    """Represents a single map area with its data"""
+    map_id: int  # (map_bank << 8) | map_number
+    location_name: str
+    map_data: List[List[Tuple]]  # Raw tile data from memory
+    player_last_position: Tuple[int, int]  # Last known player position
+    warp_tiles: List[Tuple[int, int, str]]  # (x, y, warp_type) positions
+    boundaries: Dict[str, int]  # north, south, east, west limits
+    visited_count: int
+    first_seen: float  # timestamp
+    last_seen: float   # timestamp
+    overworld_coords: Optional[Tuple[int, int]] = None  # (X, Y) in overworld coordinate system
+    
+    def get_map_bounds(self) -> Tuple[int, int, int, int]:
+        """Return (min_x, min_y, max_x, max_y) for this map"""
+        height = len(self.map_data)
+        width = len(self.map_data[0]) if height > 0 else 0
+        return (0, 0, width - 1, height - 1)
+    
+    def has_warp_at(self, x: int, y: int) -> Optional[str]:
+        """Check if there's a warp at the given position"""
+        for wx, wy, warp_type in self.warp_tiles:
+            if wx == x and wy == y:
+                return warp_type
+        return None
+
+class MapStitcher:
+    """Main class for managing map stitching and connections"""
+    
+    def __init__(self, save_file: str = None):
+        # Setup cache directory
+        self.cache_dir = ".pokeagent_cache"
+        os.makedirs(self.cache_dir, exist_ok=True)
+        
+        # Use cache folder for default save file
+        if save_file is None:
+            save_file = os.path.join(self.cache_dir, "map_stitcher_data.json")
+        self.save_file = Path(save_file)
+        self.map_areas: Dict[int, MapArea] = {}
+        self.warp_connections: List[WarpConnection] = []
+        self.pending_warps: List[Dict] = []  # Track potential warps
+        self.last_map_id: Optional[int] = None
+        self.last_position: Optional[Tuple[int, int]] = None
+        
+        # Load existing data
+        self.load_from_file()
+    
+    def _merge_map_tiles(self, area: MapArea, new_tiles: List[List[Tuple]], player_pos: Tuple[int, int]):
+        """Merge new tiles into existing map data, building up complete map over time.
+        
+        This is the core stitching logic - it takes the new 15x15 view around
+        the player and merges it into the accumulated map data for this area.
+        """
+        if not new_tiles:
+            return
+            
+        # Get dimensions of new tile data (usually 15x15)
+        new_height = len(new_tiles)
+        new_width = len(new_tiles[0]) if new_tiles else 0
+        
+        if new_height == 0 or new_width == 0:
+            return
+        
+        # Calculate the offset of the new tiles relative to player position
+        # The player is at the center of the new tiles
+        center_y = new_height // 2
+        center_x = new_width // 2
+        
+        # If this is the first data for this area, initialize with a large empty grid
+        if area.map_data is None or not area.map_data:
+            # Create a 100x100 grid initially (can expand as needed)
+            # Use None to indicate unexplored tiles
+            area.map_data = [[None for _ in range(100)] for _ in range(100)]
+            # Track the actual bounds of explored area
+            area.explored_bounds = {
+                'min_x': 50, 'max_x': 50,
+                'min_y': 50, 'max_y': 50
+            }
+            # Place player at center of our coordinate system initially
+            area.origin_offset = {'x': 50 - player_pos[0], 'y': 50 - player_pos[1]}
+            
+        # Ensure origin_offset exists
+        if not hasattr(area, 'origin_offset'):
+            area.origin_offset = {'x': 50 - player_pos[0], 'y': 50 - player_pos[1]}
+        
+        # Get the offset to map player coordinates to our stored grid
+        offset_x = area.origin_offset.get('x', 0)
+        offset_y = area.origin_offset.get('y', 0)
+        
+        # CRITICAL: Check for unreasonable coordinate jumps that indicate a map transition error
+        # If the player position would require massive grid expansion, it's likely a different map
+        grid_center_x = player_pos[0] + offset_x
+        grid_center_y = player_pos[1] + offset_y
+        
+        MAX_REASONABLE_SIZE = 200  # Maximum reasonable size for a single map area
+        
+        # Check if this would cause unreasonable expansion
+        if (grid_center_x < -50 or grid_center_x > MAX_REASONABLE_SIZE + 50 or
+            grid_center_y < -50 or grid_center_y > MAX_REASONABLE_SIZE + 50):
+            logger.warning(f"Detected unreasonable coordinate jump for map {area.map_id:04X}: "
+                         f"player at {player_pos}, grid position would be ({grid_center_x}, {grid_center_y})")
+            logger.warning(f"This likely indicates map areas are being incorrectly merged. "
+                         f"Resetting origin offset for this area.")
+            
+            # Reset the map data for this area to prevent corruption
+            area.map_data = [[None for _ in range(100)] for _ in range(100)]
+            area.explored_bounds = {
+                'min_x': 50, 'max_x': 50,
+                'min_y': 50, 'max_y': 50
+            }
+            area.origin_offset = {'x': 50 - player_pos[0], 'y': 50 - player_pos[1]}
+            offset_x = area.origin_offset['x']
+            offset_y = area.origin_offset['y']
+        
+        # Merge the new tiles into the existing map
+        for dy in range(new_height):
+            for dx in range(new_width):
+                # Calculate the world position of this tile
+                world_x = player_pos[0] - center_x + dx
+                world_y = player_pos[1] - center_y + dy
+                
+                # Calculate the position in our stored grid
+                grid_x = world_x + offset_x
+                grid_y = world_y + offset_y
+                
+                # Sanity check to prevent excessive memory usage
+                if grid_x < 0 or grid_y < 0 or grid_x >= MAX_REASONABLE_SIZE or grid_y >= MAX_REASONABLE_SIZE:
+                    logger.debug(f"Skipping tile at grid position ({grid_x}, {grid_y}) - out of reasonable bounds")
+                    continue
+                
+                # Expand grid if necessary (but within reasonable limits)
+                if grid_y >= len(area.map_data) and grid_y < MAX_REASONABLE_SIZE:
+                    # Expand vertically
+                    expansion_needed = min(grid_y - len(area.map_data) + 1, 
+                                         MAX_REASONABLE_SIZE - len(area.map_data))
+                    for _ in range(expansion_needed):
+                        area.map_data.append([None] * len(area.map_data[0]))
+                
+                if grid_x >= len(area.map_data[0]) and grid_x < MAX_REASONABLE_SIZE:
+                    # Expand horizontally
+                    new_width_needed = min(grid_x + 1, MAX_REASONABLE_SIZE)
+                    for row in area.map_data:
+                        expansion = new_width_needed - len(row)
+                        if expansion > 0:
+                            row.extend([None] * expansion)
+                
+                # Store the tile (always update with latest data)
+                if 0 <= grid_x < len(area.map_data[0]) and 0 <= grid_y < len(area.map_data):
+                    tile = new_tiles[dy][dx]
+                    # Store all tiles including 1023 (which represents walls/boundaries)
+                    # The display logic will handle showing them correctly
+                    if tile:
+                        area.map_data[grid_y][grid_x] = tile
+                        
+                        # Update explored bounds for all tiles including boundaries
+                        # tile_id 1023 represents trees/walls at map edges - we want to include these
+                        tile_id = tile[0] if tile and len(tile) > 0 else None
+                        if tile_id is not None:  # Include all tiles, even 1023
+                            if not hasattr(area, 'explored_bounds'):
+                                area.explored_bounds = {
+                                    'min_x': grid_x, 'max_x': grid_x,
+                                    'min_y': grid_y, 'max_y': grid_y
+                                }
+                            else:
+                                area.explored_bounds['min_x'] = min(area.explored_bounds['min_x'], grid_x)
+                                area.explored_bounds['max_x'] = max(area.explored_bounds['max_x'], grid_x)
+                                area.explored_bounds['min_y'] = min(area.explored_bounds['min_y'], grid_y)
+                                area.explored_bounds['max_y'] = max(area.explored_bounds['max_y'], grid_y)
+    
+    def get_map_id(self, map_bank: int, map_number: int) -> int:
+        """Convert map bank/number to unique ID"""
+        return (map_bank << 8) | map_number
+    
+    def decode_map_id(self, map_id: int) -> Tuple[int, int]:
+        """Convert map ID back to bank/number"""
+        return (map_id >> 8, map_id & 0xFF)
+    
+    def update_save_file(self, new_save_file: str):
+        """Update the save file path and reload data"""
+        self.save_file = Path(new_save_file)
+        # Clear current data and reload from new file
+        self.map_areas = {}
+        self.warp_connections = []
+        self.pending_warps = []
+        self.load_from_file()
+    
+    def update_map_area(self, map_bank: int, map_number: int, location_name: str,
+                       map_data: List[List[Tuple]], player_pos: Tuple[int, int],
+                       timestamp: float, overworld_coords: Optional[Tuple[int, int]] = None):
+        """Update or create a map area with new data"""
+        map_id = self.get_map_id(map_bank, map_number)
+        
+        # Skip map 0 (startup/initialization state) as it's not a real location
+        if map_id == 0:
+            logger.debug(f"Skipping map 0 (startup state)")
+            return
+        
+        # Validate map ID is reasonable
+        if map_id < 0 or map_id > 0xFFFF:
+            logger.error(f"Invalid map ID {map_id} from bank={map_bank}, number={map_number}")
+            return
+        
+        # Validate player position - check for invalid values
+        if player_pos:
+            px, py = player_pos
+            # Check for invalid coordinates (65535 = 0xFFFF is a common error value)
+            if px < 0 or px > 1000 or py < 0 or py > 1000 or px == 0xFFFF or py == 0xFFFF:
+                logger.warning(f"Invalid player position {player_pos} for map {map_id:04X}, ignoring update")
+                return
+        
+        if map_id in self.map_areas:
+            # Update existing area - we're revisiting this location
+            area = self.map_areas[map_id]
+            logger.info(f"Revisiting existing map area {area.location_name} (ID: {map_id:04X})")
+            area.visited_count = getattr(area, 'visited_count', 0) + 1
+            # Update location name if we have a better one (not empty or "Unknown")
+            if location_name and location_name.strip() and location_name != "Unknown":
+                if area.location_name == "Unknown" or not area.location_name:
+                    logger.info(f"Updating location name for map {map_id:04X}: '{area.location_name}' -> '{location_name}'")
+                    area.location_name = location_name
+                    # Try to resolve other unknown names since we got new location info
+                    self.resolve_unknown_location_names()
+                elif area.location_name != location_name:
+                    # Check if this is a significant name difference that might indicate a problem
+                    name1_words = set(area.location_name.lower().split())
+                    name2_words = set(location_name.lower().split())
+                    
+                    # If the names share no common words, this might be a misidentified map
+                    if not name1_words.intersection(name2_words):
+                        logger.warning(f"Significant location name mismatch for map {map_id:04X}: "
+                                     f"existing='{area.location_name}' vs new='{location_name}'. "
+                                     f"This might indicate incorrect map identification.")
+                    else:
+                        logger.info(f"Found different location name for map {map_id:04X}: '{area.location_name}' vs '{location_name}', keeping current")
+                else:
+                    area.location_name = location_name
+            
+            # MERGE map data instead of replacing - this is the key to stitching!
+            if map_data and player_pos:
+                # When revisiting, check if player position makes sense with existing map
+                if hasattr(area, 'origin_offset') and area.origin_offset:
+                    expected_grid_x = player_pos[0] + area.origin_offset['x']
+                    expected_grid_y = player_pos[1] + area.origin_offset['y']
+                    
+                    # Check if player position is reasonable for this map
+                    if (0 <= expected_grid_x <= 200 and 0 <= expected_grid_y <= 200):
+                        # Position is reasonable - merge tiles
+                        self._merge_map_tiles(area, map_data, player_pos)
+                        logger.debug(f"Merged {len(map_data) * len(map_data[0]) if map_data else 0} new tiles into area")
+                    else:
+                        logger.warning(f"Player position {player_pos} seems incorrect for map {map_id:04X} "
+                                     f"(would be at grid {expected_grid_x},{expected_grid_y})")
+                else:
+                    # First visit to this area after loading - merge normally
+                    self._merge_map_tiles(area, map_data, player_pos)
+                    logger.debug(f"Merged {len(map_data) * len(map_data[0]) if map_data else 0} new tiles into area")
+            
+            area.player_last_position = player_pos
+            area.last_seen = timestamp
+            # Remove deprecated fields - keep it simple
+            logger.debug(f"Updated map area {area.location_name} (ID: {map_id:04X})")
+        else:
+            # Create new area
+            # Try to resolve location name from map ID if empty
+            if not location_name or not location_name.strip():
+                # Import and use the location mapping
+                try:
+                    map_enum = MapLocation(map_id)
+                    final_location_name = map_enum.name.replace('_', ' ').title()
+                    logger.info(f"Resolved location name for map {map_id:04X}: {final_location_name}")
+                except ValueError:
+                    # Fallback for unknown map IDs
+                    final_location_name = f"Map_{map_id:04X}"
+                    logger.debug(f"Unknown map ID {map_id:04X}, using fallback name")
+            else:
+                final_location_name = location_name
+            
+            area = MapArea(
+                map_id=map_id,
+                location_name=final_location_name,
+                map_data=None,  # Start with empty data - will be populated by merge
+                player_last_position=player_pos,
+                warp_tiles=[],  # Deprecated - not needed
+                boundaries={"north": 0, "south": 10, "west": 0, "east": 10},  # Simple default
+                visited_count=1,
+                first_seen=timestamp,
+                last_seen=timestamp,
+                overworld_coords=None  # Not needed
+            )
+            self.map_areas[map_id] = area
+            
+            # Now merge the initial tiles
+            if map_data and player_pos:
+                self._merge_map_tiles(area, map_data, player_pos)
+                logger.debug(f"Initialized new area with {len(map_data) * len(map_data[0]) if map_data else 0} tiles")
+            logger.info(f"Added new map area: {final_location_name} (ID: {map_id:04X}) as separate location")
+            
+        # Check for area transitions and potential warp connections
+        # print(f"🔍 Transition check: last_map_id={self.last_map_id}, current_map_id={map_id}, last_pos={self.last_position}, current_pos={player_pos}")
+        if self.last_map_id is not None and self.last_map_id != map_id:
+            logger.info(f"🔄 Map transition detected! {self.last_map_id} -> {map_id}")
+            
+            # Use the last position stored in the previous map area for the from_pos
+            # This is the actual exit point from the previous map
+            from_area = self.map_areas.get(self.last_map_id)
+            from_pos = from_area.player_last_position if from_area else self.last_position
+            
+            logger.info(f"🔄 Warp coordinates: from_pos={from_pos} (exit from map {self.last_map_id}), to_pos={player_pos} (entry to map {map_id})")
+            self._detect_warp_connection(self.last_map_id, map_id, 
+                                       from_pos, player_pos, timestamp)
+            
+            # Try to resolve any unknown location names after adding connections  
+            # Note: resolve_unknown_location_names() can be called with memory_reader from calling code
+            if self.resolve_unknown_location_names():
+                logger.info("Resolved unknown location names after area transition")
+                # Save will be handled by the calling code
+        
+        # Update tracking variables for next iteration
+        if self.last_position != player_pos:
+            self.last_map_id = map_id
+            self.last_position = player_pos
+    
+    def _detect_warp_tiles(self, map_data: List[List[Tuple]]) -> List[Tuple[int, int, str]]:
+        """Detect tiles that can be warps (doors, stairs, exits)"""
+        warp_tiles = []
+        
+        for y, row in enumerate(map_data):
+            for x, tile in enumerate(row):
+                if len(tile) >= 2:
+                    tile_id, behavior = tile[:2]
+                    
+                    if hasattr(behavior, 'name'):
+                        behavior_name = behavior.name
+                    elif isinstance(behavior, int):
+                        try:
+                            behavior_enum = MetatileBehavior(behavior)
+                            behavior_name = behavior_enum.name
+                        except ValueError:
+                            continue
+                    else:
+                        continue
+                    
+                    # Classify warp types
+                    warp_type = None
+                    if "DOOR" in behavior_name:
+                        warp_type = "door"
+                    elif "STAIRS" in behavior_name:
+                        warp_type = "stairs"
+                    elif "WARP" in behavior_name:
+                        warp_type = "warp"
+                    elif x == 0 or x == len(row) - 1 or y == 0 or y == len(map_data) - 1:
+                        # Edge tiles might be exits to other routes/areas
+                        if behavior_name == "NORMAL" and tile[2] == 0:  # collision == 0
+                            warp_type = "exit"
+                    
+                    if warp_type:
+                        warp_tiles.append((x, y, warp_type))
+        
+        return warp_tiles
+    
+    def _calculate_boundaries(self, map_data: List[List[Tuple]]) -> Dict[str, int]:
+        """Calculate walkable boundaries of the map"""
+        height = len(map_data)
+        width = len(map_data[0]) if height > 0 else 0
+        
+        return {
+            "north": 0,
+            "south": height - 1,
+            "west": 0, 
+            "east": width - 1
+        }
+    
+    def _detect_warp_connection(self, from_map_id: int, to_map_id: int,
+                              from_pos: Optional[Tuple[int, int]], 
+                              to_pos: Tuple[int, int], timestamp: float):
+        """Detect and record warp connections between maps"""
+        if from_pos is None:
+            return
+            
+        from_area = self.map_areas.get(from_map_id)
+        to_area = self.map_areas.get(to_map_id)
+        
+        if not from_area or not to_area:
+            return
+        
+        # Determine warp type and direction
+        warp_type = "route_transition"  # default
+        direction = self._determine_warp_direction(from_area, to_area, from_pos, to_pos)
+        
+        # Check if we were near a warp tile
+        near_warp = from_area.has_warp_at(from_pos[0], from_pos[1])
+        if near_warp:
+            warp_type = near_warp
+        
+        # Create the connection
+        print(f"🔄 Creating warp connection: {from_pos} -> {to_pos} (maps {from_map_id} -> {to_map_id})")
+        connection = WarpConnection(
+            from_map_id=from_map_id,
+            to_map_id=to_map_id,
+            from_position=from_pos,
+            to_position=to_pos,
+            warp_type=warp_type,
+            direction=direction
+        )
+        
+        # Check if this connection already exists
+        if not self._connection_exists(connection):
+            self.warp_connections.append(connection)
+            print(f"Added warp connection: {from_area.location_name} -> {to_area.location_name} "
+                       f"({warp_type}, {direction})")
+            
+            # Auto-add reverse connection for two-way warps
+            if warp_type in ["door", "stairs", "route_transition"]:
+                reverse = connection.get_reverse_connection()
+                if not self._connection_exists(reverse):
+                    self.warp_connections.append(reverse)
+                    logger.debug(f"Added reverse connection: {to_area.location_name} -> {from_area.location_name}")
+    
+    def _determine_warp_direction(self, from_area: MapArea, to_area: MapArea,
+                                from_pos: Tuple[int, int], to_pos: Tuple[int, int]) -> str:
+        """Determine the direction of movement for a warp"""
+        from_x, from_y = from_pos
+        to_x, to_y = to_pos
+        
+        # Check if this is a vertical building transition (indoors <-> outdoors)
+        from_indoor = from_area.location_name and ("HOUSE" in from_area.location_name.upper() or "ROOM" in from_area.location_name.upper())
+        to_indoor = to_area.location_name and ("HOUSE" in to_area.location_name.upper() or "ROOM" in to_area.location_name.upper())
+        
+        if from_indoor and not to_indoor:
+            return "down"  # Exiting building
+        elif not from_indoor and to_indoor:
+            return "up"    # Entering building
+        
+        # For horizontal transitions, compare positions
+        from_bounds = from_area.get_map_bounds()
+        to_bounds = to_area.get_map_bounds()
+        
+        # Simple heuristic based on position relative to map center
+        from_center_x = (from_bounds[2] - from_bounds[0]) // 2
+        from_center_y = (from_bounds[3] - from_bounds[1]) // 2
+        
+        if from_x < from_center_x:
+            return "west"
+        elif from_x > from_center_x:
+            return "east"
+        elif from_y < from_center_y:
+            return "north"
+        else:
+            return "south"
+    
+    def _connection_exists(self, connection: WarpConnection) -> bool:
+        """Check if a similar connection already exists"""
+        for existing in self.warp_connections:
+            if (existing.from_map_id == connection.from_map_id and
+                existing.to_map_id == connection.to_map_id and
+                existing.warp_type == connection.warp_type):
+                return True
+        return False
+    
+    def _infer_overworld_coordinates(self, location_name: str, player_pos: Tuple[int, int]) -> Optional[Tuple[int, int]]:
+        """Infer overworld coordinates - should return None to keep coordinates unknown until discovered"""
+        # All coordinates start as unknown (?, ?) until actually discovered
+        # This ensures authentic exploration without pre-existing knowledge
+        return None
+    
+    def update_overworld_coordinates(self, map_id: int, coords: Tuple[int, int]):
+        """Update overworld coordinates for a discovered area"""
+        if map_id in self.map_areas:
+            self.map_areas[map_id].overworld_coords = coords
+            logger.info(f"Updated coordinates for {self.map_areas[map_id].location_name}: {coords}")
+    
+    def update_location_name(self, map_id: int, location_name: str):
+        """Update location name for an existing area"""
+        if map_id in self.map_areas and location_name and location_name.strip() and location_name != "Unknown":
+            area = self.map_areas[map_id]
+            if area.location_name == "Unknown" or not area.location_name:
+                logger.info(f"Updating location name for map {map_id:04X}: '{area.location_name}' -> '{location_name}'")
+                area.location_name = location_name
+                # Try to resolve other unknown names since we got new location info
+                self.resolve_unknown_location_names()
+                return True
+        return False
+    
+    def resolve_unknown_location_names(self, memory_reader=None):
+        """Try to resolve 'Unknown' location names using the memory reader if available"""
+        resolved_count = 0
+        
+        # If we have a memory reader, we can potentially resolve current location
+        if memory_reader is not None:
+            try:
+                current_location = memory_reader.read_location()
+                current_map_bank = memory_reader._read_u8(memory_reader.addresses.MAP_BANK)
+                current_map_number = memory_reader._read_u8(memory_reader.addresses.MAP_NUMBER)
+                current_map_id = (current_map_bank << 8) | current_map_number
+                
+                # Update current map if it's unknown
+                if current_map_id in self.map_areas:
+                    area = self.map_areas[current_map_id]
+                    if area.location_name == "Unknown" and current_location and current_location.strip() and current_location != "Unknown":
+                        old_name = area.location_name
+                        area.location_name = current_location
+                        logger.info(f"Resolved current location name for map {current_map_id:04X}: '{old_name}' -> '{area.location_name}'")
+                        resolved_count += 1
+            except Exception as e:
+                logger.debug(f"Could not resolve current location: {e}")
+        
+        if resolved_count > 0:
+            logger.info(f"Resolved {resolved_count} unknown location names")
+            return True
+        return False
+    
+    def get_connected_areas(self, map_id: int) -> List[Tuple[int, str, str]]:
+        """Get all areas connected to the given map ID"""
+        connections = []
+        for conn in self.warp_connections:
+            if conn.from_map_id == map_id:
+                to_area = self.map_areas.get(conn.to_map_id)
+                if to_area:
+                    connections.append((conn.to_map_id, to_area.location_name, conn.direction))
+        return connections
+    
+    def get_world_map_layout(self) -> Dict[str, Any]:
+        """Generate a layout showing how all areas connect"""
+        layout = {
+            "areas": {},
+            "connections": []
+        }
+        
+        # Add all known areas
+        for map_id, area in self.map_areas.items():
+            layout["areas"][f"{map_id:04X}"] = {
+                "name": area.location_name,
+                "position": area.player_last_position,
+                "bounds": area.boundaries,
+                "warp_count": len(area.warp_tiles),
+                "visited_count": area.visited_count
+            }
+        
+        # Add all connections
+        for conn in self.warp_connections:
+            from_area = self.map_areas.get(conn.from_map_id)
+            to_area = self.map_areas.get(conn.to_map_id)
+            if from_area and to_area:
+                layout["connections"].append({
+                    "from": f"{conn.from_map_id:04X}",
+                    "to": f"{conn.to_map_id:04X}",
+                    "from_name": from_area.location_name,
+                    "to_name": to_area.location_name,
+                    "warp_type": conn.warp_type,
+                    "direction": conn.direction,
+                    "from_pos": conn.from_position,
+                    "to_pos": conn.to_position
+                })
+        
+        return layout
+    
+    def get_player_position_for_location(self, location_name: str) -> Optional[Tuple[int, int]]:
+        """Get the last known player position for a specific location.
+        
+        Returns:
+            Tuple of (x, y) coordinates or None if not found or invalid
+        """
+        # Find the map area with this location name
+        for area in self.map_areas.values():
+            if area.location_name and location_name and area.location_name.lower() == location_name.lower():
+                if hasattr(area, 'player_last_position') and area.player_last_position:
+                    px, py = area.player_last_position
+                    # Validate the position
+                    if px >= 0 and px < 1000 and py >= 0 and py < 1000 and px != 0xFFFF and py != 0xFFFF:
+                        return (px, py)
+                break
+        return None
+    
+    def get_location_connections(self, location_name=None):
+        """Get connections for a specific location or all locations.
+        
+        Args:
+            location_name: Optional location name to get connections for.
+                          If None, returns all location connections.
+        
+        Returns:
+            If location_name provided: List of (to_location, from_coords, to_coords) tuples
+            Otherwise: Dict mapping location names to connection lists
+        """
+        location_connections = {}
+        
+        # Process each warp connection
+        for conn in self.warp_connections:
+            from_area = self.map_areas.get(conn.from_map_id)
+            to_area = self.map_areas.get(conn.to_map_id)
+            
+            if from_area and to_area:
+                from_location = from_area.location_name
+                to_location = to_area.location_name
+                
+                # Add forward connection
+                if from_location not in location_connections:
+                    location_connections[from_location] = []
+                
+                # Check if connection already exists
+                exists = False
+                for existing in location_connections[from_location]:
+                    if existing[0] == to_location:
+                        exists = True
+                        break
+                
+                if not exists:
+                    # Use the actual last positions from map areas, not the warp spawn point
+                    # This gives more useful information about where transitions happen
+                    from_pos = list(conn.from_position) if conn.from_position else [1, 1]
+                    to_pos = list(to_area.player_last_position) if to_area.player_last_position else list(conn.to_position)
+                    
+                    location_connections[from_location].append([
+                        to_location,
+                        from_pos,
+                        to_pos
+                    ])
+        
+        # If specific location requested, return just its connections (case-insensitive)
+        if location_name:
+            # Try to find the location with case-insensitive matching
+            for loc_name, connections in location_connections.items():
+                if loc_name and loc_name.lower() == location_name.lower():
+                    return connections
+            return []
+        
+        return location_connections
+    
+    def get_location_grid(self, location_name: str, simplified: bool = True) -> Dict[Tuple[int, int], str]:
+        """Get a simplified grid representation of a location for display.
+        
+        Args:
+            location_name: Name of the location to get grid for
+            simplified: If True, return simplified symbols (., #, D, etc.), otherwise raw tile data
+            
+        Returns:
+            Dictionary mapping (x, y) coordinates to tile symbols
+        """
+        # Find the map area with this location name (case-insensitive)
+        map_area = None
+        for area in self.map_areas.values():
+            if area.location_name and location_name and area.location_name.lower() == location_name.lower():
+                map_area = area
+                break
+        
+        if not map_area:
+            # Debug: print available locations
+            logger.debug(f"Could not find map area for '{location_name}'")
+            logger.debug(f"Available locations: {[a.location_name for a in self.map_areas.values() if a.location_name][:5]}")
+            return {}
+        
+        if not map_area.map_data:
+            logger.debug(f"Map area found for '{location_name}' but has no map_data")
+            return {}
+        
+        grid = {}
+        
+        # If we have explored bounds, use them to extract only the explored portion
+        if hasattr(map_area, 'explored_bounds'):
+            bounds = map_area.explored_bounds
+            for y in range(bounds['min_y'], bounds['max_y'] + 1):
+                for x in range(bounds['min_x'], bounds['max_x'] + 1):
+                    if y < len(map_area.map_data) and x < len(map_area.map_data[0]):
+                        tile = map_area.map_data[y][x]
+                        if tile is not None:  # Only include explored tiles
+                            # Adjust coordinates to be relative to the explored area
+                            rel_x = x - bounds['min_x']
+                            rel_y = y - bounds['min_y']
+                            
+                            if simplified:
+                                # Convert to simplified symbol
+                                symbol = self._tile_to_symbol(tile)
+                                if symbol is not None:  # Only add if it's a valid tile
+                                    # Debug specific problematic position
+                                    if rel_x == 2 and rel_y == 1:
+                                        logger.debug(f"Tile at rel(2,1) from grid[{y}][{x}]: {tile[:3] if len(tile) >= 3 else tile} -> symbol '{symbol}'")
+                                    grid[(rel_x, rel_y)] = symbol
+                            else:
+                                grid[(rel_x, rel_y)] = tile
+            
+            # Add '?' for unexplored but adjacent tiles
+            if simplified:
+                # Find all positions adjacent to explored walkable tiles
+                to_check = set()
+                for (x, y), symbol in list(grid.items()):
+                    # Only add ? next to truly walkable tiles, not walls
+                    if symbol in ['.', 'D', 'S', '^', '~', 's', 'I',  # Walkable terrain
+                                  '→', '←', '↑', '↓', '↗', '↖', '↘', '↙']:  # Ledges
+                        # Check all 4 adjacent positions (not diagonal)
+                        for dx, dy in [(0, 1), (0, -1), (1, 0), (-1, 0)]:
+                            adj_pos = (x + dx, y + dy)
+                            if adj_pos not in grid:
+                                to_check.add(adj_pos)
+                
+                # Add '?' for these unexplored adjacent positions
+                for pos in to_check:
+                    grid[pos] = '?'
+            
+            return grid
+        
+        # Fallback: old logic for non-accumulated maps
+        # Check if we should extract a focused area from the stored map
+        extract_bounds = getattr(map_area, '_display_extract_bounds', None)
+        if extract_bounds:
+            extract_start_x, extract_start_y, display_size = extract_bounds
+            # Extract only the specified area
+            for y in range(display_size):
+                for x in range(display_size):
+                    stored_y = extract_start_y + y
+                    stored_x = extract_start_x + x
+                    if (stored_y < len(map_area.map_data) and 
+                        stored_x < len(map_area.map_data[stored_y])):
+                        tile = map_area.map_data[stored_y][stored_x]
+                        if tile and len(tile) >= 3:
+                            tile_id, behavior, collision = tile[:3]
+                            
+                            if simplified:
+                                # Use the centralized tile_to_symbol function
+                                symbol = self._tile_to_symbol(tile)
+                                if symbol is not None:  # Only add if it's a valid tile
+                                    grid[(x, y)] = symbol
+                            else:
+                                # Return raw tile data
+                                grid[(x, y)] = tile
+        else:
+            # Use full stored map (fallback for old behavior)
+            for y, row in enumerate(map_area.map_data):
+                for x, tile in enumerate(row):
+                    if tile and len(tile) >= 3:
+                        tile_id, behavior, collision = tile[:3]
+                        
+                        if simplified:
+                            # Use the centralized tile_to_symbol function
+                            symbol = self._tile_to_symbol(tile)
+                            if symbol is not None:  # Only add if it's a valid tile
+                                grid[(x, y)] = symbol
+                        else:
+                            # Return raw tile data
+                            grid[(x, y)] = tile
+        
+        return grid
+    
+    def get_all_location_grids(self, simplified: bool = True) -> Dict[str, Dict[Tuple[int, int], str]]:
+        """Get grids for all known locations.
+        
+        Returns:
+            Dictionary mapping location names to their grids
+        """
+        all_grids = {}
+        for area in self.map_areas.values():
+            if area.location_name and area.map_data:
+                all_grids[area.location_name] = self.get_location_grid(area.location_name, simplified)
+        return all_grids
+    
+    def save_to_file(self):
+        """Save stitching data to JSON file"""
+        try:
+            data = {
+                "map_areas": {},
+                "location_connections": {}
+            }
+            
+            # Convert map areas to serializable format
+            for map_id, area in self.map_areas.items():
+                # Trim null rows from map_data before saving
+                if area.map_data:
+                    trimmed_map_data, trim_offsets = self._trim_null_rows(area.map_data)
+                else:
+                    trimmed_map_data, trim_offsets = [], {}
+                
+                # Save only essential data
+                area_data = {
+                    "map_id": area.map_id,
+                    "location_name": area.location_name,
+                    "map_data": trimmed_map_data,
+                    "player_last_position": area.player_last_position
+                }
+                
+                # Save trim offsets if we trimmed the data
+                if trim_offsets:
+                    area_data["trim_offsets"] = trim_offsets
+                
+                # Save additional attributes for map stitching
+                if hasattr(area, 'explored_bounds'):
+                    area_data["explored_bounds"] = area.explored_bounds
+                if hasattr(area, 'origin_offset'):
+                    area_data["origin_offset"] = area.origin_offset
+                data["map_areas"][str(map_id)] = area_data
+            
+            # Generate location_connections from warp_connections
+            # MapStitcher is the single source of truth for connections
+            data["location_connections"] = self.get_location_connections()
+            logger.debug(f"Saved {len(data['location_connections'])} location connections from {len(self.warp_connections)} warp connections")
+            
+            with open(self.save_file, 'w') as f:
+                # Save in minified format to reduce file size
+                json.dump(data, f, separators=(',', ':'))
+            
+            logger.debug(f"Saved map stitching data to {self.save_file}")
+            
+        except Exception as e:
+            logger.error(f"Failed to save map stitching data: {e}")
+    
+    def load_from_file(self):
+        """Load stitching data from JSON file"""
+        if not self.save_file.exists():
+            return
+        
+        # Check if file is empty
+        if self.save_file.stat().st_size == 0:
+            logger.debug(f"Map stitcher file {self.save_file} is empty, starting fresh")
+            return
+            
+        try:
+            with open(self.save_file, 'r') as f:
+                data = json.load(f)
+            
+            # Add loaded data to existing map areas (accumulate knowledge)
+            # Restore map areas (with map_data for world map display)
+            for map_id_str, area_data in data.get("map_areas", {}).items():
+                map_id = int(map_id_str)
+                
+                # Skip map 0 during loading as well (cleanup old data)
+                if map_id == 0:
+                    logger.debug(f"Skipping load of map 0 (startup state) during file load")
+                    continue
+                    
+                # Try to resolve location name if it's Unknown or missing
+                location_name = area_data.get("location_name")
+                if not location_name or location_name == "Unknown":
+                    # Import and use the location mapping
+                    try:
+                        map_enum = MapLocation(map_id)
+                        location_name = map_enum.name.replace('_', ' ').title()
+                        logger.info(f"Resolved location name for map {map_id:04X} during load: {location_name}")
+                    except ValueError:
+                        # Fallback for unknown map IDs
+                        location_name = f"Map_{map_id:04X}"
+                        logger.debug(f"Unknown map ID {map_id:04X} during load, using fallback name")
+                
+                # Reconstruct full map data from trimmed version
+                trimmed_data = area_data.get("map_data", [])
+                trim_offsets = area_data.get("trim_offsets", {})
+                
+                if trim_offsets and trim_offsets.get('compacted'):
+                    # New compacted format - reconstruct from tile list
+                    row_offset = trim_offsets.get('row_offset', 0)
+                    col_offset = trim_offsets.get('col_offset', 0)
+                    original_height = trim_offsets.get('original_height', 100)
+                    original_width = trim_offsets.get('original_width', 100)
+                    
+                    # Create full-sized map data array
+                    full_map_data = [[None for _ in range(original_width)] for _ in range(original_height)]
+                    
+                    # Restore tiles from compacted format
+                    if isinstance(trimmed_data, list):
+                        # New list format: [[rel_row, rel_col, tile], ...]
+                        for item in trimmed_data:
+                            if len(item) >= 3:
+                                rel_row, rel_col, tile = item[0], item[1], item[2]
+                                actual_row = row_offset + rel_row
+                                actual_col = col_offset + rel_col
+                                if actual_row < original_height and actual_col < original_width:
+                                    full_map_data[actual_row][actual_col] = tile
+                    elif isinstance(trimmed_data, dict) and 'tiles' in trimmed_data:
+                        # Old dict format (backward compatibility)
+                        for pos_key, tile in trimmed_data['tiles'].items():
+                            rel_row, rel_col = map(int, pos_key.split(','))
+                            actual_row = row_offset + rel_row
+                            actual_col = col_offset + rel_col
+                            if actual_row < original_height and actual_col < original_width:
+                                full_map_data[actual_row][actual_col] = tile
+                    
+                    map_data = full_map_data
+                elif trimmed_data and trim_offsets:
+                    # Old trimmed format (backward compatibility)
+                    row_offset = trim_offsets.get('row_offset', 0)
+                    col_offset = trim_offsets.get('col_offset', 0)
+                    original_height = trim_offsets.get('original_height', len(trimmed_data) + row_offset)
+                    original_width = trim_offsets.get('original_width', 100)
+                    
+                    # Create full-sized map data array
+                    full_map_data = [[None for _ in range(original_width)] for _ in range(original_height)]
+                    
+                    # Place trimmed data back at correct position
+                    for i, row in enumerate(trimmed_data):
+                        for j, tile in enumerate(row):
+                            if tile is not None:
+                                full_map_data[row_offset + i][col_offset + j] = tile
+                    
+                    map_data = full_map_data
+                else:
+                    # No trim offsets, use data as-is (backward compatibility)
+                    map_data = trimmed_data
+                
+                # Validate and clean player position when loading
+                player_pos_data = area_data.get("player_last_position", [0, 0])
+                if player_pos_data:
+                    px, py = player_pos_data[0], player_pos_data[1] if len(player_pos_data) > 1 else 0
+                    # Clean up invalid positions (65535 = 0xFFFF is an error value)
+                    if px < 0 or px > 1000 or py < 0 or py > 1000 or px == 0xFFFF or py == 0xFFFF:
+                        logger.warning(f"Cleaning invalid player position {player_pos_data} for map {map_id:04X}")
+                        player_pos_data = [0, 0]  # Reset to origin
+                else:
+                    player_pos_data = [0, 0]
+                
+                area = MapArea(
+                    map_id=area_data["map_id"],
+                    location_name=location_name,
+                    map_data=map_data,
+                    player_last_position=tuple(player_pos_data),
+                    warp_tiles=[],  # Deprecated - not needed
+                    boundaries={"north": 0, "south": 10, "west": 0, "east": 10},  # Default boundaries
+                    visited_count=1,  # Default
+                    first_seen=0,  # Default
+                    last_seen=0,  # Default
+                    overworld_coords=None  # Not needed
+                )
+                # Restore additional stitching attributes if present
+                if "explored_bounds" in area_data:
+                    area.explored_bounds = area_data["explored_bounds"]
+                    # When loading trimmed data, adjust explored_bounds to match
+                    # Since we trimmed null rows/columns, the bounds are now relative to the trimmed data
+                    if area.map_data:
+                        # The trimmed data starts at (0,0), so adjust bounds accordingly
+                        actual_height = len(area.map_data)
+                        actual_width = max(len(row) for row in area.map_data) if area.map_data else 0
+                        # Keep the existing explored_bounds as they track the original coordinate space
+                        # The map_data is now compact but explored_bounds maintains the relationship
+                else:
+                    # Initialize explored bounds from map data if not present
+                    if area.map_data:
+                        min_x, max_x = 100, 0
+                        min_y, max_y = 100, 0
+                        for y, row in enumerate(area.map_data):
+                            for x, tile in enumerate(row):
+                                if tile is not None:
+                                    min_x = min(min_x, x)
+                                    max_x = max(max_x, x)
+                                    min_y = min(min_y, y)
+                                    max_y = max(max_y, y)
+                        if min_x <= max_x:
+                            area.explored_bounds = {
+                                'min_x': min_x, 'max_x': max_x,
+                                'min_y': min_y, 'max_y': max_y
+                            }
+                
+                if "origin_offset" in area_data:
+                    area.origin_offset = area_data["origin_offset"]
+                else:
+                    # Initialize origin offset based on player position
+                    if area.player_last_position:
+                        # Assume player was at center of initial explored area
+                        area.origin_offset = {'x': 50 - area.player_last_position[0], 
+                                             'y': 50 - area.player_last_position[1]}
+                self.map_areas[map_id] = area
+                # Debug: log if map_data was loaded
+                if area.map_data:
+                    logger.debug(f"Loaded map_data for {location_name}: {len(area.map_data)}x{len(area.map_data[0]) if area.map_data else 0}")
+            
+            # Reconstruct warp_connections from location_connections
+            location_connections = data.get("location_connections", {})
+            
+            # Clear existing warp connections to avoid duplicates
+            self.warp_connections = []
+            
+            # Convert location_connections back to warp_connections
+            for from_location, connections in location_connections.items():
+                # Find the map_id for this location
+                from_map_id = None
+                for map_id, area in self.map_areas.items():
+                    if area.location_name == from_location:
+                        from_map_id = map_id
+                        break
+                
+                if from_map_id is None:
+                    continue
+                
+                for conn_data in connections:
+                    to_location = conn_data[0]
+                    from_pos = tuple(conn_data[1]) if len(conn_data) > 1 else (0, 0)
+                    to_pos = tuple(conn_data[2]) if len(conn_data) > 2 else (0, 0)
+                    
+                    # Find the map_id for the destination
+                    to_map_id = None
+                    for map_id, area in self.map_areas.items():
+                        if area.location_name == to_location:
+                            to_map_id = map_id
+                            break
+                    
+                    if to_map_id is None:
+                        continue
+                    
+                    # Create warp connection
+                    warp_conn = WarpConnection(
+                        from_map_id=from_map_id,
+                        to_map_id=to_map_id,
+                        from_position=from_pos,
+                        to_position=to_pos,
+                        warp_type="stairs",  # Default type
+                        direction=None
+                    )
+                    self.warp_connections.append(warp_conn)
+            
+            logger.info(f"Reconstructed {len(self.warp_connections)} warp connections from {len(location_connections)} location connections")
+            
+            logger.info(f"Loaded {len(self.map_areas)} areas and {len(self.warp_connections)} connections")
+            
+            # Try to resolve any "Unknown" location names
+            if self.resolve_unknown_location_names():
+                # Save the updated names
+                self.save_to_file()
+            
+        except Exception as e:
+            logger.error(f"Failed to load map stitching data: {e}")
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics about the stitched world map"""
+        indoor_areas = sum(1 for area in self.map_areas.values() 
+                          if area.location_name and ("HOUSE" in area.location_name.upper() or "ROOM" in area.location_name.upper()))
+        outdoor_areas = len(self.map_areas) - indoor_areas
+        
+        warp_types = {}
+        for conn in self.warp_connections:
+            warp_types[conn.warp_type] = warp_types.get(conn.warp_type, 0) + 1
+        
+        return {
+            "total_areas": len(self.map_areas),
+            "indoor_areas": indoor_areas,
+            "outdoor_areas": outdoor_areas,
+            "total_connections": len(self.warp_connections),
+            "warp_types": warp_types,
+            "most_visited": max(self.map_areas.values(), key=lambda a: a.visited_count).location_name if self.map_areas else None
+        }
+    
+    def generate_world_map_grid(self, current_map_id: Optional[int] = None) -> Dict[str, Any]:
+        """Generate a world map grid showing discovered areas and connections"""
+        # Define world map bounds (rough Pokemon Emerald overworld size)
+        map_width = 50
+        map_height = 35
+        
+        # Initialize empty grid
+        grid = [['.' for _ in range(map_width)] for _ in range(map_height)]
+        area_labels = {}
+        
+        # Place discovered areas on the grid
+        for map_id, area in self.map_areas.items():
+            coords = area.overworld_coords
+            if coords is None:
+                continue  # Skip areas without known coordinates
+                
+            x, y = coords
+            if 0 <= x < map_width and 0 <= y < map_height:
+                # Determine symbol based on area type
+                name = area.location_name.upper() if area.location_name else "UNKNOWN"
+                if any(keyword in name for keyword in ["HOUSE", "CENTER", "MART", "GYM", "ROOM"]):
+                    symbol = "H"  # Houses/buildings
+                elif "ROUTE" in name:
+                    symbol = "R"  # Routes
+                elif any(keyword in name for keyword in ["TOWN", "CITY"]):
+                    symbol = "T"  # Towns/cities
+                else:
+                    symbol = "?"  # Unknown/other
+                
+                # Mark current player location
+                if map_id == current_map_id:
+                    symbol = "P"  # Player
+                
+                grid[y][x] = symbol
+                
+                # Store area name for reference
+                area_labels[f"{x},{y}"] = area.location_name
+        
+        # Add connection lines between areas
+        for conn in self.warp_connections:
+            from_area = self.map_areas.get(conn.from_map_id)
+            to_area = self.map_areas.get(conn.to_map_id)
+            
+            if (from_area and to_area and 
+                from_area.overworld_coords and to_area.overworld_coords):
+                
+                from_x, from_y = from_area.overworld_coords
+                to_x, to_y = to_area.overworld_coords
+                
+                # Draw simple connection line (just mark endpoints for now)
+                # In a more sophisticated version, we could draw actual paths
+                if (0 <= from_x < map_width and 0 <= from_y < map_height and
+                    0 <= to_x < map_width and 0 <= to_y < map_height):
+                    
+                    # Mark connection endpoints if they're empty
+                    if grid[from_y][from_x] == '.':
+                        grid[from_y][from_x] = "+"
+                    if grid[to_y][to_x] == '.':
+                        grid[to_y][to_x] = "+"
+        
+        return {
+            "grid": grid,
+            "width": map_width,
+            "height": map_height,
+            "area_labels": area_labels,
+            "legend": {
+                "P": "Current Player Location",
+                "T": "Town/City", 
+                "R": "Route",
+                "H": "House/Building",
+                "+": "Connection Point",
+                ".": "Unexplored",
+                "?": "Other Area"
+            }
+        }
+    
+    def _should_trim_edge(self, tiles, is_row=True):
+        """Check if an edge (row or column) should be trimmed.
+        An edge should be trimmed if it's all walls (#) with no meaningful content."""
+        # Count non-wall tiles
+        non_wall_count = 0
+        for tile in tiles:
+            if tile and tile not in ['#', ' ', None]:
+                non_wall_count += 1
+        # Trim if it's all walls or mostly walls with no content
+        return non_wall_count == 0
+    
+    def _trim_null_rows(self, map_data: List[List]) -> Tuple[List[List], Dict[str, int]]:
+        """Trim rows that are entirely null/None from map data to reduce file size.
+        
+        Returns a tuple of (trimmed_data, trim_offsets) where trim_offsets contains
+        the offsets needed to reconstruct original positions.
+        """
+        if not map_data:
+            return [], {}
+        
+        # Find bounds of actual data
+        start_row = None
+        end_row = None
+        start_col = None
+        end_col = None
+        
+        # Find row bounds
+        for i, row in enumerate(map_data):
+            if row and any(tile is not None for tile in row):
+                if start_row is None:
+                    start_row = i
+                end_row = i
+        
+        if start_row is None:
+            # All data is null
+            return [], {}
+        
+        # Find column bounds across all rows
+        for row in map_data[start_row:end_row + 1]:
+            if row:
+                for j, tile in enumerate(row):
+                    if tile is not None:
+                        if start_col is None or j < start_col:
+                            start_col = j
+                        if end_col is None or j > end_col:
+                            end_col = j
+        
+        if start_col is None:
+            return [], {}
+        
+        # Create compacted data - use a list of [row, col, tile] to save space
+        # This eliminates ALL null-only rows while preserving position information
+        tiles_list = []
+        
+        # Store only non-null tiles with their positions
+        for i in range(start_row, end_row + 1):
+            if map_data[i]:
+                for j in range(start_col, end_col + 1):
+                    if j < len(map_data[i]) and map_data[i][j] is not None:
+                        # Store as [relative_row, relative_col, tile_data]
+                        # This is more compact than dict with string keys
+                        rel_row = i - start_row
+                        rel_col = j - start_col
+                        tiles_list.append([rel_row, rel_col, map_data[i][j]])
+        
+        trim_offsets = {
+            'row_offset': start_row,
+            'col_offset': start_col,
+            'original_height': len(map_data),
+            'original_width': max(len(row) for row in map_data) if map_data else 0,
+            'compacted': True  # Flag to indicate new format
+        }
+        
+        return tiles_list, trim_offsets
+    
+    def generate_location_map_display(self, location_name: str, player_pos: Tuple[int, int] = None, 
+                                      npcs: List[Dict] = None, connections: List[Dict] = None) -> List[str]:
+        """Generate a detailed map display for a specific location.
+        
+        Args:
+            location_name: Name of the location to display
+            player_pos: Current player position (x, y)
+            npcs: List of NPC positions and data
+            connections: List of location connections
+            
+        Returns:
+            List of display lines ready for formatting
+        """
+        lines = []
+        
+        # Get stored map data for this location
+        location_grid = self.get_location_grid(location_name, simplified=True)
+        
+        if not location_grid:
+            # No map data available - return empty to trigger memory fallback
+            return []
+        
+        # For accumulated maps, show the full explored area
+        # Get the dimensions of the explored area
+        max_x = max(x for x, y in location_grid.keys()) if location_grid else 0
+        max_y = max(y for x, y in location_grid.keys()) if location_grid else 0
+        min_x = min(x for x, y in location_grid.keys()) if location_grid else 0
+        min_y = min(y for x, y in location_grid.keys()) if location_grid else 0
+        
+        explored_width = max_x - min_x + 1
+        explored_height = max_y - min_y + 1
+        
+        # Show the full accumulated map (up to reasonable size)
+        # Don't try to focus on player for accumulated maps
+        if explored_width <= 30 and explored_height <= 30:
+            # Show the entire accumulated map
+            display_radius = max(explored_width, explored_height) // 2
+            display_size = max(explored_width, explored_height)
+        else:
+            # Very large area, limit to 30x30 for readability
+            display_radius = 15
+            display_size = 30
+        
+        display_center = display_radius  # Player at center
+        
+        # For accumulated maps, just use the entire grid without focusing
+        # This shows the full explored area
+        all_positions = list(location_grid.keys())
+        
+        # Find player position in the grid if available
+        local_player_pos = None
+        if player_pos:
+            # Validate player position first
+            px, py = player_pos
+            if px >= 0 and px < 1000 and py >= 0 and py < 1000 and px != 0xFFFF and py != 0xFFFF:
+                # Find the stored map area to get coordinate conversion info
+                map_area = None
+                for area in self.map_areas.values():
+                    if area.location_name and location_name and area.location_name.lower() == location_name.lower():
+                        map_area = area
+                        break
+                
+                if map_area:
+                    # Use the stored player position from the map area if available
+                    if hasattr(map_area, 'player_last_position') and map_area.player_last_position:
+                        last_px, last_py = map_area.player_last_position
+                        # Validate the stored position
+                        if last_px >= 0 and last_px < 1000 and last_py >= 0 and last_py < 1000 and last_px != 0xFFFF and last_py != 0xFFFF:
+                            player_pos = map_area.player_last_position
+                            px, py = player_pos
+                    
+                    if hasattr(map_area, 'origin_offset') and map_area.origin_offset:
+                        # Convert player world coordinates to grid-relative coordinates
+                        offset_x = map_area.origin_offset.get('x', 0)
+                        offset_y = map_area.origin_offset.get('y', 0)
+                        
+                        # Calculate player's position relative to the explored bounds
+                        grid_player_x = px + offset_x
+                        grid_player_y = py + offset_y
+                        
+                        # Convert to relative coordinates in the location_grid
+                        if hasattr(map_area, 'explored_bounds'):
+                            bounds = map_area.explored_bounds
+                            rel_x = grid_player_x - bounds['min_x']
+                            rel_y = grid_player_y - bounds['min_y']
+                            
+                            # Check if player is within the displayed area
+                            if 0 <= rel_x <= (max_x - min_x) and 0 <= rel_y <= (max_y - min_y):
+                                local_player_pos = (rel_x, rel_y)
+                                logger.debug(f"Player at relative position {local_player_pos} in {location_name}")
+                            else:
+                                logger.debug(f"Player at {player_pos} is outside displayed area of {location_name}")
+        
+        if not all_positions:
+            return []
+        
+        min_x = min(pos[0] for pos in all_positions)
+        max_x = max(pos[0] for pos in all_positions)
+        min_y = min(pos[1] for pos in all_positions)
+        max_y = max(pos[1] for pos in all_positions)
+        
+        # Minimal trimming - only remove completely empty space
+        # Don't trim '?' as those are unexplored areas we want to show
+        # Don't aggressively trim walls as they show room boundaries
+        
+        # Only trim rows that are completely empty (all spaces/None)
+        while min_y < max_y:
+            row_tiles = [location_grid.get((x, min_y), ' ') for x in range(min_x, max_x + 1)]
+            # Keep the row if it has ANY content (including ? and #)
+            if any(t not in [' ', None] for t in row_tiles):
+                break
+            min_y += 1
+        
+        # Check bottom rows - only trim completely empty
+        while max_y > min_y:
+            row_tiles = [location_grid.get((x, max_y), ' ') for x in range(min_x, max_x + 1)]
+            if any(t not in [' ', None] for t in row_tiles):
+                break
+            max_y -= 1
+        
+        # Check left columns - only trim completely empty
+        while min_x < max_x:
+            col_tiles = [location_grid.get((min_x, y), ' ') for y in range(min_y, max_y + 1)]
+            if any(t not in [' ', None] for t in col_tiles):
+                break
+            min_x += 1
+        
+        # Check right columns - only trim completely empty
+        while max_x > min_x:
+            col_tiles = [location_grid.get((max_x, y), ' ') for y in range(min_y, max_y + 1)]
+            if any(t not in [' ', None] for t in col_tiles):
+                break
+            max_x -= 1
+        
+        # Build portal positions from connections
+        portal_positions = {}
+        
+        lines.append(f"\n--- MAP: {location_name.upper()} ---")
+        
+        # Create the map display
+        for y in range(min_y, max_y + 1):
+            row = ""
+            for x in range(min_x, max_x + 1):
+                # Check if this is an edge position
+                is_edge = (x == min_x or x == max_x or y == min_y or y == max_y)
+                
+                # Check for NPCs at this position
+                npc_at_pos = None
+                if npcs:
+                    for npc in npcs:
+                        npc_x = npc.get('current_x', npc.get('x'))
+                        npc_y = npc.get('current_y', npc.get('y'))
+                        if npc_x == x and npc_y == y:
+                            npc_at_pos = npc
+                            break
+                
+                if local_player_pos and (x, y) == local_player_pos:
+                    row += "P"
+                elif npc_at_pos:
+                    row += "N"
+                elif (x, y) in location_grid:
+                    tile = location_grid[(x, y)]
+                    # Check for portal markers at edges
+                    if is_edge and tile == '.' and connections:
+                        portal_added = False
+                        for conn in connections:
+                            direction = conn.get('direction', '').lower()
+                            conn_name = conn.get('name', '')
+                            if direction and conn_name and conn_name not in ['Unknown', 'None', '']:
+                                if direction == 'east' and x == max_x:
+                                    row += "→"
+                                    portal_positions[(x, y)] = conn_name
+                                    portal_added = True
+                                    break
+                                elif direction == 'west' and x == min_x:
+                                    row += "←"
+                                    portal_positions[(x, y)] = conn_name
+                                    portal_added = True
+                                    break
+                                elif direction == 'north' and y == min_y:
+                                    row += "↑"
+                                    portal_positions[(x, y)] = conn_name
+                                    portal_added = True
+                                    break
+                                elif direction == 'south' and y == max_y:
+                                    row += "↓"
+                                    portal_positions[(x, y)] = conn_name
+                                    portal_added = True
+                                    break
+                        
+                        if not portal_added:
+                            row += tile
+                    else:
+                        row += tile
+                else:
+                    # Position not in grid - just show as space
+                    # The grid already has '?' symbols where needed from get_location_grid
+                    row += " "
+            
+            # Add spacing between characters for square aspect ratio
+            # Most terminals have characters ~2x taller than wide, so spacing helps
+            spaced_row = " ".join(row)
+            lines.append(spaced_row)
+        
+        # Add legend
+        legend_lines = ["", "Legend:"]
+        legend_lines.append("  Movement: P=Player")
+        if npcs:
+            legend_lines.append("            N=NPC/Trainer")
+        
+        # Check what terrain symbols are visible
+        visible_symbols = set(location_grid.values())
+        
+        terrain_items = []
+        symbol_meanings = {
+            ".": ".=Walkable path",
+            "#": "#=Wall/Blocked",
+            "~": "~=Tall grass",
+            "^": "^=Grass",
+            "W": "W=Water",
+            "I": "I=Ice",
+            "s": "s=Sand",
+            "D": "D=Door",
+            "S": "S=Stairs/Ladder",
+            "C": "C=Computer/PC",
+            "→": "→=Ledge (jump east)",
+            "←": "←=Ledge (jump west)",
+            "↑": "↑=Ledge (jump north)",
+            "↓": "↓=Ledge (jump south)",
+            "↗": "↗=Ledge (jump NE)",
+            "↖": "↖=Ledge (jump NW)",
+            "↘": "↘=Ledge (jump SE)",
+            "↙": "↙=Ledge (jump SW)",
+            "L": "L=Ledge",
+            "T": "T=TV",
+            "?": "?=Unknown"
+        }
+        
+        for symbol, meaning in symbol_meanings.items():
+            if symbol in visible_symbols:
+                terrain_items.append(meaning)
+        
+        if terrain_items:
+            legend_lines.append(f"  Terrain: {', '.join(terrain_items)}")
+        
+        # Add portal markers to legend if any
+        if portal_positions:
+            unique_portals = {}
+            for pos, dest in portal_positions.items():
+                x, y = pos
+                if x == min_x:
+                    unique_portals["←"] = dest
+                elif x == max_x:
+                    unique_portals["→"] = dest
+                elif y == min_y:
+                    unique_portals["↑"] = dest
+                elif y == max_y:
+                    unique_portals["↓"] = dest
+            
+            if unique_portals:
+                portal_items = []
+                for symbol, dest in unique_portals.items():
+                    portal_items.append(f"{symbol}={dest}")
+                legend_lines.append(f"  Exits: {', '.join(portal_items)}")
+        
+        lines.extend(legend_lines)
+        
+        # Add explicit portal connections with coordinates
+        if connections:
+            lines.append("")
+            lines.append("Portal Connections:")
+            for conn in connections:
+                to_location = conn.get('to', 'Unknown')
+                from_pos = conn.get('from_pos', [])
+                to_pos = conn.get('to_pos', [])
+                
+                if from_pos and to_pos and len(from_pos) >= 2 and len(to_pos) >= 2:
+                    lines.append(f"  {location_name} ({from_pos[0]},{from_pos[1]}) → {to_location} ({to_pos[0]},{to_pos[1]})")
+                elif from_pos and len(from_pos) >= 2:
+                    lines.append(f"  {location_name} ({from_pos[0]},{from_pos[1]}) → {to_location}")
+                else:
+                    lines.append(f"  → {to_location}")
+        
+        return lines
+    
+    def _tile_to_symbol(self, tile) -> str:
+        """Convert a tile tuple to a simplified symbol for display."""
+        if tile is None:
+            # This will be handled specially - unexplored areas next to walkable will show ?
+            return None  # Mark as unexplored for special handling
+        
+        if len(tile) < 3:
+            return None  # Invalid tile - unexplored
+        
+        tile_id, behavior, collision = tile[:3]
+        
+        # tile_id 1023 (0x3FF) means out-of-bounds/unloaded area
+        # These are trees/boundaries at the edge of maps - show as walls
+        if tile_id == 1023:
+            return '#'  # Display as wall/blocked
+        
+        # Get behavior value
+        if hasattr(behavior, 'value'):
+            behavior_val = behavior.value
+        else:
+            behavior_val = behavior
+        
+        # Check behavior first for special terrain (even if impassable)
+        # Grass types (from MetatileBehavior enum)
+        if behavior_val == 2:  # TALL_GRASS
+            return '~'  # Tall grass (encounters)
+        elif behavior_val == 3:  # LONG_GRASS
+            return '^'  # Long grass
+        elif behavior_val == 7:  # SHORT_GRASS
+            return '^'  # Short grass
+        elif behavior_val == 36:  # ASHGRASS
+            return '^'  # Ash grass
+        
+        # Water types
+        elif behavior_val in [16, 17, 18, 19, 20, 21, 22, 23, 24, 26]:  # Various water types
+            return 'W'  # Water
+        
+        # Ice
+        elif behavior_val in [32, 38, 39]:  # ICE, THIN_ICE, CRACKED_ICE
+            return 'I'  # Ice
+        
+        # Sand
+        elif behavior_val in [6, 33]:  # DEEP_SAND, SAND
+            return 's'  # Sand
+        
+        # Doors and warps
+        elif behavior_val == 96:  # NON_ANIMATED_DOOR
+            return 'D'  # Door
+        elif behavior_val == 105:  # ANIMATED_DOOR
+            return 'D'  # Door
+        elif behavior_val in [98, 99, 100, 101]:  # Arrow warps
+            return 'D'  # Warp/Door
+        elif behavior_val == 97:  # LADDER
+            return 'S'  # Stairs/Ladder
+        elif behavior_val in [106, 107]:  # Escalators
+            return 'S'  # Stairs
+        
+        # PC and other interactables
+        elif behavior_val in [131, 197]:  # PC, PLAYER_ROOM_PC_ON
+            return 'C'  # Computer/PC (changed from 'P' to avoid conflict with Player)
+        elif behavior_val == 134:  # TELEVISION
+            return 'T'  # TV
+        
+        # Ledges/Jumps with directional arrows
+        elif behavior_val == 56:  # JUMP_EAST
+            return '→'  # Ledge east
+        elif behavior_val == 57:  # JUMP_WEST
+            return '←'  # Ledge west
+        elif behavior_val == 58:  # JUMP_NORTH
+            return '↑'  # Ledge north
+        elif behavior_val == 59:  # JUMP_SOUTH
+            return '↓'  # Ledge south
+        elif behavior_val == 60:  # JUMP_NORTHEAST
+            return '↗'  # Ledge northeast
+        elif behavior_val == 61:  # JUMP_NORTHWEST
+            return '↖'  # Ledge northwest
+        elif behavior_val == 62:  # JUMP_SOUTHEAST
+            return '↘'  # Ledge southeast
+        elif behavior_val == 63:  # JUMP_SOUTHWEST
+            return '↙'  # Ledge southwest
+        
+        # Now check collision for basic terrain
+        elif collision == 1:  # Impassable
+            return '#'  # Wall
+        elif collision == 0:  # Walkable
+            return '.'  # Floor
+        elif collision == 3:  # Ledge/special
+            return 'L'  # Ledge
+        elif collision == 4:  # Water/surf
+            return 'W'  # Water
+        else:
+            return '?'  # Unknown
+    
+    def _is_explorable_edge(self, x: int, y: int, location_grid: Dict[Tuple[int, int], str]) -> bool:
+        """Check if an unexplored coordinate is worth exploring (adjacent to walkable tiles)."""
+        # Check all 4 adjacent tiles
+        for dx, dy in [(0, 1), (0, -1), (1, 0), (-1, 0)]:
+            adj_x, adj_y = x + dx, y + dy
+            if (adj_x, adj_y) in location_grid:
+                tile = location_grid[(adj_x, adj_y)]
+                # If adjacent to walkable tile, this is explorable
+                # Include all walkable terrain types and ledges
+                if tile in ['.', 'D', 'S', '^', '~', 's', 'I',  # Floor, doors, stairs, grass, sand, ice
+                           '→', '←', '↑', '↓', '↗', '↖', '↘', '↙']:  # Ledges in all directions
+                    return True
+        return False
+    
+    def format_world_map_display(self, current_map_id: Optional[int] = None, max_width: int = 50) -> str:
+        """Format world map for display in agent context"""
+        world_map = self.generate_world_map_grid(current_map_id)
+        grid = world_map["grid"]
+        labels = world_map["area_labels"]
+        legend = world_map["legend"]
+        
+        lines = []
+        lines.append("=== WORLD MAP ===")
+        lines.append("")
+        
+        # Show grid with coordinates
+        for y, row in enumerate(grid):
+            row_str = ""
+            for x, cell in enumerate(row):
+                row_str += cell + " "
+            lines.append(f"{y:2d}: {row_str}")
+        
+        # Add coordinate header at bottom
+        header = "    "
+        for x in range(0, len(grid[0]), 5):  # Show every 5th coordinate
+            header += f"{x:2d}   "
+        lines.append("")
+        lines.append(header)
+        
+        # Add legend
+        lines.append("")
+        lines.append("Legend:")
+        for symbol, meaning in legend.items():
+            lines.append(f"  {symbol} = {meaning}")
+        
+        # Add discovered area list
+        if labels:
+            lines.append("")
+            lines.append("Discovered Areas:")
+            sorted_areas = sorted(labels.items(), key=lambda x: x[1])
+            for coord, name in sorted_areas[:10]:  # Show first 10
+                lines.append(f"  {coord}: {name}")
+            if len(sorted_areas) > 10:
+                lines.append(f"  ... and {len(sorted_areas) - 10} more")
+        
+        return "\n".join(lines)
+    
+    def save_to_checkpoint(self, checkpoint_data: dict):
+        """Save map stitching data to checkpoint data structure"""
+        try:
+            map_stitcher_data = {
+                "map_areas": {},
+                "warp_connections": [],
+                "location_connections": {}
+            }
+            
+            # Convert map areas to serializable format (without map_data)
+            for map_id, area in self.map_areas.items():
+                area_data = {
+                    "map_id": area.map_id,
+                    "location_name": area.location_name,
+                    "player_last_position": area.player_last_position,
+                    "warp_tiles": area.warp_tiles,
+                    "boundaries": area.boundaries,
+                    "visited_count": area.visited_count,
+                    "first_seen": area.first_seen,
+                    "last_seen": area.last_seen,
+                    "overworld_coords": area.overworld_coords
+                }
+            # print( Saving area {map_id} with overworld_coords = {area.overworld_coords}")
+                map_stitcher_data["map_areas"][str(map_id)] = area_data
+            
+            # Convert connections to serializable format
+            for conn in self.warp_connections:
+                map_stitcher_data["warp_connections"].append(asdict(conn))
+            
+            # Save location connections from state_formatter
+            try:
+                if hasattr(state_formatter, 'LOCATION_CONNECTIONS'):
+                    map_stitcher_data["location_connections"] = state_formatter.LOCATION_CONNECTIONS
+                    logger.debug(f"Saved {len(state_formatter.LOCATION_CONNECTIONS)} location connections to checkpoint")
+            except ImportError:
+                logger.debug("Could not import state_formatter for location connections in checkpoint")
+            
+            checkpoint_data["map_stitcher"] = map_stitcher_data
+            logger.debug(f"Saved {len(self.map_areas)} areas and {len(self.warp_connections)} connections to checkpoint")
+            
+        except Exception as e:
+            logger.error(f"Failed to save map stitcher to checkpoint: {e}")
+    
+    def load_from_checkpoint(self, checkpoint_data: dict):
+        """Load map stitching data from checkpoint data structure"""
+        try:
+            map_stitcher_data = checkpoint_data.get("map_stitcher")
+            if not map_stitcher_data:
+                return
+            
+            # Clear existing data
+            self.map_areas.clear()
+            self.warp_connections.clear()
+            
+            # Restore map areas (without map_data)
+            for map_id_str, area_data in map_stitcher_data.get("map_areas", {}).items():
+                map_id = int(map_id_str)
+                area = MapArea(
+                    map_id=area_data["map_id"],
+                    location_name=area_data["location_name"],
+                    map_data=[],  # Will be populated when area is revisited
+                    player_last_position=tuple(area_data["player_last_position"]),
+                    warp_tiles=[tuple(wt) for wt in area_data["warp_tiles"]],
+                    boundaries=area_data["boundaries"],
+                    visited_count=area_data["visited_count"],
+                    first_seen=area_data["first_seen"],
+                    last_seen=area_data["last_seen"],
+                    overworld_coords=tuple(area_data["overworld_coords"]) if area_data.get("overworld_coords") else None
+                )
+                self.map_areas[map_id] = area
+            
+            # Restore connections
+            for conn_data in map_stitcher_data.get("warp_connections", []):
+                conn = WarpConnection(
+                    from_map_id=conn_data["from_map_id"],
+                    to_map_id=conn_data["to_map_id"],
+                    from_position=tuple(conn_data["from_position"]),
+                    to_position=tuple(conn_data["to_position"]),
+                    warp_type=conn_data["warp_type"],
+                    direction=conn_data["direction"]
+                )
+                self.warp_connections.append(conn)
+            
+            # Restore location connections to state_formatter
+            location_connections = map_stitcher_data.get("location_connections", {})
+            if location_connections:
+                try:
+                    state_formatter.LOCATION_CONNECTIONS = location_connections
+                    logger.info(f"Loaded {len(location_connections)} location connections from checkpoint")
+                except ImportError:
+                    logger.debug("Could not import state_formatter for location connections from checkpoint")
+            
+            logger.info(f"Loaded {len(self.map_areas)} areas and {len(self.warp_connections)} connections from checkpoint")
+            
+        except Exception as e:
+            logger.error(f"Failed to load map stitcher from checkpoint: {e}")