Add comprehensive wiki documentation

Created extensive wiki documentation covering all aspects of the Fantasy Map Generator: - Home.md: Wiki homepage with overview and navigation - Getting-Started.md: Complete beginner's guide for users and developers - Architecture.md: System architecture, design patterns, and technology stack - Data-Model.md: Detailed data structures and relationships - Generation-Process.md: Step-by-step map generation pipeline - Modules-Reference.md: Documentation for all 20+ modules - Features-and-UI.md: Complete feature list and UI guide - README.md: Wiki directory overview The documentation includes: - High-level architecture and design patterns - Detailed data structures with typed arrays - 17-stage generation pipeline with algorithms - All core modules (generators, renderers, UI, I/O) - 41+ UI editors and features - Code examples and usage patterns - Developer setup and contribution guidelines - User tutorials and quick start guides This wiki provides comprehensive documentation for both users wanting to create maps and developers wanting to understand or contribute to the codebase.
2025-12-17 17:51:24 +01:00 · 2025-11-04 21:37:18 +00:00 · 2025-11-04 21:37:18 +00:00 · 779e3d03b3
commit 779e3d03b3
parent dede314c94
8 changed files with 4716 additions and 0 deletions
--- a/wiki/Modules-Reference.md
+++ b/wiki/Modules-Reference.md
@ -0,0 +1,880 @@
+# Modules Reference
+
+This document provides detailed information about each module in the Fantasy Map Generator, including their purpose, main functions, and usage.
+
+## Module Organization
+
+Modules are located in the `modules/` directory and organized into categories:
+
+```
+modules/
+├── Core Generators (terrain, water, biomes)
+├── Civilization Generators (cultures, states, religions)
+├── Utility Generators (names, routes, military)
+├── Renderers (visualization)
+├── io/ (save/load/export)
+├── ui/ (editors and dialogs)
+└── dynamic/ (runtime utilities)
+```
+
+## Core Generator Modules
+
+### heightmap-generator.js
+
+**Purpose:** Generates terrain elevation for the map.
+
+**Main Functions:**
+
+```javascript
+HeightmapGenerator.generate()
+// Generates heightmap using selected template or custom image
+
+HeightmapGenerator.applyTemplate(template)
+// Applies a specific template (Pangea, Archipelago, etc.)
+
+HeightmapGenerator.fromImage(imageData)
+// Creates heightmap from uploaded image
+```
+
+**Templates Available:**
+- Pangea - Single supercontinent
+- Continents - Multiple landmasses
+- Archipelago - Many islands
+- Atoll - Ring-shaped island
+- Volcano - Volcanic island
+- High Island - Mountainous island
+- Low Island - Flat coral island
+- Mediterranean - Central sea with surrounding land
+- Peninsula - Land extending into water
+- Isthmus - Narrow land bridge
+
+**Usage:**
+```javascript
+// Generate default heightmap
+await HeightmapGenerator.generate();
+
+// Use specific template
+HeightmapGenerator.template = "Archipelago";
+await HeightmapGenerator.generate();
+```
+
+**Location in Pipeline:** Step 3 (after grid generation)
+
+---
+
+### river-generator.js
+
+**Purpose:** Generates realistic river networks based on elevation and precipitation.
+
+**Main Functions:**
+
+```javascript
+Rivers.generate()
+// Main generation function - creates all rivers
+
+Rivers.calculateFlux()
+// Calculates water accumulation in each cell
+
+Rivers.createMainRivers()
+// Creates primary river paths
+
+Rivers.createDowncutting()
+// Simulates erosion along rivers
+```
+
+**Algorithm:**
+1. Calculate water flux from precipitation
+2. Flow water downhill to adjacent cells
+3. Identify high-flux cells as river sources
+4. Create river paths following gradients
+5. Apply erosion to create valleys
+6. Detect confluences and tributaries
+
+**Data Structure:**
+```javascript
+pack.rivers = [
+  {
+    i: 0,              // River ID
+    source: 1234,      // Source cell
+    mouth: 5678,       // Mouth cell
+    cells: [...],      // Path cells
+    length: 250,       // Length
+    width: 8,          // Width
+    name: "River Name"
+  }
+]
+```
+
+**Location in Pipeline:** Step 7 (after climate calculation)
+
+---
+
+### biomes.js
+
+**Purpose:** Assigns biome types based on temperature and precipitation.
+
+**Main Functions:**
+
+```javascript
+Biomes.define()
+// Assigns biomes to all cells based on climate
+
+Biomes.getBiome(temperature, precipitation)
+// Returns biome ID for given climate values
+```
+
+**Biome Matrix:**
+
+The module uses a matrix mapping climate to biomes:
+
+| Temp\Prec | Very Dry | Dry | Wet | Very Wet |
+|-----------|----------|-----|-----|----------|
+| **Very Cold** | Glacier | Tundra | Tundra | Tundra |
+| **Cold** | Cold Desert | Taiga | Taiga | Wetland |
+| **Moderate** | Grassland | Grassland | Temp. Forest | Temp. Rainforest |
+| **Warm** | Hot Desert | Savanna | Trop. Forest | Tropical Rainforest |
+
+**Biome Data:**
+```javascript
+biomesData = {
+  i: [1, 2, 3, ...],           // IDs
+  name: ["Marine", "Hot desert", ...],
+  color: ["#53679f", "#fbe79f", ...],
+  habitability: [0, 4, 2, ...], // 0-100
+  iconsDensity: [0, 2, 5, ...],
+  icons: [[], ["dune"], ...]
+}
+```
+
+**Location in Pipeline:** Step 8 (after rivers)
+
+---
+
+### lakes.js
+
+**Purpose:** Manages lake creation and grouping.
+
+**Main Functions:**
+
+```javascript
+Lakes.defineGroup()
+// Groups adjacent lake cells together
+
+Lakes.cleanupLakes()
+// Removes small/invalid lakes
+
+Lakes.generateName(lakeId)
+// Creates procedural name for lake
+```
+
+**Process:**
+1. Identify water cells not connected to ocean
+2. Group adjacent cells into lakes
+3. Calculate lake properties (area, depth)
+4. Generate names
+5. Store in features array
+
+**Location in Pipeline:** Step 7 (alongside rivers)
+
+---
+
+## Civilization Generator Modules
+
+### cultures-generator.js
+
+**Purpose:** Creates and expands cultures across the map.
+
+**Main Functions:**
+
+```javascript
+Cultures.generate()
+// Places initial culture centers
+
+Cultures.expand()
+// Expands cultures from centers
+
+Cultures.add(culture)
+// Adds a new culture
+
+Cultures.remove(cultureId)
+// Removes a culture
+```
+
+**Culture Object:**
+```javascript
+{
+  i: 1,                    // Culture ID
+  name: "Elvari",
+  base: 5,                 // Name base index
+  type: "Generic",         // Culture type
+  center: 1234,            // Origin cell
+  color: "#3366cc",
+  expansionism: 0.8,       // 0-1 expansion rate
+  area: 500,               // Total cells
+  rural: 50000,            // Rural population
+  urban: 15000,            // Urban population
+  code: "EL",              // Two-letter code
+  shield: "heater"         // Shield shape for CoA
+}
+```
+
+**Expansion Algorithm:**
+- BFS (breadth-first search) from center
+- Prioritizes high-habitability cells
+- Respects expansionism rate
+- Stops at natural barriers or other cultures
+
+**Location in Pipeline:** Step 10 (after biomes)
+
+---
+
+### burgs-and-states.js
+
+**Purpose:** Generates settlements (burgs) and political states.
+
+**Main Functions:**
+
+```javascript
+BurgsAndStates.generate()
+// Main generation - creates capitals and states
+
+BurgsAndStates.addBurg(cell)
+// Adds a new settlement
+
+BurgsAndStates.removeBurg(burgId)
+// Removes a settlement
+
+BurgsAndStates.generateProvinces()
+// Divides states into provinces
+
+BurgsAndStates.expandStates()
+// Grows state territories
+```
+
+**Burg Object:**
+```javascript
+{
+  i: 1,
+  cell: 1234,
+  x: 150,
+  y: 200,
+  name: "Oakshire",
+  feature: 3,              // Island ID
+  state: 5,
+  capital: true,           // Is capital
+  culture: 2,
+  population: 25000,
+  type: "City",
+  port: 5,                 // Port value
+  citadel: true
+}
+```
+
+**State Object:**
+```javascript
+{
+  i: 1,
+  name: "Kingdom of Oakshire",
+  color: "#ff6633",
+  capital: 1,              // Capital burg ID
+  culture: 2,
+  religion: 3,
+  type: "Kingdom",
+  expansionism: 0.7,
+  form: "Monarchy",
+  area: 1000,              // Total cells
+  cells: 1000,
+  rural: 100000,
+  urban: 30000,
+  military: [...],         // Military units
+  diplomacy: [...]         // Relations
+}
+```
+
+**Location in Pipeline:** Step 11 (after cultures)
+
+---
+
+### religions-generator.js
+
+**Purpose:** Creates and spreads religions.
+
+**Main Functions:**
+
+```javascript
+Religions.generate()
+// Creates religions from cultures
+
+Religions.expand()
+// Spreads religions across territory
+
+Religions.add(religion)
+// Adds new religion
+
+Religions.remove(religionId)
+// Removes religion
+```
+
+**Religion Object:**
+```javascript
+{
+  i: 1,
+  name: "Church of the Sacred Oak",
+  color: "#ffd700",
+  type: "Organized",       // Folk, Organized, Cult, Heresy
+  form: "Church",
+  culture: 2,              // Origin culture
+  center: 1234,            // Origin cell
+  deity: "Oakfather",      // Deity name (if applicable)
+  area: 800,
+  cells: 800,
+  rural: 80000,
+  urban: 25000,
+  expansion: "culture",    // Expansion strategy
+  expansionism: 0.5,
+  code: "SO"
+}
+```
+
+**Location in Pipeline:** Step 12 (after states)
+
+---
+
+### military-generator.js
+
+**Purpose:** Creates military units for states.
+
+**Main Functions:**
+
+```javascript
+Military.generate()
+// Generates military units for all states
+
+Military.generateForState(stateId)
+// Generates units for specific state
+
+Military.createRegiment(state, type)
+// Creates a single military unit
+```
+
+**Military Unit:**
+```javascript
+{
+  i: 1,
+  state: 5,
+  name: "Royal Guard",
+  type: "Infantry",        // Infantry, Cavalry, Archers, etc.
+  strength: 1000,          // Number of soldiers
+  burg: 3,                 // Stationed at burg
+  icon: "infantry",
+  uIcon: "🗡️"
+}
+```
+
+**Unit Types:**
+- Infantry (foot soldiers)
+- Cavalry (mounted)
+- Archers (ranged)
+- Artillery (siege weapons)
+- Fleet (naval)
+
+**Location in Pipeline:** Step 15 (late generation)
+
+---
+
+### routes-generator.js
+
+**Purpose:** Creates road and sea route networks.
+
+**Main Functions:**
+
+```javascript
+Routes.generate()
+// Generates all routes
+
+Routes.generateRoads()
+// Creates land routes between burgs
+
+Routes.generateTrails()
+// Creates secondary paths
+
+Routes.generateSeaRoutes()
+// Creates maritime routes
+```
+
+**Algorithm:**
+- Uses modified Dijkstra's algorithm
+- Considers terrain difficulty
+- Connects burgs within states
+- Prioritizes major cities
+
+**Route Types:**
+- **Roads** - Major routes between cities
+- **Trails** - Minor paths
+- **Sea Routes** - Maritime trade routes
+
+**Location in Pipeline:** Step 14 (after provinces)
+
+---
+
+## Utility Modules
+
+### names-generator.js
+
+**Purpose:** Generates procedural names using Markov chains.
+
+**Main Functions:**
+
+```javascript
+Names.generate(base, type)
+// Generates name from base
+// base: name base index (0-99+)
+// type: "burg", "state", "river", etc.
+
+Names.addBase(baseName, examples)
+// Adds new name base from examples
+
+Names.getBase(culture)
+// Gets name base for culture
+```
+
+**Name Bases:**
+
+Pre-defined bases for different cultures:
+- English, French, German, Italian, Spanish
+- Arabic, Chinese, Japanese, Korean
+- Norse, Celtic, Slavic
+- Fantasy (Elvish, Dwarven, etc.)
+
+**Markov Chain:**
+```javascript
+// Learns from examples:
+["London", "Manchester", "Birmingham"]
+// Generates similar:
+["Lonchester", "Birmingam", "Manchdon"]
+```
+
+**Usage:**
+```javascript
+// Generate burg name
+const name = Names.generate(cultureBase, "burg");
+
+// Generate state name
+const stateName = Names.generate(cultureBase, "state");
+```
+
+---
+
+### coa-generator.js
+
+**Purpose:** Procedurally generates coats of arms (heraldry).
+
+**Main Functions:**
+
+```javascript
+COA.generate(entity, type)
+// Generates coat of arms
+// entity: state, burg, or province
+// type: determines complexity
+
+COA.shield(culture)
+// Selects shield shape based on culture
+
+COA.divisions()
+// Creates field divisions
+
+COA.charges()
+// Selects heraldic charges (symbols)
+```
+
+**Heraldic Elements:**
+- **Shield shapes** - Heater, French, Spanish, etc.
+- **Divisions** - Per pale, per fess, quarterly, etc.
+- **Charges** - Lions, eagles, crowns, etc. (200+ options)
+- **Tinctures** - Metals (or, argent) and colors (gules, azure, etc.)
+
+**COA Object:**
+```javascript
+{
+  shield: "heater",
+  division: "perPale",
+  charges: ["lion", "eagle"],
+  t1: "gules",            // Tincture 1 (field)
+  t2: "or"                // Tincture 2 (charges)
+}
+```
+
+---
+
+### markers-generator.js
+
+**Purpose:** Places special markers and points of interest.
+
+**Main Functions:**
+
+```javascript
+Markers.generate()
+// Generates all markers
+
+Markers.add(marker)
+// Adds custom marker
+
+Markers.remove(markerId)
+// Removes marker
+```
+
+**Marker Types:**
+- Volcanoes (mountains)
+- Ruins (ancient sites)
+- Battlefields
+- Mines (resources)
+- Bridges (river crossings)
+- Monuments
+- Shrines
+- Castles/Fortresses
+
+**Marker Object:**
+```javascript
+{
+  i: 1,
+  type: "volcano",
+  x: 150,
+  y: 200,
+  cell: 1234,
+  icon: "🌋",
+  size: 2,
+  note: "Mount Doom"       // Optional note
+}
+```
+
+**Location in Pipeline:** Step 16 (final generation)
+
+---
+
+### voronoi.js
+
+**Purpose:** Wrapper for Voronoi diagram generation.
+
+**Main Functions:**
+
+```javascript
+const voronoi = new Voronoi(delaunay, points);
+// Creates Voronoi from Delaunay triangulation
+
+voronoi.toGrid()
+// Converts to grid data structure
+```
+
+**Dependencies:**
+- Delaunator library (Delaunay triangulation)
+
+---
+
+### fonts.js
+
+**Purpose:** Manages custom fonts for labels.
+
+**Main Functions:**
+
+```javascript
+Fonts.load(fontName)
+// Loads font for use
+
+Fonts.getAvailable()
+// Returns list of available fonts
+```
+
+**Available Fonts:**
+Multiple font families for different map styles (serif, sans-serif, fantasy, etc.)
+
+---
+
+## Renderer Modules
+
+### coa-renderer.js
+
+**Purpose:** Renders coats of arms to SVG.
+
+**Main Functions:**
+
+```javascript
+COArenderer.renderCoat(coa, container)
+// Renders coat of arms to SVG element
+
+COArenderer.shield(shape, size)
+// Draws shield shape
+
+COArenderer.division(type, t1, t2)
+// Applies field division
+
+COArenderer.charge(type, position, size, tincture)
+// Adds heraldic charge
+```
+
+**Output:** SVG graphic of the coat of arms
+
+---
+
+### relief-icons.js
+
+**Purpose:** Renders terrain icons (mountains, forests, etc.)
+
+**Main Functions:**
+
+```javascript
+ReliefIcons.draw()
+// Draws all relief icons
+
+ReliefIcons.add(type, cell)
+// Adds icon at cell
+```
+
+**Icon Types:**
+- Mountains (peaks)
+- Hills
+- Forests
+- Swamps/wetlands
+- Volcanoes
+- Oases
+
+---
+
+### ocean-layers.js
+
+**Purpose:** Renders ocean visualization layers.
+
+**Main Functions:**
+
+```javascript
+OceanLayers.draw()
+// Draws ocean effects
+
+OceanLayers.toggle(layerName)
+// Shows/hides ocean layer
+```
+
+**Layers:**
+- Waves
+- Bathymetry (depth)
+- Ocean currents
+
+---
+
+## I/O Modules (modules/io/)
+
+### Save/Load
+
+**Functions:**
+
+```javascript
+// Save map
+downloadMap()
+// Downloads .map file
+
+// Load map
+uploadMap(file)
+// Loads from .map file
+
+loadMapFromURL(url)
+// Loads from URL
+```
+
+**Format:**
+- JSON with all map data
+- Compressed using LZ compression
+- Extension: `.map`
+
+### Export
+
+**Functions:**
+
+```javascript
+exportSVG()
+// Exports as SVG vector image
+
+exportPNG()
+// Exports as PNG raster image
+
+exportJSON()
+// Exports raw data as JSON
+```
+
+**Export Formats:**
+- SVG (vector)
+- PNG (raster)
+- JSON (data)
+
+---
+
+## UI Modules (modules/ui/)
+
+41+ specialized editors, each in its own file:
+
+### Key Editors
+
+**heightmap-editor.js** - Edit terrain elevation
+**rivers-editor.js** - Modify rivers
+**biomes-editor.js** - Edit biome distribution
+**states-editor.js** - Manage states
+**burgs-editor.js** - Edit settlements
+**cultures-editor.js** - Modify cultures
+**religions-editor.js** - Edit religions
+**provinces-editor.js** - Manage provinces
+**routes-editor.js** - Edit routes
+**military-overview.js** - Military management
+**markers-editor.js** - Place markers
+**notes-editor.js** - Annotations
+**style-editor.js** - Visual styling
+**options-editor.js** - Generation options
+
+Each editor provides:
+- Dialog interface
+- Data manipulation
+- Real-time preview
+- Validation
+
+---
+
+## Dynamic Modules (modules/dynamic/)
+
+Loaded on-demand for specific features:
+
+- 3D view components
+- Advanced export options
+- Specialized tools
+
+---
+
+## Module Communication
+
+### Global State
+
+Modules communicate through global objects:
+```javascript
+grid   // Terrain data
+pack   // Civilization data
+seed   // Random seed
+options // Settings
+```
+
+### Events
+
+Some modules use custom events:
+```javascript
+// Trigger event
+document.dispatchEvent(new CustomEvent('mapUpdated'));
+
+// Listen for event
+document.addEventListener('mapUpdated', handleUpdate);
+```
+
+### Direct Calls
+
+Most module communication is through direct function calls:
+```javascript
+Rivers.generate();
+Cultures.expand();
+BurgsAndStates.generate();
+```
+
+---
+
+## Adding New Modules
+
+### Template Structure
+
+```javascript
+"use strict";
+
+window.MyModule = (function() {
+  // Private variables
+  let privateData = {};
+
+  // Private functions
+  function privateFunction() {
+    // Implementation
+  }
+
+  // Public functions
+  function publicFunction() {
+    // Implementation
+  }
+
+  // Public API
+  return {
+    publicFunction
+  };
+})();
+```
+
+### Integration Steps
+
+1. Create module file in `modules/`
+2. Include in `index.html`:
+   ```html
+   <script src="modules/my-module.js"></script>
+   ```
+3. Call from main pipeline if needed
+4. Add UI editor if appropriate
+5. Update save/load if storing data
+
+---
+
+## Module Dependencies
+
+### Core Dependencies
+
+All modules depend on:
+- **main.js** - Global state and utilities
+- **grid/pack objects** - Data structures
+
+### Common Library Dependencies
+
+- **D3.js** - SVG manipulation
+- **jQuery** - DOM operations
+- **Delaunator** - Triangulation (for grid)
+
+### Module Dependencies
+
+```
+heightmap-generator.js
+  ↓
+river-generator.js
+  ↓
+biomes.js
+  ↓
+cultures-generator.js
+  ↓
+burgs-and-states.js
+  ↓
+religions-generator.js
+  ↓
+routes-generator.js
+```
+
+Each module typically depends on previous stages being complete.
+
+---
+
+## Performance Notes
+
+### Expensive Operations
+
+- **River generation** - Flux calculation O(n log n)
+- **Culture expansion** - BFS over cells O(n)
+- **Pathfinding** - Dijkstra for routes O(E + V log V)
+
+### Optimization Tips
+
+- Use typed arrays
+- Minimize D3 updates
+- Cache calculations
+- Use spatial indexing
+
+---
+
+## Further Reading
+
+- [Data Model](Data-Model.md) - Data structures
+- [Generation Process](Generation-Process.md) - Pipeline overview
+- [Architecture](Architecture.md) - System design