[MettaScope] camera clamping (#1557)

- It's possible to lose the map completely if you scroll too far off
- Let's clamp the map panning to ensure some part of the map is always
on-screen

[Asana
Task](https://app.asana.com/1/1209016784099267/project/1210348820405981/task/1210835069727884)

Author: monofuel

configs/user/monofuel.yaml

@@ -0,0 +1,14 @@
+# @package __global__
+
+# This file is private property of Andrew
+# DO NOT MODIFY. or do, if you want.
+# I'm not your boss I'm just a comment in a git repo.
+
+run: monofuel_local_2025_07_22
+
+wandb:
+  enabled: false
+
+trainer:
+  simulation:
+    replay_dir: ${run_dir}/replays/local # disable uploading replays to s3

mettascope/src/worldmap.ts

@@ -9,6 +9,57 @@ import { parseHtmlColor, find } from './htmlutils.js'
 import { updateHoverPanel, updateReadout, HoverPanel } from './hoverpanels.js'
 import { search, searchMatch } from './search.js'
 
+/**
+ * Clamps the map panel's pan position so that the world map always remains at
+ * least partially visible within the panel.
+ */
+function clampMapPan(panel: PanelInfo) {
+  if (state.replay === null) {
+    return
+  }
+
+  // The bounds of the world map in world-space coordinates. Tiles are drawn
+  // starting at (−TILE_SIZE/2, −TILE_SIZE/2).
+  const mapMinX = -Common.TILE_SIZE / 2
+  const mapMinY = -Common.TILE_SIZE / 2
+  const mapMaxX = state.replay.map_size[0] * Common.TILE_SIZE - Common.TILE_SIZE / 2
+  const mapMaxY = state.replay.map_size[1] * Common.TILE_SIZE - Common.TILE_SIZE / 2
+
+  // Dimensions of the visible area in world-space coordinates.
+  const rect = panel.rectInner()
+  const viewHalfWidth = rect.width / (2 * panel.zoomLevel)
+  const viewHalfHeight = rect.height / (2 * panel.zoomLevel)
+
+  // Current viewport centre in world-space.
+  let cx = -panel.panPos.x()
+  let cy = -panel.panPos.y()
+
+  const mapWidth = mapMaxX - mapMinX
+  const mapHeight = mapMaxY - mapMinY
+
+  // Minimum number of pixels of the map that must remain visible.
+  const minVisiblePixels = 500
+
+  // Convert to world coordinates based on current zoom level.
+  const minVisibleWorldUnits = minVisiblePixels / panel.zoomLevel
+
+  // Ensure the required visible area doesn't exceed the actual map size.
+  const maxVisibleUnitsX = Math.min(minVisibleWorldUnits, mapWidth / 2)
+  const maxVisibleUnitsY = Math.min(minVisibleWorldUnits, mapHeight / 2)
+
+  // Clamp horizontally.
+  const minCenterX = mapMinX + maxVisibleUnitsX - viewHalfWidth
+  const maxCenterX = mapMaxX - maxVisibleUnitsX + viewHalfWidth
+  cx = Math.max(minCenterX, Math.min(cx, maxCenterX))
+
+  // Clamp vertically.
+  const minCenterY = mapMinY + maxVisibleUnitsY - viewHalfHeight
+  const maxCenterY = mapMaxY - maxVisibleUnitsY + viewHalfHeight
+  cy = Math.max(minCenterY, Math.min(cy, maxCenterY))
+
+  panel.panPos = new Vec2f(-cx, -cy)
+}
+
 /** Generates a color from an agent ID. */
 function colorFromId(agentId: number) {
   let n = agentId + Math.PI + Math.E + Math.SQRT2
@@ -767,6 +818,9 @@ export function drawMap(panel: PanelInfo) {
     panel.panPos = new Vec2f(-x * Common.TILE_SIZE, -y * Common.TILE_SIZE)
   }
 
+  // Ensure that at least a portion of the map remains visible.
+  clampMapPan(panel)
+
   ctx.save()
   const rect = panel.rectInner()
   ctx.setScissorRect(rect.x, rect.y, rect.width, rect.height)