How azgaar/fantasy-map-generator works
Purpose and Runtime
Azgaar’s Fantasy Map Generator is a client-side web application for procedurally creating and interactively editing fantasy maps. It is transitioning from legacy JavaScript toward TypeScript while preserving .map compatibility. The browser app is served as static assets, with Vite development/build configuration in vite.config.ts; deployment can use Netlify/Docker via netlify.toml, Dockerfile, and .docker/default.conf.
Entry and Application Shell
The primary document is src/index.html; application bootstrapping is split between main.js and public/main.js. App-level initialization, installation/PWA concerns, fonts, and lifecycle services are centralized in src/services/app-shell.ts, src/services/installation.ts, and public/sw.js. The UI is primarily SVG/DOM-driven, with an optional 3D/WebGL visualization path.
World State and Data Model Boundary
The intended architecture keeps world data passive: generators and editors own behavior, while renderers consume state. The packed spatial graph is a core representation (src/types/PackedGraph.ts), supporting cell-based terrain and political/economic entities. Data-model contracts and migration intent are documented in docs/architecture/data_model.md, docs/architecture/future_data_model.md, and docs/architecture/migration_guide.md.
Procedural Generation Pipeline
Generation begins from settings and terrain/heightmap creation, then derives geographic and societal layers. Core stages include Voronoi graph construction (src/generators/voronoi.ts), terrain creation (src/generators/heightmap-generator.ts), biomes and hydrology (src/generators/biomes-generator.ts, src/generators/river-generator.ts), settlements/states (src/generators/burgs-generator.ts, src/generators/states-generator.ts), and routes/economy (src/generators/routes-generator.ts, src/generators/goods-generator.ts). The domain sequencing is further specified in docs/domain/generation_pipeline.md.
Editing and Controller Layer
Interactive map tools are controller modules that perform controlled world-state mutations and then request redraws. This layer covers terrain and geographic editing (src/controllers/heightmap-editor.ts, src/controllers/river-editor.ts), political entities (src/controllers/states-editor.ts, src/controllers/burg-editor.ts), and map infrastructure/economy (src/controllers/route-editor.ts, src/controllers/goods-editor.ts). Controller registration is consolidated in src/controllers/index.ts; shared interaction primitives live under src/components/.
Rendering and Visualization
Renderers transform world state into visual layers and should not mutate it. Geographic SVG layers are handled by modules such as src/renderers/draw-heightmap.ts, src/renderers/draw-biomes.ts, and src/renderers/draw-borders.ts; labels and symbols have specialized rendering subsystems in src/renderers/labels/labels-renderer.ts and src/renderers/emblems/renderer.ts. src/renderers/viewport/viewport-renderer.ts coordinates viewport drawing, while src/renderers/view-3d-renderer.ts supports the separate 3D path.
Persistence, Import/Export, and External Boundaries
Map files are loaded, migrated, and saved through src/services/io/load.ts, src/services/io/save.ts, and src/services/io/export.ts; autosave is in src/services/autosave.ts. Browser-local persistence is supported by bundled IndexedDB code at public/libs/indexedDB.js. Cloud-facing behavior is isolated in src/services/io/cloud.ts; version/update handling is in src/services/io/auto-update.ts and src/services/versioning.ts. Static assets, style presets, heightmaps, and third-party browser libraries are served from public/.
Main entry points: PackedGraph.ts Packed world state · viewport-renderer.ts Viewport renderer · load.ts Map load, save, export · voronoi.ts Voronoi graph
Components 21
Browser Runtime
- HTML document
src/index.html - Application bootstrap
main.js - App shell · Initializes application services, fonts, and installation concerns.
src/services/app-shell.ts - Service worker
public/sw.js - Packed world state · Passive cell graph and map entities shared across features.
src/types/PackedGraph.ts
Generation Pipeline
- Generation sequencing
docs/domain/generation_pipeline.md - Voronoi graph
src/generators/voronoi.ts - Terrain and heightmap
src/generators/heightmap-generator.ts - Biomes and rivers
src/generators/biomes-generator.ts - Burgs and states
src/generators/burgs-generator.ts - Routes and goods
src/generators/routes-generator.ts
Editing
- Editor controllers · Controlled mutations for terrain, entities, routes, and goods.
src/controllers/index.ts - Interaction components
Rendering
- Viewport renderer
src/renderers/viewport/viewport-renderer.ts - Geographic SVG layers
src/renderers/draw-heightmap.ts - Labels and emblems
src/renderers/labels/labels-renderer.ts - 3D visualization
src/renderers/view-3d-renderer.ts
Persistence & External I/O
- Map load, save, export · Loads and migrates compatible map files, then saves or exports them.
src/services/io/load.ts - Autosave
src/services/autosave.ts - Browser IndexedDB
public/libs/indexedDB.js - Cloud I/O
src/services/io/cloud.ts
Connections 24
- HTML document → Application bootstrap: loads
- Application bootstrap → App shell: initializes
- App shell → Service worker: registers
- Voronoi graph → Terrain and heightmap: provides cells
- Terrain and heightmap → Biomes and rivers: derives
- Biomes and rivers → Burgs and states: shapes
- Burgs and states → Routes and goods: enables
- Generation sequencing → Voronoi graph: specifies order
- Voronoi graph → Packed world state: builds
- Terrain and heightmap → Packed world state: writes terrain
- Biomes and rivers → Packed world state: writes geography
- Burgs and states → Packed world state: writes entities
- Routes and goods → Packed world state: writes routes and goods
- Interaction components → Editor controllers: drives tools
- Editor controllers → Packed world state: mutates
- Editor controllers → Viewport renderer: requests redraw
- Packed world state → Viewport renderer: render input
- Viewport renderer → Geographic SVG layers: coordinates
- Viewport renderer → Labels and emblems: coordinates
- Packed world state → 3D visualization: render input
- Packed world state → Map load, save, export: load/save state
- Autosave → Map load, save, export: saves through
- Map load, save, export → Browser IndexedDB: persists locally
- Map load, save, export → Cloud I/O: cloud operations