Rebuild the world map as a Google Maps-style viewer

backend/server.py

@@ -125,6 +125,7 @@ def ping():
 from src.api.claim_routes import claim_router
 from src.api.regen_routes import regen_router
 from src.api.file_routes import file_router
+from src.api.tile_routes import tile_router
 from src.api.maps_routes import maps_router
 from src.api.profile_routes import profile_router
 from src.api.skins_routes import skins_router
@@ -150,6 +151,7 @@ def ping():
 app.include_router(ledger_router)
 app.include_router(regen_router)
 app.include_router(file_router)
+app.include_router(tile_router)
 app.include_router(skins_router)
 app.include_router(profile_router)
 app.include_router(characters_router)

backend/src/api/file_routes.py

@@ -1,10 +1,11 @@
-from fastapi import APIRouter, Header, HTTPException
+from fastapi import APIRouter, Header, HTTPException, Query
 from pathlib import Path
 
 from .http_headers import conditional_file_response
 from .map_access import ensure_map_access
 from .path_safety import is_safe_segment, resolve_within
 from .webp_cache import webp_variant
+from .tile_cache import MAX_LOD, MAX_PICK_SCALE, lod_variant, pick_variant
 from ..scripts.util import dirs
 from ..scripts.util.dirs import (
     map_image,
@@ -52,17 +53,13 @@ def _image_response(
     return response
 
 
-@file_router.get("/{map_name}/mapdata/{map_type}")
-async def get_map_file(
-    map_name: str,
-    map_type: str,
-    authorization: str | None = Header(default=None),
-    if_none_match: str | None = Header(default=None),
-    if_modified_since: str | None = Header(default=None),
-):
-    map_name = ensure_map_access(map_name, authorization).id
+def resolve_mapdata_path(map_name: str, map_type: str) -> Path | None:
+    """The full-map raster behind a map mode, or None if there is none.
+
+    `map_name` must already have passed the access check.
+    """
     if not is_safe_segment(map_type):
-        raise HTTPException(status_code=404, detail="Map not found")
+        return None
 
     # The province mode paints the source pick map itself, so there is
     # nothing to generate and nothing for a regen to keep in sync.
@@ -84,7 +81,30 @@ async def get_map_file(
 
     file_path = resolve_within(root, file_path)
     if file_path is None or not file_path.is_file():
+        return None
+    return file_path
+
+
+@file_router.get("/{map_name}/mapdata/{map_type}")
+async def get_map_file(
+    map_name: str,
+    map_type: str,
+    authorization: str | None = Header(default=None),
+    if_none_match: str | None = Header(default=None),
+    if_modified_since: str | None = Header(default=None),
+    scale: int = Query(default=0, ge=0, le=MAX_PICK_SCALE),
+):
+    map_name = ensure_map_access(map_name, authorization).id
+    file_path = resolve_mapdata_path(map_name, map_type)
+    if file_path is None:
         raise HTTPException(status_code=404, detail="Map not found")
+    # Phones ask for a smaller copy: the full-size pick canvas is more than
+    # iOS Safari will hold (see tile_cache.pick_variant). Called directly
+    # (not through FastAPI) the parameter is still its Query default.
+    if isinstance(scale, int) and scale > 0:
+        file_path = pick_variant(file_path, scale)
+        if file_path is None:
+            raise HTTPException(status_code=404, detail="Map not found")
 
     # Deliberately NOT routed through webp_variant: this is the pick map. The
     # client draws it to an offscreen canvas and reads exact RGB values back to
@@ -106,6 +126,7 @@ async def get_region_file(
     accept: str | None = Header(default=None),
     if_none_match: str | None = Header(default=None),
     if_modified_since: str | None = Header(default=None),
+    lod: int = Query(default=0, ge=0, le=MAX_LOD),
 ):
     map_name = ensure_map_access(map_name, authorization).id
     # Ensure .png extension
@@ -120,6 +141,18 @@ async def get_region_file(
     if file_path is None or not file_path.is_file():
         raise HTTPException(status_code=404, detail="Region overlay not found")
 
+    # A zoomed-out client asks for a reduced copy rather than decoding the
+    # full crop only to draw it a few pixels across.
+    if isinstance(lod, int) and lod > 0:
+        reduced = lod_variant(file_path, lod)
+        if reduced is not None:
+            return conditional_file_response(
+                reduced,
+                media_type="image/webp",
+                if_none_match=if_none_match,
+                if_modified_since=if_modified_since,
+            )
+
     return _image_response(file_path, accept, if_none_match, if_modified_since)
 
 

backend/src/api/map_registry.py

@@ -3,14 +3,21 @@
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
 
 import yaml
 
 _CONFIG_DIR = Path(__file__).resolve().parent.parent / "config"
 _DEFAULT_REGISTRY_PATH = _CONFIG_DIR / "maps.yml"
+# A site's own registry, in its data volume. Lets one deployment differ from
+# the repo's (the dev site shows the Dev server's map at /map) without an
+# environment variable, which the compose files on the host do not allow.
+_SITE_REGISTRY_PATH = Path(__file__).resolve().parent.parent / "data" / "maps.yml"
+
+# The map `/map` shows when no entry says `live: true`.
+DEFAULT_LIVE_MAP_ID = "main"
 
 _registry_cache: dict[str, MapEntry] | None = None
 
@@ -23,13 +30,16 @@ class MapEntry:
     realm_id: str
     staff_permission: str | None = None
     archived: bool = False
+    #: The map this site's `/map` shows. See `live_map_id`.
+    live: bool = False
 
     def to_public_dict(self) -> dict[str, Any]:
         return {
             "id": self.id,
             "display_name": self.display_name,
             "public": self.public,
             "archived": self.archived,
+            "live": self.live,
         }
 
 
@@ -41,6 +51,8 @@ def _registry_path() -> Path:
     override = os.environ.get("MAP_REGISTRY_PATH", "").strip()
     if override:
         return Path(override)
+    if _SITE_REGISTRY_PATH.is_file():
+        return _SITE_REGISTRY_PATH
     return _DEFAULT_REGISTRY_PATH
 
 
@@ -88,13 +100,20 @@ def _parse_entry(raw: dict[str, Any]) -> MapEntry:
         if not isinstance(archived, bool):
             raise MapRegistryError(f"Map '{map_id}' requires boolean archived")
 
+    live = raw.get("live", False)
+    if not isinstance(live, bool):
+        raise MapRegistryError(f"Map '{map_id}' requires boolean live")
+    if live and archived:
+        raise MapRegistryError(f"Map '{map_id}' cannot be both live and archived")
+
     return MapEntry(
         id=map_id,
         public=public,
         display_name=display_name,
         realm_id=realm_id,
         staff_permission=staff_permission,
         archived=archived,
+        live=live,
     )
 
 
@@ -125,10 +144,27 @@ def load_map_registry(*, force: bool = False) -> dict[str, MapEntry]:
             raise MapRegistryError(f"Duplicate map id '{entry.id}'")
         entries[entry.id] = entry
 
+    live = [entry.id for entry in entries.values() if entry.live]
+    if len(live) > 1:
+        raise MapRegistryError(f"Only one map can be live, found: {', '.join(live)}")
+    if not live and DEFAULT_LIVE_MAP_ID in entries:
+        # Registries written before `live` existed: `main` is the live map.
+        default = entries[DEFAULT_LIVE_MAP_ID]
+        if not default.archived:
+            entries[DEFAULT_LIVE_MAP_ID] = replace(default, live=True)
+
     _registry_cache = entries
     return entries
 
 
+def live_map_id() -> str:
+    """The map this site's `/map` shows."""
+    for entry in load_map_registry().values():
+        if entry.live:
+            return entry.id
+    return DEFAULT_LIVE_MAP_ID
+
+
 def get_map_entry(map_id: str) -> MapEntry | None:
     normalized = _normalize_map_id(map_id)
     if not normalized: