Skip to main content

mapv10 Roadmap

Status: M0-M10 implemented; active follow-up is source-of-truth documentation reconciliation Scope: map generator and viewer only
Primary target: continent-scale 3D fantasy map, proved from smaller slices through the first full-continent streaming artifact

mapv10 now has useful artifacts on disk and a plain Three.js viewer reading those artifacts. The early smaller-slice path remains important because it proved the pipeline, product contracts, renderer separation, and visual direction before M10 scaled the same contract to a full continent.

Current implementation status:

  • Milestone 0: implemented.
  • Milestone 1: implemented for a deterministic province-slice run.
  • Milestone 2: implemented with a plain Three.js viewer boot and browser nonblank verification.
  • Milestone 3: implemented with generated water topology, masks, material products, and viewer water/material rendering.
  • Milestone 4: implemented with realm/province/Location products, semantic ID rasters, borders, and typed picking.
  • Milestone 5: implemented with route, crossing, map feature, footprint, and label products plus viewer routes/markers/labels.
  • Milestone 6: implemented with raster/vector/semantic/mesh tile manifests, z0/z1 tile assets, tile previews, viewer tile selection, cancellable terrain tile loading, cache budget, and LOD switching.
  • Milestone 7: implemented with terrain chunk meshes, water meshes, route ribbons, border-SDF raster rendering, mesh manifests, mesh validation, and separated renderer passes.
  • Milestone 8: implemented with a validated regional-slice using the same stage pipeline, product contracts, tile API, mesh API, and viewer loading path as province-slice.
  • Milestone 9: implemented as readiness evidence: explicit memory/cache/artifact budgets, coordinate precision report, many-tile streaming proof, and draft continent preset config. Full continent generation was intentionally deferred from M9 to M10.
  • Milestone 10: implemented as the first real full-continent generation/viewer proof with performance-grade streaming telemetry, LOD evidence, required-product hard-failure verification, MZ z6/z7 physical LOD + semantic display policy, and concrete remaining-work analysis.

Guiding Rules​

  • Generator and viewer are separate projects.
  • Rust generator writes typed artifacts, previews, and validation.
  • Plain TypeScript + Three.js renderer consumes artifacts.
  • UI talks to renderer through typed commands/events.
  • React/R3F must not own the map scene.
  • Use the same pipeline for province-slice, regional-slice, realm-slice, and continent.
  • Produce real products at every stage; do not hide important data inside memory-only structures.
  • Pretty PNGs are previews, never map truth.

Milestone 0 - Skeleton And Contracts​

Goal: establish the repo shape and executable boundaries.

Deliverables:

  • generator/ Rust crate skeleton.
  • viewer/ TypeScript/Three.js skeleton.
  • schema/ folder for artifact schemas/manifests.
  • typed renderer API draft.
  • typed event model draft.
  • initial roadmap, architecture, and viewer UX docs.

Exit criteria:

  • folder structure matches architecture.md.
  • no generator/viewer code depends on downstream application simulation.
  • no React renderer architecture is introduced.

Milestone 1 - Minimal Artifact Run​

Goal: produce a tiny deterministic province-slice artifact run.

Scale:

  • province-slice
  • 2,000-10,000 km²
  • 5-10 Locations

Generator stages:

  • 00-config
  • 01-continent
  • 02-geography-graph
  • 03-heightfield
  • 14-previews

Required products:

  • manifest.json
  • config.json
  • stage-index.json
  • continentPolygons.json
  • coastlines.json
  • seaRegions.json
  • ridgeGraph.json
  • basins.json
  • height.f32.bin
  • slope.f32.bin
  • normal.rg16.bin
  • preview PNGs

Exit criteria:

  • same seed/config produces identical core product bytes.
  • previews render from generated data.
  • validation catches malformed polygons and invalid raster dimensions.

Milestone 2 - Plain Three.js Viewer Boot​

Goal: load the Milestone 1 artifact run and display a clean 3D terrain scene.

Viewer systems:

  • manifest loader
  • binary raster loader
  • Three.js renderer core
  • camera controls
  • resize handling
  • basic layer toggles
  • debug product drawer

Renderer requirements:

  • no React scene ownership
  • no R3F
  • renderer API exists as a framework-neutral TypeScript module
  • canvas renders nonblank
  • terrain uses generated height data

Exit criteria:

  • viewer loads the canonical generated fixture (public/continent-lod6, served as /mapv10/runs/continent-lod6/manifest.json for the current browser proof).
  • terrain is visible.
  • height/slope/normal previews are inspectable.
  • Playwright screenshot verifies nonblank desktop and wide viewports.

Milestone 3 - Water And Materials​

Goal: make the map read as a real landscape, not a bare heightfield.

Generator stages:

  • 04-water
  • 05-biomes-materials

Required products:

  • riverGraph.json
  • riverCenterlines.json
  • lakePolygons.json
  • seaRegions.json consumed by the mesh stage as generated open-sea surface truth
  • waterMask.u8.bin
  • riverWidth.f32.bin
  • biome.u8.bin
  • materialWeights.rgba8.bin
  • forestMask.u8.bin
  • wetlandMask.u8.bin
  • previews

Viewer systems:

  • water mesh rendering
  • terrain material/splat rendering
  • geography map mode

Exit criteria:

  • rivers/lakes derive from generated topology.
  • lakes are rendered from polygons/meshes, not bbox quads.
  • open sea is rendered from generated sea-region mesh products, not a viewer-created plane.
  • terrain materials are driven by generated material products.

Milestone 4 - Provinces, Locations, Picking​

Goal: prove the strategic map layer.

Generator stages:

  • 06-political
  • basic semantic ID rasters

Required products:

  • realmPolygons.json
  • provincePolygons.json
  • locationPolygons.json
  • provinceId.u32.bin
  • locationId.u32.bin
  • neighborGraph.json
  • political-preview.png

Viewer systems:

  • border rendering
  • hover/selection
  • typed pick results
  • political map mode

Exit criteria:

  • one province contains 5-10 Locations.
  • picking returns typed entity refs.
  • borders render over 3D terrain.
  • ID rasters are used for picking/debug, not preview PNG colors.

Milestone 5 - Routes, Features, Labels​

Goal: make the map readable as a strategy map.

Generator stages:

  • 07-routes
  • 08-map-features

Required products:

  • locationConnections.json
  • roadNetwork.json
  • routeGraph.json
  • routeCenterlines.json
  • crossingAnchors.json
  • mapFeatureAnchors.json
  • mapFeatureFootprints.json
  • labelAnchors.json

Viewer systems:

  • route ribbons
  • sparse point markers
  • label projection
  • label collision/fade

Exit criteria:

  • labels are generated anchors, not baked images.
  • route and feature markers can be toggled.
  • labels change by zoom band.

Milestone 6 - Tile Pyramid And LOD​

Goal: make the architecture scale beyond the prototype slice.

Status: implemented for province-slice.

Generator stage:

  • 11-tile-pyramid

Required products:

  • raster tile manifests
  • vector tile manifests
  • semantic tile manifests
  • mesh tile manifests
  • tile previews

Viewer systems:

  • camera-bound tile selection
  • cancellable tile loading
  • explicit tile cache
  • LOD switching

Exit criteria:

  • province-slice and regional-slice use the same tile API.
  • viewer does not load all high-detail products by default.
  • missing required tiles fail visibly.

Milestone 7 - Mesh Products And Render Passes​

Goal: move from prototype geometry to explicit render products.

Status: implemented for province-slice.

Generator stage:

  • 12-meshes

Required products:

  • terrain chunk meshes
  • water meshes
  • border-SDF raster products
  • route ribbons
  • mesh manifests

Viewer systems:

  • terrain pass
  • water pass
  • route pass plus border-SDF terrain-shader branch
  • overlay pass
  • marker pass
  • label pass
  • picking/debug pass

Exit criteria:

  • render systems are separate.
  • meshes have finite, non-degenerate geometry.
  • non-rectangular shapes use real generated geometry.

Milestone 8 - Regional Slice​

Goal: prove the target strategic scale.

Status: implemented.

Scale:

  • regional-slice
  • 45,000 km²
  • roughly 90-180 Locations

Exit criteria:

  • same pipeline as province-slice: implemented.
  • same viewer path: originally proven on a local regional fixture, now superseded by the canonical viewer/public/continent-lod6 browser proof.
  • zoom bands work from region to Location detail: browser verifier loads z0 overview and z1 detail tiles.
  • generated products stay inspectable: implemented through manifests, previews, tile products, mesh products, and validation reports.

Milestone 9 - Continent Readiness​

Goal: prepare for continent-scale generation.

Status: implemented as readiness artifacts; full continent generation is not part of this milestone.

Deliverables:

  • memory budget documented.
  • tile cache budget documented.
  • artifact size budget documented.
  • coordinate precision verified.
  • streaming validated with many tiles.
  • continent preset config drafted.

Exit criteria:

  • no architecture changes required to move from regional-slice to continent: readiness report and draft preset show the same config/product contract.
  • at the end of M9, only generator content/scale settings remained; M10 has since generated and verified the full continent run.

Milestone 10 - Full Continent Streaming And LOD Proof​

Goal: turn the draft continent preset into the first real full-continent artifact run and prove that the viewer can stream it with useful LOD.

Status: implemented by the canonical viewer/public/continent-lod6 fixture and viewer/verification/m10-lod6-continuity-proof.json.

Scale:

  • continent
  • millions of km²
  • thousands of strategic Locations
  • many-tile artifact set loaded by viewport and zoom, not eagerly

Deliverables:

  • validated full-continent generator run: implemented.
  • continent artifact-size, count, tile, mesh, and coordinate-precision reports: implemented under readiness/ and stages/13-readiness/.
  • viewer proof that boot loads only overview/core products plus visible tiles: implemented by the browser probe network and debug-state telemetry.
  • request cancellation, max in-flight request limit, cache bytes, and eviction counters: implemented in terrain/runtime/auxiliary mesh caches and exposed through debug telemetry.
  • scripted browser performance probe across continent overview, province/realm zoom, Location detail, detail tile boundary pan, and zoom-back: implemented.
  • LOD proof for terrain, water, borders, routes, labels, and markers: implemented through named visible tile bands and auxiliary mesh tile membership; visual quality remains subject to verifier-lane review.
  • required-product hard-failure proof: implemented in viewer/scripts/verify-browser.mjs and recorded by the focused M10 verifier artifact.

Exit criteria:

  • full continent run uses the same product pipeline as smaller presets.
  • streaming is proven by counters and cache budgets, not by visual impression.
  • LOD levels are proven by zoom-band/selection evidence, runtime counters, and screenshots.
  • missing required products fail visibly and hard; the viewer must not silently fall back to sample-run or fabricated products.
  • no downstream game/application logic is introduced.

Current Follow-Up Recommendation​

M10 is structurally implemented and the LOD/Data Coherence Foundation chain (Waves 1-4.5) has now shipped on top of it. MZ extends that foundation with an eight-rung physical LOD ladder (z0..z7), repairs z1 so it is no longer a same-sample physical refinement, adds generated closeDetailNormal truth with close-detail scale metadata, and separates strategic semantic zoom into the generated semanticDisplayPolicy product. The R-25 route-adaptive-batching baseline (23 scenarios, 0 hard failures, 0 warnings) is historical: the gate vocabulary has since grown (Wave 1 added forbidZ0UnderlayAtPrimaryZ, ancestorZDistanceMax, sidecarReadyForActiveMeshes, noPlaceholderTextureBound, coverageHoleMax, labelTextUniqueness, labelTextMinDistinctCount, labelMaxDuplicatesForText; MZ added semanticPolicyLoaded, semanticBandEquals, primaryZAtLeast, closeDetailScaleMin, and influenceProductRequiredBeforeRendering) and the current scenario evidence covers all 32 defined scenarios. Current evidence in viewer/verification/scenarios/latest/scenario-results.json records scenarioCount: 32, stores 32 result entries, and reports 0 hard budget/fail-condition issues; the two warn-only budget entries are fallbackSlotCountMax=48 > 32 in mapv10_zoom_continent_to_location_clean_lowland and mapv10_zoom_realm_to_location_overlays_z5. PROC reclassifies remote/network-throttled stress metrics as non-blocking evidence for a local-only product; clean/local omitted-slot regressions still belong in blocking gates. The local browser screenshot baselines under viewer/baselines/browser/continent-lod6/ were captured 2026-05-07 against the pre-Wave-2 fixture and need a user-accepted recapture/update only after foundation behaviour is accepted; never update them to mask a regression. docs/wave-3b-lod-ladder-camera-decision.md records the accepted and implemented z6/z7 physical LOD decision.

The recent foundation passes:

  • Moves byte-length checks, typed-array decode, mesh world-coordinate transform, per-vertex normal computation, and vector-tile JSON parse off the main thread into a fixed pool of decoder workers (transferable typed-array results, zero-copy on most browsers).
  • Restores incremental batched merge for water/route meshes per material kind, with a per-batch dirty signature and a FrameBudget that amortizes rebuild over frames so transitions never produce a synchronous burst; borders render from the generated border-SDF raster in the terrain shader.
  • Memoizes label canvas/texture pairs by text and caches footprint materials by kind, eliminating per-label canvas allocation churn and per-footprint material allocation.
  • Keeps generator/viewer separation, the 24-tile request scheduler, the typed renderer events, and zero-fallback hard failure on missing required products.
  • Established the scenario CLI, browser screenshot baseline commands, generated-artifact middleware boundary, and run-local Valenar export validation while keeping Valenar's runtime default on its small dummy fixture.

Remaining lane work after docs reconciliation:

  1. Wire scenario/browser verification into CI after the fixture/bootstrap and baseline-distribution policy is settled.
  2. Keep generated Valenar WorldData as a run-local product lane until an explicit import/package step selects it; do not switch Valenar's runtime default away from the dummy fixture in a docs reconciliation wave.
  3. Add targeted direct polish scenarios for borders and labels before changing their visual thresholds.
  4. Continue to treat full state-field producer transport, Stage 6 Voronoi optimization, and binary artifact fingerprinting as deferred unless explicitly scoped.