mapv10 — Continent-Scale 3D Strategic Map
mapv10 is a continent-scale 3D fantasy map system built as a Rust generator (generator/) and a TypeScript + Three.js viewer (viewer/). The generator owns world truth as typed artifacts; the viewer streams those artifacts and renders them. The canonical scale is the continent preset at 2400 km × 1800 km with 6000–16000 strategic Locations and an eight-rung LOD pyramid totalling 65,533 tile slots (see architecture.md § Tile Pyramid And LOD). Every run carries the artifact contract version mapv10-artifacts-v1 (see generator/src/lib.rs ARTIFACT_SCHEMA_VERSION). For the system overview, read architecture.md.
Repository Layout
examples/map/mapv10/
generator/ Rust generator crate (16 stages, deterministic build_products pipeline)
viewer/ TypeScript + Three.js viewer (Vite, framework-free renderer core)
schema/ Shared *.schema.json contracts for manifests, products, exports
docs/ Deep-dive docs: generator.md, viewer.md, export-contract.md
Live governance docs at the root: architecture.md, README.md, roadmap.md, next-work.md, wave-protocol.md, scenarios.md, extending.md. Generator runs land at viewer/public/<run-id>/ and are served at /mapv10/runs/<run-id>/manifest.json by the dev (5443) and preview (4279) servers via viewer/server/mapv10ArtifactMiddleware.ts (see architecture.md § Workspace Layout).
Documentation
mapv10 documentation is intended to be portable: a reviewer should be able to take the Markdown files without the source tree and still understand the current architecture, artifact contracts, validation gates, and next work. Source code and schemas remain implementation evidence, but design and process decisions must be reflected in the docs below before future waves rely on them.
| Topic | File | Gloss |
|---|---|---|
| Architecture overview | architecture.md | Pipeline, coordinate system, renderer/UI boundary, governance |
| Generator deep-dive | docs/generator.md | CLI, all 16 stages, determinism contract, precision notes |
| Viewer deep-dive | docs/viewer.md | Renderer lifecycle, streaming, cache, LOD, shader modes |
| Export contract | docs/export-contract.md | Valenar WorldData field shapes, units, content-hash |
| Wave protocol | wave-protocol.md | 4-step wave dispatch and failure modes |
| Visual scenarios | scenarios.md | Scripted camera poses, per-mode performance budgets |
| Extension recipes | extending.md | Adding stages, map modes, layers, agents |
| Roadmap | roadmap.md | Milestone history, current follow-up posture |
| Backlog | next-work.md | Open work by tier |
| Current checkpoint | docs/current-checkpoint-2026-05-06.md | Current proof state and validation boundary |
| M9 readiness | m9-readiness.md | Readiness notes before the M10 continent proof |
| M10 continent proof | m10-continent-proof.md | Continent-scale acceptance proof packet |
| Performance hardening | docs/performance-and-streaming-hardening-spec.md | Streaming, LOD, and browser-performance hardening plan |
| LOD redesign | docs/lod-redesign-spec.md | Tile and camera LOD redesign contract |
| Local-only premise | docs/local-only-product-premise.md | Local product boundary and deployment premise |
| Wave 3B LOD decision | docs/wave-3b-lod-ladder-camera-decision.md | LOD ladder and camera decision record |
| Generator crate | generator/README.md | Build commands, Cargo flags |
| Viewer package | viewer/README.md | npm scripts, dev-server config |
| Schemas | schema/README.md | JSON schema files for all artifact types |
Portable source-of-truth packet
For a code-free architecture review, use this packet in order:
README.md— orientation, file map, quick-start commands, current status.architecture.md— system boundary, generator/viewer architecture, artifacts, LOD, renderer contracts, fallback doctrine, verification surface.docs/generator.md— generator CLI, pipeline orchestration, stage algorithms, emitted products, determinism and precision boundaries.docs/viewer.md— Three.js/Vite stack, renderer lifecycle, streaming, cache, shader/material contracts, browser verifier and scenario hooks.docs/export-contract.md— Valenar WorldData schema, units, path semantics, content-hash semantics, and schema-plus-imperative validation.scenarios.md— visual/performance scenario contract and browser proof shape.wave-protocol.md— mandatory Explore → Implement → Validate → Tenets process.roadmap.mdandnext-work.md— completed milestones, current queue, explicit deferrals and open decisions.
If this packet disagrees with source, the next work is to reconcile the docs
first or record the drift explicitly in next-work.md; do not let unrecorded
source behavior become hidden architecture.
Quick Start
Build the generator:
cd examples/map/mapv10/generator
cargo build --release
Bootstrap the canonical fixture (regenerates viewer/public/continent-lod6 and validates the run-local Valenar export, per viewer/package.json script fixture:continent):
cd examples/map/mapv10/viewer
npm install
npm run fixture:continent
Run the dev viewer (Vite serves on port 5443, bound to 0.0.0.0, per viewer/vite.config.ts server config):
cd examples/map/mapv10/viewer
npm run dev
Open http://localhost:5443/?manifest=/mapv10/runs/continent-lod6/manifest.json.
Verify a fixture run (scripts defined in viewer/package.json; see
viewer/README.md for the full table):
npm run typecheck
npm run build
npm run test
npm run validate:valenar-export
npm run verify:browser:continent
npm run scenarios
Run cargo test --release from generator/ for the Rust test suite, which includes the same_config_produces_same_core_product_bytes determinism check in generator/src/pipeline.rs.
Scale Presets
The generator runs the same pipeline for every preset; only the inputs differ (generator/src/config.rs scale_preset_config).
| Preset | World km (W × H) | Target Locations |
|---|---|---|
province-slice | 96 × 64 | 5–10 |
regional-slice | 250 × 180 | 90–180 |
realm-slice | 720 × 520 | 320–1200 |
continent | 2400 × 1800 | 6000–16000 |
The continent preset is the canonical fixture target. Full preset and LOD details live in architecture.md.
Status
The continent-lod6 fixture is canonical: 65,533 tile slots across 8 LOD rungs (z0–z7) over a 2400 × 1800 km world (see architecture.md § Scale Presets and § Tile Pyramid And LOD). Tile family manifests are packaged as a generated tile-coordinate index plus z-row sharded raster/vector/semantic/mesh indexes so the browser and verifier never read a multi-GB monolithic tile JSON. All 16 generator stages are implemented (see architecture.md § Generator Pipeline); per-run determinism is asserted by same_config_produces_same_core_product_bytes in generator/src/pipeline.rs. Three deep-dive docs in docs/ cover the generator pipeline, the viewer renderer, and the Valenar export schema. Current implemented status, deferrals, and the next queue are tracked in roadmap.md and next-work.md; source code and proof artifacts are implementation evidence, not a substitute for keeping this portable packet current.