Skip to main content

mapv10 Viewer UX And Visual Products

Status: viewer contract with M10 continent proof implemented Scope: clean map viewer UX, generated raster products, map modes, labels, and debug separation

mapv10 is a map generator and viewer. The viewer exists to inspect, present, and validate generated map products.

The viewer should use a plain Three.js renderer core. UI controls can be vanilla DOM first, and a later React shell can communicate through typed commands/events, but React must not own the map scene.

The current viewer is a Vite + plain TypeScript + Three.js app. Its canonical browser proof loads the ignored full-continent fixture from /mapv10/runs/continent-lod6/manifest.json, with files stored under public/continent-lod6. The artifact middleware serves generated products as typed JSON/binary assets instead of allowing Vite SPA fallback. The viewer verifies binary raster/tile/mesh byte sizes, selects terrain tiles from camera bounds and zoom band, renders generated terrain chunks with world-normal directional relief lighting, water meshes, route ribbons, markers, and labels through explicit passes, renders borders from the generated border-SDF raster in the unified terrain shader, exposes map mode/layer controls, picks typed entities from generated semantic products, and keeps product/previews in a collapsible debug drawer.

Clean Viewer UX​

The first screen should be the map, not a dashboard.

Persistent UI should be limited to:

  • compact top controls for run selection, zoom, and map mode
  • collapsible inspector for the selected province, Location, route, water body, or map feature
  • small layer controls for generated products and overlays
  • optional developer/debug drawer hidden by default

The center of the map stays clear. Dense artifact inspection belongs in debug drawers, not the default viewer.

Renderer Interaction Boundary​

UI sends commands to the renderer:

  • load run
  • change map mode
  • toggle layer
  • frame entity
  • set overlay sample data
  • resize

Renderer emits events back:

  • run loaded
  • hover changed
  • selection changed
  • camera changed
  • tile load state changed
  • validation/debug product selected

This keeps the clean viewer UX independent from the Three.js scene internals.

Reference Lessons From mapv8 And mapv9​

Use these ideas:

  • generated data and rendering are separate
  • typed artifacts have manifests
  • generated PNG previews help humans inspect a run
  • semantic ID maps are useful for picking/debugging
  • water, borders, and routes come from generated geometry/data
  • validation runs before viewer consumption

Do not copy:

  • Estonia-scale assumptions
  • fine-cell visual density
  • debug-viewer layout as the clean viewer UX
  • hydrology research as the main visual goal

Are We Using Images?​

Yes. mapv10 should use generated raster/image products like heightmaps, normal maps, masks, semantic ID maps, and preview PNGs.

These are generated products and render inputs. They are not the source of truth.

Truth:

  • continent polygons
  • realm/province/Location polygons
  • river/lake/road graphs
  • map feature anchors
  • stable IDs
  • mesh products
  • overlay state

Generated images:

  • heightmap
  • normal map
  • slope map
  • material/splat maps
  • biome/classification maps
  • water masks
  • border distance masks
  • semantic ID maps for picking
  • generic overlay masks
  • preview/contact-sheet PNGs

Wrong:

paint a pretty map image, then infer map data from pixels

Right:

generate map truth, then derive images and meshes for rendering and inspection

Paradox-Style Reference​

The useful reference is the layered strategy-map pipeline:

  • terrain base from height and material products
  • political/region overlays on top
  • readable borders over terrain
  • labels controlled by zoom and priority
  • roads/routes as their own layer
  • map modes that recolor information without replacing map truth

mapv10 should use that kind of layered readability, while staying a generator/viewer.

Initial Map Modes​

  • Geography: terrain, rivers, lakes, roads, mountain passes, labels.
  • Political: realms, provinces, Locations, borders.
  • Scalar overlay: generic heatmap/mask layer for proving mutable overlays.
  • Routes/markers: roads, route metrics, sample point markers.
  • Debug: generated products, ID maps, validation previews.

Each mode uses the same generated base data. A mode changes coloring, overlays, labels, and visible layers.

Label System​

Generator provides:

  • label text
  • anchor position
  • entity ID
  • priority
  • zoom band
  • category

Viewer handles:

  • collision avoidance
  • fade in/out by zoom
  • selected/hover emphasis
  • hiding lower-priority labels
  • label offsets that keep text off borders and icons

First Viewer Acceptance Target​

The first mapv10 viewer proof should show:

  • clean 3D terrain without UI clutter
  • a geography mode with mountains, rivers, lakes, roads, and labels
  • a political mode with readable province/Location borders
  • a scalar overlay mode that can change without regenerating terrain
  • a routes/markers mode with sparse sample markers and route lines
  • hover and selection states
  • labels that change by zoom
  • debug/artifact panels hidden by default